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

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) と同じです。この関数は常に成功します。

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

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

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)

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

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

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

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

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

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

vNULL の場合は属性が削除されますが、この機能は非推奨であり 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)

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

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

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

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

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

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

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

注釈

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

int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)

o1o2 の値を比較します。このとき o1 が比較ルーチンを持っていればそれを使い、なければ o2 のルーチンを使います。比較結果は result に返されます。失敗すると -1 を返します。 Python 文 result = cmp(o1, o2) と同じです。

int PyObject_Compare(PyObject *o1, PyObject *o2)

o1o2 の値を比較します。このとき o1 が比較ルーチンを持っていればそれを使い、なければ o2 のルーチンを使います。成功すると比較結果を返します。エラーが生じた場合の戻り値は未定義です; PyErr_Occurred() を使ってエラー検出を行って下さい。Python 式 cmp(o1, o2) と同じです。

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

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

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

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

PyObject* PyObject_Bytes(PyObject *o)

o オブジェクトの bytes 表現を計算します。 2.x では、単なる PyObject_Str() のエイリアスです。

PyObject* PyObject_Unicode(PyObject *o)
Return value: New reference.

o の Unicode 文字列表現を計算します。成功すると Unicode 文字列表現を返し失敗すると NULL を返します。 Python 式 unicode(o) と同じです。この関数は組み込み関数 unicode() の処理で呼び出されます。

int PyObject_IsInstance(PyObject *inst, PyObject *cls)

instcls のインスタンスか、 cls のサブクラスのインスタンスの場合に 1 を返し、そうでなければ 0 を 返します。 エラーの時には -1 を返し、例外をセットします。 cls がクラスオブジェクトではなく型オブジェクトの場合、 PyObject_IsInstance()instcls であるときに 1 を返します。 cls をタプルで指定した場合、 cls に指定した全てのエントリについてチェックを行います。 少なくとも一つのエントリに対するチェックが 1 を返せば結果は 1 になり、そうでなければ 0 になります。 inst がクラスインスタンスでなく、かつ cls が 型オブジェクトでもクラスオブジェクトでもタプルでもない場合、 inst には __class__ 属性がなくてはなりません

バージョン 2.1 で追加.

バージョン 2.2 で変更: 二つ目の引数にタプルのサポートを追加しました。

サブクラスの決定はかなり素直な方法で行いますが、クラスシステムの拡張を実装する人たちに知っておいて欲しいちょっとした問題点があります。 AB がクラスオブジェクトの場合、 BA のサブクラスとなるのは、 BA を直接的あるいは間接的に継承 (inherit) している場合です。 両方がクラスオブジェクトでない場合、二つのオブジェクト間のクラス関係を決めるには、より汎用的な機構を使います。 BA のサブクラスであるか調べたとき、 AB と等しければ、 PyObject_IsSubclass() は真を返します。 A および B が異なるオブジェクトなら、 B__bases__ 属性から深さ優先探索 (depth-first search)で A を探索します

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)

クラス derivedcls と同じクラスか、 cls の派生クラスの場合に 1 を返し、それ以外の場合には 0 を返します。エラーが生じると -1 を返します。 cls をタプルで指定した場合、 cls に指定した全てのエントリについてチェックを行います。少なくとも一つのエントリに対するチェックが 1 を返せば結果は 1 になり、そうでなければ 0 になります。 derived または cls のいずれかが実際のクラスオブジェクト (あるいはタプル) でない場合、上で述べた汎用アルゴリズムを使います。

バージョン 2.1 で追加.

バージョン 2.3 で変更: 以前の Python のバージョンは、二つ目の引数にタプルをサポートしていませんでした。

int PyCallable_Check(PyObject *o)

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

PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
Return value: New reference.

