# オブジェクトプロトコル (object protocol)

PyObject* `Py_NotImplemented`

  与えられたオブジェクトとメソッドの引数の型の組み合わせの処理が未実装である印として使われる、 `未実装 (NotImplemented)` シングルトン。

`Py_RETURN_NOTIMPLEMENTED`

  C 関数から `Py_NotImplemented` を返す処理を適切に行います (すなわち、 NotImplemented シングルトンの参照カウントを増やし、返却します) 。

int `PyObject_Print`(PyObject *o, FILE *fp, int flags)

  オブジェクト o をファイル fp に出力します。失敗すると `-1` を返します。 flags 引数は何らかの出力オプションを有効にする際に使います。現在サポートされている唯一のオプションは `Py_PRINT_RAW` です; このオプションを指定すると、 `repr()` の代わりに `str()` を使ってオブジェクトを書き込みます。

int `PyObject_HasAttr`(PyObject *o, PyObject *attr_name)

  o が属性 attr_name を持つときに `1` を、それ以外のときに `0` を返します。この関数は Python の式 `hasattr(o, attr_name)` と同じです。この関数は常に成功します。

  `__getattr__()` メソッドや `__getattribute__()` メソッドの呼び出し中に起こる例外は抑制されることに注意してください。 エラーを報告させるには、代わりに `PyObject_GetAttr()` を使ってください。

int `PyObject_HasAttrString`(PyObject *o, const char *attr_name)

  o が属性 attr_name を持つときに `1` を、それ以外のときに `0` を返します。この関数は Python の式 `hasattr(o, attr_name)` と同じです。この関数は常に成功します。

  `__getattr__()` メソッドや `__getattribute__()` メソッドの呼び出し中や、一時的な文字列オブジェクトの作成中に起こる例外は抑制されることに注意してください。 エラーを報告させるには、代わりに `PyObject_GetAttrString()` を使ってください。

PyObject* `PyObject_GetAttr`(PyObject *o, PyObject *attr_name)
  Return value: New reference.

  オブジェクト o から、名前 attr_name の属性を取得します。成功すると属性値を返し失敗すると `NULL` を返します。この関数は Python の式 `o.attr_name` と同じです。

PyObject* `PyObject_GetAttrString`(PyObject *o, const char *attr_name)
  Return value: New reference.

  オブジェクト o から、名前 attr_name の属性を取得します。成功すると属性値を返し失敗すると `NULL` を返します。この関数は Python の式 `o.attr_name` と同じです。

PyObject* `PyObject_GenericGetAttr`(PyObject *o, PyObject *name)
  Return value: New reference.

  型オブジェクトの `tp_getattro` スロットに置かれる、属性を取得する総称的な関数です。この関数は、 (もし存在すれば) オブジェクトの属性 `__dict__` に加え、オブジェクトの MRO にあるクラスの辞書にあるデスクリプタを探します。 デスクリプタ (descriptor) の実装 で概要が述べられている通り、データのデスクリプタはインスタンスの属性より優先され、非データデスクリプタは後回しにされます。見付からなかった場合は `AttributeError` を送出します。

int `PyObject_SetAttr`(PyObject *o, PyObject *attr_name, PyObject *v)

  オブジェクト o の attr_name という名の属性に、値 v を設定します。 失敗すると例外を送出し `-1` を返します; 成功すると `0` を返します。 この関数は Python の式 `o.attr_name = v` と同じです。

  v が `NULL` の場合は属性が削除されますが、この機能は非推奨であり `PyObject_DelAttr()` を使うのが望ましいです。

int `PyObject_SetAttrString`(PyObject *o, const char *attr_name, PyObject *v)

  オブジェクト o の attr_name という名の属性に、値 v を設定します。 失敗すると例外を送出し `-1` を返します; 成功すると `0` を返します。 この関数は Python の式 `o.attr_name = v` と同じです。

  v が `NULL` の場合は属性が削除されますが、この機能は非推奨であり `PyObject_DelAttrString()` を使うのが望ましいです。

