オブジェクトプロトコル (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 を返します。