Mirrors
/
cpython
mirror of https://github.com/python/cpython
3
0
Fork 0
Code Releases Activity
Browse Source

Issue #18589: fix hyperlinking of type slots (tp_*)

pull/224/head
Antoine Pitrou 13 years ago
parent
b3c872403d
commit
39668f57f4
9 changed files with 192 additions and 192 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 6
      Doc/c-api/allocation.rst
  2. 12
      Doc/c-api/exceptions.rst
  3. 28
      Doc/c-api/gcsupport.rst
  4. 10
      Doc/c-api/type.rst
  5. 218
      Doc/c-api/typeobj.rst
  6. 94
      Doc/extending/newtypes.rst
  7. 4
      Doc/library/gc.rst
  8. 6
      Doc/library/stdtypes.rst
  9. 6
      Doc/whatsnew/2.2.rst

6
Doc/c-api/allocation.rst
View File

@ -32,7 +32,7 @@ Allocating Objects on the Heap
Allocate a new Python object using the C structure type *TYPE* and the
Python type object *type*. Fields not defined by the Python object header
are not initialized; the object's reference count will be one. The size of
the memory allocation is determined from the :attr:`tp_basicsize` field of
the memory allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize` field of
the type object.
@ -41,7 +41,7 @@ Allocating Objects on the Heap
Allocate a new Python object using the C structure type *TYPE* and the
Python type object *type*. Fields not defined by the Python object header
are not initialized. The allocated memory allows for the *TYPE* structure
plus *size* fields of the size given by the :attr:`tp_itemsize` field of
plus *size* fields of the size given by the :c:member:`~PyTypeObject.tp_itemsize` field of
*type*. This is useful for implementing objects like tuples, which are
able to determine their size at construction time. Embedding the array of
fields into the same allocation decreases the number of allocations,
@ -52,7 +52,7 @@ Allocating Objects on the Heap
Releases memory allocated to an object using :c:func:`PyObject_New` or
:c:func:`PyObject_NewVar`. This is normally called from the
:attr:`tp_dealloc` handler specified in the object's type. The fields of
:c:member:`~PyTypeObject.tp_dealloc` handler specified in the object's type. The fields of
the object should not be accessed after this call as the memory is no
longer a valid Python object.

12
Doc/c-api/exceptions.rst
View File

@ -607,28 +607,28 @@ recursion depth automatically).
Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each
*successful* invocation of :c:func:`Py_EnterRecursiveCall`.
Properly implementing :attr:`tp_repr` for container types requires
Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
special recursion handling. In addition to protecting the stack,
:attr:`tp_repr` also needs to track objects to prevent cycles. The
:c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles. The
following two functions facilitate this functionality. Effectively,
these are the C equivalent to :func:`reprlib.recursive_repr`.
.. c:function:: int Py_ReprEnter(PyObject *object)
Called at the beginning of the :attr:`tp_repr` implementation to
Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` implementation to
detect cycles.
If the object has already been processed, the function returns a
positive integer. In that case the :attr:`tp_repr` implementation
positive integer. In that case the :c:member:`~PyTypeObject.tp_repr` implementation
should return a string object indicating a cycle. As examples,
:class:`dict` objects return ``{...}`` and :class:`list` objects
return ``[...]``.
The function will return a negative integer if the recursion limit
is reached. In that case the :attr:`tp_repr` implementation should
is reached. In that case the :c:member:`~PyTypeObject.tp_repr` implementation should
typically return ``NULL``.
Otherwise, the function returns zero and the :attr:`tp_repr`
Otherwise, the function returns zero and the :c:member:`~PyTypeObject.tp_repr`
implementation can continue normally.
.. c:function:: void Py_ReprLeave(PyObject *object)

28
Doc/c-api/gcsupport.rst
View File

