型オブジェクト

新スタイルの型を定義する構造体: PyTypeObject 構造体は、おそらく Python オブジェクトシステムの中で最も重要な構造体の1つでしょう。型オブジェクトは PyObject_*() 系や PyType_*() 系の関数で扱えますが、ほとんどの Python アプリケーションにとって、さして面白みのある機能を提供しません。型オブジェクトはオブジェクトがどのように振舞うかを決める基盤ですから、インタプリタ自体や新たな型を定義する拡張モジュールでは非常に重要な存在です。

型オブジェクトは標準の型 (standard type) に比べるとかなり大きな構造体です。各型オブジェクトは多くの値を保持しており、そのほとんどは C 関数へのポインタで、それぞれの関数はその型の機能の小さい部分を実装しています。この節では、型オブジェクトの各フィールドについて詳細を説明します。各フィールドは、構造体内で出現する順番に説明されています。

In addition to the following quick reference, the 使用例 section provides at-a-glance insight into the meaning and use of PyTypeObject.

Quick Reference

"tp slots"

PyTypeObject Slot 1

Type

special methods/attrs

Info 2

O

T

D

I

<R> tp_name

const char *

__name__

X

X

tp_basicsize

Py_ssize_t

X

X

X

tp_itemsize

Py_ssize_t

X

X

tp_dealloc

destructor

X

X

X

tp_vectorcall_offset

Py_ssize_t

?

(tp_getattr)

getattrfunc

__getattribute__, __getattr__

G

(tp_setattr)

setattrfunc

__setattr__, __delattr__

G

tp_as_async

PyAsyncMethods *

sub-slots

%

tp_repr

reprfunc

__repr__

X

X

X

tp_as_number

PyNumberMethods *

sub-slots

%

tp_as_sequence

PySequenceMethods *

sub-slots

%

tp_as_mapping

PyMappingMethods *

sub-slots

%

tp_hash

hashfunc

__hash__

X

G

tp_call

ternaryfunc

__call__

X

X

tp_str

reprfunc

__str__

X

X

tp_getattro

getattrofunc

__getattribute__, __getattr__

X

X

G

tp_setattro

setattrofunc

__setattr__, __delattr__

X

X

G

tp_as_buffer

PyBufferProcs *

%

tp_flags

unsigned long

X

X

?

tp_doc

const char *

__doc__

X

X

tp_traverse

traverseproc

X

G

tp_clear

inquiry

X

G

tp_richcompare

richcmpfunc

__lt__, __le__, __eq__, __ne__, __gt__, __ge__

X

G

tp_weaklistoffset

Py_ssize_t

X

?

tp_iter

getiterfunc

__iter__

X

tp_iternext

iternextfunc

__next__

X

tp_methods

PyMethodDef []

X

X

tp_members

PyMemberDef []

X

tp_getset

PyGetSetDef []

X

X

tp_base

PyTypeObject *

__base__

X

tp_dict

PyObject *

__dict__

?

tp_descr_get

descrgetfunc

__get__

X

tp_descr_set

descrsetfunc

__set__, __delete__

X

tp_dictoffset

Py_ssize_t

X

?

tp_init

initproc

__init__

X

X

X

tp_alloc

allocfunc

X

?

?

tp_new

newfunc

__new__

X

X

?

?

tp_free

freefunc

X

X

?

?

tp_is_gc

inquiry

X

X

<tp_bases>

PyObject *

__bases__

~

<tp_mro>

PyObject *

__mro__

~

[tp_cache]

PyObject *

[tp_subclasses]

PyObject *

__subclasses__

[tp_weaklist]

PyObject *

(tp_del)

destructor

[tp_version_tag]

unsigned int

tp_finalize

destructor

__del__

X

If COUNT_ALLOCS is defined then the following (internal-only) fields exist as well:

1

A slot name in parentheses indicates it is (effectively) deprecated. Names in angle brackets should be treated as read-only. Names in square brackets are for internal use only. "<R>" (as a prefix) means the field is required (must be non-NULL).

2

Columns:

"O": set on PyBaseObject_Type

"T": set on PyType_Type

"D": default (if slot is set to NULL)

X - PyType_Ready sets this value if it is NULL
~ - PyType_Ready always sets this value (it should be NULL)
? - PyType_Ready may set this value depending on other slots

Also see the inheritance column ("I").

"I": inheritance

X - type slot is inherited via PyType_Ready if defined with a NULL value
% - the slots of the sub-struct are inherited individually
G - inherited, but only in combination with other slots; see the slot's description
? - it's complicated; see the slot's description

Note that some slots are effectively inherited through the normal attribute lookup chain.

sub-slots

Slot

Type

special methods

am_await

unaryfunc

__await__

am_aiter

unaryfunc

__aiter__

am_anext

unaryfunc

__anext__

nb_add

binaryfunc

__add__ __radd__

nb_inplace_add

binaryfunc

__iadd__

nb_subtract

binaryfunc

__sub__ __rsub__

nb_inplace_subtract

binaryfunc

__sub__

nb_multiply

binaryfunc

__mul__ __rmul__

nb_inplace_multiply

binaryfunc

__mul__

nb_remainder

binaryfunc

__mod__ __rmod__

nb_inplace_remainder

binaryfunc

__mod__

nb_divmod

binaryfunc

__divmod__ __rdivmod__

nb_power

ternaryfunc

__pow__ __rpow__

nb_inplace_power

ternaryfunc

__pow__

nb_negative

unaryfunc

__neg__

nb_positive

unaryfunc

__pos__

nb_absolute

unaryfunc

__abs__

nb_bool

inquiry

__bool__

nb_invert

unaryfunc

__invert__

nb_lshift

binaryfunc

__lshift__ __rlshift__

nb_inplace_lshift

binaryfunc

__lshift__

nb_rshift

binaryfunc

__rshift__ __rrshift__

nb_inplace_rshift

binaryfunc

__rshift__

nb_and

binaryfunc

__and__ __rand__

nb_inplace_and

binaryfunc

__and__

nb_xor

binaryfunc

__xor__ __rxor__

nb_inplace_xor

binaryfunc

__xor__

nb_or

binaryfunc

__or__ __ror__

nb_inplace_or

binaryfunc

__or__

nb_int

unaryfunc

__int__

nb_reserved

void *

nb_float

unaryfunc

__float__

nb_floor_divide

binaryfunc

__floordiv__

nb_inplace_floor_divide

binaryfunc

__floordiv__

nb_true_divide

binaryfunc

__truediv__

nb_inplace_true_divide

binaryfunc

__truediv__

nb_index

unaryfunc

__index__

nb_matrix_multiply

binaryfunc

__matmul__ __rmatmul__

nb_inplace_matrix_multiply

binaryfunc

__matmul__

mp_length

lenfunc

__len__

mp_subscript

binaryfunc

__getitem__

mp_ass_subscript

objobjargproc

__setitem__, __delitem__

sq_length

lenfunc

__len__

sq_concat

binaryfunc

__add__

sq_repeat

ssizeargfunc

__mul__

sq_item

ssizeargfunc

__getitem__

sq_ass_item

ssizeobjargproc

__setitem__ __delitem__

sq_contains

objobjproc

__contains__

sq_inplace_concat

binaryfunc

__iadd__

sq_inplace_repeat

ssizeargfunc

__imul__

bf_getbuffer

getbufferproc()

bf_releasebuffer

releasebufferproc()

PyTypeObject Definition

PyTypeObject の構造体定義は Include/object.h で見つけられるはずです。参照の手間を省くために、ここでは定義を繰り返します:

typedef struct _typeobject {
    PyObject_VAR_HEAD
    const char *tp_name; /* For printing, in format "<module>.<name>" */
    Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    Py_ssize_t tp_vectorcall_offset;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
                                    or tp_reserved (Python 3) */
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    unsigned long tp_flags;

    const char *tp_doc; /* Documentation string */

    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    Py_ssize_t tp_weaklistoffset;

    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    Py_ssize_t tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6 */
    unsigned int tp_version_tag;

    destructor tp_finalize;

} PyTypeObject;

PyObject Slots

型オブジェクト構造体は PyVarObject 構造体を拡張したものです。 ob_size フィールドは、(通常 class 文が呼び出す type_new() で生成される) 動的な型に使います。 PyType_Type (メタタイプ) は tp_itemsize を初期化するので注意してください。すなわち、 インスタンス (つまり型オブジェクト) には ob_size フィールドが存在しなければ なりません

PyObject* PyObject._ob_next
PyObject* PyObject._ob_prev

These fields are only present when the macro Py_TRACE_REFS is defined. Their initialization to NULL is taken care of by the PyObject_HEAD_INIT macro. For statically allocated objects, these fields always remain NULL. For dynamically allocated objects, these two fields are used to link the object into a doubly-linked list of all live objects on the heap. This could be used for various debugging purposes; currently the only use is to print the objects that are still alive at the end of a run when the environment variable PYTHONDUMPREFS is set.

Inheritance:

サブタイプはこのフィールドを継承しません。

Py_ssize_t PyObject.ob_refcnt

