通用物件結構

There are a large number of structures which are used in the definition of object types for Python. This section describes these structures and how they are used.

Base object types and macros

All Python objects ultimately share a small number of fields at the beginning of the object's representation in memory. These are represented by the PyObject and PyVarObject types, which are defined, in turn, by the expansions of some macros also used, whether directly or indirectly, in the definition of all other Python objects. Additional macros can be found under reference counting.

type PyObject

為 受限 API 的一部分. （只有部分成員是穩定 ABI 的一部分。）

All object types are extensions of this type. This is a type which contains the information Python needs to treat a pointer to an object as an object. In a normal "release" build, it contains only the object's reference count and a pointer to the corresponding type object. Nothing is actually declared to be a PyObject, but every pointer to a Python object can be cast to a PyObject*.

The members must not be accessed directly; instead use macros such as Py_REFCNT and Py_TYPE.

Py_ssize_t ob_refcnt

為 穩定 ABI 的一部分.

The object's reference count, as returned by Py_REFCNT. Do not use this field directly; instead use functions and macros such as Py_REFCNT, Py_INCREF() and Py_DecRef().

The field type may be different from Py_ssize_t, depending on build configuration and platform.

PyTypeObject *ob_type

為 穩定 ABI 的一部分.

The object's type. Do not use this field directly; use Py_TYPE and Py_SET_TYPE() instead.

type PyVarObject

為 受限 API 的一部分. （只有部分成員是穩定 ABI 的一部分。）

An extension of PyObject that adds the ob_size field. This is intended for objects that have some notion of length.

As with PyObject, the members must not be accessed directly; instead use macros such as Py_SIZE, Py_REFCNT and Py_TYPE.

Py_ssize_t ob_size

為 穩定 ABI 的一部分.

A size field, whose contents should be considered an object's internal implementation detail.

Do not use this field directly; use Py_SIZE instead.

Object creation functions such as PyObject_NewVar() will generally set this field to the requested size (number of items). After creation, arbitrary values can be stored in ob_size using Py_SET_SIZE.

To get an object's publicly exposed length, as returned by the Python function len(), use PyObject_Length() instead.

PyObject_HEAD

This is a macro used when declaring new types which represent objects without a varying length. The PyObject_HEAD macro expands to:

PyObject ob_base;

請見上面 PyObject 的文件。

PyObject_VAR_HEAD

This is a macro used when declaring new types which represent objects with a length that varies from instance to instance. The PyObject_VAR_HEAD macro expands to:

PyVarObject ob_base;

請見上面 PyVarObject 的文件。

PyTypeObject PyBaseObject_Type

為 穩定 ABI 的一部分.

The base class of all other objects, the same as object in Python.

int Py_Is(PyObject *x, PyObject *y)

為 穩定 ABI 的一部分 自 3.10 版本開始.

Test if the x object is the y object, the same as x is y in Python.

在 3.10 版被加入.

int Py_IsNone(PyObject *x)

為 穩定 ABI 的一部分 自 3.10 版本開始.

Test if an object is the None singleton, the same as x is None in Python.

在 3.10 版被加入.

int Py_IsTrue(PyObject *x)

為 穩定 ABI 的一部分 自 3.10 版本開始.

Test if an object is the True singleton, the same as x is True in Python.

在 3.10 版被加入.

int Py_IsFalse(PyObject *x)

為 穩定 ABI 的一部分 自 3.10 版本開始.

Test if an object is the False singleton, the same as x is False in Python.

在 3.10 版被加入.

PyTypeObject *Py_TYPE(PyObject *o)

回傳值：借用參照。 為 穩定 ABI 的一部分 自 3.14 版本開始.

Get the type of the Python object o.

The returned reference is borrowed from o. Do not release it with Py_DECREF() or similar.

在 3.11 版的變更: Py_TYPE() is changed to an inline static function. The parameter type is no longer const PyObject*.

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)

Return non-zero if the object o type is type. Return zero otherwise. Equivalent to: Py_TYPE(o) == type.

在 3.9 版被加入.

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)

Set the type of object o to type, without any checking or reference counting.

This is a very low-level operation. Consider instead setting the Python attribute __class__ using PyObject_SetAttrString() or similar.

Note that assigning an incompatible type can lead to undefined behavior.

If type is a heap type, the caller must create a new reference to it. Similarly, if the old type of o is a heap type, the caller must release a reference to that type.

在 3.9 版被加入.

Py_ssize_t Py_SIZE(PyVarObject *o)

Get the ob_size field of o.

在 3.11 版的變更: Py_SIZE() is changed to an inline static function. The parameter type is no longer const PyVarObject*.

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)

Set the ob_size field of o to size.

在 3.9 版被加入.

PyObject_HEAD_INIT(type)

This is a macro which expands to initialization values for a new PyObject type. This macro expands to:

_PyObject_EXTRA_INIT
1, type,

PyVarObject_HEAD_INIT(type, size)

This is a macro which expands to initialization values for a new PyVarObject type, including the ob_size field. This macro expands to:

_PyObject_EXTRA_INIT
1, type, size,

實作函式與方法

type PyCFunction

為 穩定 ABI 的一部分.

Type of the functions used to implement most Python callables in C. Functions of this type take two PyObject* parameters and return one such value. If the return value is NULL, an exception shall have been set. If not NULL, the return value is interpreted as the return value of the function as exposed in Python. The function must return a new reference.

The function signature is:

PyObject *PyCFunction(PyObject *self,
                      PyObject *args);

type PyCFunctionWithKeywords

為 穩定 ABI 的一部分.

Type of the functions used to implement Python callables in C with signature METH_VARARGS | METH_KEYWORDS. The function signature is:

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