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

PyObject *Py_GetConstant(unsigned int constant_id)

次に属します: Stable ABI (バージョン 3.13 より).

定数への 強参照 を取得します。

constant_id が無効な場合、例外を設定して NULL を返します。

constant_id は次の定数識別子のいずれかでなければなりません。

定数識別子	値	返されるオブジェクト
Py_CONSTANT_NONE	0	None
Py_CONSTANT_FALSE	1	False
Py_CONSTANT_TRUE	2	True
Py_CONSTANT_ELLIPSIS	3	Ellipsis
Py_CONSTANT_NOT_IMPLEMENTED	4	NotImplemented
Py_CONSTANT_ZERO	5	0
Py_CONSTANT_ONE	6	1
Py_CONSTANT_EMPTY_STR	7	''
Py_CONSTANT_EMPTY_BYTES	8	b''
Py_CONSTANT_EMPTY_TUPLE	9	()

数値は、定数識別子を使えないプロジェクトのためにのみ示しています。

Added in version 3.13.

CPython では、これらの定数はすべて 不死 です。

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)

次に属します: Stable ABI (バージョン 3.13 より).

Py_GetConstant() と同様ですが、借用参照 を返します。

この関数は主に後方互換性を目的としています。 新しいコードでは Py_GetConstant() を使うことを推奨します。

参照はインタープリタから借用され、インタープリタがファイナライズされるまで有効です。

Added in version 3.13.

PyObject *Py_NotImplemented

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

Py_RETURN_NOTIMPLEMENTED

C 関数内から Py_NotImplemented を返す処理を適切に行います (つまり NotImplemented への新しい 強参照 を作成して返します)。

Py_PRINT_RAW

Flag to be used with multiple functions that print the object (like PyObject_Print() and PyFile_WriteObject()). If passed, these functions use the str() of the object instead of the repr().

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

オブジェクト o をファイル fp に出力します。 エラー時は -1 を返します。 flags 引数で出力オプションを有効にします。 現在サポートされるオプションは Py_PRINT_RAW のみで、指定するとオブジェクトの repr() 結果の代わりに str() 結果を書き出します。

int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)

次に属します: Stable ABI (バージョン 3.13 より).

o に attr_name 属性があれば 1、なければ 0 を返します。 Python の式 hasattr(o, attr_name) と同等です。 失敗すると -1 を返します。

Added in version 3.13.

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

次に属します: Stable ABI (バージョン 3.13 より).

PyObject_HasAttrWithError() と同じですが、attr_name は PyObject* ではなく、UTF-8 でエンコードされたバイト文字列を指す const char* で指定します。

Added in version 3.13.

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

次に属します: Stable ABI.

o に attr_name 属性があれば 1、なければ 0 を返します。 この関数は常に成功します。

注釈

__getattr__() メソッドや __getattribute__() メソッドの呼び出し中に発生した例外は伝播せず、sys.unraisablehook() に渡されます。 適切にエラーを処理するには、代わりに PyObject_HasAttrWithError()、PyObject_GetOptionalAttr()、PyObject_GetAttr() を使ってください。

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

次に属します: Stable ABI.

PyObject_HasAttr() と同じですが、attr_name は PyObject* ではなく、UTF-8 でエンコードされたバイト文字列を指す const char* で指定します。

注釈

Exceptions that occur when this calls __getattr__() and __getattribute__() methods or while creating the temporary str object are silently ignored. For proper error handling, use PyObject_HasAttrStringWithError(), PyObject_GetOptionalAttrString() or PyObject_GetAttrString() instead.

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)

戻り値: 新しい参照。 次に属します: Stable ABI.

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

属性がない場合を失敗として扱いたくなければ、代わりに PyObject_GetOptionalAttr() を使えます。

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)

戻り値: 新しい参照。 次に属します: Stable ABI.

PyObject_GetAttr() と同じですが、attr_name は PyObject* ではなく、UTF-8 でエンコードされたバイト文字列を指す const char* で指定します。

属性がない場合を失敗として扱いたくなければ、代わりに PyObject_GetOptionalAttrString() を使えます。

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);

次に属します: Stable ABI (バージョン 3.13 より).

属性が見つからなくても AttributeError を送出しない PyObject_GetAttr() の変種です。

属性が見つかった場合は 1 を返し、*result に属性への新しい 強参照 を設定します。 属性が見つからない場合は 0 を返し、*result に NULL を設定して、AttributeError を抑制します。 AttributeError 以外のエラーが発生した場合は -1 を返し、*result に NULL を設定します。

Added in version 3.13.

int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);

次に属します: Stable ABI (バージョン 3.13 より).

PyObject_GetOptionalAttr() と同じですが、attr_name は PyObject* ではなく、UTF-8 でエンコードされたバイト文字列を指す const char* で指定します。

Added in version 3.13.

PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)

戻り値: 新しい参照。 次に属します: Stable ABI.

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

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

次に属します: Stable ABI.

オブジェクト 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)

次に属します: Stable ABI.