int `PyObject_GenericSetAttr`(PyObject *o, PyObject *name, PyObject *value)

  属性の設定と削除を行う汎用的な関数で、型オブジェクトの `tp_setattro` スロットに置かれます。 オブジェクトの MRO にあるクラスの辞書からデータディスクリプタを探し、見付かった場合はインスタンスの辞書にある属性の設定や削除よりも優先されます。 そうでない場合は、(もし存在すれば) オブジェクトの `__dict__` に属性を設定もしくは削除します。 成功すると `0` が返され、そうでない場合は `AttributeError` が送出され `-1` が返されます。

int `PyObject_DelAttr`(PyObject *o, PyObject *attr_name)

  オブジェクト o の attr_name という名の属性を削除します。失敗すると `-1` を返します。この関数は Python の文 `del o.attr_name` と同じです。

int `PyObject_DelAttrString`(PyObject *o, const char *attr_name)

  オブジェクト o の attr_name という名の属性を削除します。失敗すると `-1` を返します。この関数は Python の文 `del o.attr_name` と同じです。

PyObject* `PyObject_GenericGetDict`(PyObject *o, void *context)
  Return value: New reference.

  `__dict__` デスクリプタの getter の総称的な実装です。必要な場合は、辞書を作成します。

  バージョン 3.3 で追加.

int `PyObject_GenericSetDict`(PyObject *o, PyObject *value, void *context)

  `__dict__` デスクリプタの setter の総称的な実装です。この実装では辞書を削除することは許されていません。

  バージョン 3.3 で追加.

PyObject* `PyObject_RichCompare`(PyObject *o1, PyObject *o2, int opid)
  Return value: New reference.

  o1 と o2 を opid に指定した演算によって比較します。 opid は `Py_LT`, `Py_LE`, `Py_EQ`, `Py_NE`, `Py_GT`, または `Py_GE`, のいずれかでなければならず、それぞれ `<`, `<=`, `==`, `!=`, `>`, および `>=` に対応します。この関数は Python の式 `o1 op o2` と同じで、 `op` が opid に対応する演算子です。成功すると比較結果の値を返し失敗すると `NULL` を返します。

int `PyObject_RichCompareBool`(PyObject *o1, PyObject *o2, int opid)

  o1 と o2 を opid に指定した演算によって比較します。 opid は `Py_LT`, `Py_LE`, `Py_EQ`, `Py_NE`, `Py_GT`, または `Py_GE`, のいずれかでなければならず、それぞれ `<`, `<=`, `==`, `!=`, `>`, および `>=` に対応します。比較結果が真ならば `1` を、偽ならば `0` を、エラーが発生すると `-1` を返します。この関数は Python の式 `o1 op o2` と同じで、 `op` が opid に対応する演算子です。

注釈

o1 と o2 が同一のオブジェクトである場合、 `PyObject_RichCompareBool()` は `Py_EQ` に対して常に `1` を返し、 `Py_NE` に対して常に `0` を返します。

PyObject* `PyObject_Repr`(PyObject *o)
  Return value: New reference.

  オブジェクト o の文字列表現を計算します。成功すると文字列表現を返し、失敗すると `NULL` を返します。 Python 式 `repr(o)` と同じです。この関数は組み込み関数 `repr()` の処理で呼び出されます。

  バージョン 3.4 で変更: アクティブな例外を黙って捨てないことを保証するのに便利なように、この関数はデバッグアサーションを含むようになりました。

PyObject* `PyObject_ASCII`(PyObject *o)
  Return value: New reference.

  `PyObject_Repr()` と同様、オブジェクト o の文字列表現を計算しますが、 `PyObject_Repr()` によって返された文字列に含まれる非 ASCII 文字を、エスケープ文字 `\x` 、 `\u` 、 `\U` でエスケープします。この関数は Pythoh 2 の `PyObject_Repr()` が返す文字列と同じ文字列を生成します。 `ascii()` によって呼び出されます。

PyObject* `PyObject_Str`(PyObject *o)
  Return value: New reference.

  オブジェクト o の文字列表現を計算します。成功すると文字列表現を返し、失敗すると `NULL` を返します。 Python 式 `str(o)` と同じです。この関数は組み込み関数 `str()` や、 `print()` 関数の処理で呼び出されます。

  バージョン 3.4 で変更: アクティブな例外を黙って捨てないことを保証するのに便利なように、この関数はデバッグアサーションを含むようになりました。

