通用物件結構¶

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.

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.

PyObject¶: 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*. Access to the members must be done by using the macros Py_REFCNT and Py_TYPE.

PyVarObject¶: This is an extension of PyObject that adds the ob_size field. This is only used for objects that have some notion of length. This type does not often appear in the Python/C API. Access to the members must be done by using the macros Py_REFCNT, Py_TYPE, and Py_SIZE.

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;

See documentation of PyObject above.

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;

See documentation of PyVarObject above.

Py_TYPE(o)¶

This macro is used to access the ob_type member of a Python object. It expands to:

(((PyObject*)(o))->ob_type)

Py_REFCNT(o)¶

This macro is used to access the ob_refcnt member of a Python object. It expands to:

(((PyObject*)(o))->ob_refcnt)

Py_SIZE(o)¶

This macro is used to access the ob_size member of a Python object. It expands to:

(((PyVarObject*)(o))->ob_size)

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,

PyCFunction¶: 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.

PyCFunctionWithKeywords¶: Type of the functions used to implement Python callables in C that take keyword arguments: they take three PyObject* parameters and return one such value. See PyCFunction above for the meaning of the return value.

PyMethodDef¶

Structure used to describe a method of an extension type. This structure has four fields:

Field	C Type	Meaning
`ml_name`	const char *	name of the method
`ml_meth`	PyCFunction	pointer to the C implementation
`ml_flags`	int	flag bits indicating how the call should be constructed
`ml_doc`	const char *	points to the contents of the docstring

The ml_meth is a C function pointer. The functions may be of different types, but they always return