型オブジェクトの参照カウントで、 PyObject_HEAD_INIT はこの値を 1 に初期化します。静的にメモリ確保された型オブジェクトでは、型のインスタンス (ob_type が該当する型を指しているオブジェクト) は参照をカウントする対象には なりません 。動的にメモリ確保される型オブジェクトの場合、インスタンスは参照カウントの対象に なります

Inheritance:

サブタイプはこのフィールドを継承しません。

PyTypeObject* PyObject.ob_type

This is the type's type, in other words its metatype. It is initialized by the argument to the PyObject_HEAD_INIT macro, and its value should normally be &PyType_Type. However, for dynamically loadable extension modules that must be usable on Windows (at least), the compiler complains that this is not a valid initializer. Therefore, the convention is to pass NULL to the PyObject_HEAD_INIT macro and to initialize this field explicitly at the start of the module's initialization function, before doing anything else. This is typically done like this:

Foo_Type.ob_type = &PyType_Type;

This should be done before any instances of the type are created. PyType_Ready() checks if ob_type is NULL, and if so, initializes it to the ob_type field of the base class. PyType_Ready() will not change this field if it is non-zero.

Inheritance:

サブタイプはこのフィールドを継承します。

PyVarObject Slots

Py_ssize_t PyVarObject.ob_size

静的にメモリ確保されている型オブジェクトの場合、このフィールドはゼロに初期化されます。動的にメモリ確保されている型オブジェクトの場合、このフィールドは内部使用される特殊な意味を持ちます。

Inheritance:

サブタイプはこのフィールドを継承しません。

PyTypeObject Slots

Each slot has a section describing inheritance. If PyType_Ready() may set a value when the field is set to NULL then there will also be a "Default" section. (Note that many fields set on PyBaseObject_Type and PyType_Type effectively act as defaults.)

const char* PyTypeObject.tp_name

型の名前が入っている NUL 終端された文字列へのポインタです。モジュールのグローバル変数としてアクセスできる型の場合、この文字列は完全なモジュール名、ドット、そして型の名前と続く文字列になります; 組み込み型の場合、ただの型の名前です。モジュールがあるパッケージのサブモジュールの場合、完全なパッケージ名が完全なモジュール名の一部になっています。例えば、パッケージ P 内のサブモジュール Q に入っているモジュール M 内で定義されている T は、 tp_name"P.Q.M.T" に初期化します。

動的にメモリ確保される型オブジェクトの場合、このフィールドは単に型の名前になり、モジュール名は型の辞書内でキー '__module__' に対する値として明示的に保存されます。

静的にメモリ確保される型オブジェクトの場合、 tp_name フィールドにはドットが含まれているはずです。 最後のドットよりも前にある部分文字列全体は __module__ 属性として、またドットよりも後ろにある部分は __name__ 属性としてアクセスできます。

ドットが入っていない場合、 tp_name フィールドの内容全てが __name__ 属性になり、 __module__ 属性は (前述のように型の辞書内で明示的にセットしないかぎり) 未定義になります。 このため、その型は pickle 化できないことになります。 さらに、 pydoc が作成するモジュールドキュメントのリストにも載らなくなります。

This field must not be NULL. It is the only required field in PyTypeObject() (other than potentially tp_itemsize).

Inheritance:

サブタイプはこのフィールドを継承しません。

Py_ssize_t PyTypeObject.tp_basicsize
Py_ssize_t PyTypeObject.tp_itemsize

これらのフィールドは、型インスタンスのバイトサイズを計算できるようにします。

型には二つの種類があります: 固定長インスタンスの型は、 tp_itemsize フィールドがゼロで、可変長インスタンスの方は tp_itemsize フィールドが非ゼロの値になります。固定長インスタンスの型の場合、全てのインスタンスは等しく tp_basicsize で与えられたサイズになります。

可変長インスタンスの型の場合、インスタンスには ob_size フィールドがなくてはならず、インスタンスのサイズは N をオブジェクトの "長さ" として、 tp_basicsizetp_itemsize の N 倍を足したものになります。 N の値は通常、インスタンスの ob_size フィールドに記憶されます。ただし例外がいくつかあります: 例えば、整数では負の値を ob_size に使って、インスタンスの表す値が負であることを示し、 N 自体は abs(ob_size) になります。また、 ob_size フィールドがあるからといって、必ずしもインスタンスが可変長であることを意味しません (例えば、 リスト型の構造体は固定長のインスタンスになるにもかかわらず、インスタンスにはちゃんと意味を持った ob_size フィールドがあります)。

基本サイズには、 PyObject_HEAD マクロまたは PyObject_VAR_HEAD マクロ (インスタンス構造体を宣言するのに使ったどちらかのマクロ) で宣言されているフィールドが入っています。さらに、 _ob_prev および _ob_next フィールドがある場合、これらのフィールドもサイズに加算されます。従って、 tp_basicsize の正しい初期化値を得るには、インスタンスデータのレイアウトを宣言するのに使う構造体に対して sizeof 演算子を使うしかありません。基本サイズには、GC ヘッダサイズは入っていません。

アラインメントに関する注釈: 変数の各要素を配置する際に特定のアラインメントが必要となる場合、 tp_basicsize の値に気をつけなければなりません。例: ある型が double の配列を実装しているとします。 tp_itemsizesizeof(double) です。 tp_basicsizesizeof(double) (ここではこれを double のアラインメントが要求するサイズと仮定する) の個数分のサイズになるようにするのはプログラマの責任です。

For any type with variable-length instances, this field must not be NULL.

Inheritance:

これらのフィールドはサブタイプに別々に継承されます。基底タイプが 0 でない tp_itemsize を持っていた場合、基底タイプの実装に依存しますが、一般的にはサブタイプで別の 0 で無い値を tp_itemsize に設定するのは安全ではありません。

destructor PyTypeObject.tp_dealloc

A pointer to the instance destructor function. This function must be defined unless the type guarantees that its instances will never be deallocated (as is the case for the singletons None and Ellipsis). The function signature is:

void tp_dealloc(PyObject *self);

The destructor function is called by the Py_DECREF() and Py_XDECREF() macros when the new reference count is zero. At this point, the instance is still in existence, but there are no references to it. The destructor function should free all references which the instance owns, free all memory buffers owned by the instance (using the freeing function corresponding to the allocation function used to allocate the buffer), and call the type's tp_free function. If the type is not subtypable (doesn't have the Py_TPFLAGS_BASETYPE flag bit set), it is permissible to call the object deallocator directly instead of via tp_free. The object deallocator should be the one used to allocate the instance; this is normally PyObject_Del() if the instance was allocated using PyObject_New() or PyObject_VarNew(), or PyObject_GC_Del() if the instance was allocated using PyObject_GC_New() or PyObject_GC_NewVar().

Finally, if the type is heap allocated (Py_TPFLAGS_HEAPTYPE), the deallocator should decrement the reference count for its type object after calling the type deallocator. In order to avoid dangling pointers, the recommended way to achieve this is:

static void foo_dealloc(foo_object *self) {
    PyTypeObject *tp = Py_TYPE(self);
    // free references and buffers here
    tp->tp_free(self);
    Py_DECREF(tp);
}

Inheritance:

サブタイプはこのフィールドを継承します。

Py_ssize_t PyTypeObject.tp_vectorcall_offset

An optional offset to a per-instance function that implements calling the object using the vectorcall protocol, a more efficient alternative of the simpler tp_call.

This field is only used if the flag _Py_TPFLAGS_HAVE_VECTORCALL is set. If so, this must be a positive integer containing the offset in the instance of a vectorcallfunc pointer. The signature is the same as for _PyObject_Vectorcall():

PyObject *vectorcallfunc(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

The vectorcallfunc pointer may be zero, in which case the instance behaves as if _Py_TPFLAGS_HAVE_VECTORCALL was not set: calling the instance falls back to tp_call.

Any class that sets _Py_TPFLAGS_HAVE_VECTORCALL must also set tp_call and make sure its behaviour is consistent with the vectorcallfunc function. This can be done by setting tp_call to PyVectorcall_Call:

PyObject *PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)

Call callable's vectorcallfunc with positional and keyword arguments given in a tuple and dict, respectively.

This function is intended to be used in the tp_call slot. It does not fall back to tp_call and it currently does not check the _Py_TPFLAGS_HAVE_VECTORCALL flag. To call an object, use one of the PyObject_Call functions instead.

注釈

It is not recommended for heap types to implement the vectorcall protocol. When a user sets __call__ in Python code, only tp_call is updated, possibly making it inconsistent with the vectorcall function.

注釈

The semantics of the tp_vectorcall_offset slot are provisional and expected to be finalized in Python 3.9. If you use vectorcall, plan for updating your code for Python 3.9.

バージョン 3.8 で変更: This slot was used for print formatting in Python 2.x. In Python 3.0 to 3.7, it was reserved and named tp_print.

Inheritance:

This field is inherited by subtypes together with tp_call: a subtype inherits tp_vectorcall_offset from its base type when the subtype’s tp_call is NULL.

Note that heap types (including subclasses defined in Python) do not inherit the _Py_TPFLAGS_HAVE_VECTORCALL flag.

getattrfunc PyTypeObject.tp_getattr

オプションのポインタで、get-attribute-string を行う関数を指します。

This field is deprecated. When it is defined, it should point to a function that acts the same as the tp_getattro function, but taking a C string instead of a Python string object to give the attribute name.

