オブジェクトプロトコル (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¶: オブジェクトを出力する複数の関数 (PyObject_Print() や PyFile_WriteObject() など) で使うフラグです。このフラグを渡すと、これらの関数はオブジェクトの repr() 結果の代わりに str() 結果を使います。

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

void PyObject_Dump(PyObject *op)¶

オブジェクト op を stderr にダンプします。デバッグのためにのみ使ってください。

メモリが破損した後でもオブジェクトのダンプを試みられるように、次のように出力します。

アクセス時にクラッシュする可能性が最も低いフィールドから順に情報を書き出します。
この関数はアタッチされたスレッド状態がなくても呼び出せますが、デッドロックを引き起こす可能性があるため推奨されません。
現在のインタープリタに属さないオブジェクトもダンプできますが、クラッシュや意図しない動作を引き起こす可能性があります。
オブジェクトのメモリが解放済みかどうかを検出するヒューリスティックを実装しています。解放済みと判断した場合は、内容を表示せず、メモリアドレスだけを表示します。
出力形式はいつでも変更される可能性があります。

出力例:

object address  : 0x7f80124702c0
object refcount : 2
object type     : 0x9902e0
object type name: str
object repr     : 'abcdef'

Added in version 3.15.

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() のため、非推奨となっていますが、削除される予定はありません。

例外が設定されているときに、v を NULL にしてこの関数を呼び出してはいけません。 NULL チェックを忘れるとこの状態になることがあり、属性が削除されてしまいます。

バージョン 3.15 で変更: 例外が設定されている場合、値を NULL にして呼び出してはいけません。

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() を使うのが望ましいです。

例外が設定されているときに、v を NULL にしてこの関数を呼び出してはいけません。 NULL チェックを忘れるとこの状態になることがあり、属性が削除されてしまいます。

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

バージョン 3.15 で変更: 例外が設定されている場合、値を NULL にして呼び出してはいけません。

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() の処理で呼び出されます。

引数が NULL の場合は文字列 '<NULL>' を返します。

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

PyObject *PyObject_ASCII(PyObject *o)¶

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

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

引数が NULL の場合は文字列 '<NULL>' を返します。

PyObject *PyObject_Str(PyObject *o)¶

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

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

引数が NULL の場合は文字列 '<NULL>' を返します。

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

PyObject *PyObject_Bytes(PyObject *o)¶

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

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

引数が NULL の場合は bytes オブジェクト 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 のマネージド辞書をクリアします。

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

Added in version 3.13.

int PyUnstable_Object_EnableDeferredRefcount(PyObject *obj)¶

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

ランタイムが対応していれば、obj の遅延参照カウントを有効にします。フリースレッドビルドでは、インタープリタが obj の参照カウントの更新を省略できるため、マルチスレッドの性能が向上する可能性があります。その代わり、obj はインタープリタからの参照がなくなった時点では解放されず、トレーシングガベージコレクタによってのみ解放されるようになります。

obj の遅延参照カウントが有効になった場合は 1 を返します。遅延参照カウントがサポートされていない場合や、すでに obj で有効になっている場合など、インタープリタがヒントを無視した場合は 0 を返します。この関数はスレッドセーフで、失敗しません。

GIL が有効なビルドは遅延参照カウントをサポートしないため、この関数は何もしません。 obj がガベージコレクタの追跡対象でない場合も何もしません (gc.is_tracked() と PyObject_GC_IsTracked() を参照)。

この関数は、オブジェクトを作成するコード (例えば tp_new スロット) から、obj を作成した直後に呼び出すことを想定しています。

Added in version 3.14.

int PyUnstable_Object_IsUniqueReferencedTemporary(PyObject *obj)¶

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

obj が唯一の参照を持つ一時オブジェクトかどうかを調べます。そうであると分かる場合は 1、それ以外の場合は 0 を返します。この関数は失敗しませんが、判定は保守的なので、実際に唯一の参照を持つ一時オブジェクトでも 0 を返すことがあります。

オブジェクトが唯一の参照を持つ一時オブジェクトであれば、現在のコードがそのオブジェクトへの唯一の参照を持つことが保証されます。 C 関数の引数については、参照カウントが 1 かどうかを調べる代わりにこの関数を使うべきです。 Python 3.14 以降、インタープリタはオペランドスタックにオブジェクトを読み込むとき、可能であれば参照を借用して一部の参照カウントの変更を省略します。このため、参照カウントが 1 というだけでは、関数の引数への参照が唯一であることは保証されません。

次の例では、my_func に渡される引数は唯一の参照を持つ一時オブジェクトです。

my_func([1, 2, 3])

次の例では、参照カウントが 1 であっても、my_func に渡される引数は唯一の参照を持つ一時オブジェクトでは ありません。

my_list = [1, 2, 3]
my_func(my_list)

Py_REFCNT() 関数も参照してください。

Added in version 3.14.

int PyUnstable_IsImmortal(PyObject *obj)¶: これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

obj が不死の場合はゼロ以外、そうでなければゼロを返します。この関数は失敗しません。

注釈

ある CPython バージョンで不死のオブジェクトが、別のバージョンでも不死であるとは限りません。

Added in version 3.14.

int PyUnstable_TryIncRef(PyObject *obj)¶

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

obj の参照カウントがゼロでなければ、参照カウントを増やします。増やすことに成功した場合は 1、それ以外の場合は 0 を返します。

obj に対してあらかじめ PyUnstable_EnableTryIncRef() を呼び出しておく必要があります。そうしなければ、フリースレッドビルドでは誤って 0 を返す場合があります。

この関数は論理的には次の C コードと同等ですが、フリースレッドビルドではアトミックに動作します。

if (Py_REFCNT(op) > 0) {
   Py_INCREF(op);
   return 1;
}
return 0;

これは、Python の弱参照オブジェクトのオーバーヘッドなしで弱参照を管理するための基礎として使うことを想定しています。

通常、この関数を正しく使うには obj の解放関数 (tp_dealloc) によるサポートが必要です。例えば、次の概略コードを応用すると、特定の型に対して WeakValueDictionary のように動作する「weakmap」を実装できます。

PyMutex mutex;

PyObject *
add_entry(weakmap_key_type *key, PyObject *value)
{
    PyUnstable_EnableTryIncRef(value);
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_add_entry(weakmap, key, value);
    PyMutex_Unlock(&mutex);
    Py_RETURN_NONE;
}

PyObject *
get_value(weakmap_key_type *key)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    PyObject *result = weakmap_find(weakmap, key);
    if (PyUnstable_TryIncRef(result)) {
        // `result` は安全に使える
        PyMutex_Unlock(&mutex);
        return result;
    }
    // ここに到達した場合、`result` のガベージコレクションが始まっているが、
    // まだ weakmap からは削除されていない
    PyMutex_Unlock(&mutex);
    return NULL;
}

