1459 lines
66 KiB
ReStructuredText
1459 lines
66 KiB
ReStructuredText
.. highlightlang:: c
|
|
|
|
.. _type-structs:
|
|
|
|
Type Objects
|
|
============
|
|
|
|
Perhaps one of the most important structures of the Python object system is the
|
|
structure that defines a new type: the :c:type:`PyTypeObject` structure. Type
|
|
objects can be handled using any of the :c:func:`PyObject_\*` or
|
|
:c:func:`PyType_\*` functions, but do not offer much that's interesting to most
|
|
Python applications. These objects are fundamental to how objects behave, so
|
|
they are very important to the interpreter itself and to any extension module
|
|
that implements new types.
|
|
|
|
Type objects are fairly large compared to most of the standard types. The reason
|
|
for the size is that each type object stores a large number of values, mostly C
|
|
function pointers, each of which implements a small part of the type's
|
|
functionality. The fields of the type object are examined in detail in this
|
|
section. The fields will be described in the order in which they occur in the
|
|
structure.
|
|
|
|
Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
|
|
intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor,
|
|
freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc,
|
|
cmpfunc, reprfunc, hashfunc
|
|
|
|
The structure definition for :c:type:`PyTypeObject` can be found in
|
|
:file:`Include/object.h`. For convenience of reference, this repeats the
|
|
definition found there:
|
|
|
|
.. literalinclude:: ../includes/typestruct.h
|
|
|
|
|
|
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 :c:member:`~PyTypeObject.tp_itemsize`, which means that its instances (i.e.
|
|
type objects) *must* have the :attr:`ob_size` field.
|
|
|
|
|
|
.. c:member:: PyObject* PyObject._ob_next
|
|
PyObject* PyObject._ob_prev
|
|
|
|
These fields are only present when the macro ``Py_TRACE_REFS`` is defined.
|
|
Their initialization to *NULL* is taken care of by the ``PyObject_HEAD_INIT``
|
|
macro. For statically allocated objects, these fields always remain *NULL*.
|
|
For dynamically allocated objects, these two fields are used to link the object
|
|
into a doubly-linked list of *all* live objects on the heap. This could be used
|
|
for various debugging purposes; currently the only use is to print the objects
|
|
that are still alive at the end of a run when the environment variable
|
|
:envvar:`PYTHONDUMPREFS` is set.
|
|
|
|
These fields are not inherited by subtypes.
|
|
|
|
|
|
.. c:member:: Py_ssize_t PyObject.ob_refcnt
|
|
|
|
This is the type object's reference count, initialized to ``1`` by the
|
|
``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects,
|
|
the type's instances (objects whose :attr:`ob_type` points back to the type) do
|
|
*not* count as references. But for dynamically allocated type objects, the
|
|
instances *do* count as references.
|
|
|
|
This field is not inherited by subtypes.
|
|
|
|
.. versionchanged:: 2.5
|
|
This field used to be an :c:type:`int` type. This might require changes
|
|
in your code for properly supporting 64-bit systems.
|
|
|
|
|
|
.. c:member:: PyTypeObject* PyObject.ob_type
|
|
|
|
This is the type's type, in other words its metatype. It is initialized by the
|
|
argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be
|
|
``&PyType_Type``. However, for dynamically loadable extension modules that must
|
|
be usable on Windows (at least), the compiler complains that this is not a valid
|
|
initializer. Therefore, the convention is to pass *NULL* to the
|
|
``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the
|
|
start of the module's initialization function, before doing anything else. This
|
|
is typically done like this::
|
|
|
|
Foo_Type.ob_type = &PyType_Type;
|
|
|
|
This should be done before any instances of the type are created.
|
|
:c:func:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so,
|
|
initializes it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1
|
|
and later it is initialized to the :attr:`ob_type` field of the base class.
|
|
:c:func:`PyType_Ready` will not change this field if it is non-zero.
|
|
|
|
In Python 2.2, this field is not inherited by subtypes. In 2.2.1, and in 2.3
|
|
and beyond, it is inherited by subtypes.
|
|
|
|
|
|
.. c:member:: Py_ssize_t PyVarObject.ob_size
|
|
|
|
For statically allocated type objects, this should be initialized to zero. For
|
|
dynamically allocated type objects, this field has a special internal meaning.
|
|
|
|
This field is not inherited by subtypes.
|
|
|
|
|
|
.. c:member:: char* PyTypeObject.tp_name
|
|
|
|
Pointer to a NUL-terminated string containing the name of the type. For types
|
|
that are accessible as module globals, the string should be the full module
|
|
name, followed by a dot, followed by the type name; for built-in types, it
|
|
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 :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
|
|
``'__module__'``.
|
|
|
|
For statically allocated type objects, the tp_name field should contain a dot.
|
|
Everything before the last dot is made accessible as the :attr:`__module__`
|
|
attribute, and everything after the last dot is made accessible as the
|
|
:attr:`~definition.__name__` attribute.
|
|
|
|
If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is made accessible as the
|
|
:attr:`~definition.__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. Additionally, it will not be listed in
|
|
module documentations created with pydoc.
|
|
|
|
This field is not inherited by subtypes.
|
|
|
|
|
|
.. c:member:: Py_ssize_t PyTypeObject.tp_basicsize
|
|
Py_ssize_t PyTypeObject.tp_itemsize
|
|
|
|
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
|
|
: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 :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, long ints use a negative :attr:`ob_size` to indicate a
|
|
negative number, and N is ``abs(ob_size)`` there. Also, the presence of an
|
|
:attr:`ob_size` field in the instance layout doesn't mean that the instance
|
|
structure is variable-length (for example, the structure for the list type has
|
|
fixed-length instances, yet those instances have a meaningful :attr:`ob_size`
|
|
field).
|
|
|
|
The basic size includes the fields in the instance declared by the macro
|
|
: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 :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 (this is new in Python 2.2;
|
|
in 2.1 and 2.0, the GC header size was included in :c:member:`~PyTypeObject.tp_basicsize`).
|
|
|
|
These fields are inherited separately by subtypes. If the base type has a
|
|
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 :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
|
|
:c:member:`~PyTypeObject.tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the
|
|
alignment requirement for ``double``).
|
|
|
|
|
|
.. c:member:: destructor PyTypeObject.tp_dealloc
|
|
|
|
A pointer to the instance destructor function. This function must be defined
|
|
unless the type guarantees that its instances will never be deallocated (as is
|
|
the case for the singletons ``None`` and ``Ellipsis``).
|
|
|
|
The destructor function is called by the :c:func:`Py_DECREF` and
|
|
:c:func:`Py_XDECREF` macros when the new reference count is zero. At this point,
|
|
the instance is still in existence, but there are no references to it. The
|
|
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 :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
|
|
: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
|
|
:c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`.
|
|
|
|
This field is inherited by subtypes.
|
|
|
|
|
|
.. c:member:: printfunc PyTypeObject.tp_print
|
|
|
|
An optional pointer to the instance print function.
|
|
|
|
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.StringIO` instance), the
|
|
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 :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 :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 :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.
|
|
|
|
|
|
.. c:member:: getattrfunc PyTypeObject.tp_getattr
|
|
|
|
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 :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 ::
|
|
|
|
PyObject * tp_getattr(PyObject *o, char *attr_name);
|
|
|
|
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
|
|
|
|
An optional pointer to the function for setting and deleting attributes.
|
|
|
|
This field is deprecated. When it is defined, it should point to a function
|
|
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 ::
|
|
|
|
PyObject * tp_setattr(PyObject *o, char *attr_name, PyObject *v);
|
|
|
|
The *v* argument is set to *NULL* to delete the attribute.
|
|
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:: cmpfunc PyTypeObject.tp_compare
|
|
|
|
An optional pointer to the three-way comparison function.
|
|
|
|
The signature is the same as for :c:func:`PyObject_Compare`. The function should
|
|
return ``1`` if *self* greater than *other*, ``0`` if *self* is equal to
|
|
*other*, and ``-1`` if *self* less than *other*. It should return ``-1`` and
|
|
set an exception condition when an error occurred during the comparison.
|
|
|
|
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_richcompare` and
|
|
:c:member:`~PyTypeObject.tp_hash`: a subtypes inherits all three of :c:member:`~PyTypeObject.tp_compare`,
|
|
:c:member:`~PyTypeObject.tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash` when the subtype's
|
|
:c:member:`~PyTypeObject.tp_compare`, :c:member:`~PyTypeObject.tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash` are all *NULL*.
|
|
|
|
|
|
.. c:member:: reprfunc PyTypeObject.tp_repr
|
|
|
|
.. index:: builtin: repr
|
|
|
|
An optional pointer to a function that implements the built-in function
|
|
:func:`repr`.
|
|
|
|
The signature is the same as for :c:func:`PyObject_Repr`; it must return a string
|
|
or a Unicode object. Ideally, this function should return a string that, when
|
|
passed to :func:`eval`, given a suitable environment, returns an object with the
|
|
same value. If this is not feasible, it should return a string starting with
|
|
``'<'`` and ending with ``'>'`` from which both the type and the value of the
|
|
object can be deduced.
|
|
|
|
When this field is not set, a string of the form ``<%s object at %p>`` is
|
|
returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's
|
|
memory address.
|
|
|
|
This field is inherited by subtypes.
|
|
|
|
.. c:member:: PyNumberMethods* tp_as_number
|
|
|
|
Pointer to an additional structure that contains fields relevant only to
|
|
objects which implement the number protocol. These fields are documented in
|
|
:ref:`number-structs`.
|
|
|
|
The :c:member:`~PyTypeObject.tp_as_number` field is not inherited, but the contained fields are
|
|
inherited individually.
|
|
|
|
|
|
.. c:member:: PySequenceMethods* tp_as_sequence
|
|
|
|
Pointer to an additional structure that contains fields relevant only to
|
|
objects which implement the sequence protocol. These fields are documented
|
|
in :ref:`sequence-structs`.
|
|
|
|
The :c:member:`~PyTypeObject.tp_as_sequence` field is not inherited, but the contained fields
|
|
are inherited individually.
|
|
|
|
|
|
.. c:member:: PyMappingMethods* tp_as_mapping
|
|
|
|
Pointer to an additional structure that contains fields relevant only to
|
|
objects which implement the mapping protocol. These fields are documented in
|
|
:ref:`mapping-structs`.
|
|
|
|
The :c:member:`~PyTypeObject.tp_as_mapping` field is not inherited, but the contained fields
|
|
are inherited individually.
|
|
|
|
|
|
.. c:member:: hashfunc PyTypeObject.tp_hash
|
|
|
|
.. index:: builtin: hash
|
|
|
|
An optional pointer to a function that implements the built-in function
|
|
:func:`hash`.
|
|
|
|
The signature is the same as for :c:func:`PyObject_Hash`; it must return a C
|
|
long. The value ``-1`` should not be returned as a normal return value; when an
|
|
error occurs during the computation of the hash value, the function should set
|
|
an exception and return ``-1``.
|
|
|
|
This field can be set explicitly to :c:func:`PyObject_HashNotImplemented` to
|
|
block inheritance of the hash method from a parent type. This is interpreted
|
|
as the equivalent of ``__hash__ = None`` at the Python level, causing
|
|
``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note
|
|
that the converse is also true - setting ``__hash__ = None`` on a class at
|
|
the Python level will result in the ``tp_hash`` slot being set to
|
|
:c:func:`PyObject_HashNotImplemented`.
|
|
|
|
When this field is not set, two possibilities exist: if the :c:member:`~PyTypeObject.tp_compare`
|
|
and :c:member:`~PyTypeObject.tp_richcompare` fields are both *NULL*, a default hash value based on
|
|
the object's address is returned; otherwise, a :exc:`TypeError` is raised.
|
|
|
|
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_richcompare` and
|
|
:c:member:`~PyTypeObject.tp_compare`: a subtypes inherits all three of :c:member:`~PyTypeObject.tp_compare`,
|
|
:c:member:`~PyTypeObject.tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash`, when the subtype's
|
|
:c:member:`~PyTypeObject.tp_compare`, :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are all *NULL*.
|
|
|
|
|
|
.. c:member:: ternaryfunc PyTypeObject.tp_call
|
|
|
|
An optional pointer to a function that implements calling the object. This
|
|
should be *NULL* if the object is not callable. The signature is the same as
|
|
for :c:func:`PyObject_Call`.
|
|
|
|
This field is inherited by subtypes.
|
|
|
|
|
|
.. c:member:: reprfunc PyTypeObject.tp_str
|
|
|
|
An optional pointer to a function that implements the built-in operation
|
|
:func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls the
|
|
constructor for that type. This constructor calls :c:func:`PyObject_Str` to do
|
|
the actual work, and :c:func:`PyObject_Str` will call this handler.)
|
|
|
|
The signature is the same as for :c:func:`PyObject_Str`; it must return a string
|
|
or a Unicode object. This function should return a "friendly" string
|
|
representation of the object, as this is the representation that will be used by
|
|
the print statement.
|
|
|
|
When this field is not set, :c:func:`PyObject_Repr` is called to return a string
|
|
representation.
|
|
|
|
This field is inherited by subtypes.
|
|
|
|
|
|
.. c:member:: getattrofunc PyTypeObject.tp_getattro
|
|
|
|
An optional pointer to the get-attribute function.
|
|
|
|
The signature is the same as for :c:func:`PyObject_GetAttr`. It is usually
|
|
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 :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
|
|
|
|
An optional pointer to the function for setting and deleting attributes.
|
|
|
|
The signature is the same as for :c:func:`PyObject_SetAttr`, but setting
|
|
*v* to *NULL* to delete an attribute must be supported. It is usually
|
|
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 :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
|
|
|
|
Pointer to an additional structure that contains fields relevant only to objects
|
|
which implement the buffer interface. These fields are documented in
|
|
:ref:`buffer-structs`.
|
|
|
|
The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, but the contained fields are
|
|
inherited individually.
|
|
|
|
|
|
.. c:member:: long PyTypeObject.tp_flags
|
|
|
|
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
|
|
: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.
|
|
|
|
Inheritance of this field is complicated. Most flag bits are inherited
|
|
individually, i.e. if the base type has a flag bit set, the subtype inherits
|
|
this flag bit. The flag bits that pertain to extension structures are strictly
|
|
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 :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
|
|
:c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist (as
|
|
indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) 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 :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.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
|
|
|
|
If this bit is set, the :c:type:`PyBufferProcs` struct referenced by
|
|
:c:member:`~PyTypeObject.tp_as_buffer` has the :attr:`bf_getcharbuffer` field.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN
|
|
|
|
If this bit is set, the :c:type:`PySequenceMethods` struct referenced by
|
|
:c:member:`~PyTypeObject.tp_as_sequence` has the :attr:`sq_contains` field.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_GC
|
|
|
|
This bit is obsolete. The bit it used to name is no longer in use. The symbol
|
|
is now defined as zero.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_HAVE_INPLACEOPS
|
|
|
|
If this bit is set, the :c:type:`PySequenceMethods` struct referenced by
|
|
:c:member:`~PyTypeObject.tp_as_sequence` and the :c:type:`PyNumberMethods` structure referenced by
|
|
:c:member:`~PyTypeObject.tp_as_number` contain the fields for in-place operators. In particular,
|
|
this means that the :c:type:`PyNumberMethods` structure has the fields
|
|
:attr:`nb_inplace_add`, :attr:`nb_inplace_subtract`,
|
|
:attr:`nb_inplace_multiply`, :attr:`nb_inplace_divide`,
|
|
:attr:`nb_inplace_remainder`, :attr:`nb_inplace_power`,
|
|
:attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :attr:`nb_inplace_and`,
|
|
:attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; and the
|
|
:c:type:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and
|
|
:attr:`sq_inplace_repeat`.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_CHECKTYPES
|
|
|
|
If this bit is set, the binary and ternary operations in the
|
|
:c:type:`PyNumberMethods` structure referenced by :c:member:`~PyTypeObject.tp_as_number` accept
|
|
arguments of arbitrary object types, and do their own type conversions if
|
|
needed. If this bit is clear, those operations require that all arguments have
|
|
the current type as their type, and the caller is supposed to perform a coercion
|
|
operation first. This applies to :attr:`nb_add`, :attr:`nb_subtract`,
|
|
:attr:`nb_multiply`, :attr:`nb_divide`, :attr:`nb_remainder`, :attr:`nb_divmod`,
|
|
:attr:`nb_power`, :attr:`nb_lshift`, :attr:`nb_rshift`, :attr:`nb_and`,
|
|
:attr:`nb_xor`, and :attr:`nb_or`.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_HAVE_RICHCOMPARE
|
|
|
|
If this bit is set, the type object has the :c:member:`~PyTypeObject.tp_richcompare` field, as
|
|
well as the :c:member:`~PyTypeObject.tp_traverse` and the :c:member:`~PyTypeObject.tp_clear` fields.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_HAVE_WEAKREFS
|
|
|
|
If this bit is set, the :c:member:`~PyTypeObject.tp_weaklistoffset` field is defined. Instances
|
|
of a type are weakly referenceable if the type's :c:member:`~PyTypeObject.tp_weaklistoffset` field
|
|
has a value greater than zero.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_HAVE_ITER
|
|
|
|
If this bit is set, the type object has the :c:member:`~PyTypeObject.tp_iter` and
|
|
:c:member:`~PyTypeObject.tp_iternext` fields.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_HAVE_CLASS
|
|
|
|
If this bit is set, the type object has several new fields defined starting in
|
|
Python 2.2: :c:member:`~PyTypeObject.tp_methods`, :c:member:`~PyTypeObject.tp_members`, :c:member:`~PyTypeObject.tp_getset`,
|
|
:c:member:`~PyTypeObject.tp_base`, :c:member:`~PyTypeObject.tp_dict`, :c:member:`~PyTypeObject.tp_descr_get`, :c:member:`~PyTypeObject.tp_descr_set`,
|
|
:c:member:`~PyTypeObject.tp_dictoffset`, :c:member:`~PyTypeObject.tp_init`, :c:member:`~PyTypeObject.tp_alloc`, :c:member:`~PyTypeObject.tp_new`,
|
|
:c:member:`~PyTypeObject.tp_free`, :c:member:`~PyTypeObject.tp_is_gc`, :c:member:`~PyTypeObject.tp_bases`, :c:member:`~PyTypeObject.tp_mro`,
|
|
:c:member:`~PyTypeObject.tp_cache`, :c:member:`~PyTypeObject.tp_subclasses`, and :c:member:`~PyTypeObject.tp_weaklist`.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_HEAPTYPE
|
|
|
|
This bit is set when the type object itself is allocated on the heap. In this
|
|
case, the :attr:`ob_type` field of its instances is considered a reference to
|
|
the type, and the type object is INCREF'ed when a new instance is created, and
|
|
DECREF'ed when an instance is destroyed (this does not apply to instances of
|
|
subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
|
|
DECREF'ed).
|
|
|
|
|
|
.. data:: Py_TPFLAGS_BASETYPE
|
|
|
|
This bit is set when the type can be used as the base type of another type. If
|
|
this bit is clear, the type cannot be subtyped (similar to a "final" class in
|
|
Java).
|
|
|
|
|
|
.. data:: Py_TPFLAGS_READY
|
|
|
|
This bit is set when the type object has been fully initialized by
|
|
:c:func:`PyType_Ready`.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_READYING
|
|
|
|
This bit is set while :c:func:`PyType_Ready` is in the process of initializing
|
|
the type object.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_HAVE_GC
|
|
|
|
This bit is set when the object supports garbage collection. If this bit
|
|
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 :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` are present in
|
|
the type object; but those fields also exist when
|
|
:const:`Py_TPFLAGS_HAVE_GC` is clear but
|
|
:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_DEFAULT
|
|
|
|
This is a bitmask of all the bits that pertain to the existence of certain
|
|
fields in the type object and its extension structures. Currently, it includes
|
|
the following bits: :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`,
|
|
:const:`Py_TPFLAGS_HAVE_SEQUENCE_IN`, :const:`Py_TPFLAGS_HAVE_INPLACEOPS`,
|
|
:const:`Py_TPFLAGS_HAVE_RICHCOMPARE`, :const:`Py_TPFLAGS_HAVE_WEAKREFS`,
|
|
:const:`Py_TPFLAGS_HAVE_ITER`, and :const:`Py_TPFLAGS_HAVE_CLASS`.
|
|
|
|
|
|
.. c:member:: char* PyTypeObject.tp_doc
|
|
|
|
An optional pointer to a NUL-terminated C string giving the docstring for this
|
|
type object. This is exposed as the :attr:`__doc__` attribute on the type and
|
|
instances of the type.
|
|
|
|
This field is *not* inherited by subtypes.
|
|
|
|
The following three fields only exist if the
|
|
:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set.
|
|
|
|
|
|
.. c:member:: traverseproc PyTypeObject.tp_traverse
|
|
|
|
An optional pointer to a traversal function for the garbage collector. This is
|
|
only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. More information
|
|
about Python's garbage collection scheme can be found in section
|
|
:ref:`supporting-cycle-detection`.
|
|
|
|
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::
|
|
|
|
static int
|
|
local_traverse(localobject *self, visitproc visit, void *arg)
|
|
{
|
|
Py_VISIT(self->args);
|
|
Py_VISIT(self->kw);
|
|
Py_VISIT(self->dict);
|
|
return 0;
|
|
}
|
|
|
|
Note that :c:func:`Py_VISIT` is called only on those members that can participate
|
|
in reference cycles. Although there is also a ``self->key`` member, it can only
|
|
be *NULL* or a Python string and therefore cannot be part of a reference cycle.
|
|
|
|
On the other hand, even if you know a member can never be part of a cycle, as a
|
|
debugging aid you may want to visit it anyway just so the :mod:`gc` module's
|
|
:func:`~gc.get_referents` function will include it.
|
|
|
|
Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to
|
|
:c:func:`local_traverse` to have these specific names; don't name them just
|
|
anything.
|
|
|
|
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 *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
|
|
bit set.
|
|
|
|
|
|
.. c:member:: inquiry PyTypeObject.tp_clear
|
|
|
|
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 :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 :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 :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 :c:member:`~PyTypeObject.tp_clear`.
|
|
|
|
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::
|
|
|
|
static int
|
|
local_clear(localobject *self)
|
|
{
|
|
Py_CLEAR(self->key);
|
|
Py_CLEAR(self->args);
|
|
Py_CLEAR(self->kw);
|
|
Py_CLEAR(self->dict);
|
|
return 0;
|
|
}
|
|
|
|
The :c:func:`Py_CLEAR` macro should be used, because clearing references is
|
|
delicate: the reference to the contained object must not be decremented until
|
|
after the pointer to the contained object is set to *NULL*. This is because
|
|
decrementing the reference count may cause the contained object to become trash,
|
|
triggering a chain of reclamation activity that may include invoking arbitrary
|
|
Python code (due to finalizers, or weakref callbacks, associated with the
|
|
contained object). If it's possible for such code to reference *self* again,
|
|
it's important that the pointer to the contained object be *NULL* at that time,
|
|
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 :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
|
|
: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 :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 *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
|
|
bit set.
|
|
|
|
|
|
.. c:member:: richcmpfunc PyTypeObject.tp_richcompare
|
|
|
|
An optional pointer to the rich comparison function, whose signature is
|
|
``PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)``.
|
|
|
|
The function should return the result of the comparison (usually ``Py_True``
|
|
or ``Py_False``). If the comparison is undefined, it must return
|
|
``Py_NotImplemented``, if another error occurred it must return ``NULL`` and
|
|
set an exception condition.
|
|
|
|
.. note::
|
|
|
|
If you want to implement a type for which only a limited set of
|
|
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 :c:member:`~PyTypeObject.tp_compare` and
|
|
:c:member:`~PyTypeObject.tp_hash`: a subtype inherits all three of :c:member:`~PyTypeObject.tp_compare`,
|
|
:c:member:`~PyTypeObject.tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash`, when the subtype's
|
|
:c:member:`~PyTypeObject.tp_compare`, :c:member:`~PyTypeObject.tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash` are all *NULL*.
|
|
|
|
The following constants are defined to be used as the third argument for
|
|
:c:member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`:
|
|
|
|
+----------------+------------+
|
|
| Constant | Comparison |
|
|
+================+============+
|
|
| :const:`Py_LT` | ``<`` |
|
|
+----------------+------------+
|
|
| :const:`Py_LE` | ``<=`` |
|
|
+----------------+------------+
|
|
| :const:`Py_EQ` | ``==`` |
|
|
+----------------+------------+
|
|
| :const:`Py_NE` | ``!=`` |
|
|
+----------------+------------+
|
|
| :const:`Py_GT` | ``>`` |
|
|
+----------------+------------+
|
|
| :const:`Py_GE` | ``>=`` |
|
|
+----------------+------------+
|
|
|
|
|
|
The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is
|
|
set.
|
|
|
|
.. c:member:: long PyTypeObject.tp_weaklistoffset
|
|
|
|
If the instances of this type are weakly referenceable, this field is greater
|
|
than zero and contains the offset in the instance structure of the weak
|
|
reference list head (ignoring the GC header, if present); this offset is used by
|
|
:c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The
|
|
instance structure needs to include a field of type :c:type:`PyObject\*` which is
|
|
initialized to *NULL*.
|
|
|
|
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
|
|
:c:member:`~PyTypeObject.tp_weaklistoffset`, this should not be a problem.
|
|
|
|
When a type defined by a class statement has no :attr:`~object.__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 :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
|
|
:c:member:`~PyTypeObject.tp_weaklistoffset`.
|
|
|
|
When a type's :attr:`__slots__` declaration does not contain a slot named
|
|
:attr:`__weakref__`, the type inherits its :c:member:`~PyTypeObject.tp_weaklistoffset` from its
|
|
base type.
|
|
|
|
The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_ITER` flag bit is
|
|
set.
|
|
|
|
|
|
.. c:member:: getiterfunc PyTypeObject.tp_iter
|
|
|
|
An optional pointer to a function that returns an iterator for the object. Its
|
|
presence normally signals that the instances of this type are iterable (although
|
|
sequences may be iterable without this function, and classic instances always
|
|
have this function, even if they don't define an :meth:`__iter__` method).
|
|
|
|
This function has the same signature as :c:func:`PyObject_GetIter`.
|
|
|
|
This field is inherited by subtypes.
|
|
|
|
|
|
.. c:member:: iternextfunc PyTypeObject.tp_iternext
|
|
|
|
An optional pointer to a function that returns the next item in an iterator.
|
|
When the iterator is exhausted, it must return *NULL*; a :exc:`StopIteration`
|
|
exception may or may not be set. When another error occurs, it must return
|
|
*NULL* too. Its presence normally signals that the instances of this type
|
|
are iterators (although classic instances always have this function, even if
|
|
they don't define a :meth:`~iterator.next` method).
|
|
|
|
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).
|
|
|
|
This function has the same signature as :c:func:`PyIter_Next`.
|
|
|
|
This field is inherited by subtypes.
|
|
|
|
The next fields, up to and including :c:member:`~PyTypeObject.tp_weaklist`, only exist if the
|
|
:const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set.
|
|
|
|
|
|
.. c:member:: struct PyMethodDef* PyTypeObject.tp_methods
|
|
|
|
An optional pointer to a static *NULL*-terminated array of :c:type:`PyMethodDef`
|
|
structures, declaring regular methods of this type.
|
|
|
|
For each entry in the array, an entry is added to the type's dictionary (see
|
|
:c:member:`~PyTypeObject.tp_dict` below) containing a method descriptor.
|
|
|
|
This field is not inherited by subtypes (methods are inherited through a
|
|
different mechanism).
|
|
|
|
|
|
.. c:member:: struct PyMemberDef* PyTypeObject.tp_members
|
|
|
|
An optional pointer to a static *NULL*-terminated array of :c:type:`PyMemberDef`
|
|
structures, declaring regular data members (fields or slots) of instances of
|
|
this type.
|
|
|
|
For each entry in the array, an entry is added to the type's dictionary (see
|
|
:c:member:`~PyTypeObject.tp_dict` below) containing a member descriptor.
|
|
|
|
This field is not inherited by subtypes (members are inherited through a
|
|
different mechanism).
|
|
|
|
|
|
.. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset
|
|
|
|
An optional pointer to a static *NULL*-terminated array of :c:type:`PyGetSetDef`
|
|
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
|
|
: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).
|
|
|
|
.. XXX belongs elsewhere
|
|
|
|
Docs for PyGetSetDef::
|
|
|
|
typedef PyObject *(*getter)(PyObject *, void *);
|
|
typedef int (*setter)(PyObject *, PyObject *, void *);
|
|
|
|
typedef struct PyGetSetDef {
|
|
char *name; /* attribute name */
|
|
getter get; /* C function to get the attribute */
|
|
setter set; /* C function to set or delete the attribute */
|
|
char *doc; /* optional doc string */
|
|
void *closure; /* optional additional data for getter and setter */
|
|
} PyGetSetDef;
|
|
|
|
|
|
.. c:member:: PyTypeObject* PyTypeObject.tp_base
|
|
|
|
An optional pointer to a base type from which type properties are inherited. At
|
|
this level, only single inheritance is supported; multiple inheritance require
|
|
dynamically creating a type object by calling the metatype.
|
|
|
|
This field is not inherited by subtypes (obviously), but it defaults to
|
|
``&PyBaseObject_Type`` (which to Python programmers is known as the type
|
|
:class:`object`).
|
|
|
|
|
|
.. c:member:: PyObject* PyTypeObject.tp_dict
|
|
|
|
The type's dictionary is stored here by :c:func:`PyType_Ready`.
|
|
|
|
This field should normally be initialized to *NULL* before PyType_Ready is
|
|
called; it may also be initialized to a dictionary containing initial attributes
|
|
for the type. Once :c:func:`PyType_Ready` has initialized the type, extra
|
|
attributes for the type may be added to this dictionary only if they don't
|
|
correspond to overloaded operations (like :meth:`__add__`).
|
|
|
|
This field is not inherited by subtypes (though the attributes defined in here
|
|
are inherited through a different mechanism).
|
|
|
|
|
|
.. c:member:: descrgetfunc PyTypeObject.tp_descr_get
|
|
|
|
An optional pointer to a "descriptor get" function.
|
|
|
|
The function signature is ::
|
|
|
|
PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
|
|
|
|
.. XXX explain.
|
|
|
|
This field is inherited by subtypes.
|
|
|
|
|
|
.. c:member:: descrsetfunc PyTypeObject.tp_descr_set
|
|
|
|
An optional pointer to a function for setting and deleting
|
|
a descriptor's value.
|
|
|
|
The function signature is ::
|
|
|
|
int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
|
|
|
|
The *value* argument is set to *NULL* to delete the value.
|
|
This field is inherited by subtypes.
|
|
|
|
.. XXX explain.
|
|
|
|
|
|
.. c:member:: long PyTypeObject.tp_dictoffset
|
|
|
|
If the instances of this type have a dictionary containing instance variables,
|
|
this field is non-zero and contains the offset in the instances of the type of
|
|
the instance variable dictionary; this offset is used by
|
|
:c:func:`PyObject_GenericGetAttr`.
|
|
|
|
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
|
|
the start of the instance structure. If the value is less than zero, it
|
|
specifies the offset from the *end* of the instance structure. A negative
|
|
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 :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,
|
|
: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
|
|
: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 :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 long ints use the sign of :attr:`ob_size` to
|
|
store the sign of the number. (There's never a need to do this calculation
|
|
yourself; it is done for you by :c:func:`_PyObject_GetDictPtr`.)
|
|
|
|
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 :c:member:`~PyTypeObject.tp_dictoffset`, this should not be a problem.
|
|
|
|
When a type defined by a class statement has no :attr:`~object.__slots__` declaration,
|
|
and none of its base types has an instance variable dictionary, a dictionary
|
|
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 :c:member:`~PyTypeObject.tp_dictoffset` from its base type.
|
|
|
|
(Adding a slot named :attr:`~object.__dict__` to the :attr:`__slots__` declaration does
|
|
not have the expected effect, it just causes confusion. Maybe this should be
|
|
added as a feature just like :attr:`__weakref__` though.)
|
|
|
|
|
|
.. c:member:: initproc PyTypeObject.tp_init
|
|
|
|
An optional pointer to an instance initialization function.
|
|
|
|
This function corresponds to the :meth:`__init__` method of classes. Like
|
|
:meth:`__init__`, it is possible to create an instance without calling
|
|
:meth:`__init__`, and it is possible to reinitialize an instance by calling its
|
|
:meth:`__init__` method again.
|
|
|
|
The function signature is ::
|
|
|
|
int tp_init(PyObject *self, PyObject *args, PyObject *kwds)
|
|
|
|
The self argument is the instance to be initialized; the *args* and *kwds*
|
|
arguments represent positional and keyword arguments of the call to
|
|
:meth:`__init__`.
|
|
|
|
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
|
|
: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. (VERSION
|
|
NOTE: described here is what is implemented in Python 2.2.1 and later. In
|
|
Python 2.2, the :c:member:`~PyTypeObject.tp_init` of the type of the object returned by
|
|
:c:member:`~PyTypeObject.tp_new` was always called, if not *NULL*.)
|
|
|
|
This field is inherited by subtypes.
|
|
|
|
|
|
.. c:member:: allocfunc PyTypeObject.tp_alloc
|
|
|
|
An optional pointer to an instance allocation function.
|
|
|
|
The function signature is ::
|
|
|
|
PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)
|
|
|
|
The purpose of this function is to separate memory allocation from memory
|
|
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 :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 :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 :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
|
|
to :c:func:`PyType_GenericAlloc`, to force a standard heap allocation strategy.
|
|
That is also the recommended value for statically defined types.
|
|
|
|
|
|
.. c:member:: newfunc PyTypeObject.tp_new
|
|
|
|
An optional pointer to an instance creation function.
|
|
|
|
If this function is *NULL* for a particular type, that type cannot be called to
|
|
create new instances; presumably there is some other way to create instances,
|
|
like a factory function.
|
|
|
|
The function signature is ::
|
|
|
|
PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)
|
|
|
|
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 :c:member:`~PyTypeObject.tp_new`
|
|
function is called; it may be a subtype of that type (but not an unrelated
|
|
type).
|
|
|
|
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 :c:member:`~PyTypeObject.tp_init` handler. A good
|
|
rule of thumb is that for immutable types, all initialization should take place
|
|
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 :c:member:`~PyTypeObject.tp_base` is *NULL* or ``&PyBaseObject_Type``. The latter exception
|
|
is a precaution so that old extension types don't become callable simply by
|
|
being linked with Python 2.2.
|
|
|
|
|
|
.. c:member:: destructor PyTypeObject.tp_free
|
|
|
|
An optional pointer to an instance deallocation function.
|
|
|
|
The signature of this function has changed slightly: in Python 2.2 and 2.2.1,
|
|
its signature is :c:type:`destructor`::
|
|
|
|
void tp_free(PyObject *)
|
|
|
|
In Python 2.3 and beyond, its signature is :c:type:`freefunc`::
|
|
|
|
void tp_free(void *)
|
|
|
|
The only initializer that is compatible with both versions is ``_PyObject_Del``,
|
|
whose definition has suitably adapted in Python 2.3.
|
|
|
|
This field is inherited by static subtypes, but not by dynamic subtypes
|
|
(subtypes created by a class statement); in the latter, this field is set to a
|
|
deallocator suitable to match :c:func:`PyType_GenericAlloc` and the value of the
|
|
:const:`Py_TPFLAGS_HAVE_GC` flag bit.
|
|
|
|
|
|
.. c:member:: inquiry PyTypeObject.tp_is_gc
|
|
|
|
An optional pointer to a function called by the garbage collector.
|
|
|
|
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
|
|
: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
|
|
``0`` for a non-collectible instance. The signature is ::
|
|
|
|
int tp_is_gc(PyObject *self)
|
|
|
|
(The only example of this are types themselves. The metatype,
|
|
:c:data:`PyType_Type`, defines this function to distinguish between statically
|
|
and dynamically allocated types.)
|
|
|
|
This field is inherited by subtypes. (VERSION NOTE: in Python 2.2, it was not
|
|
inherited. It is inherited in 2.2.1 and later versions.)
|
|
|
|
|
|
.. c:member:: PyObject* PyTypeObject.tp_bases
|
|
|
|
Tuple of base types.
|
|
|
|
This is set for types created by a class statement. It should be *NULL* for
|
|
statically defined types.
|
|
|
|
This field is not inherited.
|
|
|
|
|
|
.. c:member:: PyObject* PyTypeObject.tp_mro
|
|
|
|
Tuple containing the expanded set of base types, starting with the type itself
|
|
and ending with :class:`object`, in Method Resolution Order.
|
|
|
|
This field is not inherited; it is calculated fresh by :c:func:`PyType_Ready`.
|
|
|
|
|
|
.. c:member:: PyObject* PyTypeObject.tp_cache
|
|
|
|
Unused. Not inherited. Internal use only.
|
|
|
|
|
|
.. c:member:: PyObject* PyTypeObject.tp_subclasses
|
|
|
|
List of weak references to subclasses. Not inherited. Internal use only.
|
|
|
|
|
|
.. c:member:: PyObject* PyTypeObject.tp_weaklist
|
|
|
|
Weak reference list head, for weak references to this type object. Not
|
|
inherited. Internal use only.
|
|
|
|
The remaining fields are only defined if the feature test macro
|
|
:const:`COUNT_ALLOCS` is defined, and are for internal use only. They are
|
|
documented here for completeness. None of these fields are inherited by
|
|
subtypes.
|
|
|
|
|
|
.. c:member:: Py_ssize_t PyTypeObject.tp_allocs
|
|
|
|
Number of allocations.
|
|
|
|
|
|
.. c:member:: Py_ssize_t PyTypeObject.tp_frees
|
|
|
|
Number of frees.
|
|
|
|
|
|
.. c:member:: Py_ssize_t PyTypeObject.tp_maxalloc
|
|
|
|
Maximum simultaneously allocated objects.
|
|
|
|
|
|
.. c:member:: PyTypeObject* PyTypeObject.tp_next
|
|
|
|
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
|
|
becomes part of a refcount cycle, that cycle might be collected by a garbage
|
|
collection on any thread). This is not a problem for Python API calls, since
|
|
the thread on which tp_dealloc is called will own the Global Interpreter Lock
|
|
(GIL). However, if the object being destroyed in turn destroys objects from some
|
|
other C or C++ library, care should be taken to ensure that destroying those
|
|
objects on the thread which called tp_dealloc will not violate any assumptions
|
|
of the library.
|
|
|
|
|
|
.. _number-structs:
|
|
|
|
Number Object Structures
|
|
========================
|
|
|
|
.. sectionauthor:: Amaury Forgeot d'Arc
|
|
|
|
|
|
.. c:type:: PyNumberMethods
|
|
|
|
This structure holds pointers to the functions which an object uses to
|
|
implement the number protocol. Almost every function below is used by the
|
|
function of similar name documented in the :ref:`number` section.
|
|
|
|
Here is the structure definition::
|
|
|
|
typedef struct {
|
|
binaryfunc nb_add;
|
|
binaryfunc nb_subtract;
|
|
binaryfunc nb_multiply;
|
|
binaryfunc nb_divide;
|
|
binaryfunc nb_remainder;
|
|
binaryfunc nb_divmod;
|
|
ternaryfunc nb_power;
|
|
unaryfunc nb_negative;
|
|
unaryfunc nb_positive;
|
|
unaryfunc nb_absolute;
|
|
inquiry nb_nonzero; /* Used by PyObject_IsTrue */
|
|
unaryfunc nb_invert;
|
|
binaryfunc nb_lshift;
|
|
binaryfunc nb_rshift;
|
|
binaryfunc nb_and;
|
|
binaryfunc nb_xor;
|
|
binaryfunc nb_or;
|
|
coercion nb_coerce; /* Used by the coerce() function */
|
|
unaryfunc nb_int;
|
|
unaryfunc nb_long;
|
|
unaryfunc nb_float;
|
|
unaryfunc nb_oct;
|
|
unaryfunc nb_hex;
|
|
|
|
/* Added in release 2.0 */
|
|
binaryfunc nb_inplace_add;
|
|
binaryfunc nb_inplace_subtract;
|
|
binaryfunc nb_inplace_multiply;
|
|
binaryfunc nb_inplace_divide;
|
|
binaryfunc nb_inplace_remainder;
|
|
ternaryfunc nb_inplace_power;
|
|
binaryfunc nb_inplace_lshift;
|
|
binaryfunc nb_inplace_rshift;
|
|
binaryfunc nb_inplace_and;
|
|
binaryfunc nb_inplace_xor;
|
|
binaryfunc nb_inplace_or;
|
|
|
|
/* Added in release 2.2 */
|
|
binaryfunc nb_floor_divide;
|
|
binaryfunc nb_true_divide;
|
|
binaryfunc nb_inplace_floor_divide;
|
|
binaryfunc nb_inplace_true_divide;
|
|
|
|
/* Added in release 2.5 */
|
|
unaryfunc nb_index;
|
|
} PyNumberMethods;
|
|
|
|
|
|
Binary and ternary functions may receive different kinds of arguments, depending
|
|
on the flag bit :const:`Py_TPFLAGS_CHECKTYPES`:
|
|
|
|
- If :const:`Py_TPFLAGS_CHECKTYPES` is not set, the function arguments are
|
|
guaranteed to be of the object's type; the caller is responsible for calling
|
|
the coercion method specified by the :attr:`nb_coerce` member to convert the
|
|
arguments:
|
|
|
|
.. c:member:: coercion PyNumberMethods.nb_coerce
|
|
|
|
This function is used by :c:func:`PyNumber_CoerceEx` and has the same
|
|
signature. The first argument is always a pointer to an object of the
|
|
defined type. If the conversion to a common "larger" type is possible, the
|
|
function replaces the pointers with new references to the converted objects
|
|
and returns ``0``. If the conversion is not possible, the function returns
|
|
``1``. If an error condition is set, it will return ``-1``.
|
|
|
|
- If the :const:`Py_TPFLAGS_CHECKTYPES` flag is set, binary and ternary
|
|
functions must check the type of all their operands, and implement the
|
|
necessary conversions (at least one of the operands is an instance of the
|
|
defined type). This is the recommended way; with Python 3 coercion will
|
|
disappear completely.
|
|
|
|
If the operation is not defined for the given operands, binary and ternary
|
|
functions must return ``Py_NotImplemented``, if another error occurred they must
|
|
return ``NULL`` and set an exception.
|
|
|
|
|
|
.. _mapping-structs:
|
|
|
|
Mapping Object Structures
|
|
=========================
|
|
|
|
.. sectionauthor:: Amaury Forgeot d'Arc
|
|
|
|
|
|
.. c:type:: PyMappingMethods
|
|
|
|
This structure holds pointers to the functions which an object uses to
|
|
implement the mapping protocol. It has three members:
|
|
|
|
.. c:member:: lenfunc PyMappingMethods.mp_length
|
|
|
|
This function is used by :c:func:`PyMapping_Length` and
|
|
:c:func:`PyObject_Size`, and has the same signature. This slot may be set to
|
|
*NULL* if the object has no defined length.
|
|
|
|
.. c:member:: binaryfunc PyMappingMethods.mp_subscript
|
|
|
|
This function is used by :c:func:`PyObject_GetItem` and has the same
|
|
signature. This slot must be filled for the :c:func:`PyMapping_Check`
|
|
function to return ``1``, it can be *NULL* otherwise.
|
|
|
|
.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript
|
|
|
|
This function is used by :c:func:`PyObject_SetItem` and
|
|
:c:func:`PyObject_DelItem`. It has the same signature as
|
|
:c:func:`PyObject_SetItem`, but *v* can also be set to *NULL* to delete
|
|
an item. If this slot is *NULL*, the object does not support item
|
|
assignment and deletion.
|
|
|
|
|
|
.. _sequence-structs:
|
|
|
|
Sequence Object Structures
|
|
==========================
|
|
|
|
.. sectionauthor:: Amaury Forgeot d'Arc
|
|
|
|
|
|
.. c:type:: PySequenceMethods
|
|
|
|
This structure holds pointers to the functions which an object uses to
|
|
implement the sequence protocol.
|
|
|
|
.. c:member:: lenfunc PySequenceMethods.sq_length
|
|
|
|
This function is used by :c:func:`PySequence_Size` and :c:func:`PyObject_Size`,
|
|
and has the same signature.
|
|
|
|
.. c:member:: binaryfunc PySequenceMethods.sq_concat
|
|
|
|
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 :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 :c:member:`~PyTypeObject.tp_as_number.nb_multiply`
|
|
slot.
|
|
|
|
.. c:member:: ssizeargfunc PySequenceMethods.sq_item
|
|
|
|
This function is used by :c:func:`PySequence_GetItem` and has the same
|
|
signature. This slot must be filled for the :c:func:`PySequence_Check`
|
|
function to return ``1``, it can be *NULL* otherwise.
|
|
|
|
Negative indexes are handled as follows: if the :attr:`sq_length` slot is
|
|
filled, it is called and the sequence length is used to compute a positive
|
|
index which is passed to :attr:`sq_item`. If :attr:`sq_length` is *NULL*,
|
|
the index is passed as is to the function.
|
|
|
|
.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item
|
|
|
|
This function is used by :c:func:`PySequence_SetItem` and has the same
|
|
signature. This slot may be left to *NULL* if the object does not support
|
|
item assignment and deletion.
|
|
|
|
.. c:member:: objobjproc PySequenceMethods.sq_contains
|
|
|
|
This function may be used by :c:func:`PySequence_Contains` and has the same
|
|
signature. This slot may be left to *NULL*, in this case
|
|
:c:func:`PySequence_Contains` simply traverses the sequence until it finds a
|
|
match.
|
|
|
|
.. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat
|
|
|
|
This function is used by :c:func:`PySequence_InPlaceConcat` and has the same
|
|
signature. It should modify its first operand, and return it.
|
|
|
|
.. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat
|
|
|
|
This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same
|
|
signature. It should modify its first operand, and return it.
|
|
|
|
.. XXX need to explain precedence between mapping and sequence
|
|
.. XXX explains when to implement the sq_inplace_* slots
|
|
|
|
|
|
.. _buffer-structs:
|
|
|
|
Buffer Object Structures
|
|
========================
|
|
|
|
.. sectionauthor:: Greg J. Stein <greg@lyra.org>
|
|
|
|
|
|
The buffer interface exports a model where an object can expose its internal
|
|
data as a set of chunks of data, where each chunk is specified as a
|
|
pointer/length pair. These chunks are called :dfn:`segments` and are presumed
|
|
to be non-contiguous in memory.
|
|
|
|
If an object does not export the buffer interface, then its :c:member:`~PyTypeObject.tp_as_buffer`
|
|
member in the :c:type:`PyTypeObject` structure should be *NULL*. Otherwise, the
|
|
:c:member:`~PyTypeObject.tp_as_buffer` will point to a :c:type:`PyBufferProcs` structure.
|
|
|
|
.. note::
|
|
|
|
It is very important that your :c:type:`PyTypeObject` structure uses
|
|
:const:`Py_TPFLAGS_DEFAULT` for the value of the :c:member:`~PyTypeObject.tp_flags` member rather
|
|
than ``0``. This tells the Python runtime that your :c:type:`PyBufferProcs`
|
|
structure contains the :attr:`bf_getcharbuffer` slot. Older versions of Python
|
|
did not have this member, so a new Python interpreter using an old extension
|
|
needs to be able to test for its presence before using it.
|
|
|
|
|
|
.. c:type:: PyBufferProcs
|
|
|
|
Structure used to hold the function pointers which define an implementation of
|
|
the buffer protocol.
|
|
|
|
The first slot is :attr:`bf_getreadbuffer`, of type :c:type:`readbufferproc`.
|
|
If this slot is *NULL*, then the object does not support reading from the
|
|
internal data. This is non-sensical, so implementors should fill this in, but
|
|
callers should test that the slot contains a non-*NULL* value.
|
|
|
|
The next slot is :attr:`bf_getwritebuffer` having type
|
|
:c:type:`writebufferproc`. This slot may be *NULL* if the object does not
|
|
allow writing into its returned buffers.
|
|
|
|
The third slot is :attr:`bf_getsegcount`, with type :c:type:`segcountproc`.
|
|
This slot must not be *NULL* and is used to inform the caller how many segments
|
|
the object contains. Simple objects such as :c:type:`PyString_Type` and
|
|
:c:type:`PyBuffer_Type` objects contain a single segment.
|
|
|
|
.. index:: single: PyType_HasFeature()
|
|
|
|
The last slot is :attr:`bf_getcharbuffer`, of type :c:type:`charbufferproc`.
|
|
This slot will only be present if the :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`
|
|
flag is present in the :c:member:`~PyTypeObject.tp_flags` field of the object's
|
|
:c:type:`PyTypeObject`. Before using this slot, the caller should test whether it
|
|
is present by using the :c:func:`PyType_HasFeature` function. If the flag is
|
|
present, :attr:`bf_getcharbuffer` may be *NULL*, indicating that the object's
|
|
contents cannot be used as *8-bit characters*. The slot function may also raise
|
|
an error if the object's contents cannot be interpreted as 8-bit characters.
|
|
For example, if the object is an array which is configured to hold floating
|
|
point values, an exception may be raised if a caller attempts to use
|
|
:attr:`bf_getcharbuffer` to fetch a sequence of 8-bit characters. This notion of
|
|
exporting the internal buffers as "text" is used to distinguish between objects
|
|
that are binary in nature, and those which have character-based content.
|
|
|
|
.. note::
|
|
|
|
The current policy seems to state that these characters may be multi-byte
|
|
characters. This implies that a buffer size of *N* does not mean there are *N*
|
|
characters present.
|
|
|
|
|
|
.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
|
|
|
|
Flag bit set in the type structure to indicate that the :attr:`bf_getcharbuffer`
|
|
slot is known. This being set does not indicate that the object supports the
|
|
buffer interface or that the :attr:`bf_getcharbuffer` slot is non-*NULL*.
|
|
|
|
|
|
.. c:type:: Py_ssize_t (*readbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)
|
|
|
|
Return a pointer to a readable segment of the buffer in ``*ptrptr``. This
|
|
function is allowed to raise an exception, in which case it must return ``-1``.
|
|
The *segment* which is specified must be zero or positive, and strictly less
|
|
than the number of segments returned by the :attr:`bf_getsegcount` slot
|
|
function. On success, it returns the length of the segment, and sets
|
|
``*ptrptr`` to a pointer to that memory.
|
|
|
|
|
|
.. c:type:: Py_ssize_t (*writebufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)
|
|
|
|
Return a pointer to a writable memory buffer in ``*ptrptr``, and the length of
|
|
that segment as the function return value. The memory buffer must correspond to
|
|
buffer segment *segment*. Must return ``-1`` and set an exception on error.
|
|
:exc:`TypeError` should be raised if the object only supports read-only buffers,
|
|
and :exc:`SystemError` should be raised when *segment* specifies a segment that
|
|
doesn't exist.
|
|
|
|
.. Why doesn't it raise ValueError for this one?
|
|
GJS: because you shouldn't be calling it with an invalid
|
|
segment. That indicates a blatant programming error in the C code.
|
|
|
|
|
|
.. c:type:: Py_ssize_t (*segcountproc) (PyObject *self, Py_ssize_t *lenp)
|
|
|
|
Return the number of memory segments which comprise the buffer. If *lenp* is
|
|
not *NULL*, the implementation must report the sum of the sizes (in bytes) of
|
|
all segments in ``*lenp``. The function cannot fail.
|
|
|
|
|
|
.. c:type:: Py_ssize_t (*charbufferproc) (PyObject *self, Py_ssize_t segment, char **ptrptr)
|
|
|
|
Return the size of the segment *segment* that *ptrptr* is set to. ``*ptrptr``
|
|
is set to the memory buffer. Returns ``-1`` on error.
|