Inheritance:

Group: tp_getattr, tp_getattro

This field is inherited by subtypes together with tp_getattro: a subtype inherits both tp_getattr and tp_getattro from its base type when the subtype's tp_getattr and tp_getattro are both NULL.

setattrfunc PyTypeObject.tp_setattr

オプションのポインタで、属性の設定と削除を行う関数を指します。

This field is deprecated. When it is defined, it should point to a function that acts the same as the tp_setattro function, but taking a C string instead of a Python string object to give the attribute name.

Inheritance:

Group: tp_setattr, tp_setattro

This field is inherited by subtypes together with tp_setattro: a subtype inherits both tp_setattr and tp_setattro from its base type when the subtype's tp_setattr and tp_setattro are both NULL.

PyAsyncMethods* PyTypeObject.tp_as_async

追加の構造体を指すポインタです。 この構造体は、 C レベルで awaitable プロトコルと asynchronous iterator プロトコルを実装するオブジェクトだけに関係するフィールドを持ちます。 詳しいことは async オブジェクト構造体 を参照してください。

バージョン 3.5 で追加: 以前は tp_comparetp_reserved として知られていました。

Inheritance:

The tp_as_async field is not inherited, but the contained fields are inherited individually.

reprfunc PyTypeObject.tp_repr

オプションのポインタで、組み込み関数 repr() を実装している関数を指します。

The signature is the same as for PyObject_Repr():

PyObject *tp_repr(PyObject *self);

The function must return a string or a Unicode object. Ideally, this function should return a string that, when passed to eval(), given a suitable environment, returns an object with the same value. If this is not feasible, it should return a string starting with '<' and ending with '>' from which both the type and the value of the object can be deduced.

Inheritance:

サブタイプはこのフィールドを継承します。

Default:

このフィールドが設定されていない場合、 <%s object at %p> の形式をとる文字列が返されます。 %s は型の名前に、 %p はオブジェクトのメモリアドレスに置き換えられます。

PyNumberMethods* PyTypeObject.tp_as_number

数値プロトコルを実装した追加の構造体を指すポインタです。これらのフィールドについては 数値オブジェクト構造体 で説明されています。

Inheritance:

tp_as_number フィールドは継承されませんが、そこの含まれるフィールドが個別に継承されます。

PySequenceMethods* PyTypeObject.tp_as_sequence

シーケンスプロトコルを実装した追加の構造体を指すポインタです。これらのフィールドについては シーケンスオブジェクト構造体 で説明されています。

Inheritance:

tp_as_sequence フィールドは継承されませんが、これに含まれるフィールドが個別に継承されます。

PyMappingMethods* PyTypeObject.tp_as_mapping

マッピングプロトコルを実装した追加の構造体を指すポインタです。これらのフィールドについては マップオブジェクト構造体 で説明されています。

Inheritance:

tp_as_mapping フィールドは継承されませんが、これに含まれるフィールドが個別に継承されます。

hashfunc PyTypeObject.tp_hash

オプションのポインタで、組み込み関数 hash() を実装している関数を指します。

The signature is the same as for PyObject_Hash():

Py_hash_t tp_hash(PyObject *);

The value -1 should not be returned as a normal return value; when an error occurs during the computation of the hash value, the function should set an exception and return -1.

When this field is not set (and tp_richcompare is not set), an attempt to take the hash of the object raises TypeError. This is the same as setting it to PyObject_HashNotImplemented().

このフィールドは明示的に PyObject_HashNotImplemented() に設定することで、親 type からのハッシュメソッドの継承をブロックすることができます。これは Python レベルでの __hash__ = None と同等に解釈され、 isinstance(o, collections.Hashable) が正しく False を返すようになります。逆もまた可能であることに注意してください - Python レベルで __hash__ = None を設定することで tp_hash スロットは PyObject_HashNotImplemented() に設定されます。

Inheritance:

Group: tp_hash, tp_richcompare

This field is inherited by subtypes together with tp_richcompare: a subtype inherits both of tp_richcompare and tp_hash, when the subtype's tp_richcompare and tp_hash are both NULL.

ternaryfunc PyTypeObject.tp_call

An optional pointer to a function that implements calling the object. This should be NULL if the object is not callable. The signature is the same as for PyObject_Call():

PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs);

Inheritance:

サブタイプはこのフィールドを継承します。

reprfunc PyTypeObject.tp_str

オプションのポインタで、組み込みの演算 str() を実装している関数を指します。(str が型の一つになったため、 str()str のコンストラクタを呼び出すことに注意してください。このコンストラクタは実際の処理を行う上で PyObject_Str() を呼び出し、さらに PyObject_Str() がこのハンドラを呼び出すことになります。)

The signature is the same as for PyObject_Str():

PyObject *tp_str(PyObject *self);

The function must return a string or a Unicode object. It should be a "friendly" string representation of the object, as this is the representation that will be used, among other things, by the print() function.

Inheritance:

サブタイプはこのフィールドを継承します。

Default:

このフィールドが設定されていない場合、文字列表現を返すためには PyObject_Repr() が呼び出されます。

getattrofunc PyTypeObject.tp_getattro

オプションのポインタで、get-attribute を実装している関数を指します。

The signature is the same as for PyObject_GetAttr():

PyObject *tp_getattro(PyObject *self, PyObject *attr);

It is usually convenient to set this field to PyObject_GenericGetAttr(), which implements the normal way of looking for object attributes.

Inheritance:

Group: tp_getattr, tp_getattro

This field is inherited by subtypes together with tp_getattr: a subtype inherits both tp_getattr and tp_getattro from its base type when the subtype's tp_getattr and tp_getattro are both NULL.

Default:

PyBaseObject_Type uses PyObject_GenericGetAttr().

setattrofunc PyTypeObject.tp_setattro

オプションのポインタで、属性の設定と削除を行う関数を指します。

The signature is the same as for PyObject_SetAttr():

PyObject *tp_setattro(PyObject *self, PyObject *attr, PyObject *value);

In addition, setting value to NULL to delete an attribute must be supported. It is usually convenient to set this field to PyObject_GenericSetAttr(), which implements the normal way of setting object attributes.

Inheritance:

Group: tp_setattr, tp_setattro

This field is inherited by subtypes together with tp_setattr: a subtype inherits both tp_setattr and tp_setattro from its base type when the subtype's tp_setattr and tp_setattro are both NULL.

Default:

PyBaseObject_Type uses PyObject_GenericSetAttr().

PyBufferProcs* PyTypeObject.tp_as_buffer

バッファインタフェースを実装しているオブジェクトにのみ関連する、一連のフィールド群が入った別の構造体を指すポインタです。構造体内の各フィールドは バッファオブジェクト構造体 (buffer object structure) で説明します。

Inheritance:

tp_as_buffer フィールド自体は継承されませんが、これに含まれるフィールドは個別に継承されます。

unsigned long PyTypeObject.tp_flags

This field is a bit mask of various flags. Some flags indicate variant semantics for certain situations; others are used to indicate that certain fields in the type object (or in the extension structures referenced via tp_as_number, tp_as_sequence, tp_as_mapping, and tp_as_buffer) that were historically not always present are valid; if such a flag bit is clear, the type fields it guards must not be accessed and must be considered to have a zero or NULL value instead.

Inheritance:

Inheritance of this field is complicated. Most flag bits are inherited individually, i.e. if the base type has a flag bit set, the subtype inherits this flag bit. The flag bits that pertain to extension structures are strictly inherited if the extension structure is inherited, i.e. the base type's value of the flag bit is copied into the subtype together with a pointer to the extension structure. The Py_TPFLAGS_HAVE_GC flag bit is inherited together with the tp_traverse and tp_clear fields, i.e. if the Py_TPFLAGS_HAVE_GC flag bit is clear in the subtype and the tp_traverse and tp_clear fields in the subtype exist and have NULL values.

Default:

PyBaseObject_Type uses Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE.

Bit Masks:

以下に挙げるビットマスクは現在定義されているものです; フラグは | 演算子で論理和を取って tp_flags フィールドの値を作成できます。 PyType_HasFeature() マクロは型とフラグ値、 tp および f をとり、 tp->tp_flags & f が非ゼロかどうか調べます。

Py_TPFLAGS_HEAPTYPE