PyObject* `PyObject_Bytes`(PyObject *o)
  Return value: New reference.

  オブジェクト o のバイト列表現を計算します。失敗すると `NULL` を返し、成功すると bytes オブジェクトを返します。 o が整数でないときの、 Python 式 `bytes(o)` と同じです。 `bytes(o)` と違って、 o が整数のときには、ゼロで初期化された bytes オブジェクトを返すのではなく TypeError が送出されます。

int `PyObject_IsSubclass`(PyObject *derived, PyObject *cls)

  クラス derived がクラス cls と同一であるか、そこから派生したクラスである場合は `1` を返し、そうでない場合は `0` を返します。 エラーが起きた場合は `-1` を返します。

  cls がタプルの場合、 cls の全ての要素に対してチェックします。 少なくとも1つのチェックで `1` が返ったとき、結果は `1` となり、それ以外のとき `0` になります。

  cls に `__subclasscheck__()` メソッドがある場合は、子クラスの状態が PEP 3119 にある通りかどうかを判定するために呼ばれます。 そうでないとき derived が cls の子クラスになるのは、直接的あるいは間接的な子クラスである場合、つまり `cls.__mro__` に含まれる場合です。

  通常は、クラスオブジェクト、つまり `type` のインスタンスやそこから派生したクラスだけがクラスと見なされます。 しかし、オブジェクトに属性 `__bases__` (これは基底クラスのタプルでなければならない) を持たせることで上書きできます。

int `PyObject_IsInstance`(PyObject *inst, PyObject *cls)

  inst がクラス cls もしくは cls の子クラスのインスタンスである場合に `1` を返し、そうでない場合に `0` を返します。 エラーが起きると `-1` を返し例外を設定します。

  cls がタプルの場合、 cls の全ての要素に対してチェックします。 少なくとも1つのチェックで `1` が返ったとき、結果は `1` となり、それ以外のとき `0` になります。

  cls に `__instancecheck__()` メソッドがある場合は、子クラスの状態が PEP 3119 にある通りかどうかを判定するために呼ばれます。 そうでないとき inst が cls のインスタンスになるのは、そのクラスが cls の子クラスである場合です。

  インスタンス inst に属性 `__class__` を持たせることで、そのクラスと見なされるものを上書きできます。

  オブジェクト cls とその基底クラスがクラスと見なされる場合、属性 `__bases__` (これは基底クラスのタプルでなければならない) を持たせることで上書きできます。

int `PyCallable_Check`(PyObject *o)

  オブジェクト o が呼び出し可能オブジェクトかどうか調べます。オブジェクトが呼び出し可能であるときに `1` を返し、そうでないときには `0` を返します。この関数呼び出しは常に成功します。

PyObject* `PyObject_Call`(PyObject *callable, PyObject *args, PyObject *kwargs)
  Return value: New reference.

  呼び出し可能な Python のオブジェクト callable を、タプル args として与えられる引数と辞書 kwargs として与えられる名前付き引数とともに呼び出します。

  args は `NULL` であってはならず、引数を必要としない場合は空のタプルを使ってください。 kwargs は `NULL` でも構いません。

  成功したら呼び出しの結果を返し、失敗したら例外を送出し `NULL` を返します。

  これは次の Python の式と同等です: `callable(*args, **kwargs)` 。

PyObject* `PyObject_CallObject`(PyObject *callable, PyObject *args)
  Return value: New reference.

  呼び出し可能な Python のオブジェクト callable を、タプル args として与えられる引数とともに呼び出します。 引数が不要な場合は、 args は `NULL` で構いません。

  成功したら呼び出しの結果を返し、失敗したら例外を送出し `NULL` を返します。

  これは次の Python の式と同等です: `callable(*args)` 。

PyObject* `PyObject_CallFunction`(PyObject *callable, const char *format, ...)
  Return value: New reference.

  呼び出し可能な Python オブジェクト callable を可変数個の C 引数とともに呼び出します。 C 引数は `Py_BuildValue()` 形式のフォーマット文字列を使って記述します。

  成功したら呼び出しの結果を返し、失敗したら例外を送出し `NULL` を返します。

  これは次の Python の式と同等です: `callable(*args)` 。

  Note that if you only pass `PyObject *` args, `PyObject_CallFunctionObjArgs()` is a faster alternative.

  バージョン 3.4 で変更: format の型が `char *` から変更されました。

