Changeset 391 for python/trunk/Doc/c-api/structures.rst
- Timestamp:
- Mar 19, 2014, 11:31:01 PM (11 years ago)
- Location:
- python/trunk
- Files:
-
- 2 edited
-
. (modified) (1 prop)
-
Doc/c-api/structures.rst (modified) (14 diffs)
Legend:
- Unmodified
- Added
- Removed
-
python/trunk
-
Property svn:mergeinfo
set to
/python/vendor/Python-2.7.6 merged eligible /python/vendor/current merged eligible
-
Property svn:mergeinfo
set to
-
python/trunk/Doc/c-api/structures.rst
r2 r391 12 12 All Python objects ultimately share a small number of fields at the beginning 13 13 of the object's representation in memory. These are represented by the 14 :c type:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn,14 :c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn, 15 15 by the expansions of some macros also used, whether directly or indirectly, in 16 16 the definition of all other Python objects. 17 17 18 18 19 .. c type:: PyObject19 .. c:type:: PyObject 20 20 21 21 All object types are extensions of this type. This is a type which … … 27 27 28 28 29 .. c type:: PyVarObject30 31 This is an extension of :c type:`PyObject` that adds the :attr:`ob_size`29 .. c:type:: PyVarObject 30 31 This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size` 32 32 field. This is only used for objects that have some notion of *length*. 33 33 This type does not often appear in the Python/C API. It corresponds to the 34 34 fields defined by the expansion of the ``PyObject_VAR_HEAD`` macro. 35 35 36 These macros are used in the definition of :c type:`PyObject` and37 :c type:`PyVarObject`:38 39 40 .. c macro:: PyObject_HEAD36 These macros are used in the definition of :c:type:`PyObject` and 37 :c:type:`PyVarObject`: 38 39 40 .. c:macro:: PyObject_HEAD 41 41 42 42 This is a macro which expands to the declarations of the fields of the 43 :c type:`PyObject` type; it is used when declaring new types which represent43 :c:type:`PyObject` type; it is used when declaring new types which represent 44 44 objects without a varying length. The specific fields it expands to depend 45 on the definition of :c macro:`Py_TRACE_REFS`. By default, that macro is46 not defined, and :c macro:`PyObject_HEAD` expands to::45 on the definition of :c:macro:`Py_TRACE_REFS`. By default, that macro is 46 not defined, and :c:macro:`PyObject_HEAD` expands to:: 47 47 48 48 Py_ssize_t ob_refcnt; 49 49 PyTypeObject *ob_type; 50 50 51 When :c macro:`Py_TRACE_REFS` is defined, it expands to::51 When :c:macro:`Py_TRACE_REFS` is defined, it expands to:: 52 52 53 53 PyObject *_ob_next, *_ob_prev; … … 56 56 57 57 58 .. c macro:: PyObject_VAR_HEAD58 .. c:macro:: PyObject_VAR_HEAD 59 59 60 60 This is a macro which expands to the declarations of the fields of the 61 :c type:`PyVarObject` type; it is used when declaring new types which61 :c:type:`PyVarObject` type; it is used when declaring new types which 62 62 represent objects with a length that varies from instance to instance. 63 63 This macro always expands to:: … … 66 66 Py_ssize_t ob_size; 67 67 68 Note that :c macro:`PyObject_HEAD` is part of the expansion, and that its own69 expansion varies depending on the definition of :c macro:`Py_TRACE_REFS`.70 71 72 .. c macro:: PyObject_HEAD_INIT(type)68 Note that :c:macro:`PyObject_HEAD` is part of the expansion, and that its own 69 expansion varies depending on the definition of :c:macro:`Py_TRACE_REFS`. 70 71 72 .. c:macro:: PyObject_HEAD_INIT(type) 73 73 74 74 This is a macro which expands to initialization values for a new 75 :c type:`PyObject` type. This macro expands to::75 :c:type:`PyObject` type. This macro expands to:: 76 76 77 77 _PyObject_EXTRA_INIT … … 79 79 80 80 81 .. c macro:: PyVarObject_HEAD_INIT(type, size)81 .. c:macro:: PyVarObject_HEAD_INIT(type, size) 82 82 83 83 This is a macro which expands to initialization values for a new 84 :c type:`PyVarObject` type, including the :attr:`ob_size` field.84 :c:type:`PyVarObject` type, including the :attr:`ob_size` field. 85 85 This macro expands to:: 86 86 … … 89 89 90 90 91 .. c type:: PyCFunction91 .. c:type:: PyCFunction 92 92 93 93 Type of the functions used to implement most Python callables in C. 94 Functions of this type take two :c type:`PyObject\*` parameters and return94 Functions of this type take two :c:type:`PyObject\*` parameters and return 95 95 one such value. If the return value is *NULL*, an exception shall have 96 96 been set. If not *NULL*, the return value is interpreted as the return … … 99 99 100 100 101 .. c type:: PyMethodDef101 .. c:type:: PyMethodDef 102 102 103 103 Structure used to describe a method of an extension type. This structure has … … 120 120 121 121 The :attr:`ml_meth` is a C function pointer. The functions may be of different 122 types, but they always return :c type:`PyObject\*`. If the function is not of123 the :c type:`PyCFunction`, the compiler will require a cast in the method table.124 Even though :c type:`PyCFunction` defines the first parameter as125 :c type:`PyObject\*`, it is common that the method implementation uses a the122 types, but they always return :c:type:`PyObject\*`. If the function is not of 123 the :c:type:`PyCFunction`, the compiler will require a cast in the method table. 124 Even though :c:type:`PyCFunction` defines the first parameter as 125 :c:type:`PyObject\*`, it is common that the method implementation uses a the 126 126 specific C type of the *self* object. 127 127 … … 137 137 138 138 This is the typical calling convention, where the methods have the type 139 :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values. 140 The first one is the *self* object for methods; for module functions, it 141 has the value given to :cfunc:`Py_InitModule4` (or *NULL* if 142 :cfunc:`Py_InitModule` was used). The second parameter (often called 143 *args*) is a tuple object representing all arguments. This parameter is 144 typically processed using :cfunc:`PyArg_ParseTuple` or 145 :cfunc:`PyArg_UnpackTuple`. 139 :c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values. 140 The first one is the *self* object for methods; for module functions, it is 141 the module object. The second parameter (often called *args*) is a tuple 142 object representing all arguments. This parameter is typically processed 143 using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`. 146 144 147 145 148 146 .. data:: METH_KEYWORDS 149 147 150 Methods with these flags must be of type :c type:`PyCFunctionWithKeywords`.148 Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`. 151 149 The function expects three parameters: *self*, *args*, and a dictionary of 152 150 all the keyword arguments. The flag is typically combined with 153 151 :const:`METH_VARARGS`, and the parameters are typically processed using 154 :c func:`PyArg_ParseTupleAndKeywords`.152 :c:func:`PyArg_ParseTupleAndKeywords`. 155 153 156 154 … … 159 157 Methods without parameters don't need to check whether arguments are given if 160 158 they are listed with the :const:`METH_NOARGS` flag. They need to be of type 161 :c type:`PyCFunction`. When used with object methods, the first parameter is162 typically named ``self`` and will hold a reference to the object instance.163 In all cases thesecond parameter will be *NULL*.159 :c:type:`PyCFunction`. The first parameter is typically named ``self`` and 160 will hold a reference to the module or object instance. In all cases the 161 second parameter will be *NULL*. 164 162 165 163 … … 167 165 168 166 Methods with a single object argument can be listed with the :const:`METH_O` 169 flag, instead of invoking :c func:`PyArg_ParseTuple` with a ``"O"`` argument.170 They have the type :c type:`PyCFunction`, with the *self* parameter, and a171 :c type:`PyObject\*` parameter representing the single argument.167 flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument. 168 They have the type :c:type:`PyCFunction`, with the *self* parameter, and a 169 :c:type:`PyObject\*` parameter representing the single argument. 172 170 173 171 … … 175 173 176 174 This calling convention is deprecated. The method must be of type 177 :c type:`PyCFunction`. The second argument is *NULL* if no arguments are175 :c:type:`PyCFunction`. The second argument is *NULL* if no arguments are 178 176 given, a single object if exactly one argument is given, and a tuple of 179 177 objects if more than one argument is given. There is no way for a function … … 228 226 229 227 230 .. c type:: PyMemberDef228 .. c:type:: PyMemberDef 231 229 232 230 Structure which describes an attribute of a type which corresponds to a C … … 280 278 =============== ================== 281 279 282 :c macro:`T_OBJECT` and :cmacro:`T_OBJECT_EX` differ in that283 :c macro:`T_OBJECT` returns ``None`` if the member is *NULL* and284 :c macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use285 :c macro:`T_OBJECT_EX` over :cmacro:`T_OBJECT` because :cmacro:`T_OBJECT_EX`280 :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that 281 :c:macro:`T_OBJECT` returns ``None`` if the member is *NULL* and 282 :c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use 283 :c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX` 286 284 handles use of the :keyword:`del` statement on that attribute more correctly 287 than :c macro:`T_OBJECT`.288 289 :attr:`flags` can be 0 for write and read access or :c macro:`READONLY` for290 read-only access. Using :c macro:`T_STRING` for :attr:`type` implies291 :c macro:`READONLY`. Only :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX`285 than :c:macro:`T_OBJECT`. 286 287 :attr:`flags` can be 0 for write and read access or :c:macro:`READONLY` for 288 read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies 289 :c:macro:`READONLY`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` 292 290 members can be deleted. (They are set to *NULL*). 293 291 294 292 295 .. c function:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name)293 .. c:function:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name) 296 294 297 295 Return a bound method object for an extension type implemented in C. This 298 can be useful in the implementation of a : attr:`tp_getattro` or299 : attr:`tp_getattr` handler that does not use the300 :c func:`PyObject_GenericGetAttr` function.296 can be useful in the implementation of a :c:member:`~PyTypeObject.tp_getattro` or 297 :c:member:`~PyTypeObject.tp_getattr` handler that does not use the 298 :c:func:`PyObject_GenericGetAttr` function.
Note:
See TracChangeset
for help on using the changeset viewer.