This bit is set when the type object itself is allocated on the heap, for example, types created dynamically using PyType_FromSpec(). In this case, the ob_type field of its instances is considered a reference to the type, and the type object is INCREF'ed when a new instance is created, and DECREF'ed when an instance is destroyed (this does not apply to instances of subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or DECREF'ed).

Inheritance:

???

Py_TPFLAGS_BASETYPE

型を別の型の基底タイプとして使える場合にセットされるビットです。このビットがクリアならば、この型のサブタイプは生成できません (Java における "final" クラスに似たクラスになります)。

Inheritance:

???

Py_TPFLAGS_READY

型オブジェクトが PyType_Ready() で完全に初期化されるとセットされるビットです。

Inheritance:

???

Py_TPFLAGS_READYING

PyType_Ready() による型オブジェクトの初期化処理中にセットされるビットです。

Inheritance:

???

Py_TPFLAGS_HAVE_GC

オブジェクトがガベージコレクション (GC) をサポートする場合にセットされるビットです。このビットがセットされている場合、インスタンスは PyObject_GC_New() を使って生成し、 PyObject_GC_Del() を使って破棄しなければなりません。詳しい情報は 循環参照ガベージコレクションをサポートする にあります。このビットは、GC に関連するフィールド tp_traverse および tp_clear が型オブジェクト内に存在することも示しています。

Inheritance:

Group: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear

The Py_TPFLAGS_HAVE_GC flag bit is inherited together with the tp_traverse and tp_clear fields, i.e. if the Py_TPFLAGS_HAVE_GC flag bit is clear in the subtype and the tp_traverse and tp_clear fields in the subtype exist and have NULL values.

Py_TPFLAGS_DEFAULT

型オブジェクトおよび拡張機能構造体の特定のフィールドの存在の有無に関連する全てのビットからなるビットマスクです。現状では、このビットマスクには以下のビット: Py_TPFLAGS_HAVE_STACKLESS_EXTENSION および Py_TPFLAGS_HAVE_VERSION_TAG が入っています。

Inheritance:

???

Py_TPFLAGS_METHOD_DESCRIPTOR

This bit indicates that objects behave like unbound methods.

If this flag is set for type(meth), then:

  • meth.__get__(obj, cls)(*args, **kwds) (with obj not None) must be equivalent to meth(obj, *args, **kwds).

  • meth.__get__(None, cls)(*args, **kwds) must be equivalent to meth(*args, **kwds).

This flag enables an optimization for typical method calls like obj.meth(): it avoids creating a temporary "bound method" object for obj.meth.

バージョン 3.8 で追加.

Inheritance:

This flag is never inherited by heap types. For extension types, it is inherited whenever tp_descr_get is inherited.

Py_TPFLAGS_LONG_SUBCLASS
Py_TPFLAGS_LIST_SUBCLASS
Py_TPFLAGS_TUPLE_SUBCLASS
Py_TPFLAGS_BYTES_SUBCLASS
Py_TPFLAGS_UNICODE_SUBCLASS
Py_TPFLAGS_DICT_SUBCLASS
Py_TPFLAGS_BASE_EXC_SUBCLASS
Py_TPFLAGS_TYPE_SUBCLASS

これらのフラグは PyLong_Check() のような関数が、型がとある組み込み型のサブクラスかどうかを素早く判断するのに使われます; この専用のチェックは PyObject_IsInstance() のような汎用的なチェックよりも高速です。 組み込み型を継承した独自の型では tp_flags を適切に設定すべきで、そうしないとその型が関わるコードでは、どんなチェックの方法が使われるかによって振る舞いが異なってしまうでしょう。

Py_TPFLAGS_HAVE_FINALIZE

型構造体に tp_finalize スロットが存在しているときにセットされるビットです。

バージョン 3.4 で追加.

バージョン 3.8 で非推奨: This flag isn't necessary anymore, as the interpreter assumes the tp_finalize slot is always present in the type structure.

_Py_TPFLAGS_HAVE_VECTORCALL

This bit is set when the class implements the vectorcall protocol. See tp_vectorcall_offset for details.

Inheritance:

This bit is set on static subtypes if tp_flags is not overridden: a subtype inherits _Py_TPFLAGS_HAVE_VECTORCALL from its base type when the subtype’s tp_call is NULL and the subtype's Py_TPFLAGS_HEAPTYPE is not set.

Heap types do not inherit _Py_TPFLAGS_HAVE_VECTORCALL.

注釈

This flag is provisional and expected to become public in Python 3.9, with a different name and, possibly, changed semantics. If you use vectorcall, plan for updating your code for Python 3.9.

バージョン 3.8 で追加.

const char* PyTypeObject.tp_doc

オプションのポインタで、この型オブジェクトの docstring を与える NUL 終端された C の文字列を指します。この値は型オブジェクトと型のインスタンスにおける __doc__ 属性として公開されます。

Inheritance:

サブタイプはこのフィールドを継承 しません

traverseproc PyTypeObject.tp_traverse

An optional pointer to a traversal function for the garbage collector. This is only used if the Py_TPFLAGS_HAVE_GC flag bit is set. The signature is:

int tp_traverse(PyObject *self, visitproc visit, void *arg);

Pythonのガベージコレクションの仕組みについての詳細は、 循環参照ガベージコレクションをサポートする にあります。

tp_traverse ポインタは、ガベージコレクタが循環参照を見つけるために使われます。 tp_traverse 関数の典型的な実装は、インスタンスの Pythonオブジェクトである各メンバに対して Py_VISIT() を呼び出します。例えば、次のコードは _thread 拡張モジュールの local_traverse() 関数です:

static int
local_traverse(localobject *self, visitproc visit, void *arg)
{
    Py_VISIT(self->args);
    Py_VISIT(self->kw);
    Py_VISIT(self->dict);
    return 0;
}

Note that Py_VISIT() is called only on those members that can participate in reference cycles. Although there is also a self->key member, it can only be NULL or a Python string and therefore cannot be part of a reference cycle.

一方、メンバが循環参照の一部になり得ないと判っていても、デバッグ目的で巡回したい場合があるかもしれないので、 gc モジュールの get_referents() 関数は循環参照になり得ないメンバも返します。

Py_VISIT()local_traverse()visitarg という決まった名前の引数を持つことを要求します。

Inheritance:

Group: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear

このフィールドは tp_clear および Py_TPFLAGS_HAVE_GC フラグビットと共にサブタイプに継承されます: すなわち、サブタイプの tp_traverse および tp_clear が両方ともゼロの場合、サブタイプは基底タイプから tp_traversetp_clear を両方とも継承します。

inquiry PyTypeObject.tp_clear

An optional pointer to a clear function for the garbage collector. This is only used if the Py_TPFLAGS_HAVE_GC flag bit is set. The signature is:

int tp_clear(PyObject *);

tp_clear メンバ関数は GC が検出した循環しているゴミの循環参照を壊すために用いられます。総合的な視点で考えると、システム内の全ての tp_clear 関数が連携して、全ての循環参照を破壊しなければなりません。 (訳注: ある型が tp_clear を実装しなくても全ての循環参照が破壊できるのであれば実装しなくても良い) これはとても繊細で、もし少しでも不確かな部分があるのであれば、 tp_clear 関数を提供するべきです。例えば、タプルは tp_clear を実装しません。なぜなら、タプルだけで構成された循環参照がみつかることは無いからです。従って、タプル以外の型の tp_clear 関数だけで、タプルを含むどんな循環参照も必ず破壊できることになります。これは簡単に判ることではなく、 tp_clear の実装を避ける良い理由はめったにありません。

Implementations of tp_clear should drop the instance's references to those of its members that may be Python objects, and set its pointers to those members to NULL, as in the following example:

static int
local_clear(localobject *self)
{
    Py_CLEAR(self->key);
    Py_CLEAR(self->args);
    Py_CLEAR(self->kw);
    Py_CLEAR(self->dict);
    return 0;
}

The Py_CLEAR() macro should be used, because clearing references is delicate: the reference to the contained object must not be decremented until after the pointer to the contained object is set to NULL. This is because decrementing the reference count may cause the contained object to become trash, triggering a chain of reclamation activity that may include invoking arbitrary Python code (due to finalizers, or weakref callbacks, associated with the contained object). If it's possible for such code to reference self again, it's important that the pointer to the contained object be NULL at that time, so that self knows the contained object can no longer be used. The Py_CLEAR() macro performs the operations in a safe order.

tp_clear 関数の目的は参照カウントを破壊することなので、 Python 文字列や Python 整数のような、循環参照に含むことのできないオブジェクトをクリアする必要はありません。一方、所有する全ての Python オブジェクトをクリアするようにし、その型の tp_dealloc 関数が tp_clear 関数を実行するようにすると実装が楽になるでしょう。

Pythonのガベージコレクションの仕組みについての詳細は、 循環参照ガベージコレクションをサポートする にあります。

Inheritance:

Group: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear

このフィールドは tp_traverse および Py_TPFLAGS_HAVE_GC フラグビットと共にサブタイプに継承されます: すなわち、サブタイプの tp_traverse および tp_clear が両方ともゼロの場合、サブタイプは基底タイプから tp_traversetp_clear を両方とも継承します。

richcmpfunc PyTypeObject.tp_richcompare

An optional pointer to the rich comparison function, whose signature is:

PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);

The first parameter is guaranteed to be an instance of the type that is defined by PyTypeObject.

この関数は、比較結果を返すべきです。(普通は Py_TruePy_False です。) 比較が未定義の場合は、Py_NotImplemented を、それ以外のエラーが発生した場合には例外状態をセットして NULL を返さなければなりません。

tp_richcompare および PyObject_RichCompare() 関数の第三引数に使うための定数としては以下が定義されています:

定数

比較

Py_LT

<

Py_LE

<=

Py_EQ

==

Py_NE

!=

Py_GT

>

Py_GE

>=

The following macro is defined to ease writing rich comparison functions:

PyObject *Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op)

Return Py_True or Py_False from the function, depending on the result of a comparison. VAL_A and VAL_B must be orderable by C comparison operators (for example, they may be C ints or floats). The third argument specifies the requested operation, as for PyObject_RichCompare().

The return value's reference count is properly incremented.