PyObject* `PyObject_CallMethod`(PyObject *obj, const char *name, const char *format, ...)
  Return value: New reference.

  オブジェクト obj の name という名前のメソッドを、いくつかの C 引数とともに呼び出します。 C 引数はタプルを生成する `Py_BuildValue()` 形式のフォーマット文字列で記述されています。

  format は `NULL` でもよく、引数が与えられないことを表します。

  成功したら呼び出しの結果を返し、失敗したら例外を送出し `NULL` を返します。

  これは次の Python の式と同等です: `obj.name(arg1, arg2, ...)` 。

  Note that if you only pass `PyObject *` args, `PyObject_CallMethodObjArgs()` is a faster alternative.

  バージョン 3.4 で変更: name と format の型が `char *` から変更されました。

PyObject* `PyObject_CallFunctionObjArgs`(PyObject *callable, ...)
  Return value: New reference.

  Call a callable Python object callable, with a variable number of `PyObject*` arguments. The arguments are provided as a variable number of parameters followed by `NULL`.

  成功したら呼び出しの結果を返し、失敗したら例外を送出し `NULL` を返します。

  これは次の Python の式と同等です: `callable(arg1, arg2, ...)` 。

PyObject* `PyObject_CallMethodObjArgs`(PyObject *obj, PyObject *name, ...)
  Return value: New reference.

  Calls a method of the Python object obj, where the name of the method is given as a Python string object in name. It is called with a variable number of `PyObject*` arguments. The arguments are provided as a variable number of parameters followed by `NULL`.

  成功したら呼び出しの結果を返し、失敗したら例外を送出し `NULL` を返します。