PyObject_SetAttr() と同じですが、attr_name は PyObject* ではなく、UTF-8 でエンコードされたバイト文字列を指す const char* で指定します。

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

この関数に渡す属性名の種類は少数にとどめるべきです。 通常は、静的に割り当てた文字列を attr_name に使うことでそうします。 コンパイル時に分からない属性名には、PyUnicode_FromString() と PyObject_SetAttr() を直接呼び出すことを推奨します。 詳細は、キーオブジェクトを作成するために内部で使われる可能性のある PyUnicode_InternFromString() を参照してください。

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

次に属します: Stable ABI.

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

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)

次に属します: Stable ABI (バージョン 3.13 より).

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

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

次に属します: Stable ABI (バージョン 3.13 より).

PyObject_DelAttr() と同じですが、attr_name は PyObject* ではなく、UTF-8 でエンコードされたバイト文字列を指す const char* で指定します。

この関数に渡す属性名の種類は少数にとどめるべきです。 通常は、静的に割り当てた文字列を attr_name に使うことでそうします。 コンパイル時に分からない属性名には、PyUnicode_FromString() と PyObject_DelAttr() を直接呼び出すことを推奨します。 詳細は、検索用のキーオブジェクトを作成するために内部で使われる可能性のある PyUnicode_InternFromString() を参照してください。

PyObject *PyObject_GenericGetDict(PyObject *o, void *context)

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.10 より).

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

オブジェクト o の __dict__ を取得するためにこの関数を呼び出すこともできます。 その場合は context に NULL を渡してください。 この関数は辞書のメモリを割り当てる必要がある場合があるため、オブジェクトの属性にアクセスするなら PyObject_GetAttr() の方が効率的なことがあります。

失敗すると例外を設定して NULL を返します。

Added in version 3.3.

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

次に属します: Stable ABI (バージョン 3.7 より).

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

Added in version 3.3.

PyObject **_PyObject_GetDictPtr(PyObject *obj)

オブジェクト obj の __dict__ へのポインタを返します。 __dict__ がない場合は、例外を設定せずに NULL を返します。

この関数は辞書のメモリを割り当てる必要がある場合があるため、オブジェクトの属性にアクセスするなら PyObject_GetAttr() の方が効率的なことがあります。

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

戻り値: 新しい参照。 次に属します: Stable ABI.

opid で指定された演算を使って o1 と o2 の値を比較します。 opid は Py_LT、Py_LE、Py_EQ、Py_NE、Py_GT、Py_GE のいずれかで、それぞれ <、<=、==、!=、>、>= に対応します。 これは、op を opid に対応する演算子とした Python の式 o1 op o2 と同等です。 成功すると比較の結果を返し、失敗すると NULL を返します。

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

次に属します: Stable ABI.

PyObject_RichCompare() と同様に、opid で指定された演算を使って o1 と o2 の値を比較します。 ただし、エラー時は -1、結果が偽なら 0、それ以外は 1 を返します。

注釈

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

PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)

次に属します: Stable ABI.

format_spec を使って obj を書式化します。 Python の式 format(obj, format_spec) と同等です。

format_spec は NULL にできます。 その場合は format(obj) と同等です。 成功すると書式化された文字列を返し、失敗すると NULL を返します。

PyObject *PyObject_Repr(PyObject *o)

戻り値: 新しい参照。 次に属します: Stable ABI.

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

If argument is NULL, return the string '<NULL>'.

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

PyObject *PyObject_ASCII(PyObject *o)

戻り値: 新しい参照。 次に属します: Stable ABI.

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

If argument is NULL, return the string '<NULL>'.

PyObject *PyObject_Str(PyObject *o)

戻り値: 新しい参照。 次に属します: Stable ABI.

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

If argument is NULL, return the string '<NULL>'.

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

PyObject *PyObject_Bytes(PyObject *o)

戻り値: 新しい参照。 次に属します: Stable ABI.

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

If argument is NULL, return the bytes object b'<NULL>'.

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)

次に属します: Stable ABI.

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

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

If cls has a __subclasscheck__() method, it will be called to determine the subclass status as described in PEP 3119. Otherwise, derived is a subclass of cls if it is a direct or indirect subclass, i.e. contained in cls.__mro__.

通常はクラスオブジェクト、つまり type またはその派生クラスのインスタンスだけがクラスとみなされます。 ただし、オブジェクトに __bases__ 属性 (基底クラスのタプルでなければなりません) を持たせることで、この判定を変えられます。

int PyObject_IsInstance(PyObject *inst, PyObject *cls)

次に属します: Stable ABI.

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

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

cls に __instancecheck__() メソッドがある場合、PEP 3119 に従って判定するためにこのメソッドが呼び出されます。 そうでなければ、inst のクラスが cls のサブクラスである場合に、inst は cls のインスタンスとみなされます。

インスタンス inst は __class__ 属性を持つことで、自分のクラスとみなされるものを変更できます。

オブジェクト cls は __bases__ 属性 (基底クラスのタプルでなければなりません) を持つことで、クラスとみなされるかどうか、および基底クラスを変更できます。