呼び出し可能な Python オブジェクト callable_object をタプルで指定された引数 args および辞書で指定された名前つき引数 (named argument) kw とともに呼び出します。名前つき引数を必要としない場合、 kwNULL にしてもかまいません。 argsNULL であってはなりません。引数が全く必要ない場合には空のタプルを使ってください。成功すると呼び出し結果として得られたオブジェクトを返し、失敗すると NULL を返します。 Python の式 apply(callable_object, args, kw) あるいは callable_object(*args, **kw) と同じです。

バージョン 2.2 で追加.

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

呼び出し可能な Python オブジェクト callable_object をタプルで指定された引数 args とともに呼び出します。 引数を必要としない場合、 argsNULL にしてもかまいません。成功すると呼び出し結果として得られたオブジェクトを返し、失敗すると NULL を返します。 Python の式 apply(callable_object, args) あるいは callable_object(*args) と同じです。

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

呼び出し可能な Python オブジェクト callable_object を可変数個の C 引数とともに呼び出します。C 引数は Py_BuildValue() 形式のフォーマット文字列を使って記述します。 formatNULL にしてもよく、与える引数がないことを表します。成功すると呼び出し結果として得られたオブジェクトを返し、失敗すると NULL を返します。 Python の式 apply(callable, args) あるいは callable(*args) と同じです。もしも、 PyObject * args だけを引数に渡す場合は、 PyObject_CallFunctionObjArgs() がより速い方法であることを覚えておいてください。

PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)
Return value: New reference.

オブジェクト omethod という名前のメソッドを、可変数個の C 引数とともに呼び出します。C 引数はタプルを生成するような Py_BuildValue() 形式のフォーマット文字列を使って記述します。 formatNULL にしてもよく、与える引数がないことを表します。成功すると呼び出し結果として得られたオブジェクトを返し、失敗すると NULL を返します。 Python の式 o.method(args) と同じです。もしも、 PyObject * args だけを引数に渡す場合は、 PyObject_CallMethodObjArgs() がより速い方法であることを覚えておいてください。

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

呼び出し可能な Python オブジェクト callable を可変数個の PyObject* 引数とともに呼び出します。引数列は末尾に NULL がついた可変数個のパラメタとして与えます。成功すると呼び出し結果として得られたオブジェクトを返し失敗すると NULL を返します。

バージョン 2.2 で追加.

PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
Return value: New reference.

オブジェクト o のメソッドを呼び出します、メソッド名は Python 文字列オブジェクト name で与えます。可変数個の PyObject* 引数と共に呼び出されます. 引数列は末尾に NULL がついた可変数個のパラメタとして与えます。成功すると呼び出し結果として得られたオブジェクトを返し失敗すると NULL を返します。

バージョン 2.2 で追加.

long PyObject_Hash(PyObject *o)

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

long PyObject_HashNotImplemented(PyObject *o)

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

バージョン 2.6 で追加.

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.

oNULL でない場合、オブジェクト o のオブジェクト型に相当する型オブジェクトを返します。失敗すると SystemError を送出して NULL を返します。 Python の式 type(o) と同じです。 この関数は戻り値の参照カウントをインクリメントします。参照カウントのインクリメントが必要でない限り、広く使われていて PyTypeObject* 型のポインタを返す表記法 o->ob_type の代わりに使う理由は全くありません。

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

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

バージョン 2.2 で追加.

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

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

バージョン 2.5 で変更: これらの関数は以前は int を返していました。この変更により、 64bit システムを正しくサポートするには修正が必要になります。

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 と同じです。

int PyObject_DelItem(PyObject *o, PyObject *key)

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

int PyObject_AsFileDescriptor(PyObject *o)

Python オブジェクトからファイル記述子を取り出します。オブジェクトが整数か長整数なら、その値を返します。 (長)整数でない場合、オブジェクトに fileno() メソッドがあれば呼び出します; この場合、 fileno() メソッドは整数または長整数をファイル記述子の値として返さなければなりません。失敗すると -1 を返します。

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 を返します。