diff options
Diffstat (limited to 'Doc/c-api/structures.rst')
| -rw-r--r-- | Doc/c-api/structures.rst | 92 |
1 files changed, 46 insertions, 46 deletions
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index dbacedf..bb741fb 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -11,12 +11,12 @@ 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, +:c:type:`PyObject` and :c:type:`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 +.. c:type:: 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 @@ -26,88 +26,88 @@ the definition of all other Python objects. macro. -.. ctype:: PyVarObject +.. c:type:: PyVarObject - This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size` + This is an extension of :c:type:`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`: +These macros are used in the definition of :c:type:`PyObject` and +:c:type:`PyVarObject`: .. XXX need to document PEP 3123 changes here -.. cmacro:: PyObject_HEAD +.. c:macro:: PyObject_HEAD 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 + :c:type:`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:: + on the definition of :c:macro:`Py_TRACE_REFS`. By default, that macro is + not defined, and :c:macro:`PyObject_HEAD` expands to:: Py_ssize_t ob_refcnt; PyTypeObject *ob_type; - When :cmacro:`Py_TRACE_REFS` is defined, it expands to:: + When :c:macro:`Py_TRACE_REFS` is defined, it expands to:: PyObject *_ob_next, *_ob_prev; Py_ssize_t ob_refcnt; PyTypeObject *ob_type; -.. cmacro:: PyObject_VAR_HEAD +.. c:macro:: 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 + :c:type:`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; - Note that :cmacro:`PyObject_HEAD` is part of the expansion, and that its own - expansion varies depending on the definition of :cmacro:`Py_TRACE_REFS`. + Note that :c:macro:`PyObject_HEAD` is part of the expansion, and that its own + expansion varies depending on the definition of :c:macro:`Py_TRACE_REFS`. -.. cmacro:: PyObject_HEAD_INIT(type) +.. c:macro:: PyObject_HEAD_INIT(type) This is a macro which expands to initialization values for a new - :ctype:`PyObject` type. This macro expands to:: + :c:type:`PyObject` type. This macro expands to:: _PyObject_EXTRA_INIT 1, type, -.. cmacro:: PyVarObject_HEAD_INIT(type, size) +.. c:macro:: PyVarObject_HEAD_INIT(type, size) This is a macro which expands to initialization values for a new - :ctype:`PyVarObject` type, including the :attr:`ob_size` field. + :c:type:`PyVarObject` type, including the :attr:`ob_size` field. This macro expands to:: _PyObject_EXTRA_INIT 1, type, size, -.. ctype:: PyCFunction +.. c:type:: PyCFunction Type of the functions used to implement most Python callables in C. - Functions of this type take two :ctype:`PyObject\*` parameters and return + Functions of this type take two :c:type:`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 +.. c:type:: PyCFunctionWithKeywords Type of the functions used to implement Python callables in C that take - keyword arguments: they take three :ctype:`PyObject\*` parameters and return - one such value. See :ctype:`PyCFunction` above for the meaning of the return + keyword arguments: they take three :c:type:`PyObject\*` parameters and return + one such value. See :c:type:`PyCFunction` above for the meaning of the return value. -.. ctype:: PyMethodDef +.. c:type:: PyMethodDef Structure used to describe a method of an extension type. This structure has four fields: @@ -128,10 +128,10 @@ These macros are used in the definition of :ctype:`PyObject` and +------------------+-------------+-------------------------------+ The :attr:`ml_meth` is a C function pointer. The functions may be of different -types, but they always return :ctype:`PyObject\*`. If the function is not of -the :ctype:`PyCFunction`, the compiler will require a cast in the method table. -Even though :ctype:`PyCFunction` defines the first parameter as -:ctype:`PyObject\*`, it is common that the method implementation uses a the +types, but they always return :c:type:`PyObject\*`. If the function is not of +the :c:type:`PyCFunction`, the compiler will require a cast in the method table. +Even though :c:type:`PyCFunction` defines the first parameter as +:c:type:`PyObject\*`, it is common that the method implementation uses a the specific C type of the *self* object. The :attr:`ml_flags` field is a bitfield which can include the following flags. @@ -145,27 +145,27 @@ 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. + :c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values. The first one is the *self* object for methods; for module functions, it is the module object. 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`. + using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`. .. data:: METH_KEYWORDS - Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`. + Methods with these flags must be of type :c:type:`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`. + :c:func:`PyArg_ParseTupleAndKeywords`. .. data:: METH_NOARGS 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`. The first parameter is typically named *self* and will + :c:type:`PyCFunction`. The first parameter is typically named *self* and will hold a reference to the module or object instance. In all cases the second parameter will be *NULL*. @@ -173,9 +173,9 @@ convention flags can be combined with a binding flag. .. data:: METH_O Methods with a single object argument can be listed with the :const:`METH_O` - flag, instead of invoking :cfunc:`PyArg_ParseTuple` with a ``"O"`` argument. - They have the type :ctype:`PyCFunction`, with the *self* parameter, and a - :ctype:`PyObject\*` parameter representing the single argument. + flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument. + They have the type :c:type:`PyCFunction`, with the *self* parameter, and a + :c:type:`PyObject\*` parameter representing the single argument. These two constants are not used to indicate the calling convention but the @@ -219,7 +219,7 @@ definition with the same method name. than wrapper object calls. -.. ctype:: PyMemberDef +.. c:type:: PyMemberDef Structure which describes an attribute of a type which corresponds to a C struct member. Its fields are: @@ -271,14 +271,14 @@ definition with the same method name. T_PYSSIZET Py_ssize_t =============== ================== - :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX` differ in that - :cmacro:`T_OBJECT` returns ``None`` if the member is *NULL* and - :cmacro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use - :cmacro:`T_OBJECT_EX` over :cmacro:`T_OBJECT` because :cmacro:`T_OBJECT_EX` + :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that + :c:macro:`T_OBJECT` returns ``None`` if the member is *NULL* and + :c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use + :c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX` handles use of the :keyword:`del` statement on that attribute more correctly - than :cmacro:`T_OBJECT`. + than :c:macro:`T_OBJECT`. - :attr:`flags` can be 0 for write and read access or :cmacro:`READONLY` for - read-only access. Using :cmacro:`T_STRING` for :attr:`type` implies - :cmacro:`READONLY`. Only :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX` + :attr:`flags` can be 0 for write and read access or :c:macro:`READONLY` for + read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies + :c:macro:`READONLY`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` members can be deleted. (They are set to *NULL*). |