Py_hash_t PyObject_Hash(PyObject *o)

次に属します: Stable ABI.

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

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

Py_hash_t PyObject_HashNotImplemented(PyObject *o)

次に属します: Stable ABI.

type(o) が ハッシュ可能 でないことを示す TypeError を設定し、-1 を返します。 この関数を tp_hash スロットに設定すると特別に扱われ、ハッシュ可能でないことを型からインタープリタに明示できます。

int PyObject_IsTrue(PyObject *o)

次に属します: Stable ABI.

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

int PyObject_Not(PyObject *o)

次に属します: Stable ABI.

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

PyObject *PyObject_Type(PyObject *o)

戻り値: 新しい参照。 次に属します: Stable ABI.

o が NULL でない場合、オブジェクト o の型に対応する型オブジェクトを返します。 失敗すると SystemError を送出して NULL を返します。 Python の式 type(o) と同等です。 この関数は戻り値への新しい 強参照 を作成します。 新しい 強参照 が必要な場合を除き、PyTypeObject* 型のポインタを返す Py_TYPE() 関数の代わりにこの関数を使う理由はありません。

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

オブジェクト o の型が type またはそのサブタイプであればゼロ以外、そうでなければ 0 を返します。 どちらの引数も NULL であってはいけません。

Py_ssize_t PyObject_Size(PyObject *o)

Py_ssize_t PyObject_Length(PyObject *o)

次に属します: Stable ABI.

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

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)

オブジェクト o の推定の長さを返します。 まず実際の長さを返すことを試み、次に __length_hint__() による推定値を試み、最後にデフォルト値を返します。 エラー時は -1 を返します。 Python の式 operator.length_hint(o, defaultvalue) と同等です。

Added in version 3.4.

PyObject *PyObject_GetItem(PyObject *o, PyObject *key)

戻り値: 新しい参照。 次に属します: Stable ABI.

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

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

次に属します: Stable ABI.

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

int PyObject_DelItem(PyObject *o, PyObject *key)

次に属します: Stable ABI.

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

int PyObject_DelItemString(PyObject *o, const char *key)

次に属します: Stable ABI.

PyObject_DelItem() と同じですが、key は PyObject* ではなく、UTF-8 でエンコードされたバイト文字列を指す const char* で指定します。

PyObject *PyObject_Dir(PyObject *o)

戻り値: 新しい参照。 次に属します: Stable ABI.

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

PyObject *PyObject_GetIter(PyObject *o)

戻り値: 新しい参照。 次に属します: Stable ABI.

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

PyObject *PyObject_SelfIter(PyObject *obj)

戻り値: 新しい参照。 次に属します: Stable ABI.

Python の __iter__(self): return self メソッドと同等です。 イテレータ 型の PyTypeObject.tp_iter スロットに使うことを想定しています。

PyObject *PyObject_GetAIter(PyObject *o)

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.10 より).

Python の式 aiter(o) と同等です。 AsyncIterable オブジェクトを受け取り、それに対する AsyncIterator を返します。 通常は新しいイテレータですが、引数が AsyncIterator の場合はそれ自身を返します。 オブジェクトを反復処理できない場合は TypeError を送出して NULL を返します。

Added in version 3.10.

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)

次に属します: Stable ABI (バージョン 3.12 より).

cls 用に確保されたサブクラス固有のデータへのポインタを取得します。

オブジェクト o は cls のインスタンスでなければならず、cls は負の PyType_Spec.basicsize を使って作成されていなければなりません。 Python はこれを検証しません。

エラー時には例外を設定して NULL を返します。

Added in version 3.12.

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)

次に属します: Stable ABI (バージョン 3.12 より).

cls 用に確保されたインスタンスのメモリ領域のサイズ、つまり PyObject_GetTypeData() が返すメモリのサイズを返します。

このサイズは -PyType_Spec.basicsize で要求したサイズより大きい場合があります。 その大きいサイズを使っても安全です (例えば memset() で使えます)。

型 cls は負の PyType_Spec.basicsize を使って作成されて いなければなりません。 Python はこれを検証しません。

エラー時は例外を設定して負の値を返します。

Added in version 3.12.

void *PyObject_GetItemData(PyObject *o)

Py_TPFLAGS_ITEMS_AT_END が設定されたクラスの、要素ごとのデータへのポインタを取得します。

エラー時は例外を設定して NULL を返します。 o に Py_TPFLAGS_ITEMS_AT_END が設定されていない場合は TypeError を送出します。

Added in version 3.12.

int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)

obj のマネージド辞書を巡回します。

この関数は Py_TPFLAGS_MANAGED_DICT フラグが設定された型の巡回関数内でのみ呼び出さなければなりません。

Added in version 3.13.

void PyObject_ClearManagedDict(PyObject *obj)

obj のマネージド辞書をクリアします。

This function must only be called in a clear function of the type which has the Py_TPFLAGS_MANAGED_DICT flag set.

Added in version 3.13.