@ -12,10 +12,10 @@ other objects, or which only store references to atomic types (such as numbers
or strings), do not need to provide any explicit support for garbage
collection.
To create a container type, the :attr:`tp_flags` field of the type object must
To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of the type object must
include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
:attr:`tp_traverse` handler. If instances of the type are mutable, a
:attr:`tp_clear` implementation must also be provided.
:c:member:`~PyTypeObject.tp_traverse` handler. If instances of the type are mutable, a
:c:member:`~PyTypeObject.tp_clear` implementation must also be provided.
.. data:: Py_TPFLAGS_HAVE_GC
@ -57,7 +57,7 @@ Constructors for container types must conform to two rules:
Adds the object *op* to the set of container objects tracked by the
collector. The collector can run at unexpected times so objects must be
valid while being tracked. This should be called once all the fields
followed by the :attr:`tp_traverse` handler become valid, usually near the
followed by the :c:member:`~PyTypeObject.tp_traverse` handler become valid, usually near the
end of the constructor.
@ -86,8 +86,8 @@ rules:
Remove the object *op* from the set of container objects tracked by the
collector. Note that :c:func:`PyObject_GC_Track` can be called again on
this object to add it back to the set of tracked objects. The deallocator
(:attr:`tp_dealloc` handler) should call this for the object before any of
the fields used by the :attr:`tp_traverse` handler become invalid.
(:c:member:`~PyTypeObject.tp_dealloc` handler) should call this for the object before any of
the fields used by the :c:member:`~PyTypeObject.tp_traverse` handler become invalid.
.. c:function:: void _PyObject_GC_UNTRACK(PyObject *op)
@ -95,19 +95,19 @@ rules:
A macro version of :c:func:`PyObject_GC_UnTrack`. It should not be used for
extension modules.
The :attr:`tp_traverse` handler accepts a function parameter of this type:
The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function parameter of this type:
.. c:type:: int (*visitproc)(PyObject *object, void *arg)
Type of the visitor function passed to the :attr:`tp_traverse` handler.
Type of the visitor function passed to the :c:member:`~PyTypeObject.tp_traverse` handler.
The function should be called with an object to traverse as *object* and
the third parameter to the :attr:`tp_traverse` handler as *arg*. The
the third parameter to the :c:member:`~PyTypeObject.tp_traverse` handler as *arg*. The
Python core uses several visitor functions to implement cyclic garbage
detection; it's not expected that users will need to write their own
visitor functions.
The :attr:`tp_traverse` handler must have the following type:
The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
.. c:type:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
@ -119,15 +119,15 @@ The :attr:`tp_traverse` handler must have the following type:
object argument. If *visit* returns a non-zero value that value should be
returned immediately.
To simplify writing :attr:`tp_traverse` handlers, a :c:func:`Py_VISIT` macro is
provided. In order to use this macro, the :attr:`tp_traverse` implementation
To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:func:`Py_VISIT` macro is
provided. In order to use this macro, the :c:member:`~PyTypeObject.tp_traverse` implementation
must name its arguments exactly *visit* and *arg*:
.. c:function:: void Py_VISIT(PyObject *o)
Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns
a non-zero value, then return it. Using this macro, :attr:`tp_traverse`
a non-zero value, then return it. Using this macro, :c:member:`~PyTypeObject.tp_traverse`
handlers look like::
static int
@ -138,7 +138,7 @@ must name its arguments exactly *visit* and *arg*:
return 0;
}
The :attr:`tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL*
The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL*
if the object is immutable.

10
Doc/c-api/type.rst
View File

@ -37,10 +37,10 @@ Type Objects
.. c:function:: long PyType_GetFlags(PyTypeObject* type)
Return the :attr:`tp_flags` member of *type*. This function is primarily
Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily
meant for use with `Py_LIMITED_API`; the individual flag bits are
guaranteed to be stable across Python releases, but access to
:attr:`tp_flags` itself is not part of the limited API.
:c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API.
.. versionadded:: 3.2
@ -70,14 +70,14 @@ Type Objects
.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
Generic handler for the :attr:`tp_alloc` slot of a type object. Use
Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type object. Use
Python's default memory allocation mechanism to allocate a new instance and
initialize all its contents to *NULL*.
.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
Generic handler for the :attr:`tp_new` slot of a type object. Create a
new instance using the type's :attr:`tp_alloc` slot.
Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type object. Create a
new instance using the type's :c:member:`~PyTypeObject.tp_alloc` slot.
.. c:function:: int PyType_Ready(PyTypeObject *type)

218
Doc/c-api/typeobj.rst
View File

@ -35,7 +35,7 @@ definition found there:
The type object structure extends the :c:type:`PyVarObject` structure. The
:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`,
usually called from a class statement). Note that :c:data:`PyType_Type` (the
metatype) initializes :attr:`tp_itemsize`, which means that its instances (i.e.
metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that its instances (i.e.
type objects) *must* have the :attr:`ob_size` field.
@ -102,7 +102,7 @@ type objects) *must* have the :attr:`ob_size` field.
should be just the type name. If the module is a submodule of a package, the
full package name is part of the full module name. For example, a type named
:class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P`
should have the :attr:`tp_name` initializer ``"P.Q.M.T"``.
should have the :c:member:`~PyTypeObject.tp_name` initializer ``"P.Q.M.T"``.
For dynamically allocated type objects, this should just be the type name, and
the module name explicitly stored in the type dict as the value for key
@ -113,7 +113,7 @@ type objects) *must* have the :attr:`ob_size` field.
attribute, and everything after the last dot is made accessible as the
:attr:`__name__` attribute.
If no dot is present, the entire :attr:`tp_name` field is made accessible as the
If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is made accessible as the
:attr:`__name__` attribute, and the :attr:`__module__` attribute is undefined
(unless explicitly set in the dictionary, as explained above). This means your
type will be impossible to pickle.
@ -127,13 +127,13 @@ type objects) *must* have the :attr:`ob_size` field.
These fields allow calculating the size in bytes of instances of the type.
There are two kinds of types: types with fixed-length instances have a zero
:attr:`tp_itemsize` field, types with variable-length instances have a non-zero
:attr:`tp_itemsize` field. For a type with fixed-length instances, all
instances have the same size, given in :attr:`tp_basicsize`.
:c:member:`~PyTypeObject.tp_itemsize` field, types with variable-length instances have a non-zero
:c:member:`~PyTypeObject.tp_itemsize` field. For a type with fixed-length instances, all
instances have the same size, given in :c:member:`~PyTypeObject.tp_basicsize`.
For a type with variable-length instances, the instances must have an
:attr:`ob_size` field, and the instance size is :attr:`tp_basicsize` plus N
times :attr:`tp_itemsize`, where N is the "length" of the object. The value of
:attr:`ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N
times :c:member:`~PyTypeObject.tp_itemsize`, where N is the "length" of the object. The value of
N is typically stored in the instance's :attr:`ob_size` field. There are
exceptions: for example, ints use a negative :attr:`ob_size` to indicate a
negative number, and N is ``abs(ob_size)`` there. Also, the presence of an
@ -146,20 +146,20 @@ type objects) *must* have the :attr:`ob_size` field.
:c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to
declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
:attr:`_ob_next` fields if they are present. This means that the only correct
way to get an initializer for the :attr:`tp_basicsize` is to use the
way to get an initializer for the :c:member:`~PyTypeObject.tp_basicsize` is to use the
``sizeof`` operator on the struct used to declare the instance layout.
The basic size does not include the GC header size.
These fields are inherited separately by subtypes. If the base type has a
non-zero :attr:`tp_itemsize`, it is generally not safe to set
:attr:`tp_itemsize` to a different non-zero value in a subtype (though this
non-zero :c:member:`~PyTypeObject.tp_itemsize`, it is generally not safe to set
:c:member:`~PyTypeObject.tp_itemsize` to a different non-zero value in a subtype (though this
depends on the implementation of the base type).
A note about alignment: if the variable items require a particular alignment,
this should be taken care of by the value of :attr:`tp_basicsize`. Example:
suppose a type implements an array of ``double``. :attr:`tp_itemsize` is
this should be taken care of by the value of :c:member:`~PyTypeObject.tp_basicsize`. Example:
suppose a type implements an array of ``double``. :c:member:`~PyTypeObject.tp_itemsize` is
``sizeof(double)``. It is the programmer's responsibility that
:attr:`tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the
:c:member:`~PyTypeObject.tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the
alignment requirement for ``double``).
@ -175,10 +175,10 @@ type objects) *must* have the :attr:`ob_size` field.
destructor function should free all references which the instance owns, free all
memory buffers owned by the instance (using the freeing function corresponding
to the allocation function used to allocate the buffer), and finally (as its
last action) call the type's :attr:`tp_free` function. If the type is not
last action) call the type's :c:member:`~PyTypeObject.tp_free` function. If the type is not
subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is
permissible to call the object deallocator directly instead of via
:attr:`tp_free`. The object deallocator should be the one used to allocate the
:c:member:`~PyTypeObject.tp_free`. The object deallocator should be the one used to allocate the
instance; this is normally :c:func:`PyObject_Del` if the instance was allocated
using :c:func:`PyObject_New` or :c:func:`PyObject_VarNew`, or
:c:func:`PyObject_GC_Del` if the instance was allocated using
@ -193,25 +193,25 @@ type objects) *must* have the :attr:`ob_size` field.
The print function is only called when the instance is printed to a *real* file;
when it is printed to a pseudo-file (like a :class:`StringIO` instance), the
instance's :attr:`tp_repr` or :attr:`tp_str` function is called to convert it to
a string. These are also called when the type's :attr:`tp_print` field is
*NULL*. A type should never implement :attr:`tp_print` in a way that produces
different output than :attr:`tp_repr` or :attr:`tp_str` would.
instance's :c:member:`~PyTypeObject.tp_repr` or :c:member:`~PyTypeObject.tp_str` function is called to convert it to
a string. These are also called when the type's :c:member:`~PyTypeObject.tp_print` field is
*NULL*. A type should never implement :c:member:`~PyTypeObject.tp_print` in a way that produces
different output than :c:member:`~PyTypeObject.tp_repr` or :c:member:`~PyTypeObject.tp_str` would.
The print function is called with the same signature as :c:func:`PyObject_Print`:
``int tp_print(PyObject *self, FILE *file, int flags)``. The *self* argument is
the instance to be printed. The *file* argument is the stdio file to which it
is to be printed. The *flags* argument is composed of flag bits. The only flag
bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW`
flag bit is set, the instance should be printed the same way as :attr:`tp_str`
flag bit is set, the instance should be printed the same way as :c:member:`~PyTypeObject.tp_str`
would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance
should be printed the same was as :attr:`tp_repr` would format it. It should
should be printed the same was as :c:member:`~PyTypeObject.tp_repr` would format it. It should
return ``-1`` and set an exception condition when an error occurred during the
comparison.
It is possible that the :attr:`tp_print` field will be deprecated. In any case,
it is recommended not to define :attr:`tp_print`, but instead to rely on
:attr:`tp_repr` and :attr:`tp_str` for printing.
It is possible that the :c:member:`~PyTypeObject.tp_print` field will be deprecated. In any case,
it is recommended not to define :c:member:`~PyTypeObject.tp_print`, but instead to rely on
:c:member:`~PyTypeObject.tp_repr` and :c:member:`~PyTypeObject.tp_str` for printing.
This field is inherited by subtypes.
@ -221,13 +221,13 @@ type objects) *must* have the :attr:`ob_size` field.
An optional pointer to the get-attribute-string function.
This field is deprecated. When it is defined, it should point to a function
that acts the same as the :attr:`tp_getattro` function, but taking a C string
that acts the same as the :c:member:`~PyTypeObject.tp_getattro` function, but taking a C string
instead of a Python string object to give the attribute name. The signature is
the same as for :c:func:`PyObject_GetAttrString`.
This field is inherited by subtypes together with :attr:`tp_getattro`: a subtype
inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when
the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattro`: a subtype
inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both *NULL*.
.. c:member:: setattrfunc PyTypeObject.tp_setattr
@ -235,13 +235,13 @@ type objects) *must* have the :attr:`ob_size` field.
An optional pointer to the set-attribute-string function.
This field is deprecated. When it is defined, it should point to a function
that acts the same as the :attr:`tp_setattro` function, but taking a C string
that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, but taking a C string
instead of a Python string object to give the attribute name. The signature is
the same as for :c:func:`PyObject_SetAttrString`.
This field is inherited by subtypes together with :attr:`tp_setattro`: a subtype
inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when
the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype
inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*.
.. c:member:: void* PyTypeObject.tp_reserved
@ -275,7 +275,7 @@ type objects) *must* have the :attr:`ob_size` field.
objects which implement the number protocol. These fields are documented in
:ref:`number-structs`.
The :attr:`tp_as_number` field is not inherited, but the contained fields are
The :c:member:`~PyTypeObject.tp_as_number` field is not inherited, but the contained fields are
inherited individually.
@ -285,7 +285,7 @@ type objects) *must* have the :attr:`ob_size` field.
objects which implement the sequence protocol. These fields are documented
in :ref:`sequence-structs`.
The :attr:`tp_as_sequence` field is not inherited, but the contained fields
The :c:member:`~PyTypeObject.tp_as_sequence` field is not inherited, but the contained fields
are inherited individually.
@ -295,7 +295,7 @@ type objects) *must* have the :attr:`ob_size` field.
objects which implement the mapping protocol. These fields are documented in
:ref:`mapping-structs`.
The :attr:`tp_as_mapping` field is not inherited, but the contained fields
The :c:member:`~PyTypeObject.tp_as_mapping` field is not inherited, but the contained fields
are inherited individually.
@ -323,9 +323,9 @@ type objects) *must* have the :attr:`ob_size` field.
object raises :exc:`TypeError`.
This field is inherited by subtypes together with
:attr:`tp_richcompare`: a subtype inherits both of
:attr:`tp_richcompare` and :attr:`tp_hash`, when the subtype's
:attr:`tp_richcompare` and :attr:`tp_hash` are both *NULL*.
:c:member:`~PyTypeObject.tp_richcompare`: a subtype inherits both of
:c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash`, when the subtype's
:c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both *NULL*.
.. c:member:: ternaryfunc PyTypeObject.tp_call
@ -363,9 +363,9 @@ type objects) *must* have the :attr:`ob_size` field.
convenient to set this field to :c:func:`PyObject_GenericGetAttr`, which
implements the normal way of looking for object attributes.
This field is inherited by subtypes together with :attr:`tp_getattr`: a subtype
inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when
the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattr`: a subtype
inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both *NULL*.
.. c:member:: setattrofunc PyTypeObject.tp_setattro
@ -376,9 +376,9 @@ type objects) *must* have the :attr:`ob_size` field.
convenient to set this field to :c:func:`PyObject_GenericSetAttr`, which
implements the normal way of setting object attributes.
This field is inherited by subtypes together with :attr:`tp_setattr`: a subtype
inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when
the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattr`: a subtype
inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*.
.. c:member:: PyBufferProcs* PyTypeObject.tp_as_buffer
@ -387,7 +387,7 @@ type objects) *must* have the :attr:`ob_size` field.
which implement the buffer interface. These fields are documented in
:ref:`buffer-structs`.
The :attr:`tp_as_buffer` field is not inherited, but the contained fields are
The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, but the contained fields are
inherited individually.
@ -396,8 +396,8 @@ type objects) *must* have the :attr:`ob_size` field.
This field is a bit mask of various flags. Some flags indicate variant
semantics for certain situations; others are used to indicate that certain
fields in the type object (or in the extension structures referenced via
:attr:`tp_as_number`, :attr:`tp_as_sequence`, :attr:`tp_as_mapping`, and
:attr:`tp_as_buffer`) that were historically not always present are valid; if
:c:member:`~PyTypeObject.tp_as_number`, :c:member:`~PyTypeObject.tp_as_sequence`, :c:member:`~PyTypeObject.tp_as_mapping`, and
:c:member:`~PyTypeObject.tp_as_buffer`) that were historically not always present are valid; if
such a flag bit is clear, the type fields it guards must not be accessed and
must be considered to have a zero or *NULL* value instead.
@ -407,13 +407,13 @@ type objects) *must* have the :attr:`ob_size` field.
inherited if the extension structure is inherited, i.e. the base type's value of
the flag bit is copied into the subtype together with a pointer to the extension
structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
the :attr:`tp_traverse` and :attr:`tp_clear` fields, i.e. if the
the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the
:const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
:attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist and have
:c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have
*NULL* values.
The following bit masks are currently defined; these can be ORed together using
the ``|`` operator to form the value of the :attr:`tp_flags` field. The macro
the ``|`` operator to form the value of the :c:member:`~PyTypeObject.tp_flags` field. The macro
:c:func:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and
checks whether ``tp->tp_flags & f`` is non-zero.
@ -453,7 +453,7 @@ type objects) *must* have the :attr:`ob_size` field.
is set, instances must be created using :c:func:`PyObject_GC_New` and
destroyed using :c:func:`PyObject_GC_Del`. More information in section
:ref:`supporting-cycle-detection`. This bit also implies that the
GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in
GC-related fields :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` are present in
the type object.
@ -481,8 +481,8 @@ type objects) *must* have the :attr:`ob_size` field.
about Python's garbage collection scheme can be found in section
:ref:`supporting-cycle-detection`.
The :attr:`tp_traverse` pointer is used by the garbage collector to detect
reference cycles. A typical implementation of a :attr:`tp_traverse` function
The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage collector to detect
reference cycles. A typical implementation of a :c:member:`~PyTypeObject.tp_traverse` function
simply calls :c:func:`Py_VISIT` on each of the instance's members that are Python
objects. For example, this is function :c:func:`local_traverse` from the
:mod:`_thread` extension module::
@ -508,9 +508,9 @@ type objects) *must* have the :attr:`ob_size` field.
:c:func:`local_traverse` to have these specific names; don't name them just
anything.
This field is inherited by subtypes together with :attr:`tp_clear` and the
:const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
:attr:`tp_clear` are all inherited from the base type if they are all zero in
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_clear` and the
:const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
:c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in
the subtype.
@ -519,17 +519,17 @@ type objects) *must* have the :attr:`ob_size` field.
An optional pointer to a clear function for the garbage collector. This is only
used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set.
The :attr:`tp_clear` member function is used to break reference cycles in cyclic
garbage detected by the garbage collector. Taken together, all :attr:`tp_clear`
The :c:member:`~PyTypeObject.tp_clear` member function is used to break reference cycles in cyclic
garbage detected by the garbage collector. Taken together, all :c:member:`~PyTypeObject.tp_clear`
functions in the system must combine to break all reference cycles. This is
subtle, and if in any doubt supply a :attr:`tp_clear` function. For example,
the tuple type does not implement a :attr:`tp_clear` function, because it's
subtle, and if in any doubt supply a :c:member:`~PyTypeObject.tp_clear` function. For example,
the tuple type does not implement a :c:member:`~PyTypeObject.tp_clear` function, because it's
possible to prove that no reference cycle can be composed entirely of tuples.
Therefore the :attr:`tp_clear` functions of other types must be sufficient to
Therefore the :c:member:`~PyTypeObject.tp_clear` functions of other types must be sufficient to
break any cycle containing a tuple. This isn't immediately obvious, and there's
rarely a good reason to avoid implementing :attr:`tp_clear`.
rarely a good reason to avoid implementing :c:member:`~PyTypeObject.tp_clear`.
Implementations of :attr:`tp_clear` should drop the instance's references to
Implementations of :c:member:`~PyTypeObject.tp_clear` should drop the instance's references to
those of its members that may be Python objects, and set its pointers to those
members to *NULL*, as in the following example::
@ -554,18 +554,18 @@ type objects) *must* have the :attr:`ob_size` field.
so that *self* knows the contained object can no longer be used. The
:c:func:`Py_CLEAR` macro performs the operations in a safe order.
Because the goal of :attr:`tp_clear` functions is to break reference cycles,
Because the goal of :c:member:`~PyTypeObject.tp_clear` functions is to break reference cycles,
it's not necessary to clear contained objects like Python strings or Python
integers, which can't participate in reference cycles. On the other hand, it may
be convenient to clear all contained Python objects, and write the type's
:attr:`tp_dealloc` function to invoke :attr:`tp_clear`.
:c:member:`~PyTypeObject.tp_dealloc` function to invoke :c:member:`~PyTypeObject.tp_clear`.
More information about Python's garbage collection scheme can be found in
section :ref:`supporting-cycle-detection`.
This field is inherited by subtypes together with :attr:`tp_traverse` and the
:const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
:attr:`tp_clear` are all inherited from the base type if they are all zero in
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_traverse` and the
:const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
:c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in
the subtype.
@ -585,13 +585,13 @@ type objects) *must* have the :attr:`ob_size` field.
comparisons makes sense (e.g. ``==`` and ``!=``, but not ``<`` and
friends), directly raise :exc:`TypeError` in the rich comparison function.
This field is inherited by subtypes together with :attr:`tp_hash`:
a subtype inherits :attr:`tp_richcompare` and :attr:`tp_hash` when
the subtype's :attr:`tp_richcompare` and :attr:`tp_hash` are both
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_hash`:
a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` when
the subtype's :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both
*NULL*.
The following constants are defined to be used as the third argument for
:attr:`tp_richcompare` and for :c:func:`PyObject_RichCompare`:
:c:member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`:
+----------------+------------+
| Constant | Comparison |
@ -619,26 +619,26 @@ type objects) *must* have the :attr:`ob_size` field.
instance structure needs to include a field of type :c:type:`PyObject\*` which is
initialized to *NULL*.
Do not confuse this field with :attr:`tp_weaklist`; that is the list head for
Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for
weak references to the type object itself.
This field is inherited by subtypes, but see the rules listed below. A subtype
may override this offset; this means that the subtype uses a different weak
reference list head than the base type. Since the list head is always found via
:attr:`tp_weaklistoffset`, this should not be a problem.
:c:member:`~PyTypeObject.tp_weaklistoffset`, this should not be a problem.
When a type defined by a class statement has no :attr:`__slots__` declaration,
and none of its base types are weakly referenceable, the type is made weakly
referenceable by adding a weak reference list head slot to the instance layout
and setting the :attr:`tp_weaklistoffset` of that slot's offset.
and setting the :c:member:`~PyTypeObject.tp_weaklistoffset` of that slot's offset.
When a type's :attr:`__slots__` declaration contains a slot named
:attr:`__weakref__`, that slot becomes the weak reference list head for
instances of the type, and the slot's offset is stored in the type's
:attr:`tp_weaklistoffset`.
:c:member:`~PyTypeObject.tp_weaklistoffset`.
When a type's :attr:`__slots__` declaration does not contain a slot named
:attr:`__weakref__`, the type inherits its :attr:`tp_weaklistoffset` from its
:attr:`__weakref__`, the type inherits its :c:member:`~PyTypeObject.tp_weaklistoffset` from its
base type.
.. c:member:: getiterfunc PyTypeObject.tp_iter
@ -660,7 +660,7 @@ type objects) *must* have the :attr:`ob_size` field.
*NULL* too. Its presence signals that the instances of this type are
iterators.
Iterator types should also define the :attr:`tp_iter` function, and that
Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` function, and that
function should return the iterator instance itself (not a new iterator
instance).
@ -675,7 +675,7 @@ type objects) *must* have the :attr:`ob_size` field.
structures, declaring regular methods of this type.
For each entry in the array, an entry is added to the type's dictionary (see
:attr:`tp_dict` below) containing a method descriptor.
:c:member:`~PyTypeObject.tp_dict` below) containing a method descriptor.
This field is not inherited by subtypes (methods are inherited through a
different mechanism).
@ -688,7 +688,7 @@ type objects) *must* have the :attr:`ob_size` field.
this type.
For each entry in the array, an entry is added to the type's dictionary (see
:attr:`tp_dict` below) containing a member descriptor.
:c:member:`~PyTypeObject.tp_dict` below) containing a member descriptor.
This field is not inherited by subtypes (members are inherited through a
different mechanism).
@ -700,7 +700,7 @@ type objects) *must* have the :attr:`ob_size` field.
structures, declaring computed attributes of instances of this type.
For each entry in the array, an entry is added to the type's dictionary (see
:attr:`tp_dict` below) containing a getset descriptor.
:c:member:`~PyTypeObject.tp_dict` below) containing a getset descriptor.
This field is not inherited by subtypes (computed attributes are inherited
through a different mechanism).
@ -748,7 +748,7 @@ type objects) *must* have the :attr:`ob_size` field.
.. warning::
It is not safe to use :c:func:`PyDict_SetItem` on or otherwise modify
:attr:`tp_dict` with the dictionary C-API.
:c:member:`~PyTypeObject.tp_dict` with the dictionary C-API.
.. c:member:: descrgetfunc PyTypeObject.tp_descr_get
@ -784,7 +784,7 @@ type objects) *must* have the :attr:`ob_size` field.
the instance variable dictionary; this offset is used by
:c:func:`PyObject_GenericGetAttr`.
Do not confuse this field with :attr:`tp_dict`; that is the dictionary for
Do not confuse this field with :c:member:`~PyTypeObject.tp_dict`; that is the dictionary for
attributes of the type object itself.
If the value of this field is greater than zero, it specifies the offset from
@ -793,20 +793,20 @@ type objects) *must* have the :attr:`ob_size` field.
offset is more expensive to use, and should only be used when the instance
structure contains a variable-length part. This is used for example to add an
instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note
that the :attr:`tp_basicsize` field should account for the dictionary added to
that the :c:member:`~PyTypeObject.tp_basicsize` field should account for the dictionary added to
the end in that case, even though the dictionary is not included in the basic
object layout. On a system with a pointer size of 4 bytes,
:attr:`tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is
:c:member:`~PyTypeObject.tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is
at the very end of the structure.
The real dictionary offset in an instance can be computed from a negative
:attr:`tp_dictoffset` as follows::
:c:member:`~PyTypeObject.tp_dictoffset` as follows::
dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
if dictoffset is not aligned on sizeof(void*):
round up to sizeof(void*)
where :attr:`tp_basicsize`, :attr:`tp_itemsize` and :attr:`tp_dictoffset` are
where :c:member:`~PyTypeObject.tp_basicsize`, :c:member:`~PyTypeObject.tp_itemsize` and :c:member:`~PyTypeObject.tp_dictoffset` are
taken from the type object, and :attr:`ob_size` is taken from the instance. The
absolute value is taken because ints use the sign of :attr:`ob_size` to
store the sign of the number. (There's never a need to do this calculation
@ -815,15 +815,15 @@ type objects) *must* have the :attr:`ob_size` field.
This field is inherited by subtypes, but see the rules listed below. A subtype
may override this offset; this means that the subtype instances store the
dictionary at a difference offset than the base type. Since the dictionary is
always found via :attr:`tp_dictoffset`, this should not be a problem.
always found via :c:member:`~PyTypeObject.tp_dictoffset`, this should not be a problem.
When a type defined by a class statement has no :attr:`__slots__` declaration,
and none of its base types has an instance variable dictionary, a dictionary
slot is added to the instance layout and the :attr:`tp_dictoffset` is set to
slot is added to the instance layout and the :c:member:`~PyTypeObject.tp_dictoffset` is set to
that slot's offset.
When a type defined by a class statement has a :attr:`__slots__` declaration,
the type inherits its :attr:`tp_dictoffset` from its base type.
the type inherits its :c:member:`~PyTypeObject.tp_dictoffset` from its base type.
(Adding a slot named :attr:`__dict__` to the :attr:`__slots__` declaration does
not have the expected effect, it just causes confusion. Maybe this should be
@ -847,12 +847,12 @@ type objects) *must* have the :attr:`ob_size` field.
arguments represent positional and keyword arguments of the call to
:meth:`__init__`.
The :attr:`tp_init` function, if not *NULL*, is called when an instance is
created normally by calling its type, after the type's :attr:`tp_new` function
has returned an instance of the type. If the :attr:`tp_new` function returns an
The :c:member:`~PyTypeObject.tp_init` function, if not *NULL*, is called when an instance is
created normally by calling its type, after the type's :c:member:`~PyTypeObject.tp_new` function
has returned an instance of the type. If the :c:member:`~PyTypeObject.tp_new` function returns an
instance of some other type that is not a subtype of the original type, no
:attr:`tp_init` function is called; if :attr:`tp_new` returns an instance of a
subtype of the original type, the subtype's :attr:`tp_init` is called.
:c:member:`~PyTypeObject.tp_init` function is called; if :c:member:`~PyTypeObject.tp_new` returns an instance of a
subtype of the original type, the subtype's :c:member:`~PyTypeObject.tp_init` is called.
This field is inherited by subtypes.
@ -869,14 +869,14 @@ type objects) *must* have the :attr:`ob_size` field.
initialization. It should return a pointer to a block of memory of adequate
length for the instance, suitably aligned, and initialized to zeros, but with
:attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If
the type's :attr:`tp_itemsize` is non-zero, the object's :attr:`ob_size` field
the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :attr:`ob_size` field
should be initialized to *nitems* and the length of the allocated memory block
should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of
``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block
should be :attr:`tp_basicsize`.
should be :c:member:`~PyTypeObject.tp_basicsize`.
Do not use this function to do any other instance initialization, not even to
allocate additional memory; that should be done by :attr:`tp_new`.
allocate additional memory; that should be done by :c:member:`~PyTypeObject.tp_new`.
This field is inherited by static subtypes, but not by dynamic subtypes
(subtypes created by a class statement); in the latter, this field is always set
@ -898,20 +898,20 @@ type objects) *must* have the :attr:`ob_size` field.
The subtype argument is the type of the object being created; the *args* and
*kwds* arguments represent positional and keyword arguments of the call to the
type. Note that subtype doesn't have to equal the type whose :attr:`tp_new`
type. Note that subtype doesn't have to equal the type whose :c:member:`~PyTypeObject.tp_new`
function is called; it may be a subtype of that type (but not an unrelated
type).
The :attr:`tp_new` function should call ``subtype->tp_alloc(subtype, nitems)``
The :c:member:`~PyTypeObject.tp_new` function should call ``subtype->tp_alloc(subtype, nitems)``
to allocate space for the object, and then do only as much further
initialization as is absolutely necessary. Initialization that can safely be
ignored or repeated should be placed in the :attr:`tp_init` handler. A good
ignored or repeated should be placed in the :c:member:`~PyTypeObject.tp_init` handler. A good
rule of thumb is that for immutable types, all initialization should take place
in :attr:`tp_new`, while for mutable types, most initialization should be
deferred to :attr:`tp_init`.
in :c:member:`~PyTypeObject.tp_new`, while for mutable types, most initialization should be
deferred to :c:member:`~PyTypeObject.tp_init`.
This field is inherited by subtypes, except it is not inherited by static types
whose :attr:`tp_base` is *NULL* or ``&PyBaseObject_Type``.
whose :c:member:`~PyTypeObject.tp_base` is *NULL* or ``&PyBaseObject_Type``.
.. c:member:: destructor PyTypeObject.tp_free
@ -935,7 +935,7 @@ type objects) *must* have the :attr:`ob_size` field.
The garbage collector needs to know whether a particular object is collectible
or not. Normally, it is sufficient to look at the object's type's
:attr:`tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But
:c:member:`~PyTypeObject.tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But
some types have a mixture of statically and dynamically allocated instances, and
the statically allocated instances are not collectible. Such types should
define this function; it should return ``1`` for a collectible instance, and
@ -1006,7 +1006,7 @@ subtypes.
.. c:member:: PyTypeObject* PyTypeObject.tp_next
Pointer to the next type object with a non-zero :attr:`tp_allocs` field.
Pointer to the next type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field.
Also, note that, in a garbage collected Python, tp_dealloc may be called from
any Python thread, not just the thread which created the object (if the object
@ -1145,13 +1145,13 @@ Sequence Object Structures
This function is used by :c:func:`PySequence_Concat` and has the same
signature. It is also used by the ``+`` operator, after trying the numeric
addition via the :attr:`tp_as_number.nb_add` slot.
addition via the :c:member:`~PyTypeObject.tp_as_number.nb_add` slot.
.. c:member:: ssizeargfunc PySequenceMethods.sq_repeat
This function is used by :c:func:`PySequence_Repeat` and has the same
signature. It is also used by the ``*`` operator, after trying numeric
multiplication via the :attr:`tp_as_number.nb_mul` slot.
multiplication via the :c:member:`~PyTypeObject.tp_as_number.nb_mul` slot.
.. c:member:: ssizeargfunc PySequenceMethods.sq_item

94
Doc/extending/newtypes.rst
View File

@ -135,11 +135,11 @@ This is so that Python knows how much memory to allocate when you call
.. note::
If you want your type to be subclassable from Python, and your type has the same
:attr:`tp_basicsize` as its base type, you may have problems with multiple
:c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have problems with multiple
inheritance. A Python subclass of your type will have to list your type first
in its :attr:`__bases__`, or else it will not be able to call your type's
:meth:`__new__` method without getting an error. You can avoid this problem by
ensuring that your type has a larger value for :attr:`tp_basicsize` than its
ensuring that your type has a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its
base type does. Most of the time, this will be true anyway, because either your
base type will be :class:`object`, or else you will be adding data members to
your base type, and therefore increasing its size.
@ -159,7 +159,7 @@ to :const:`Py_TPFLAGS_DEFAULT`. ::
All types should include this constant in their flags. It enables all of the
members defined by the current version of Python.
We provide a doc string for the type in :attr:`tp_doc`. ::
We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::
"Noddy objects", /* tp_doc */
@ -168,12 +168,12 @@ from the others. We aren't going to implement any of these in this version of
the module. We'll expand this example later to have more interesting behavior.
For now, all we want to be able to do is to create new :class:`Noddy` objects.
To enable object creation, we have to provide a :attr:`tp_new` implementation.
To enable object creation, we have to provide a :c:member:`~PyTypeObject.tp_new` implementation.
In this case, we can just use the default implementation provided by the API
function :c:func:`PyType_GenericNew`. We'd like to just assign this to the
:attr:`tp_new` slot, but we can't, for portability sake, On some platforms or
:c:member:`~PyTypeObject.tp_new` slot, but we can't, for portability sake, On some platforms or
compilers, we can't statically initialize a structure member with a function
defined in another C module, so, instead, we'll assign the :attr:`tp_new` slot
defined in another C module, so, instead, we'll assign the :c:member:`~PyTypeObject.tp_new` slot
in the module initialization function just before calling
:c:func:`PyType_Ready`::
@ -268,13 +268,13 @@ allocation and deallocation. At a minimum, we need a deallocation method::
Py_TYPE(self)->tp_free((PyObject*)self);
}
which is assigned to the :attr:`tp_dealloc` member::
which is assigned to the :c:member:`~PyTypeObject.tp_dealloc` member::
(destructor)Noddy_dealloc, /*tp_dealloc*/
This method decrements the reference counts of the two Python attributes. We use
:c:func:`Py_XDECREF` here because the :attr:`first` and :attr:`last` members
could be *NULL*. It then calls the :attr:`tp_free` member of the object's type
could be *NULL*. It then calls the :c:member:`~PyTypeObject.tp_free` member of the object's type
to free the object's memory. Note that the object's type might not be
:class:`NoddyType`, because the object may be an instance of a subclass.
@ -306,7 +306,7 @@ strings, so we provide a new method::
return (PyObject *)self;
}
and install it in the :attr:`tp_new` member::
and install it in the :c:member:`~PyTypeObject.tp_new` member::
Noddy_new, /* tp_new */
@ -326,17 +326,17 @@ any arguments passed when the type was called, and that returns the new object
created. New methods always accept positional and keyword arguments, but they
often ignore the arguments, leaving the argument handling to initializer
methods. Note that if the type supports subclassing, the type passed may not be
the type being defined. The new method calls the :attr:`tp_alloc` slot to
allocate memory. We don't fill the :attr:`tp_alloc` slot ourselves. Rather
the type being defined. The new method calls the :c:member:`~PyTypeObject.tp_alloc` slot to
allocate memory. We don't fill the :c:member:`~PyTypeObject.tp_alloc` slot ourselves. Rather
:c:func:`PyType_Ready` fills it for us by inheriting it from our base class,
which is :class:`object` by default. Most types use the default allocation.
.. note::
If you are creating a co-operative :attr:`tp_new` (one that calls a base type's
:attr:`tp_new` or :meth:`__new__`), you must *not* try to determine what method
If you are creating a co-operative :c:member:`~PyTypeObject.tp_new` (one that calls a base type's
:c:member:`~PyTypeObject.tp_new` or :meth:`__new__`), you must *not* try to determine what method
to call using method resolution order at runtime. Always statically determine
what type you are going to call, and call its :attr:`tp_new` directly, or via
what type you are going to call, and call its :c:member:`~PyTypeObject.tp_new` directly, or via
``type->tp_base->tp_new``. If you do not do this, Python subclasses of your
type that also inherit from other Python-defined classes may not work correctly.
(Specifically, you may not be able to create instances of such subclasses
@ -373,11 +373,11 @@ We provide an initialization function::
return 0;
}
by filling the :attr:`tp_init` slot. ::
by filling the :c:member:`~PyTypeObject.tp_init` slot. ::
(initproc)Noddy_init, /* tp_init */
The :attr:`tp_init` slot is exposed in Python as the :meth:`__init__` method. It
The :c:member:`~PyTypeObject.tp_init` slot is exposed in Python as the :meth:`__init__` method. It
is used to initialize an object after it's created. Unlike the new method, we
can't guarantee that the initializer is called. The initializer isn't called
when unpickling objects and it can be overridden. Our initializer accepts
@ -407,7 +407,7 @@ reference counts. When don't we have to do this?
* when we know that deallocation of the object [#]_ will not cause any calls
back into our type's code
* when decrementing a reference count in a :attr:`tp_dealloc` handler when
* when decrementing a reference count in a :c:member:`~PyTypeObject.tp_dealloc` handler when
garbage-collections is not supported [#]_
We want to expose our instance variables as attributes. There are a
@ -423,7 +423,7 @@ number of ways to do that. The simplest way is to define member definitions::
{NULL} /* Sentinel */
};
and put the definitions in the :attr:`tp_members` slot::
and put the definitions in the :c:member:`~PyTypeObject.tp_members` slot::
Noddy_members, /* tp_members */
@ -483,7 +483,7 @@ definitions::
{NULL} /* Sentinel */
};
and assign them to the :attr:`tp_methods` slot::
and assign them to the :c:member:`~PyTypeObject.tp_methods` slot::
Noddy_methods, /* tp_methods */
@ -578,7 +578,7 @@ We create an array of :c:type:`PyGetSetDef` structures::
{NULL} /* Sentinel */
};
and register it in the :attr:`tp_getset` slot::
and register it in the :c:member:`~PyTypeObject.tp_getset` slot::
Noddy_getseters, /* tp_getset */
@ -595,7 +595,7 @@ We also remove the member definitions for these attributes::
{NULL} /* Sentinel */
};
We also need to update the :attr:`tp_init` handler to only allow strings [#]_ to
We also need to update the :c:member:`~PyTypeObject.tp_init` handler to only allow strings [#]_ to
be passed::
static int
@ -713,7 +713,7 @@ functions. With :c:func:`Py_VISIT`, :c:func:`Noddy_traverse` can be simplified:
.. note::
Note that the :attr:`tp_traverse` implementation must name its arguments exactly
Note that the :c:member:`~PyTypeObject.tp_traverse` implementation must name its arguments exactly
*visit* and *arg* in order to use :c:func:`Py_VISIT`. This is to encourage
uniformity across these boring implementations.
@ -750,7 +750,7 @@ its reference count. We do this because, as was discussed earlier, if the
reference count drops to zero, we might cause code to run that calls back into
the object. In addition, because we now support garbage collection, we also
have to worry about code being run that triggers garbage collection. If garbage
collection is run, our :attr:`tp_traverse` handler could get called. We can't
collection is run, our :c:member:`~PyTypeObject.tp_traverse` handler could get called. We can't
take a chance of having :c:func:`Noddy_traverse` called when a member's reference
count has dropped to zero and its value hasn't been set to *NULL*.
@ -770,8 +770,8 @@ Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
That's pretty much it. If we had written custom :attr:`tp_alloc` or
:attr:`tp_free` slots, we'd need to modify them for cyclic-garbage collection.
That's pretty much it. If we had written custom :c:member:`~PyTypeObject.tp_alloc` or
:c:member:`~PyTypeObject.tp_free` slots, we'd need to modify them for cyclic-garbage collection.
Most extensions will use the versions automatically provided.
@ -830,8 +830,8 @@ the :attr:`__init__` method of the base type.
This pattern is important when writing a type with custom :attr:`new` and
:attr:`dealloc` methods. The :attr:`new` method should not actually create the
memory for the object with :attr:`tp_alloc`, that will be handled by the base
class when calling its :attr:`tp_new`.
memory for the object with :c:member:`~PyTypeObject.tp_alloc`, that will be handled by the base
class when calling its :c:member:`~PyTypeObject.tp_new`.
When filling out the :c:func:`PyTypeObject` for the :class:`Shoddy` type, you see
a slot for :c:func:`tp_base`. Due to cross platform compiler issues, you can't
@ -857,8 +857,8 @@ the module's :c:func:`init` function. ::
}
Before calling :c:func:`PyType_Ready`, the type structure must have the
:attr:`tp_base` slot filled in. When we are deriving a new type, it is not
necessary to fill out the :attr:`tp_alloc` slot with :c:func:`PyType_GenericNew`
:c:member:`~PyTypeObject.tp_base` slot filled in. When we are deriving a new type, it is not
necessary to fill out the :c:member:`~PyTypeObject.tp_alloc` slot with :c:func:`PyType_GenericNew`
-- the allocate function from the base type will be inherited.
After that, calling :c:func:`PyType_Ready` and adding the type object to the
@ -901,7 +901,7 @@ that will be helpful in such a situation! ::
These fields tell the runtime how much memory to allocate when new objects of
this type are created. Python has some built-in support for variable length
structures (think: strings, lists) which is where the :attr:`tp_itemsize` field
structures (think: strings, lists) which is where the :c:member:`~PyTypeObject.tp_itemsize` field
comes in. This will be dealt with later. ::
char *tp_doc;
@ -997,7 +997,7 @@ function just calls :func:`str`.) These handlers are both optional.
reprfunc tp_repr;
reprfunc tp_str;
The :attr:`tp_repr` handler should return a string object containing a
The :c:member:`~PyTypeObject.tp_repr` handler should return a string object containing a
representation of the instance for which it is called. Here is a simple
example::
@ -1008,15 +1008,15 @@ example::
obj->obj_UnderlyingDatatypePtr->size);
}
If no :attr:`tp_repr` handler is specified, the interpreter will supply a
representation that uses the type's :attr:`tp_name` and a uniquely-identifying
If no :c:member:`~PyTypeObject.tp_repr` handler is specified, the interpreter will supply a
representation that uses the type's :c:member:`~PyTypeObject.tp_name` and a uniquely-identifying
value for the object.
The :attr:`tp_str` handler is to :func:`str` what the :attr:`tp_repr` handler
The :c:member:`~PyTypeObject.tp_str` handler is to :func:`str` what the :c:member:`~PyTypeObject.tp_repr` handler
described above is to :func:`repr`; that is, it is called when Python code calls
:func:`str` on an instance of your object. Its implementation is very similar
to the :attr:`tp_repr` function, but the resulting string is intended for human
consumption. If :attr:`tp_str` is not specified, the :attr:`tp_repr` handler is
to the :c:member:`~PyTypeObject.tp_repr` function, but the resulting string is intended for human
consumption. If :c:member:`~PyTypeObject.tp_str` is not specified, the :c:member:`~PyTypeObject.tp_repr` handler is
used instead.
Here is a simple example::
@ -1081,7 +1081,7 @@ type object to create :term:`descriptor`\s which are placed in the dictionary of
type object. Each descriptor controls access to one attribute of the instance
object. Each of the tables is optional; if all three are *NULL*, instances of
the type will only have attributes that are inherited from their base type, and
should leave the :attr:`tp_getattro` and :attr:`tp_setattro` fields *NULL* as
should leave the :c:member:`~PyTypeObject.tp_getattro` and :c:member:`~PyTypeObject.tp_setattro` fields *NULL* as
well, allowing the base type to handle attributes.
The tables are declared as three fields of the type object::
@ -1090,7 +1090,7 @@ The tables are declared as three fields of the type object::
struct PyMemberDef *tp_members;
struct PyGetSetDef *tp_getset;
If :attr:`tp_methods` is not *NULL*, it must refer to an array of
If :c:member:`~PyTypeObject.tp_methods` is not *NULL*, it must refer to an array of
:c:type:`PyMethodDef` structures. Each entry in the table is an instance of this
structure::
@ -1146,13 +1146,13 @@ combined using bitwise-OR.
single: WRITE_RESTRICTED
single: RESTRICTED
An interesting advantage of using the :attr:`tp_members` table to build
An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` table to build
descriptors that are used at runtime is that any attribute defined this way can
have an associated doc string simply by providing the text in the table. An
application can use the introspection API to retrieve the descriptor from the
class object, and get the doc string using its :attr:`__doc__` attribute.
As with the :attr:`tp_methods` table, a sentinel entry with a :attr:`name` value
As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :attr:`name` value
of *NULL* is required.
.. XXX Descriptors need to be explained in more detail somewhere, but not here.
@ -1176,7 +1176,7 @@ support added in Python 2.2. It explains how the handler functions are
called, so that if you do need to extend their functionality, you'll understand
what needs to be done.
The :attr:`tp_getattr` handler is called when the object requires an attribute
The :c:member:`~PyTypeObject.tp_getattr` handler is called when the object requires an attribute
look-up. It is called in the same situations where the :meth:`__getattr__`
method of a class would be called.
@ -1196,11 +1196,11 @@ Here is an example::
return NULL;
}
The :attr:`tp_setattr` handler is called when the :meth:`__setattr__` or
The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:`__setattr__` or
:meth:`__delattr__` method of a class instance would be called. When an
attribute should be deleted, the third parameter will be *NULL*. Here is an
example that simply raises an exception; if this were really all you wanted, the
:attr:`tp_setattr` handler should be set to *NULL*. ::
:c:member:`~PyTypeObject.tp_setattr` handler should be set to *NULL*. ::
static int
newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
@ -1216,7 +1216,7 @@ Object Comparison
richcmpfunc tp_richcompare;
The :attr:`tp_richcompare` handler is called when comparisons are needed. It is
The :c:member:`~PyTypeObject.tp_richcompare` handler is called when comparisons are needed. It is
analogous to the :ref:`rich comparison methods <richcmpfuncs>`, like
:meth:`__lt__`, and also called by :c:func:`PyObject_RichCompare` and
:c:func:`PyObject_RichCompareBool`.
@ -1307,7 +1307,7 @@ instance of your data type. Here is a moderately pointless example::
This function is called when an instance of your data type is "called", for
example, if ``obj1`` is an instance of your data type and the Python script
contains ``obj1('hello')``, the :attr:`tp_call` handler is invoked.
contains ``obj1('hello')``, the :c:member:`~PyTypeObject.tp_call` handler is invoked.
This function takes three arguments:
@ -1394,7 +1394,7 @@ those objects which do not benefit by weak referencing (such as numbers).
For an object to be weakly referencable, the extension must include a
:c:type:`PyObject\*` field in the instance structure for the use of the weak
reference mechanism; it must be initialized to *NULL* by the object's
constructor. It must also set the :attr:`tp_weaklistoffset` field of the
constructor. It must also set the :c:member:`~PyTypeObject.tp_weaklistoffset` field of the
corresponding type object to the offset of the field. For example, the instance
type is defined with the following structure::
@ -1480,7 +1480,7 @@ might be something like the following::
.. [#] This is true when we know that the object is a basic type, like a string or a
float.
.. [#] We relied on this in the :attr:`tp_dealloc` handler in this example, because our
.. [#] We relied on this in the :c:member:`~PyTypeObject.tp_dealloc` handler in this example, because our
type doesn't support garbage collection. Even if a type supports garbage
collection, there are calls that can be made to "untrack" the object from
garbage collection, however, these calls are advanced and not covered here.

4
Doc/library/gc.rst
View File

@ -121,8 +121,8 @@ The :mod:`gc` module provides the following functions:
Return a list of objects directly referred to by any of the arguments. The
referents returned are those objects visited by the arguments' C-level
:attr:`tp_traverse` methods (if any), and may not be all objects actually
directly reachable. :attr:`tp_traverse` methods are supported only by objects
:c:member:`~PyTypeObject.tp_traverse` methods (if any), and may not be all objects actually
directly reachable. :c:member:`~PyTypeObject.tp_traverse` methods are supported only by objects
that support garbage collection, and are only required to visit objects that may
be involved in a cycle. So, for example, if an integer is directly reachable
from an argument, that integer object may or may not appear in the result list.

6
Doc/library/stdtypes.rst
View File

@ -751,7 +751,7 @@ support:
iterators for those iteration types. (An example of an object supporting
multiple forms of iteration would be a tree structure which supports both
breadth-first and depth-first traversal.) This method corresponds to the
:attr:`tp_iter` slot of the type structure for Python objects in the Python/C
:c:member:`~PyTypeObject.tp_iter` slot of the type structure for Python objects in the Python/C
API.
The iterator objects themselves are required to support the following two
@ -762,7 +762,7 @@ methods, which together form the :dfn:`iterator protocol`:
Return the iterator object itself. This is required to allow both containers
and iterators to be used with the :keyword:`for` and :keyword:`in` statements.
This method corresponds to the :attr:`tp_iter` slot of the type structure for
This method corresponds to the :c:member:`~PyTypeObject.tp_iter` slot of the type structure for
Python objects in the Python/C API.
@ -770,7 +770,7 @@ methods, which together form the :dfn:`iterator protocol`:
Return the next item from the container. If there are no further items, raise
the :exc:`StopIteration` exception. This method corresponds to the
:attr:`tp_iternext` slot of the type structure for Python objects in the
:c:member:`~PyTypeObject.tp_iternext` slot of the type structure for Python objects in the
Python/C API.
Python defines several iterator objects to support iteration over general and

6
Doc/whatsnew/2.2.rst
View File

@ -450,9 +450,9 @@ signal that the iterator is done.
Python classes can define an :meth:`__iter__` method, which should create and
return a new iterator for the object; if the object is its own iterator, this
method can just return ``self``. In particular, iterators will usually be their
own iterators. Extension types implemented in C can implement a :attr:`tp_iter`
own iterators. Extension types implemented in C can implement a :c:member:`~PyTypeObject.tp_iter`
function in order to return an iterator, and extension types that want to behave
as iterators can define a :attr:`tp_iternext` function.
as iterators can define a :c:member:`~PyTypeObject.tp_iternext` function.
So, after all this, what do iterators actually do? They have one required
method, :meth:`next`, which takes no arguments and returns the next value. When
@ -478,7 +478,7 @@ there are no more values to be returned, calling :meth:`next` should raise the
In 2.2, Python's :keyword:`for` statement no longer expects a sequence; it
expects something for which :func:`iter` will return an iterator. For backward
compatibility and convenience, an iterator is automatically constructed for
sequences that don't implement :meth:`__iter__` or a :attr:`tp_iter` slot, so
sequences that don't implement :meth:`__iter__` or a :c:member:`~PyTypeObject.tp_iter` slot, so
``for i in [1,2,3]`` will still work. Wherever the Python interpreter loops
over a sequence, it's been changed to use the iterator protocol. This means you
can do things like this::

Write Preview
Loading…
Cancel
Save