PyObject* `_PyObject_Vectorcall`(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

  Call a callable Python object callable, using `vectorcall` if possible.

  args is a C array with the positional arguments.

  nargsf is the number of positional arguments plus optionally the flag `PY_VECTORCALL_ARGUMENTS_OFFSET` (see below). To get actual number of arguments, use `PyVectorcall_NARGS(nargsf)`.

  kwnames can be either `NULL` (no keyword arguments) or a tuple of keyword names. In the latter case, the values of the keyword arguments are stored in args after the positional arguments. The number of keyword arguments does not influence nargsf.

  kwnames must contain only objects of type `str` (not a subclass), and all keys must be unique.

  成功したら呼び出しの結果を返し、失敗したら例外を送出し `NULL` を返します。

  This uses the vectorcall protocol if the callable supports it; otherwise, the arguments are converted to use `tp_call`.

  注釈

  This function is provisional and expected to become public in Python 3.9, with a different name and, possibly, changed semantics. If you use the function, plan for updating your code for Python 3.9.

  バージョン 3.8 で追加.

`PY_VECTORCALL_ARGUMENTS_OFFSET`

  If set in a vectorcall nargsf argument, the callee is allowed to temporarily change `args[-1]`. In other words, args points to argument 1 (not 0) in the allocated vector. The callee must restore the value of `args[-1]` before returning.

  Whenever they can do so cheaply (without additional allocation), callers are encouraged to use `PY_VECTORCALL_ARGUMENTS_OFFSET`. Doing so will allow callables such as bound methods to make their onward calls (which include a prepended self argument) cheaply.

  バージョン 3.8 で追加.

Py_ssize_t `PyVectorcall_NARGS`(size_t nargsf)

  Given a vectorcall nargsf argument, return the actual number of arguments. Currently equivalent to `nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET`.

  バージョン 3.8 で追加.

PyObject* `_PyObject_FastCallDict`(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

  Same as `_PyObject_Vectorcall()` except that the keyword arguments are passed as a dictionary in kwdict. This may be `NULL` if there are no keyword arguments.

  For callables supporting `vectorcall`, the arguments are internally converted to the vectorcall convention. Therefore, this function adds some overhead compared to `_PyObject_Vectorcall()`. It should only be used if the caller already has a dictionary ready to use.

  注釈

  This function is provisional and expected to become public in Python 3.9, with a different name and, possibly, changed semantics. If you use the function, plan for updating your code for Python 3.9.

  バージョン 3.8 で追加.

Py_hash_t `PyObject_Hash`(PyObject *o)

  オブジェクト o のハッシュ値を計算して返します。失敗すると `-1` を返します。 Python の式 `hash(o)` と同じです。

  バージョン 3.2 で変更: 返り値の型が Py_hash_t になりました。この型は、 Py_ssize_t と同じサイズをもつ符号付き整数です。

Py_hash_t `PyObject_HashNotImplemented`(PyObject *o)

  `type(o)` がハッシュ不可能であることを示す `TypeError` を設定し、 `-1` を返します。この関数は `tp_hash` スロットに格納されたときには特別な扱いを受け、その type がハッシュ不可能であることをインタプリタに明示的に示します。

int `PyObject_IsTrue`(PyObject *o)

  o が真を表すとみなせる場合には `1` を、そうでないときには `0` を返します。 Python の式 `not not o` と同じです。失敗すると `-1` を返します。

int `PyObject_Not`(PyObject *o)

  o が真を表すとみなせる場合には `0` を、そうでないときには `1` を返します。 Python の式 `not o` と同じです。失敗すると `-1` を返します。

PyObject* `PyObject_Type`(PyObject *o)
  Return value: New reference.

  When o is non-`NULL`, returns a type object corresponding to the object type of object o. On failure, raises `SystemError` and returns `NULL`. This is equivalent to the Python expression `type(o)`. This function increments the reference count of the return value. There's really no reason to use this function instead of the common expression `o->ob_type`, which returns a pointer of type `PyTypeObject*`, except when the incremented reference count is needed.

int `PyObject_TypeCheck`(PyObject *o, PyTypeObject *type)

  オブジェクト o が、 type か type のサブタイプであるときに真を返します。どちらのパラメタも `NULL` であってはなりません。

Py_ssize_t `PyObject_Size`(PyObject *o)
Py_ssize_t `PyObject_Length`(PyObject *o)

  o の長さを返します。ただしオブジェクト o がシーケンス型プロトコルとマップ型プロトコルの両方を提供している場合、シーケンスとしての長さを返します。エラーが生じると `-1` を返します。 Python の式 `len(o)` と同じです。

Py_ssize_t `PyObject_LengthHint`(PyObject *o, Py_ssize_t default)

  オブジェクト o の概算の長さを返します。 最初に実際の長さを、次に `__length_hint__()` を使って概算の長さを、そして最後にデフォルトの値を返そうとします。 この関数は Python の式 `operator.length_hint(o, default)` と同じです。

  バージョン 3.4 で追加.

PyObject* `PyObject_GetItem`(PyObject *o, PyObject *key)
  Return value: New reference.

  オブジェクト key に対応する o の要素を返します。失敗すると `NULL` を返します。Python の式 `o[key]` と同じです。

int `PyObject_SetItem`(PyObject *o, PyObject *key, PyObject *v)

  オブジェクト key を値 v に対応付けます。 失敗すると、例外を送出し `-1` を返します。成功すると `0` を返します。 これは Python の文 `o[key] = v` と同等です。 この関数は v への参照を 盗み取りません 。

int `PyObject_DelItem`(PyObject *o, PyObject *key)

  オブジェクト o から key に関する対応付けを削除します。失敗すると `-1` を返します。Python の文 `del o[key]` と同じです。

PyObject* `PyObject_Dir`(PyObject *o)
  Return value: New reference.

  この関数は Python の式 `dir(o)` と同じで、オブジェクトの変数名に割り当てている文字列からなるリスト (空の場合もあります) を返します。エラーの場合には `NULL` を返します。引数を `NULL` にすると、Python における `dir()` と同様に、現在のローカルな名前を返します; この場合、アクティブな実行フレームがなければ `NULL` を返しますが、 `PyErr_Occurred()` は偽を返します。

PyObject* `PyObject_GetIter`(PyObject *o)
  Return value: New reference.

  Python の式 `iter(o)` と同じです。引数にとったオブジェクトに対する新たなイテレータか、オブジェクトがすでにイテレータの場合にはオブジェクト自身を返します。オブジェクトが反復処理不可能であった場合には `TypeError` を送出して `NULL` を返します。