On error, sets an exception and returns NULL from the function.

バージョン 3.7 で追加.

Inheritance:

Group: tp_hash, tp_richcompare

This field is inherited by subtypes together with tp_hash: a subtype inherits tp_richcompare and tp_hash when the subtype's tp_richcompare and tp_hash are both NULL.

Default:

PyBaseObject_Type provides a tp_richcompare implementation, which may be inherited. However, if only tp_hash is defined, not even the inherited function is used and instances of the type will not be able to participate in any comparisons.

Py_ssize_t PyTypeObject.tp_weaklistoffset

If the instances of this type are weakly referenceable, this field is greater than zero and contains the offset in the instance structure of the weak reference list head (ignoring the GC header, if present); this offset is used by PyObject_ClearWeakRefs() and the PyWeakref_*() functions. The instance structure needs to include a field of type PyObject* which is initialized to NULL.

このフィールドを tp_weaklist と混同しないようにしてください; これは型オブジェクト自身への弱参照からなるリストの先頭です。

Inheritance:

このフィールドはサブタイプに継承されますが、以下の規則を読んでください。サブタイプはこのオフセット値をオーバライドすることがあります; 従って、サブタイプでは弱参照リストの先頭が基底タイプとは異なる場合があります。リストの先頭は常に tp_weaklistoffset で分かるはずなので、このことは問題にはならないはずです。

class 文で定義された型に __slots__ 宣言が全くなく、かつ基底タイプが弱参照可能でない場合、その型を弱参照可能にするには弱参照リストの先頭を表すスロットをインスタンスデータレイアウト構造体に追加し、スロットのオフセットを tp_weaklistoffset に設定します。

型の __slots__ の宣言に __weakref__ という名前のスロットが含まれているとき、スロットはその型のインスタンスにおける弱参照リストの先頭を表すスロットになり、スロットのオフセットが型の tp_weaklistoffset に入ります。

型の __slots__ 宣言が __weakref__ という名前のスロットを含んでいないとき、その型は基底タイプから tp_weaklistoffset を継承します。

getiterfunc PyTypeObject.tp_iter

オプションの変数で、そのオブジェクトのイテレータを返す関数へのポインタです。この値が存在することは、通常この型のインスタンスがイテレート可能であることを示しています (しかし、シーケンスはこの関数がなくてもイテレート可能です)。

This function has the same signature as PyObject_GetIter():

PyObject *tp_iter(PyObject *self);

Inheritance:

サブタイプはこのフィールドを継承します。

iternextfunc PyTypeObject.tp_iternext

An optional pointer to a function that returns the next item in an iterator. The signature is:

PyObject *tp_iternext(PyObject *self);

When the iterator is exhausted, it must return NULL; a StopIteration exception may or may not be set. When another error occurs, it must return NULL too. Its presence signals that the instances of this type are iterators.

イテレータ型では、 tp_iter 関数も定義されていなければならず、その関数は (新たなイテレータインスタンスではなく) イテレータインスタンス自体を返さねばなりません。

この関数のシグネチャは PyIter_Next() と同じです。

Inheritance:

サブタイプはこのフィールドを継承します。

struct PyMethodDef* PyTypeObject.tp_methods

An optional pointer to a static NULL-terminated array of PyMethodDef structures, declaring regular methods of this type.

配列の各要素ごとに、メソッドデスクリプタの入った、要素が型の辞書 (下記の tp_dict 参照) に追加されます。

Inheritance:

サブタイプはこのフィールドを継承しません (メソッドは別個のメカニズムで継承されています)。

struct PyMemberDef* PyTypeObject.tp_members

An optional pointer to a static NULL-terminated array of PyMemberDef structures, declaring regular data members (fields or slots) of instances of this type.

配列の各要素ごとに、メンバデスクリプタの入った要素が型の辞書 (下記の tp_dict 参照) に追加されます。

Inheritance:

サブタイプはこのフィールドを継承しません (メンバは別個のメカニズムで継承されています)。

struct PyGetSetDef* PyTypeObject.tp_getset

An optional pointer to a static NULL-terminated array of PyGetSetDef structures, declaring computed attributes of instances of this type.

配列の各要素ごとに、 getter/setter デスクリプタの入った、要素が型の辞書 (下記の tp_dict 参照) に追加されます。

Inheritance:

サブタイプはこのフィールドを継承しません (算出属性は別個のメカニズムで継承されています)。

PyTypeObject* PyTypeObject.tp_base

オプションのポインタで、型に関するプロパティを継承する基底タイプを指します。このフィールドのレベルでは、単継承 (single inheritance) だけがサポートされています; 多重継承はメタタイプの呼び出しによる動的な型オブジェクトの生成を必要とします。

注釈

Slot initialization is subject to the rules of initializing globals. C99 requires the initializers to be "address constants". Function designators like PyType_GenericNew(), with implicit conversion to a pointer, are valid C99 address constants.

However, the unary '&' operator applied to a non-static variable like PyBaseObject_Type() is not required to produce an address constant. Compilers may support this (gcc does), MSVC does not. Both compilers are strictly standard conforming in this particular behavior.

Consequently, tp_base should be set in the extension module's init function.

Inheritance:

This field is not inherited by subtypes (obviously).

Default:

This field defaults to &PyBaseObject_Type (which to Python programmers is known as the type object).

PyObject* PyTypeObject.tp_dict

型の辞書は PyType_Ready() によってこのフィールドに収められます。

This field should normally be initialized to NULL before PyType_Ready is called; it may also be initialized to a dictionary containing initial attributes for the type. Once PyType_Ready() has initialized the type, extra attributes for the type may be added to this dictionary only if they don't correspond to overloaded operations (like __add__()).

Inheritance:

サブタイプはこのフィールドを継承しません (が、この辞書内で定義されている属性は異なるメカニズムで継承されます)。

Default:

If this field is NULL, PyType_Ready() will assign a new dictionary to it.

警告

tp_dictPyDict_SetItem() を使ったり、辞書 C-API で編集するのは安全ではありません。

descrgetfunc PyTypeObject.tp_descr_get

オプションのポインタで、デスクリプタの get 関数を指します。

The function signature is:

PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);

Inheritance:

サブタイプはこのフィールドを継承します。

descrsetfunc PyTypeObject.tp_descr_set

オプションのポインタで、デスクリプタの値の設定と削除を行う関数を指します。

The function signature is:

int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);

The value argument is set to NULL to delete the value.

Inheritance:

サブタイプはこのフィールドを継承します。

Py_ssize_t PyTypeObject.tp_dictoffset

型のインスタンスにインスタンス変数の入った辞書がある場合、このフィールドは非ゼロの値になり、型のインスタンスデータ構造体におけるインスタンス変数辞書へのオフセットが入ります; このオフセット値は PyObject_GenericGetAttr() が使います。

このフィールドを tp_dict と混同しないようにしてください; これは型オブジェクト自身の属性の辞書です。

このフィールドの値がゼロより大きければ、値はインスタンス構造体の先頭からの オフセットを表します。値がゼロより小さければ、インスタンス構造体の 末尾 からのオフセットを表します。負のオフセットを使うコストは比較的高くつくので、 インスタンス構造体に可変長部分があるときのみ使うべきです。例えば、 strtuple のサブタイプにインスタンス変数の辞書を追加する場合には、負のオフセットを使います。この場合、たとえ辞書が基本のオブジェクトレイアウトに含まれていなくても、 tp_basicsize フィールドは追加された辞書を考慮にいれなければならないことに注意してください。ポインタサイズが 4 バイトのシステムでは、 構造体の最後尾に辞書が宣言されていることを示す場合、 tp_dictoffset-4 にしなければなりません。

負の tp_dictoffset から、インスタンスでの実際のオフセットを計算するには以下のようにします:

dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
if dictoffset is not aligned on sizeof(void*):
    round up to sizeof(void*)

ここで、 tp_basicsizetp_itemsize および tp_dictoffset は型オブジェクトから取り出され、 ob_size はインスタンスから取り出されます。 絶対値を取っているのは、整数は符号を記憶するのに ob_size の符号を使うためです。 (この計算を自分で行う必要はまったくありません; 計算は _PyObject_GetDictPtr() がやってくれます。)

Inheritance:

このフィールドはサブタイプに継承されますが、以下の規則を読んでください。サブタイプはこのオフセット値をオーバライドすることがあります; 従って、サブタイプでは辞書のオフセットが基底タイプとは異なる場合があります。辞書のオフセットは常に tp_dictoffset で分かるはずなので、このことは問題にはならないはずです。

class 文で定義された型に __slots__ 宣言がなく、かつ基底タイプの全てにインスタンス変数辞書がない場合、辞書のスロットをインスタンスデータレイアウト構造体に追加し、スロットのオフセットを tp_dictoffset に設定します。

class 文で定義された型に __slots__ 宣言がある場合、この型は基底タイプから tp_dictoffset を継承します。

(__dict__ という名前のスロットを __slots__ 宣言に追加しても、期待どおりの効果は得られず、単に混乱を招くだけになります。とはいえ、これは将来 __weakref__ のように追加されるはずです。)

Default:

This slot has no default. For static types, if the field is NULL then no __dict__ gets created for instances.

initproc PyTypeObject.tp_init

