This document is for an old version of Python that is no longer supported. You should upgrade and read the Python documentation for the current stable release.

# オブジェクトプロトコル (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)

  オブジェクト 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_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` を返します。

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

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

int `PyObject_Compare`(PyObject *o1, PyObject *o2)

  o1 と o2 の値を比較します。このとき 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)

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

  バージョン 2.1 で追加.

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

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

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

  クラス derived が cls と同じクラスか、 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 とともに呼び出します。名前つき引数を必要としない場合、 kw を NULL にしてもかまいません。 args は NULL であってはなりません。引数が全く必要ない場合には空のタプルを使ってください。成功すると呼び出し結果として得られたオブジェクトを返し、失敗すると 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 とともに呼び出します。 引数を必要としない場合、 args を NULL にしてもかまいません。成功すると呼び出し結果として得られたオブジェクトを返し、失敗すると 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()` 形式のフォーマット文字列を使って記述します。 format は NULL にしてもよく、与える引数がないことを表します。成功すると呼び出し結果として得られたオブジェクトを返し、失敗すると NULL を返します。 Python の式 `apply(callable, args)` あるいは `callable(*args)` と同じです。もしも、 `PyObject *` args だけを引数に渡す場合は、 `PyObject_CallFunctionObjArgs()` がより速い方法であることを覚えておいてください。

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

  オブジェクト o の method という名前のメソッドを、可変数個の C 引数とともに呼び出します。C 引数はタプルを生成するような `Py_BuildValue()` 形式のフォーマット文字列を使って記述します。 format は NULL にしてもよく、与える引数がないことを表します。成功すると呼び出し結果として得られたオブジェクトを返し、失敗すると 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.

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

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

  オブジェクト o が、 type か type のサブタイプであるときに真を返します。どちらのパラメタも 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 を返します。