// weakmap の値の tp_dealloc 関数
void
value_dealloc(PyObject *value)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_remove_value(weakmap, value);

    ...
    PyMutex_Unlock(&mutex);
}

Added in version 3.14.

void PyUnstable_EnableTryIncRef(PyObject *obj)¶: これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

obj に対して後で PyUnstable_TryIncRef() を使えるようにします。呼び出し時に、呼び出し側は obj への強参照を保持していなければなりません。

Added in version 3.14.

int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)¶

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

op への参照が 1 つだけかどうかを調べます。

GIL が有効なビルドでは、この関数は Py_REFCNT(op) == 1 と同等です。

フリースレッドビルドでは、op の参照カウントが 1 かどうかに加えて、op がこのスレッドだけで使われているかどうかも調べます。 Py_REFCNT(op) == 1 はフリースレッドビルドではスレッドセーフでは ありません。代わりにこの関数を使うことを推奨します。

この関数は Python インタープリタを呼び出しませんが、呼び出し側はアタッチされたスレッド状態を保持していなければなりません。この関数は失敗しません。

Added in version 3.14.

int PyUnstable_SetImmortal(PyObject *op)¶

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

オブジェクト op を不死にします。引数のオブジェクトへの参照は、呼び出し元スレッドが唯一の参照として保持している必要があります。これはフリースレッドビルドで、スレッド間で共有するオブジェクトの参照カウントを巡る競合を減らすために使うことを想定しています。

この処理は一方向です。オブジェクトを不死にすることはできますが、再び有限の寿命を持つようには戻せません。不死のオブジェクトは参照カウントの対象にならず、ガベージコレクションで回収されることもありません。 GC の追跡対象になっている場合は、追跡対象から外されます。

この関数は、オブジェクトを作成するコード (例えば tp_new スロット) から、op を作成した直後に呼び出すことを想定しています。オブジェクトが不死になった場合は 1、ならなかった場合は 0 を返します。この関数は失敗しません。

Added in version 3.15.

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

前のトピックへ

次のトピックへ

このページ