オプションのポインタで、インスタンス初期化関数を指します。

この関数はクラスにおける __init__() メソッドに対応します。 __init__() と同様、 __init__() を呼び出さずにインスタンスを作成できます。また、 __init__() を再度呼び出してインスタンスの再初期化もできます。

The function signature is:

int tp_init(PyObject *self, PyObject *args, PyObject *kwds);

self 引数は初期化するインスタンスです; args および kwds 引数は、 __init__() を呼び出す際の位置引数およびキーワード引数です。

The tp_init function, if not NULL, is called when an instance is created normally by calling its type, after the type's tp_new function has returned an instance of the type. If the tp_new function returns an instance of some other type that is not a subtype of the original type, no tp_init function is called; if tp_new returns an instance of a subtype of the original type, the subtype's tp_init is called.

Returns 0 on success, -1 and sets an exception on error.

Inheritance:

サブタイプはこのフィールドを継承します。

Default:

For static types this field does not have a default.

allocfunc PyTypeObject.tp_alloc

オプションのポインタで、インスタンスのメモリ確保関数を指します。

The function signature is:

PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems);

Inheritance:

This field is inherited by static subtypes, but not by dynamic subtypes (subtypes created by a class statement).

Default:

For dynamic subtypes, this field is always set to PyType_GenericAlloc(), to force a standard heap allocation strategy.

For static subtypes, PyBaseObject_Type uses PyType_GenericAlloc(). That is the recommended value for all statically defined types.

newfunc PyTypeObject.tp_new

オプションのポインタで、インスタンス生成関数を指します。

The function signature is:

PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds);

subtype 引数は生成するオブジェクトの型です; args および kwds 引数は、型を呼び出すときの位置引数およびキーワード引数です。サブタイプは tp_new 関数を呼び出すときに使う型と同じである必要はないことに注意してください; その型の (無関係ではない) サブタイプのこともあります。

tp_new 関数は subtype->tp_alloc(subtype, nitems) を呼び出してオブジェクトのメモリ領域を確保し、初期化で絶対に必要とされる処理だけを行います。省略したり繰り返したりしても問題のない初期化処理は tp_init ハンドラ内に配置しなければなりません。だいたいの目安としては、変更不能な型では初期化は全て tp_new で行い、一方、変更可能な型ではほとんどの初期化を tp_init に回すべきです。

Inheritance:

This field is inherited by subtypes, except it is not inherited by static types whose tp_base is NULL or &PyBaseObject_Type.

Default:

For static types this field has no default. This means if the slot is defined as NULL, the type cannot be called to create new instances; presumably there is some other way to create instances, like a factory function.

freefunc PyTypeObject.tp_free

An optional pointer to an instance deallocation function. Its signature is:

void tp_free(void *self);

このシグネチャと互換性のある初期化子は PyObject_Free() です。

Inheritance:

This field is inherited by static subtypes, but not by dynamic subtypes (subtypes created by a class statement)

Default:

In dynamic subtypes, this field is set to a deallocator suitable to match PyType_GenericAlloc() and the value of the Py_TPFLAGS_HAVE_GC flag bit.

For static subtypes, PyBaseObject_Type uses PyObject_Del.

inquiry PyTypeObject.tp_is_gc

オプションのポインタで、ガベージコレクタから呼び出される関数を指します。

The garbage collector needs to know whether a particular object is collectible or not. Normally, it is sufficient to look at the object's type's tp_flags field, and check the Py_TPFLAGS_HAVE_GC flag bit. But some types have a mixture of statically and dynamically allocated instances, and the statically allocated instances are not collectible. Such types should define this function; it should return 1 for a collectible instance, and 0 for a non-collectible instance. The signature is:

int tp_is_gc(PyObject *self);

(上記のような型の例は、型オブジェクト自体です。メタタイプ PyType_Type は、型のメモリ確保が静的か動的かを区別するためにこの関数を定義しています。)

Inheritance:

サブタイプはこのフィールドを継承します。

Default:

This slot has no default. If this field is NULL, Py_TPFLAGS_HAVE_GC is used as the functional equivalent.

PyObject* PyTypeObject.tp_bases

基底型からなるタプルです。

This is set for types created by a class statement. It should be NULL for statically defined types.

Inheritance:

このフィールドは継承されません。

PyObject* PyTypeObject.tp_mro

基底タイプ群を展開した集合が入っているタプルです。集合は該当する型自体からはじまり、 object で終わります。メソッド解決順序 (Method Resolution Order) に従って並んでいます。

Inheritance:

このフィールドは継承されません; フィールドの値は PyType_Ready() で毎回計算されます。

PyObject* PyTypeObject.tp_cache

Unused. Internal use only.

Inheritance:

このフィールドは継承されません。

PyObject* PyTypeObject.tp_subclasses

List of weak references to subclasses. Internal use only.

Inheritance:

このフィールドは継承されません。

PyObject* PyTypeObject.tp_weaklist

この型オブジェクトに対する弱参照からなるリストの先頭です。

Inheritance:

このフィールドは継承されません。

destructor PyTypeObject.tp_del

This field is deprecated. Use tp_finalize instead.

unsigned int PyTypeObject.tp_version_tag

Used to index into the method cache. Internal use only.

Inheritance:

このフィールドは継承されません。

destructor PyTypeObject.tp_finalize

An optional pointer to an instance finalization function. Its signature is:

void tp_finalize(PyObject *self);

tp_finalize が設定されている場合、インスタンスをファイナライズするときに、インタプリタがこの関数を1回呼び出します。 ガベージコレクタ (このインスタンスが孤立した循環参照の一部だった場合) やオブジェクトが破棄される直前にもこの関数は呼び出されます。 どちらの場合でも、循環参照を破壊しようとする前に呼び出されることが保証されていて、確実にオブジェクトが正常な状態にあるようにします。

tp_finalize は現在の例外状態を変更すべきではありません; 従って、単純でないファイナライザを書くには次の方法が推奨されます:

static void
local_finalize(PyObject *self)
{
    PyObject *error_type, *error_value, *error_traceback;

    /* Save the current exception, if any. */
    PyErr_Fetch(&error_type, &error_value, &error_traceback);

    /* ... */

    /* Restore the saved exception. */
    PyErr_Restore(error_type, error_value, error_traceback);
}

このフィールドを (継承した場合も含めて) 考慮から漏らさないように、 Py_TPFLAGS_HAVE_FINALIZE フラグビットも設定しなければなりません。

Inheritance:

サブタイプはこのフィールドを継承します。

バージョン 3.4 で追加.

参考

"オブジェクトの安全な終了処理" (PEP 442)

残りのフィールドは、機能テスト用のマクロである COUNT_ALLOCS が定義されている場合のみ利用でき、内部で使用するためだけのものです。これらのフィールドについて記述するのは単に完全性のためです。サブタイプはこれらのフィールドを継承しません。

Py_ssize_t PyTypeObject.tp_allocs

メモリ確保の回数です。

Py_ssize_t PyTypeObject.tp_frees

メモリ解放の回数です。

Py_ssize_t PyTypeObject.tp_maxalloc

同時にメモリ確保できる最大オブジェクト数です。

PyTypeObject* PyTypeObject.tp_prev

Pointer to the previous type object with a non-zero tp_allocs field.

PyTypeObject* PyTypeObject.tp_next

次のゼロでない tp_allocs フィールドを持つ型オブジェクトへのポインタです。

Also, note that, in a garbage collected Python, tp_dealloc may be called from any Python thread, not just the thread which created the object (if the object becomes part of a refcount cycle, that cycle might be collected by a garbage collection on any thread). This is not a problem for Python API calls, since the thread on which tp_dealloc is called will own the Global Interpreter Lock (GIL). However, if the object being destroyed in turn destroys objects from some other C or C++ library, care should be taken to ensure that destroying those objects on the thread which called tp_dealloc will not violate any assumptions of the library.

Heap Types

Traditionally, types defined in C code are static, that is, a static PyTypeObject structure is defined directly in code and initialized using PyType_Ready().

This results in types that are limited relative to types defined in Python:

  • Static types are limited to one base, i.e. they cannot use multiple inheritance.

  • Static type objects (but not necessarily their instances) are immutable. It is not possible to add or modify the type object's attributes from Python.

  • Static type objects are shared across sub-interpreters, so they should not include any subinterpreter-specific state.

Also, since PyTypeObject is not part of the stable ABI, any extension modules using static types must be compiled for a specific Python minor version.

An alternative to static types is heap-allocated types, or heap types for short, which correspond closely to classes created by Python's class statement.

This is done by filling a PyType_Spec structure and calling PyType_FromSpecWithBases().

数値オブジェクト構造体

PyNumberMethods

この構造体は数値型プロトコルを実装するために使われる関数群へのポインタを保持しています。 以下のそれぞれの関数は 数値型プロトコル (number protocol) で解説されている似た名前の関数から利用されます。

以下は構造体の定義です:

