[Python-checkins] r71981 - in python/branches/py3k: Doc/c-api/structures.rst
jeroen.ruigrok
python-checkins at python.org
Sun Apr 26 22:21:12 CEST 2009
Author: jeroen.ruigrok
Date: Sun Apr 26 22:21:12 2009
New Revision: 71981
Log:
Merged revisions 71873 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r71873 | jeroen.ruigrok | 2009-04-25 13:15:06 +0200 (za, 25 apr 2009) | 2 lines
Reformat prior to expanding.
........
Modified:
python/branches/py3k/ (props changed)
python/branches/py3k/Doc/c-api/structures.rst
Modified: python/branches/py3k/Doc/c-api/structures.rst
==============================================================================
--- python/branches/py3k/Doc/c-api/structures.rst (original)
+++ python/branches/py3k/Doc/c-api/structures.rst Sun Apr 26 22:21:12 2009
@@ -9,28 +9,29 @@
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 @@
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 @@
.. 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 @@
.. 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 @@
.. 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 @@
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 @@
.. 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 @@
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
More information about the Python-checkins
mailing list