diff options
| -rw-r--r-- | Doc/c-api/structures.rst | 103 |
1 files changed, 54 insertions, 49 deletions
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 489eaea..b654eb7 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -9,28 +9,29 @@ 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 -:ctype:`PyObject` and :ctype:`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. +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 +:ctype:`PyObject` and :ctype:`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. .. ctype:: 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. It corresponds to the fields defined - by the expansion of the ``PyObject_HEAD`` macro. + 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. It + corresponds to the fields defined by the expansion of the ``PyObject_HEAD`` + macro. .. ctype:: PyVarObject - This is an extension of :ctype:`PyObject` that adds the :attr:`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. It corresponds to the fields defined by - the expansion of the ``PyObject_VAR_HEAD`` macro. + This is an extension of :ctype:`PyObject` that adds the :attr:`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. It corresponds to the + fields defined by the expansion of the ``PyObject_VAR_HEAD`` macro. These macros are used in the definition of :ctype:`PyObject` and :ctype:`PyVarObject`: @@ -41,9 +42,9 @@ These macros are used in the definition of :ctype:`PyObject` and This is a macro which expands to the declarations of the fields of the :ctype:`PyObject` type; it is used when declaring new types which represent - objects without a varying length. The specific fields it expands to depend on - the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is not - defined, and :cmacro:`PyObject_HEAD` expands to:: + objects without a varying length. The specific fields it expands to depend + on the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is + not defined, and :cmacro:`PyObject_HEAD` expands to:: Py_ssize_t ob_refcnt; PyTypeObject *ob_type; @@ -58,9 +59,9 @@ These macros are used in the definition of :ctype:`PyObject` and .. cmacro:: PyObject_VAR_HEAD This is a macro which expands to the declarations of the fields of the - :ctype:`PyVarObject` type; it is used when declaring new types which represent - objects with a length that varies from instance to instance. This macro always - expands to:: + :ctype:`PyVarObject` type; it is used when declaring new types which + represent objects with a length that varies from instance to instance. + This macro always expands to:: PyObject_HEAD Py_ssize_t ob_size; @@ -73,11 +74,12 @@ These macros are used in the definition of :ctype:`PyObject` and .. ctype:: PyCFunction - Type of the functions used to implement most Python callables in C. Functions of - this type take two :ctype:`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. + Type of the functions used to implement most Python callables in C. + Functions of this type take two :ctype:`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. .. ctype:: PyCFunctionWithKeywords @@ -126,20 +128,21 @@ convention flags can be combined with a binding flag. .. data:: METH_VARARGS This is the typical calling convention, where the methods have the type - :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values. The - first one is the *self* object for methods; for module functions, it has the - value given to :cfunc:`Py_InitModule4` (or *NULL* if :cfunc:`Py_InitModule` was - used). The second parameter (often called *args*) is a tuple object - representing all arguments. This parameter is typically processed using - :cfunc:`PyArg_ParseTuple` or :cfunc:`PyArg_UnpackTuple`. + :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values. + The first one is the *self* object for methods; for module functions, it + has the value given to :cfunc:`Py_InitModule4` (or *NULL* if + :cfunc:`Py_InitModule` was used). The second parameter (often called + *args*) is a tuple object representing all arguments. This parameter is + typically processed using :cfunc:`PyArg_ParseTuple` or + :cfunc:`PyArg_UnpackTuple`. .. data:: METH_KEYWORDS - Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`. The - function expects three parameters: *self*, *args*, and a dictionary of all the - keyword arguments. The flag is typically combined with :const:`METH_VARARGS`, - and the parameters are typically processed using + Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`. + The function expects three parameters: *self*, *args*, and a dictionary of + all the keyword arguments. The flag is typically combined with + :const:`METH_VARARGS`, and the parameters are typically processed using :cfunc:`PyArg_ParseTupleAndKeywords`. @@ -148,8 +151,8 @@ convention flags can be combined with a binding flag. Methods without parameters don't need to check whether arguments are given if they are listed with the :const:`METH_NOARGS` flag. They need to be of type :ctype:`PyCFunction`. When used with object methods, the first parameter is - typically named ``self`` and will hold a reference to the object instance. In - all cases the second parameter will be *NULL*. + typically named ``self`` and will hold a reference to the object instance. + In all cases the second parameter will be *NULL*. .. data:: METH_O @@ -170,18 +173,19 @@ method. .. index:: builtin: classmethod - The method will be passed the type object as the first parameter rather than an - instance of the type. This is used to create *class methods*, similar to what - is created when using the :func:`classmethod` built-in function. + The method will be passed the type object as the first parameter rather + than an instance of the type. This is used to create *class methods*, + similar to what is created when using the :func:`classmethod` built-in + function. .. data:: METH_STATIC .. index:: builtin: staticmethod - The method will be passed *NULL* as the first parameter rather than an instance - of the type. This is used to create *static methods*, similar to what is - created when using the :func:`staticmethod` built-in function. + The method will be passed *NULL* as the first parameter rather than an + instance of the type. This is used to create *static methods*, similar to + what is created when using the :func:`staticmethod` built-in function. One other constant controls whether a method is loaded in place of another definition with the same method name. @@ -191,12 +195,13 @@ definition with the same method name. The method will be loaded in place of existing definitions. Without *METH_COEXIST*, the default is to skip repeated definitions. Since slot - wrappers are loaded before the method table, the existence of a *sq_contains* - slot, for example, would generate a wrapped method named :meth:`__contains__` - and preclude the loading of a corresponding PyCFunction with the same name. - With the flag defined, the PyCFunction will be loaded in place of the wrapper - object and will co-exist with the slot. This is helpful because calls to - PyCFunctions are optimized more than wrapper object calls. + wrappers are loaded before the method table, the existence of a + *sq_contains* slot, for example, would generate a wrapped method named + :meth:`__contains__` and preclude the loading of a corresponding + PyCFunction with the same name. With the flag defined, the PyCFunction + will be loaded in place of the wrapper object and will co-exist with the + slot. This is helpful because calls to PyCFunctions are optimized more + than wrapper object calls. .. ctype:: PyMemberDef |