typedef struct {
     binaryfunc nb_add;
     binaryfunc nb_subtract;
     binaryfunc nb_multiply;
     binaryfunc nb_remainder;
     binaryfunc nb_divmod;
     ternaryfunc nb_power;
     unaryfunc nb_negative;
     unaryfunc nb_positive;
     unaryfunc nb_absolute;
     inquiry nb_bool;
     unaryfunc nb_invert;
     binaryfunc nb_lshift;
     binaryfunc nb_rshift;
     binaryfunc nb_and;
     binaryfunc nb_xor;
     binaryfunc nb_or;
     unaryfunc nb_int;
     void *nb_reserved;
     unaryfunc nb_float;

     binaryfunc nb_inplace_add;
     binaryfunc nb_inplace_subtract;
     binaryfunc nb_inplace_multiply;
     binaryfunc nb_inplace_remainder;
     ternaryfunc nb_inplace_power;
     binaryfunc nb_inplace_lshift;
     binaryfunc nb_inplace_rshift;
     binaryfunc nb_inplace_and;
     binaryfunc nb_inplace_xor;
     binaryfunc nb_inplace_or;

     binaryfunc nb_floor_divide;
     binaryfunc nb_true_divide;
     binaryfunc nb_inplace_floor_divide;
     binaryfunc nb_inplace_true_divide;

     unaryfunc nb_index;

     binaryfunc nb_matrix_multiply;
     binaryfunc nb_inplace_matrix_multiply;
} PyNumberMethods;

注釈

二項関数と三項関数は、すべてのオペランドの型をチェックしなければならず、必要な変換を実装しなければなりません (すくなくともオペランドの一つは定義している型のインスタンスです). もし与えられたオペランドに対して操作が定義されなければ、二項関数と三項関数は Py_NotImplemented を返さなければならず、他のエラーが起こった場合は、NULL を返して例外を設定しなければなりません。

注釈

nb_reserved フィールドは常に NULL でなければなりません。以前は nb_long と呼ばれていて、 Python 3.0.1 で名前が変更されました。

binaryfunc PyNumberMethods.nb_add
binaryfunc PyNumberMethods.nb_subtract
binaryfunc PyNumberMethods.nb_multiply
binaryfunc PyNumberMethods.nb_remainder
binaryfunc PyNumberMethods.nb_divmod
ternaryfunc PyNumberMethods.nb_power
unaryfunc PyNumberMethods.nb_negative
unaryfunc PyNumberMethods.nb_positive
unaryfunc PyNumberMethods.nb_absolute
inquiry PyNumberMethods.nb_bool
unaryfunc PyNumberMethods.nb_invert
binaryfunc PyNumberMethods.nb_lshift
binaryfunc PyNumberMethods.nb_rshift
binaryfunc PyNumberMethods.nb_and
binaryfunc PyNumberMethods.nb_xor
binaryfunc PyNumberMethods.nb_or
unaryfunc PyNumberMethods.nb_int
void *PyNumberMethods.nb_reserved
unaryfunc PyNumberMethods.nb_float
binaryfunc PyNumberMethods.nb_inplace_add
binaryfunc PyNumberMethods.nb_inplace_subtract
binaryfunc PyNumberMethods.nb_inplace_multiply
binaryfunc PyNumberMethods.nb_inplace_remainder
ternaryfunc PyNumberMethods.nb_inplace_power
binaryfunc PyNumberMethods.nb_inplace_lshift
binaryfunc PyNumberMethods.nb_inplace_rshift
binaryfunc PyNumberMethods.nb_inplace_and
binaryfunc PyNumberMethods.nb_inplace_xor
binaryfunc PyNumberMethods.nb_inplace_or
binaryfunc PyNumberMethods.nb_floor_divide
binaryfunc PyNumberMethods.nb_true_divide
binaryfunc PyNumberMethods.nb_inplace_floor_divide
binaryfunc PyNumberMethods.nb_inplace_true_divide
unaryfunc PyNumberMethods.nb_index
binaryfunc PyNumberMethods.nb_matrix_multiply
binaryfunc PyNumberMethods.nb_inplace_matrix_multiply

マップオブジェクト構造体

PyMappingMethods

この構造体はマップ型プロトコルを実装するために使われる関数群へのポインタを保持しています。 以下の3つのメンバを持っています:

lenfunc PyMappingMethods.mp_length

This function is used by PyMapping_Size() and PyObject_Size(), and has the same signature. This slot may be set to NULL if the object has no defined length.

binaryfunc PyMappingMethods.mp_subscript

This function is used by PyObject_GetItem() and PySequence_GetSlice(), and has the same signature as PyObject_GetItem(). This slot must be filled for the PyMapping_Check() function to return 1, it can be NULL otherwise.

objobjargproc PyMappingMethods.mp_ass_subscript

This function is used by PyObject_SetItem(), PyObject_DelItem(), PyObject_SetSlice() and PyObject_DelSlice(). It has the same signature as PyObject_SetItem(), but v can also be set to NULL to delete an item. If this slot is NULL, the object does not support item assignment and deletion.

シーケンスオブジェクト構造体

PySequenceMethods

この構造体はシーケンス型プロトコルを実装するために使われる関数群へのポインタを保持しています。

lenfunc PySequenceMethods.sq_length

This function is used by PySequence_Size() and PyObject_Size(), and has the same signature. It is also used for handling negative indices via the sq_item and the sq_ass_item slots.

binaryfunc PySequenceMethods.sq_concat

This function is used by PySequence_Concat() and has the same signature. It is also used by the + operator, after trying the numeric addition via the nb_add slot.

ssizeargfunc PySequenceMethods.sq_repeat

This function is used by PySequence_Repeat() and has the same signature. It is also used by the * operator, after trying numeric multiplication via the nb_multiply slot.

ssizeargfunc PySequenceMethods.sq_item

This function is used by PySequence_GetItem() and has the same signature. It is also used by PyObject_GetItem(), after trying the subscription via the mp_subscript slot. This slot must be filled for the PySequence_Check() function to return 1, it can be NULL otherwise.

Negative indexes are handled as follows: if the sq_length slot is filled, it is called and the sequence length is used to compute a positive index which is passed to sq_item. If sq_length is NULL, the index is passed as is to the function.

ssizeobjargproc PySequenceMethods.sq_ass_item

This function is used by PySequence_SetItem() and has the same signature. It is also used by PyObject_SetItem() and PyObject_DelItem(), after trying the item assignment and deletion via the mp_ass_subscript slot. This slot may be left to NULL if the object does not support item assignment and deletion.

objobjproc PySequenceMethods.sq_contains

This function may be used by PySequence_Contains() and has the same signature. This slot may be left to NULL, in this case PySequence_Contains() simply traverses the sequence until it finds a match.

binaryfunc PySequenceMethods.sq_inplace_concat

This function is used by PySequence_InPlaceConcat() and has the same signature. It should modify its first operand, and return it. This slot may be left to NULL, in this case PySequence_InPlaceConcat() will fall back to PySequence_Concat(). It is also used by the augmented assignment +=, after trying numeric in-place addition via the nb_inplace_add slot.

ssizeargfunc PySequenceMethods.sq_inplace_repeat

This function is used by PySequence_InPlaceRepeat() and has the same signature. It should modify its first operand, and return it. This slot may be left to NULL, in this case PySequence_InPlaceRepeat() will fall back to PySequence_Repeat(). It is also used by the augmented assignment *=, after trying numeric in-place multiplication via the nb_inplace_multiply slot.

バッファオブジェクト構造体 (buffer object structure)

PyBufferProcs

この構造体は buffer プロトコル が要求する関数群へのポインタを保持しています。 そのプロトコルは、エクスポーターオブジェクトが如何にして、その内部データをコンシューマオブジェクトに渡すかを定義します。

getbufferproc PyBufferProcs.bf_getbuffer

この関数のシグネチャは以下の通りです:

int (PyObject *exporter, Py_buffer *view, int flags);

flags で指定された方法で view を埋めてほしいという exporter に対する要求を処理します。ステップ(3) を除いて、この関数の実装では以下のステップを行わなければなりません:

  1. Check if the request can be met. If not, raise PyExc_BufferError, set view->obj to NULL and return -1.

  2. 要求されたフィールドを埋めます。

  3. エクスポートした回数を保持する内部カウンタをインクリメントします。

  4. view->objexporter を設定し、 view->obj をインクリメントします。

  5. 0 を返します。

exporter がバッファプロバイダのチェインかツリーの一部であれば、2つの主要な方式が使用できます:

  • 再エクスポート: ツリーの各要素がエクスポートされるオブジェクトとして振る舞い、自身への新しい参照を view->obj へセットします。

  • リダイレクト: バッファ要求がツリーのルートオブジェクトにリダイレクトされます。ここでは、 view->obj はルートオブジェクトへの新しい参照になります。

view の個別のフィールドは バッファ構造体 の節で説明されており、エクスポートが特定の要求に対しどう対応しなければならないかの規則は、 バッファ要求のタイプ の節にあります。

Py_buffer 構造体の中から参照している全てのメモリはエクスポータに属し、コンシューマがいなくなるまで有効でなくてはなりません。 formatshapestridessuboffsetsinternal はコンシューマからは読み出し専用です。

PyBuffer_FillInfo() は、全てのリクエストタイプを正しく扱う際に、単純なバイトバッファを公開する簡単な方法を提供します。

PyObject_GetBuffer() は、この関数をラップするコンシューマ向けのインタフェースです。

releasebufferproc PyBufferProcs.bf_releasebuffer

この関数のシグネチャは以下の通りです:

void (PyObject *exporter, Py_buffer *view);

Handle a request to release the resources of the buffer. If no resources need to be released, PyBufferProcs.bf_releasebuffer may be NULL. Otherwise, a standard implementation of this function will take these optional steps:

  1. エクスポートした回数を保持する内部カウンタをデクリメントします。

  2. カウンタが 0 の場合は、view に関連付けられた全てのメモリを解放します。

エクスポータは、バッファ固有のリソースを監視し続けるために internal フィールドを使わなければなりません。このフィールドは、コンシューマが view 引数としてオリジナルのバッファのコピーを渡しているであろう間、変わらないことが保証されています。

この関数は、view->obj をデクリメントしてはいけません、なぜならそれは PyBuffer_Release() で自動的に行われるからです(この方式は参照の循環を防ぐのに有用です)。

PyBuffer_Release() は、この関数をラップするコンシューマ向けのインタフェースです。

async オブジェクト構造体

バージョン 3.5 で追加.

PyAsyncMethods

この構造体は awaitable オブジェクトと asynchronous iterator オブジェクトを実装するのに必要な関数へのポインタを保持しています。

以下は構造体の定義です:

typedef struct {
    unaryfunc am_await;
    unaryfunc am_aiter;
    unaryfunc am_anext;
} PyAsyncMethods;
unaryfunc PyAsyncMethods.am_await

この関数のシグネチャは以下の通りです:

PyObject *am_await(PyObject *self);

返されるオブジェクトはイテレータでなければなりません。 つまりこのオブジェクトに対して PyIter_Check()1 を返さなければなりません。

This slot may be set to NULL if an object is not an awaitable.

unaryfunc PyAsyncMethods.am_aiter

この関数のシグネチャは以下の通りです:

PyObject *am_aiter(PyObject *self);

awaitable オブジェクトを返さなければなりません。 詳しいことは __anext__() を参照してください。

This slot may be set to NULL if an object does not implement asynchronous iteration protocol.

unaryfunc PyAsyncMethods.am_anext

この関数のシグネチャは以下の通りです:

PyObject *am_anext(PyObject *self);

Must return an awaitable object. See __anext__() for details. This slot may be set to NULL.

Slot Type typedefs

PyObject *(*allocfunc)(PyTypeObject *cls, Py_ssize_t nitems)

この関数の目的は、メモリ確保をメモリ初期化から分離することにあります。この関数は、インスタンス用の的確なサイズ、適切なアラインメント、ゼロによる初期化がなされ、 ob_refcnt1 に、 ob_type を型引数 (type argument) にセットしたメモリブロックへのポインタを返さねばなりません。型の tp_itemsize がゼロでない場合、オブジェクトの ob_size フィールドは nitems に初期化され、確保されるメモリブロックの長さは tp_basicsize + nitems*tp_itemsizesizeof(void*) の倍数に切り上げた値になるはずです; それ以外の場合、 nitems の値は使われず、メモリブロックの長さは tp_basicsize になるはずです。

This function should not do any other instance initialization, not even to allocate additional memory; that should be done by tp_new.

void (*destructor)(PyObject *)
PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

See tp_vectorcall_offset.

Arguments to vectorcallfunc are the same as for _PyObject_Vectorcall().

バージョン 3.8 で追加.

void (*freefunc)(void *)

See tp_free.

PyObject *(*newfunc)(PyObject *, PyObject *, PyObject *)

See tp_new.

int (*initproc)(PyObject *, PyObject *, PyObject *)

See tp_init.

PyObject *(*reprfunc)(PyObject *)

See tp_repr.

PyObject *(*getattrfunc)(PyObject *self, char *attr)

Return the value of the named attribute for the object.

int (*setattrfunc)(PyObject *self, char *attr, PyObject *value)

Set the value of the named attribute for the object. The value argument is set to NULL to delete the attribute.

PyObject *(*getattrofunc)(PyObject *self, PyObject *attr)

Return the value of the named attribute for the object.

See tp_getattro.

int (*setattrofunc)(PyObject *self, PyObject *attr, PyObject *value)

Set the value of the named attribute for the object. The value argument is set to NULL to delete the attribute.

See tp_setattro.

PyObject *(*descrgetfunc)(PyObject *, PyObject *, PyObject *)

See tp_descrget.

int (*descrsetfunc)(PyObject *, PyObject *, PyObject *)

See tp_descrset.

Py_hash_t (*hashfunc)(PyObject *)

See tp_hash.

PyObject *(*richcmpfunc)(PyObject *, PyObject *, int)

See tp_richcompare.

PyObject *(*getiterfunc)(PyObject *)

See tp_iter.

PyObject *(*iternextfunc)(PyObject *)

See tp_iternext.

Py_ssize_t (*lenfunc)(PyObject *)
int (*getbufferproc)(PyObject *, Py_buffer *, int)
void (*releasebufferproc)(PyObject *, Py_buffer *)
PyObject *(*unaryfunc)(PyObject *)
PyObject *(*binaryfunc)(PyObject *, PyObject *)
PyObject *(*ternaryfunc)(PyObject *, PyObject *, PyObject *)
PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t)
int (*ssizeobjargproc)(PyObject *, Py_ssize_t)
int (*objobjproc)(PyObject *, PyObject *)
int (*objobjargproc)(PyObject *, PyObject *, PyObject *)

使用例

The following are simple examples of Python type definitions. They include common usage you may encounter. Some demonstrate tricky corner cases. For more examples, practical info, and a tutorial, see 拡張の型の定義: チュートリアル and Defining Extension Types: Assorted Topics.

A basic static type:

typedef struct {
    PyObject_HEAD
    const char *data;
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
    .tp_basicsize = sizeof(MyObject),
    .tp_doc = "My objects",
    .tp_new = myobj_new,
    .tp_dealloc = (destructor)myobj_dealloc,
    .tp_repr = (reprfunc)myobj_repr,
};

You may also find older code (especially in the CPython code base) with a more verbose initializer:

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    "mymod.MyObject",               /* tp_name */
    sizeof(MyObject),               /* tp_basicsize */
    0,                              /* tp_itemsize */
    (destructor)myobj_dealloc,      /* tp_dealloc */
    0,                              /* tp_vectorcall_offset */
    0,                              /* tp_getattr */
    0,                              /* tp_setattr */
    0,                              /* tp_as_async */
    (reprfunc)myobj_repr,           /* tp_repr */
    0,                              /* tp_as_number */
    0,                              /* tp_as_sequence */
    0,                              /* tp_as_mapping */
    0,                              /* tp_hash */
    0,                              /* tp_call */
    0,                              /* tp_str */
    0,                              /* tp_getattro */
    0,                              /* tp_setattro */
    0,                              /* tp_as_buffer */
    0,                              /* tp_flags */
    "My objects",                   /* tp_doc */
    0,                              /* tp_traverse */
    0,                              /* tp_clear */
    0,                              /* tp_richcompare */
    0,                              /* tp_weaklistoffset */
    0,                              /* tp_iter */
    0,                              /* tp_iternext */
    0,                              /* tp_methods */
    0,                              /* tp_members */
    0,                              /* tp_getset */
    0,                              /* tp_base */
    0,                              /* tp_dict */
    0,                              /* tp_descr_get */
    0,                              /* tp_descr_set */
    0,                              /* tp_dictoffset */
    0,                              /* tp_init */
    0,                              /* tp_alloc */
    myobj_new,                      /* tp_new */
};

A type that supports weakrefs, instance dicts, and hashing:

typedef struct {
    PyObject_HEAD
    const char *data;
    PyObject *inst_dict;
    PyObject *weakreflist;
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
    .tp_basicsize = sizeof(MyObject),
    .tp_doc = "My objects",
    .tp_weaklistoffset = offsetof(MyObject, weakreflist),
    .tp_dictoffset = offsetof(MyObject, inst_dict),
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
    .tp_new = myobj_new,
    .tp_traverse = (traverseproc)myobj_traverse,
    .tp_clear = (inquiry)myobj_clear,
    .tp_alloc = PyType_GenericNew,
    .tp_dealloc = (destructor)myobj_dealloc,
    .tp_repr = (reprfunc)myobj_repr,
    .tp_hash = (hashfunc)myobj_hash,
    .tp_richcompare = PyBaseObject_Type.tp_richcompare,
};

A str subclass that cannot be subclassed and cannot be called to create instances (e.g. uses a separate factory func):

typedef struct {
    PyUnicodeObject raw;
    char *extra;
} MyStr;

static PyTypeObject MyStr_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyStr",
    .tp_basicsize = sizeof(MyStr),
    .tp_base = NULL,  // set to &PyUnicode_Type in module init
    .tp_doc = "my custom str",
    .tp_flags = Py_TPFLAGS_DEFAULT,
    .tp_new = NULL,
    .tp_repr = (reprfunc)myobj_repr,
};

The simplest static type (with fixed-length instances):

typedef struct {
    PyObject_HEAD
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
};

The simplest static type (with variable-length instances):

typedef struct {
    PyObject_VAR_HEAD
    const char *data[1];
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
    .tp_basicsize = sizeof(MyObject) - sizeof(char *),
    .tp_itemsize = sizeof(char *),
};