From 27612d1b42a02cbab406a6a8172be28f231bed8a Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Mon, 4 Jun 2018 09:51:28 -0600 Subject: [PATCH 01/43] Improve C-API doc for PyTypeObject. --- Doc/c-api/typeobj.rst | 628 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 588 insertions(+), 40 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 6cbcc273c1f153..dcb76d56c63d6d 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -20,10 +20,63 @@ 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, intargfunc, -intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor, -freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc, -reprfunc, hashfunc +Quick Reference +--------------- + +=========================================== ================= ====================== +PyTypeObject Slot [#slots]_ Inherited [#inh]_ Type +=========================================== ================= ====================== +:c:member:`~PyTypeObject.tp_name` .. char * +:c:member:`~PyTypeObject.tp_basicsize` X int +:c:member:`~PyTypeObject.tp_itemsize` ? int +:c:member:`~PyTypeObject.tp_dealloc` X :c:type:`destructor` +(:c:member:`~PyTypeObject.tp_print`) X :c:type:`printfunc` +(:c:member:`~PyTypeObject.tp_getattr`) X :c:type:`getattrfunc` +(:c:member:`~PyTypeObject.tp_setattr`) X :c:type:`setattrfunc` +(:c:member:`~PyTypeObject.tp_reserved`) .. void* +:c:member:`~PyTypeObject.tp_repr` X :c:type:`reprfunc` +:c:member:`~PyTypeObject.tp_as_number` \* PyNumberMethods * +:c:member:`~PyTypeObject.tp_as_sequence` \* PySequenceMethods * +:c:member:`~PyTypeObject.tp_as_mapping` \* PyMappingMethods * +:c:member:`~PyTypeObject.tp_hash` X :c:type:`hashfunc` +:c:member:`~PyTypeObject.tp_call` X :c:type:`ternaryfunc` +:c:member:`~PyTypeObject.tp_str` X :c:type:`reprfunc` +:c:member:`~PyTypeObject.tp_getattro` X :c:type:`getattrofunc` +:c:member:`~PyTypeObject.tp_setattro` X :c:type:`setattrofunc` +:c:member:`~PyTypeObject.tp_as_buffer` \* PyBufferProcs * +:c:member:`~PyTypeObject.tp_flags` ? long +:c:member:`~PyTypeObject.tp_doc` .. char * +:c:member:`~PyTypeObject.tp_traverse` X traverseproc +:c:member:`~PyTypeObject.tp_clear` X inquiry +:c:member:`~PyTypeObject.tp_richcompare` X :c:type:`richcmpfunc` +:c:member:`~PyTypeObject.tp_weaklistoffset` X long +:c:member:`~PyTypeObject.tp_iter` X :c:type:`getiterfunc` +:c:member:`~PyTypeObject.tp_iternext` X :c:type:`iternextfunc` +:c:member:`~PyTypeObject.tp_methods` L PyMethodDef[] +:c:member:`~PyTypeObject.tp_members` L PyMemberDef[] +:c:member:`~PyTypeObject.tp_getset` L PyGetSetDef[] +:c:member:`~PyTypeObject.tp_base` .. PyTypeObject * +:c:member:`~PyTypeObject.tp_dict` L PyObject * +:c:member:`~PyTypeObject.tp_descr_get` X :c:type:`descrgetfunc` +:c:member:`~PyTypeObject.tp_descr_set` X :c:type:`descrsetfunc` +:c:member:`~PyTypeObject.tp_dictoffset` X long +:c:member:`~PyTypeObject.tp_init` X initproc +:c:member:`~PyTypeObject.tp_alloc` ? :c:type:`allocfunc` +:c:member:`~PyTypeObject.tp_new` ? :c:type:`newfunc` +:c:member:`~PyTypeObject.tp_free` ? :c:type:`freefunc` +:c:member:`~PyTypeObject.tp_is_gc` X inquiry +[:c:member:`~PyTypeObject.tp_bases`] .. PyObject * +[:c:member:`~PyTypeObject.tp_mro`] .. PyObject * +[:c:member:`~PyTypeObject.tp_cache`] .. PyObject * +[:c:member:`~PyTypeObject.tp_subclasses`] .. PyObject * +[:c:member:`~PyTypeObject.tp_weaklist`] .. PyObject * +=========================================== ================= ====================== + +.. XXX add tp_del? + + +PyTypeObject Definition +----------------------- The structure definition for :c:type:`PyTypeObject` can be found in :file:`Include/object.h`. For convenience of reference, this repeats the @@ -32,6 +85,9 @@ definition found there: .. literalinclude:: ../includes/typestruct.h +PyObject Slots +-------------- + 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 @@ -51,6 +107,8 @@ type objects) *must* have the :attr:`ob_size` field. that are still alive at the end of a run when the environment variable :envvar:`PYTHONDUMPREFS` is set. + **Inheritance:** + These fields are not inherited by subtypes. @@ -62,6 +120,8 @@ type objects) *must* have the :attr:`ob_size` field. *not* count as references. But for dynamically allocated type objects, the instances *do* count as references. + **Inheritance:** + This field is not inherited by subtypes. @@ -83,17 +143,31 @@ type objects) *must* have the :attr:`ob_size` field. initializes it to the :attr:`ob_type` field of the base class. :c:func:`PyType_Ready` will not change this field if it is non-zero. + **Inheritance:** + This field is inherited by subtypes. +PyVarObject Slots +----------------- + .. 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. + **Inheritance:** + This field is not inherited by subtypes. +PyTypeObject Slots +------------------ + +Each slot has a section describing inheritance and one for the default +value. If a slot does not have any information about the default +value, that section is omitted. + .. c:member:: const char* PyTypeObject.tp_name Pointer to a NUL-terminated string containing the name of the type. For types @@ -119,8 +193,15 @@ type objects) *must* have the :attr:`ob_size` field. type will be impossible to pickle. Additionally, it will not be listed in module documentations created with pydoc. + **Inheritance:** + This field is not inherited by subtypes. + **Default:** + + This field does not have a default. It is the only required + field in :c:func:`PyTypeObject`. + .. c:member:: Py_ssize_t PyTypeObject.tp_basicsize Py_ssize_t PyTypeObject.tp_itemsize @@ -151,11 +232,6 @@ type objects) *must* have the :attr:`ob_size` field. ``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 :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 @@ -163,6 +239,19 @@ type objects) *must* have the :attr:`ob_size` field. :c:member:`~PyTypeObject.tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the alignment requirement for ``double``). + **Inheritance:** + + 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). + + **Default:** + + :c:type:`PyBaseObject_Type` uses ``sizeof(PyObject)`` for + :attr:`tp_basicsize`, However, :attr:`tp_itemsize` does not have + a default. + .. c:member:: destructor PyTypeObject.tp_dealloc @@ -185,8 +274,14 @@ type objects) *must* have the :attr:`ob_size` field. :c:func:`PyObject_GC_Del` if the instance was allocated using :c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`. + **Inheritance:** + This field is inherited by subtypes. + **Default:** + + :c:type:`PyBaseObject_Type` provides a simple function. + .. c:member:: printfunc PyTypeObject.tp_print @@ -203,10 +298,18 @@ type objects) *must* have the :attr:`ob_size` field. PyObject * tp_getattr(PyObject *o, char *attr_name); + **Inheritance:** + + Group: :attr:`tp_getattr`, :attr:`tp_getattro` + 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*. + **Default:** + + This field does not have a default. + .. c:member:: setattrfunc PyTypeObject.tp_setattr @@ -219,10 +322,19 @@ type objects) *must* have the :attr:`ob_size` field. PyObject * tp_setattr(PyObject *o, char *attr_name, PyObject *v); The *v* argument is set to *NULL* to delete the attribute. + + **Inheritance:** + + Group: :attr:`tp_setattr`, :attr:`tp_setattro` + 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*. + **Default:** + + This field does not have a default. + .. c:member:: PyAsyncMethods* tp_as_async @@ -233,6 +345,14 @@ type objects) *must* have the :attr:`ob_size` field. .. versionadded:: 3.5 Formerly known as ``tp_compare`` and ``tp_reserved``. + **Inheritance:** + + This field is inherited by subtypes. + + **Default:** + + This field does not have a default. + .. c:member:: reprfunc PyTypeObject.tp_repr @@ -252,37 +372,62 @@ type objects) *must* have the :attr:`ob_size` field. returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's memory address. + **Inheritance:** + This field is inherited by subtypes. -.. c:member:: PyNumberMethods* tp_as_number + **Default:** + + :c:type:`PyBaseObject_Type` provides a simple function. + + +.. c:member:: PyNumberMethods* PyTypeObject.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`. + **Inheritance:** + The :c:member:`~PyTypeObject.tp_as_number` field is not inherited, but the contained fields are inherited individually. + **Default:** + + This field does not have a default. + -.. c:member:: PySequenceMethods* tp_as_sequence +.. c:member:: PySequenceMethods* PyTypeObject.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`. + **Inheritance:** + The :c:member:`~PyTypeObject.tp_as_sequence` field is not inherited, but the contained fields are inherited individually. + **Default:** + + This field does not have a default. + -.. c:member:: PyMappingMethods* tp_as_mapping +.. c:member:: PyMappingMethods* PyTypeObject.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`. + **Inheritance:** + The :c:member:`~PyTypeObject.tp_as_mapping` field is not inherited, but the contained fields are inherited individually. + **Default:** + + This field does not have a default. + .. c:member:: hashfunc PyTypeObject.tp_hash @@ -296,6 +441,9 @@ type objects) *must* have the :attr:`ob_size` field. normal return value; when an error occurs during the computation of the hash value, the function should set an exception and return ``-1``. + When this field is not set, an attempt to take the hash of the + object raises :exc:`TypeError`. + 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 @@ -304,14 +452,19 @@ type objects) *must* have the :attr:`ob_size` field. the Python level will result in the ``tp_hash`` slot being set to :c:func:`PyObject_HashNotImplemented`. - When this field is not set, an attempt to take the hash of the - object raises :exc:`TypeError`. + **Inheritance:** + + Group: :attr:`tp_hash`, :attr:`tp_richcompare` This field is inherited by subtypes together with :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*. + **Default:** + + :c:type:`PyBaseObject_Type` uses :c:func:`_Py_HashPointer`. + .. c:member:: ternaryfunc PyTypeObject.tp_call @@ -319,8 +472,14 @@ type objects) *must* have the :attr:`ob_size` field. should be *NULL* if the object is not callable. The signature is the same as for :c:func:`PyObject_Call`. + **Inheritance:** + This field is inherited by subtypes. + **Default:** + + This field does not have a default. + .. c:member:: reprfunc PyTypeObject.tp_str @@ -337,8 +496,14 @@ type objects) *must* have the :attr:`ob_size` field. When this field is not set, :c:func:`PyObject_Repr` is called to return a string representation. + **Inheritance:** + This field is inherited by subtypes. + **Default:** + + :c:type:`PyBaseObject_Type` provides a simple function. + .. c:member:: getattrofunc PyTypeObject.tp_getattro @@ -348,10 +513,18 @@ 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. + **Inheritance:** + + Group: :attr:`tp_getattr`, :attr:`tp_getattro` + 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*. + **Default:** + + :c:type:`PyBaseObject_Type` uses :c:func:`PyObject_GenericGetAttr`. + .. c:member:: setattrofunc PyTypeObject.tp_setattro @@ -362,9 +535,17 @@ 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. + **Inheritance:** + + Group: :attr:`tp_setattr`, :attr:`tp_setattro` + 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*. + THE SUBTYpe's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*. + + **Default:** + + :c:type:`PyBaseObject_Type` uses :c:func:`PyObject_GenericSetAttr`. .. c:member:: PyBufferProcs* PyTypeObject.tp_as_buffer @@ -373,8 +554,14 @@ type objects) *must* have the :attr:`ob_size` field. 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. + **Inheritance:** + + The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, + but the contained fields are inherited individually. + + **Default:** + + This field does not have a default. .. c:member:: unsigned long PyTypeObject.tp_flags @@ -387,6 +574,8 @@ type objects) *must* have the :attr:`ob_size` field. 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:** + 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 @@ -398,12 +587,20 @@ type objects) *must* have the :attr:`ob_size` field. :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have *NULL* values. + .. XXX are most flag bits *really* inherited individually? + + **Default:** + + :c:type:`PyBaseObject_Type` uses + ``Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE``. + + **Bit Masks:** + 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_HEAPTYPE This bit is set when the type object itself is allocated on the heap. In this @@ -413,6 +610,10 @@ type objects) *must* have the :attr:`ob_size` field. subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or DECREF'ed). + **Inheritance:** + + ??? + .. data:: Py_TPFLAGS_BASETYPE @@ -420,18 +621,30 @@ type objects) *must* have the :attr:`ob_size` field. this bit is clear, the type cannot be subtyped (similar to a "final" class in Java). + **Inheritance:** + + ??? + .. data:: Py_TPFLAGS_READY This bit is set when the type object has been fully initialized by :c:func:`PyType_Ready`. + **Inheritance:** + + ??? + .. data:: Py_TPFLAGS_READYING This bit is set while :c:func:`PyType_Ready` is in the process of initializing the type object. + **Inheritance:** + + ??? + .. data:: Py_TPFLAGS_HAVE_GC @@ -442,6 +655,17 @@ type objects) *must* have the :attr:`ob_size` field. GC-related fields :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` are present in the type object. + **Inheritance:** + + Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear` + + 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 :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 *NULL* + values. + .. data:: Py_TPFLAGS_DEFAULT @@ -450,6 +674,12 @@ type objects) *must* have the :attr:`ob_size` field. the following bits: :const:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`, :const:`Py_TPFLAGS_HAVE_VERSION_TAG`. + **Inheritance:** + + ??? + + .. XXX Document more flags here? + .. data:: Py_TPFLAGS_LONG_SUBCLASS .. data:: Py_TPFLAGS_LIST_SUBCLASS @@ -483,8 +713,14 @@ type objects) *must* have the :attr:`ob_size` field. type object. This is exposed as the :attr:`__doc__` attribute on the type and instances of the type. + **Inheritance:** + This field is *not* inherited by subtypes. + **Default:** + + This field does not have a default. + .. c:member:: traverseproc PyTypeObject.tp_traverse @@ -520,11 +756,19 @@ type objects) *must* have the :attr:`ob_size` field. :c:func:`local_traverse` to have these specific names; don't name them just anything. + **Inheritance:** + + Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear` + 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. + **Default:** + + This field does not have a default. + .. c:member:: inquiry PyTypeObject.tp_clear @@ -575,11 +819,19 @@ type objects) *must* have the :attr:`ob_size` field. More information about Python's garbage collection scheme can be found in section :ref:`supporting-cycle-detection`. + **Inheritance:** + + Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear` + 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. + **Default:** + + This field does not have a default. + .. c:member:: richcmpfunc PyTypeObject.tp_richcompare @@ -599,11 +851,6 @@ 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 :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 :c:member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`: @@ -623,6 +870,21 @@ type objects) *must* have the :attr:`ob_size` field. | :const:`Py_GE` | ``>=`` | +----------------+------------+ + **Inheritance:** + + Group: :attr:`tp_hash`, :attr:`tp_richcompare` + + 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*. + + **Default:** + + PyBaseObject_Type provides a tp_richcompare. However, if only + :attr:`tp_hash` is defined, not even this is used and instances + of the type will not be able to participate in any comparisons. + The following macro is defined to ease writing rich comparison functions: .. c:function:: PyObject *Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op) @@ -652,6 +914,8 @@ type objects) *must* have the :attr:`ob_size` field. Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for weak references to the type object itself. + **Inheritance:** + 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 @@ -671,6 +935,11 @@ type objects) *must* have the :attr:`ob_size` field. :attr:`__weakref__`, the type inherits its :c:member:`~PyTypeObject.tp_weaklistoffset` from its base type. + **Default:** + + This field does not have a default. + + .. c:member:: getiterfunc PyTypeObject.tp_iter An optional pointer to a function that returns an iterator for the object. Its @@ -679,8 +948,14 @@ type objects) *must* have the :attr:`ob_size` field. This function has the same signature as :c:func:`PyObject_GetIter`. + **Inheritance:** + This field is inherited by subtypes. + **Default:** + + This field does not have a default. + .. c:member:: iternextfunc PyTypeObject.tp_iternext @@ -696,8 +971,14 @@ type objects) *must* have the :attr:`ob_size` field. This function has the same signature as :c:func:`PyIter_Next`. + **Inheritance:** + This field is inherited by subtypes. + **Default:** + + This field does not have a default. + .. c:member:: struct PyMethodDef* PyTypeObject.tp_methods @@ -707,9 +988,15 @@ type objects) *must* have the :attr:`ob_size` field. 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. + **Inheritance:** + This field is not inherited by subtypes (methods are inherited through a different mechanism). + **Default:** + + This field does not have a default. + .. c:member:: struct PyMemberDef* PyTypeObject.tp_members @@ -720,9 +1007,15 @@ type objects) *must* have the :attr:`ob_size` field. 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. + **Inheritance:** + This field is not inherited by subtypes (members are inherited through a different mechanism). + **Default:** + + This field does not have a default. + .. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset @@ -732,9 +1025,30 @@ type objects) *must* have the :attr:`ob_size` field. 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. + .. 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 the attribute */ + char *doc; /* optional doc string */ + void *closure; /* optional additional data for getter and setter */ + } PyGetSetDef; + + **Inheritance:** + This field is not inherited by subtypes (computed attributes are inherited through a different mechanism). + **Default:** + + This field does not have a default. + .. c:member:: PyTypeObject* PyTypeObject.tp_base @@ -742,9 +1056,14 @@ type objects) *must* have the :attr:`ob_size` field. 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`). + **Inheritance:** + + This field is not inherited by subtypes (obviously). + + **Default:** + + This field defaults to ``&PyBaseObject_Type`` (which to Python + programmers is known as the type :class:`object`). .. c:member:: PyObject* PyTypeObject.tp_dict @@ -757,9 +1076,16 @@ type objects) *must* have the :attr:`ob_size` field. attributes for the type may be added to this dictionary only if they don't correspond to overloaded operations (like :meth:`__add__`). + **Inheritance:** + This field is not inherited by subtypes (though the attributes defined in here are inherited through a different mechanism). + **Default:** + + If this field is NULL, :c:func:`PyType_Ready` will assign a new + dictionary to it. + .. warning:: It is not safe to use :c:func:`PyDict_SetItem` on or otherwise modify @@ -776,8 +1102,14 @@ type objects) *must* have the :attr:`ob_size` field. .. XXX explain. + **Inheritance:** + This field is inherited by subtypes. + **Default:** + + This field does not have a default. + .. c:member:: descrsetfunc PyTypeObject.tp_descr_set @@ -789,10 +1121,17 @@ type objects) *must* have the :attr:`ob_size` field. 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. + **Inheritance:** + + This field is inherited by subtypes. + + **Default:** + + This field does not have a default. + .. c:member:: Py_ssize_t PyTypeObject.tp_dictoffset @@ -829,6 +1168,8 @@ type objects) *must* have the :attr:`ob_size` field. 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`.) + **Inheritance:** + 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 @@ -846,6 +1187,11 @@ type objects) *must* have the :attr:`ob_size` field. not have the expected effect, it just causes confusion. Maybe this should be added as a feature just like :attr:`__weakref__` though.) + **Default:** + + This slot has no default. For static types, if the field is + NULL then no __dict__ gets created for instances. + .. c:member:: initproc PyTypeObject.tp_init @@ -871,8 +1217,14 @@ type objects) *must* have the :attr:`ob_size` field. :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. + **Inheritance:** + This field is inherited by subtypes. + **Default:** + + For static types this field does not have a default. + .. c:member:: allocfunc PyTypeObject.tp_alloc @@ -895,20 +1247,26 @@ type objects) *must* have the :attr:`ob_size` field. 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. + **Inheritance:** + + This field is inherited by static subtypes, but not by dynamic + subtypes (subtypes created by a class statement). + + **Default:** + + For dynamic subtypes, this field is always set to + :c:func:`PyType_GenericAlloc`, to force a standard heap + allocation strategy. + + For static subtypess, PyBaseObject_Type uses + :c:func:`PyType_GenericAlloc`. That is the recommended value + for all 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) @@ -927,9 +1285,18 @@ type objects) *must* have the :attr:`ob_size` field. in :c:member:`~PyTypeObject.tp_new`, while for mutable types, most initialization should be deferred to :c:member:`~PyTypeObject.tp_init`. + **Inheritance:** + 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``. + **Default:** + + For static types this field has no default. This means if the + slot is defined as NULL, the type cannot be called to create new + instances; presumably there is some other way to create + instances, like a factory function. + .. c:member:: destructor PyTypeObject.tp_free @@ -940,11 +1307,19 @@ type objects) *must* have the :attr:`ob_size` field. An initializer that is compatible with this signature is :c:func:`PyObject_Free`. - 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 + **Inheritance:** + + This field is inherited by static subtypes, but not by dynamic + subtypes (subtypes created by a class statement) + + **Default:** + + In dynamic subtypes, 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. + For static subtypes, :c:type:`PyBaseObject_Type` uses PyObject_Del. + .. c:member:: inquiry PyTypeObject.tp_is_gc @@ -964,8 +1339,15 @@ type objects) *must* have the :attr:`ob_size` field. :c:data:`PyType_Type`, defines this function to distinguish between statically and dynamically allocated types.) + **Inheritance:** + This field is inherited by subtypes. + **Default:** + + This slot has no default. If this field is NULL, + :const:`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent. + .. c:member:: PyObject* PyTypeObject.tp_bases @@ -974,6 +1356,8 @@ type objects) *must* have the :attr:`ob_size` field. This is set for types created by a class statement. It should be *NULL* for statically defined types. + **Inheritance:** + This field is not inherited. @@ -982,7 +1366,11 @@ type objects) *must* have the :attr:`ob_size` field. 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`. + + **Inheritance:** + + This field is not inherited; it is calculated fresh by + :c:func:`PyType_Ready`. .. c:member:: destructor PyTypeObject.tp_finalize @@ -1028,19 +1416,34 @@ type objects) *must* have the :attr:`ob_size` field. .. c:member:: PyObject* PyTypeObject.tp_cache - Unused. Not inherited. Internal use only. + Unused. Internal use only. + + **Inheritance:** + + This field is not inherited. .. c:member:: PyObject* PyTypeObject.tp_subclasses List of weak references to subclasses. Not inherited. Internal use only. + **Inheritance:** + + This field is not inherited. + .. c:member:: PyObject* PyTypeObject.tp_weaklist Weak reference list head, for weak references to this type object. Not inherited. Internal use only. + **Inheritance:** + + This field is not inherited. + +.. XXX missing tp_del? + + 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 @@ -1416,3 +1819,148 @@ Async Object Structures Must return an :term:`awaitable` object. See :meth:`__anext__` for details. This slot may be set to *NULL*. + + +.. _slot-typedefs: + +Slot Type typedefs +================== + ++-------------------+--------------------+-------------+ +| typedef | Parameter Types | Return Type | ++===================+====================+=============+ +| allocfunc | .. line-block:: | PyObject * | +| | | | +| | PyTypeObject * | | +| | Py_ssize_t | | ++-------------------+--------------------+-------------+ +| destructor | void * | void | ++-------------------+--------------------+-------------+ +| freefunc | void * | void | ++-------------------+--------------------+-------------+ +| traverseproc | .. line-block:: | int | +| | | | +| | void * | | +| | "visitproc" | | +| | void * | | ++-------------------+--------------------+-------------+ +| newfunc | .. line-block:: | PyObject * | +| | | | +| | PyObject * | | +| | PyObject * | | +| | PyObject * | | ++-------------------+--------------------+-------------+ +| initproc | .. line-block:: | int | +| | | | +| | PyObject * | | +| | PyObject * | | +| | PyObject * | | ++-------------------+--------------------+-------------+ +| reprfunc | PyObject * | PyObject * | ++-------------------+--------------------+-------------+ +| printfunc | .. line-block:: | int | +| | | | +| | PyObject * | | +| | FILE * | | +| | int | | ++-------------------+--------------------+-------------+ +| getattrfunc | .. line-block:: | PyObject * | +| | | | +| | PyObject * | | +| | const char * | | ++-------------------+--------------------+-------------+ +| setattrfunc | .. line-block:: | int | +| | | | +| | PyObject * | | +| | const char * | | +| | PyObject * | | ++-------------------+--------------------+-------------+ +| descrgetfunc | .. line-block:: | PyObject * | +| | | | +| | PyObject * | | +| | PyObject * | | +| | PyObject * | | ++-------------------+--------------------+-------------+ +| descrsetfunc | .. line-block:: | int | +| | | | +| | PyObject * | | +| | PyObject * | | +| | PyObject * | | ++-------------------+--------------------+-------------+ +| hashfunc | PyObject * | Py_hash_t | ++-------------------+--------------------+-------------+ +| richcmpfunc | .. line-block:: | PyObject * | +| | | | +| | PyObject * | | +| | PyObject * | | +| | int | | ++-------------------+--------------------+-------------+ +| getiterfunc | PyObject * | PyObject * | ++-------------------+--------------------+-------------+ +| iternextfunc | PyObject * | PyObject * | ++-------------------+--------------------+-------------+ +| lenfunc | PyObject * | Py_ssize_t | ++-------------------+--------------------+-------------+ +| getbufferproc | .. line-block:: | int | +| | | | +| | PyObject * | | +| | PyBuffer * | | +| | int | | ++-------------------+--------------------+-------------+ +| releasebufferproc | .. line-block:: | void | +| | | | +| | PyObject * | | +| | PyBuffer * | | ++-------------------+--------------------+-------------+ +| inquiry | void * | int | ++-------------------+--------------------+-------------+ +| unaryfunc | .. line-block:: | PyObject * | +| | | | +| | PyObject * | | ++-------------------+--------------------+-------------+ +| binaryfunc | .. line-block:: | PyObject * | +| | | | +| | PyObject * | | +| | PyObject * | | ++-------------------+--------------------+-------------+ +| ternaryfunc | .. line-block:: | PyObject * | +| | | | +| | PyObject * | | +| | PyObject * | | +| | PyObject * | | ++-------------------+--------------------+-------------+ +| ssizeargfunc | .. line-block:: | PyObject * | +| | | | +| | PyObject * | | +| | Py_ssize_t | | ++-------------------+--------------------+-------------+ +| ssizeobjargproc | .. line-block:: | int | +| | | | +| | PyObject * | | +| | Py_ssize_t | | ++-------------------+--------------------+-------------+ +| objobjproc | .. line-block:: | int | +| | | | +| | PyObject * | | +| | PyObject * | | ++-------------------+--------------------+-------------+ +| objobjargproc | .. line-block:: | int | +| | | | +| | PyObject * | | +| | PyObject * | | +| | PyObject * | | ++-------------------+--------------------+-------------+ + + +.. rubric:: Footnotes + +.. [#slots] A slot name in parentheses indicates it is (effectively) deprecated. + Names in square brackets are for internal use only. +.. [#inh] + The meaning of the markers in the "Inherited" column:: + + X - type slot is inherited via PyType_Ready() if defined with a NULL value. + * - the slots of the sub-struct are inherited individually. + G - inherited, but only in combination with other slots; see the slot's description. + L - not inherited but available through the normal attribute lookup chain. + ? - it's complicated; see the slot's description. From 04b48526e2e91b8c2531672ac22884af1ecc63a5 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 16:36:42 -0600 Subject: [PATCH 02/43] Fix up the quick reference table. --- Doc/c-api/typeobj.rst | 159 +++++++++++++++++++++++++++++------------- 1 file changed, 109 insertions(+), 50 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index dcb76d56c63d6d..f5bee33708bc0d 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -23,56 +23,115 @@ structure. Quick Reference --------------- -=========================================== ================= ====================== -PyTypeObject Slot [#slots]_ Inherited [#inh]_ Type -=========================================== ================= ====================== -:c:member:`~PyTypeObject.tp_name` .. char * -:c:member:`~PyTypeObject.tp_basicsize` X int -:c:member:`~PyTypeObject.tp_itemsize` ? int -:c:member:`~PyTypeObject.tp_dealloc` X :c:type:`destructor` -(:c:member:`~PyTypeObject.tp_print`) X :c:type:`printfunc` -(:c:member:`~PyTypeObject.tp_getattr`) X :c:type:`getattrfunc` -(:c:member:`~PyTypeObject.tp_setattr`) X :c:type:`setattrfunc` -(:c:member:`~PyTypeObject.tp_reserved`) .. void* -:c:member:`~PyTypeObject.tp_repr` X :c:type:`reprfunc` -:c:member:`~PyTypeObject.tp_as_number` \* PyNumberMethods * -:c:member:`~PyTypeObject.tp_as_sequence` \* PySequenceMethods * -:c:member:`~PyTypeObject.tp_as_mapping` \* PyMappingMethods * -:c:member:`~PyTypeObject.tp_hash` X :c:type:`hashfunc` -:c:member:`~PyTypeObject.tp_call` X :c:type:`ternaryfunc` -:c:member:`~PyTypeObject.tp_str` X :c:type:`reprfunc` -:c:member:`~PyTypeObject.tp_getattro` X :c:type:`getattrofunc` -:c:member:`~PyTypeObject.tp_setattro` X :c:type:`setattrofunc` -:c:member:`~PyTypeObject.tp_as_buffer` \* PyBufferProcs * -:c:member:`~PyTypeObject.tp_flags` ? long -:c:member:`~PyTypeObject.tp_doc` .. char * -:c:member:`~PyTypeObject.tp_traverse` X traverseproc -:c:member:`~PyTypeObject.tp_clear` X inquiry -:c:member:`~PyTypeObject.tp_richcompare` X :c:type:`richcmpfunc` -:c:member:`~PyTypeObject.tp_weaklistoffset` X long -:c:member:`~PyTypeObject.tp_iter` X :c:type:`getiterfunc` -:c:member:`~PyTypeObject.tp_iternext` X :c:type:`iternextfunc` -:c:member:`~PyTypeObject.tp_methods` L PyMethodDef[] -:c:member:`~PyTypeObject.tp_members` L PyMemberDef[] -:c:member:`~PyTypeObject.tp_getset` L PyGetSetDef[] -:c:member:`~PyTypeObject.tp_base` .. PyTypeObject * -:c:member:`~PyTypeObject.tp_dict` L PyObject * -:c:member:`~PyTypeObject.tp_descr_get` X :c:type:`descrgetfunc` -:c:member:`~PyTypeObject.tp_descr_set` X :c:type:`descrsetfunc` -:c:member:`~PyTypeObject.tp_dictoffset` X long -:c:member:`~PyTypeObject.tp_init` X initproc -:c:member:`~PyTypeObject.tp_alloc` ? :c:type:`allocfunc` -:c:member:`~PyTypeObject.tp_new` ? :c:type:`newfunc` -:c:member:`~PyTypeObject.tp_free` ? :c:type:`freefunc` -:c:member:`~PyTypeObject.tp_is_gc` X inquiry -[:c:member:`~PyTypeObject.tp_bases`] .. PyObject * -[:c:member:`~PyTypeObject.tp_mro`] .. PyObject * -[:c:member:`~PyTypeObject.tp_cache`] .. PyObject * -[:c:member:`~PyTypeObject.tp_subclasses`] .. PyObject * -[:c:member:`~PyTypeObject.tp_weaklist`] .. PyObject * -=========================================== ================= ====================== - -.. XXX add tp_del? ++---------------------------------------------+-------------------+-------------------------------+ +| PyTypeObject Slot [#slots]_ | Inherited [#inh]_ | Type :ref:`slot-typedefs` | ++=============================================+===================+===============================+ +| :c:member:`~PyTypeObject.tp_name` | .. | const char * | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_basicsize` | X | Py_ssize_t | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_itemsize` | ? | Py_ssize_t | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_dealloc` | X | :c:type:`destructor` | ++---------------------------------------------+-------------------+-------------------------------+ +| (:c:member:`~PyTypeObject.tp_print`) | X | :c:type:`printfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| (:c:member:`~PyTypeObject.tp_getattr`) | X | :c:type:`getattrfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| (:c:member:`~PyTypeObject.tp_setattr`) | X | :c:type:`setattrfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_as_async` | \* | :c:type:`PyAsyncMethods` * | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_repr` | X | :c:type:`reprfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_as_number` | \* | :c:type:`PyNumberMethods` * | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_as_sequence` | \* | :c:type:`PySequenceMethods` * | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_as_mapping` | \* | :c:type:`PyMappingMethods` * | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_hash` | X | :c:type:`hashfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_call` | X | :c:type:`ternaryfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_str` | X | :c:type:`reprfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_getattro` | X | :c:type:`getattrofunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_setattro` | X | :c:type:`setattrofunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_as_buffer` | \* | :c:type:`PyBufferProcs` * | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_flags` | ? | unsigned long | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_doc` | .. | const char * | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_traverse` | X | :c:type:`traverseproc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_clear` | X | :c:type:`inquiry` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_richcompare` | X | :c:type:`richcmpfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_weaklistoffset` | X | Py_ssize_t | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_iter` | X | :c:type:`getiterfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_iternext` | X | :c:type:`iternextfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_methods` | L | :c:type:`PyMethodDef` [] | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_members` | L | :c:type:`PyMemberDef` [] | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_getset` | L | :c:type:`PyGetSetDef` [] | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_base` | .. | :c:type:`PyTypeObject` * | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_dict` | L | :c:type:`PyObject` * | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_descr_get` | X | :c:type:`descrgetfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_descr_set` | X | :c:type:`descrsetfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_dictoffset` | X | Py_ssize_t | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_init` | X | :c:type:`initproc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_alloc` | ? | :c:type:`allocfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_new` | ? | :c:type:`newfunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_free` | ? | :c:type:`freefunc` | ++---------------------------------------------+-------------------+-------------------------------+ +| :c:member:`~PyTypeObject.tp_is_gc` | X | :c:type:`inquiry` | ++---------------------------------------------+-------------------+-------------------------------+ +| [:c:member:`~PyTypeObject.tp_bases`] | .. | :c:type:`PyObject` * | ++---------------------------------------------+-------------------+-------------------------------+ +| [:c:member:`~PyTypeObject.tp_mro`] | .. | :c:type:`PyObject` * | ++---------------------------------------------+-------------------+-------------------------------+ +| [:c:member:`~PyTypeObject.tp_cache`] | .. | :c:type:`PyObject` * | ++---------------------------------------------+-------------------+-------------------------------+ +| [:c:member:`~PyTypeObject.tp_subclasses`] | .. | :c:type:`PyObject` * | ++---------------------------------------------+-------------------+-------------------------------+ +| [:c:member:`~PyTypeObject.tp_weaklist`] | .. | :c:type:`PyObject` * | ++---------------------------------------------+-------------------+-------------------------------+ +| -- | ++---------------------------------------------+-------------------+-------------------------------+ +| [(:c:member:`~PyTypeObject.tp_del`)] | .. | :c:type:`destructor` | ++---------------------------------------------+-------------------+-------------------------------+ +| [:c:member:`~PyTypeObject.tp_version_tag`] | .. | unsigned int | ++---------------------------------------------+-------------------+-------------------------------+ +| [:c:member:`~PyTypeObject.tp_finalize`] | .. | :c:type:`destructor` | ++---------------------------------------------+-------------------+-------------------------------+ +| [:c:member:`~PyTypeObject.tp_allocs`] | .. | Py_ssize_t | ++---------------------------------------------+-------------------+-------------------------------+ +| [:c:member:`~PyTypeObject.tp_frees`] | .. | Py_ssize_t | ++---------------------------------------------+-------------------+-------------------------------+ +| [:c:member:`~PyTypeObject.tp_maxalloc`] | .. | Py_ssize_t | ++---------------------------------------------+-------------------+-------------------------------+ +| [:c:member:`~PyTypeObject.tp_prev`] | .. | :c:type:`PyTypeObject` * | ++---------------------------------------------+-------------------+-------------------------------+ +| [:c:member:`~PyTypeObject.tp_next`] | .. | :c:type:`PyTypeObject` * | ++---------------------------------------------+-------------------+-------------------------------+ PyTypeObject Definition From e1aced83aa5b64428c1e5d44c4776fad92b051c2 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 16:37:25 -0600 Subject: [PATCH 03/43] Avoid accidental bold. --- Doc/c-api/typeobj.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index f5bee33708bc0d..931e671d2862a0 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -946,7 +946,7 @@ value, that section is omitted. The following macro is defined to ease writing rich comparison functions: - .. c:function:: PyObject *Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op) + .. c:function:: PyObject \*Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op) Return ``Py_True`` or ``Py_False`` from the function, depending on the result of a comparison. From 337c9322286f6b76532b95392036fc4ff40a1339 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 16:42:52 -0600 Subject: [PATCH 04/43] Fix typos. --- Doc/c-api/typeobj.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 931e671d2862a0..fa1742fb7526d1 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -308,7 +308,7 @@ value, that section is omitted. **Default:** :c:type:`PyBaseObject_Type` uses ``sizeof(PyObject)`` for - :attr:`tp_basicsize`, However, :attr:`tp_itemsize` does not have + :attr:`tp_basicsize`. However, :attr:`tp_itemsize` does not have a default. @@ -1317,7 +1317,7 @@ value, that section is omitted. :c:func:`PyType_GenericAlloc`, to force a standard heap allocation strategy. - For static subtypess, PyBaseObject_Type uses + For static subtypes, PyBaseObject_Type uses :c:func:`PyType_GenericAlloc`. That is the recommended value for all statically defined types. From af5733de28e1790a642fa5de6665a5d8540945fe Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 16:46:56 -0600 Subject: [PATCH 05/43] Add markup for NULL. --- Doc/c-api/typeobj.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index fa1742fb7526d1..7d507634b80db0 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -901,7 +901,7 @@ value, that section is omitted. 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 + ``Py_NotImplemented``, if another error occurred it must return *NULL* and set an exception condition. .. note:: @@ -956,7 +956,7 @@ value, that section is omitted. The return value's reference count is properly incremented. - On error, sets an exception and returns NULL from the function. + On error, sets an exception and returns *NULL* from the function. .. versionadded:: 3.7 @@ -1142,7 +1142,7 @@ value, that section is omitted. **Default:** - If this field is NULL, :c:func:`PyType_Ready` will assign a new + If this field is *NULL*, :c:func:`PyType_Ready` will assign a new dictionary to it. .. warning:: @@ -1249,7 +1249,7 @@ value, that section is omitted. **Default:** This slot has no default. For static types, if the field is - NULL then no __dict__ gets created for instances. + *NULL* then no __dict__ gets created for instances. .. c:member:: initproc PyTypeObject.tp_init @@ -1352,7 +1352,7 @@ value, that section is omitted. **Default:** For static types this field has no default. This means if the - slot is defined as NULL, the type cannot be called to create new + slot is defined as *NULL*, the type cannot be called to create new instances; presumably there is some other way to create instances, like a factory function. @@ -1404,7 +1404,7 @@ value, that section is omitted. **Default:** - This slot has no default. If this field is NULL, + This slot has no default. If this field is *NULL*, :const:`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent. @@ -1604,12 +1604,12 @@ Number Object Structures and implement the necessary conversions (at least one of the operands is an instance of the defined type). 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`` + ``Py_NotImplemented``, if another error occurred they must return *NULL* and set an exception. .. note:: - The :c:data:`nb_reserved` field should always be ``NULL``. It + The :c:data:`nb_reserved` field should always be *NULL*. It was previously called :c:data:`nb_long`, and was renamed in Python 3.0.1. @@ -2018,7 +2018,7 @@ Slot Type typedefs .. [#inh] The meaning of the markers in the "Inherited" column:: - X - type slot is inherited via PyType_Ready() if defined with a NULL value. + X - type slot is inherited via PyType_Ready() if defined with a *NULL* value. * - the slots of the sub-struct are inherited individually. G - inherited, but only in combination with other slots; see the slot's description. L - not inherited but available through the normal attribute lookup chain. From 4c923e8995e6bd31525230fed840034f3dc0ef7c Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 16:49:54 -0600 Subject: [PATCH 06/43] Add markup for __dict__. --- Doc/c-api/typeobj.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 7d507634b80db0..c408f516bd8154 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1249,7 +1249,7 @@ value, that section is omitted. **Default:** This slot has no default. For static types, if the field is - *NULL* then no __dict__ gets created for instances. + *NULL* then no :attr:`__dict__` gets created for instances. .. c:member:: initproc PyTypeObject.tp_init From 3dbba8c57ae8101387b28645eead3be78c72d06b Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 17:05:21 -0600 Subject: [PATCH 07/43] Add markup in the typedefs table. --- Doc/c-api/typeobj.rst | 248 +++++++++++++++++++++--------------------- 1 file changed, 124 insertions(+), 124 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index c408f516bd8154..3d8b31eae83f21 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1885,130 +1885,130 @@ Async Object Structures Slot Type typedefs ================== -+-------------------+--------------------+-------------+ -| typedef | Parameter Types | Return Type | -+===================+====================+=============+ -| allocfunc | .. line-block:: | PyObject * | -| | | | -| | PyTypeObject * | | -| | Py_ssize_t | | -+-------------------+--------------------+-------------+ -| destructor | void * | void | -+-------------------+--------------------+-------------+ -| freefunc | void * | void | -+-------------------+--------------------+-------------+ -| traverseproc | .. line-block:: | int | -| | | | -| | void * | | -| | "visitproc" | | -| | void * | | -+-------------------+--------------------+-------------+ -| newfunc | .. line-block:: | PyObject * | -| | | | -| | PyObject * | | -| | PyObject * | | -| | PyObject * | | -+-------------------+--------------------+-------------+ -| initproc | .. line-block:: | int | -| | | | -| | PyObject * | | -| | PyObject * | | -| | PyObject * | | -+-------------------+--------------------+-------------+ -| reprfunc | PyObject * | PyObject * | -+-------------------+--------------------+-------------+ -| printfunc | .. line-block:: | int | -| | | | -| | PyObject * | | -| | FILE * | | -| | int | | -+-------------------+--------------------+-------------+ -| getattrfunc | .. line-block:: | PyObject * | -| | | | -| | PyObject * | | -| | const char * | | -+-------------------+--------------------+-------------+ -| setattrfunc | .. line-block:: | int | -| | | | -| | PyObject * | | -| | const char * | | -| | PyObject * | | -+-------------------+--------------------+-------------+ -| descrgetfunc | .. line-block:: | PyObject * | -| | | | -| | PyObject * | | -| | PyObject * | | -| | PyObject * | | -+-------------------+--------------------+-------------+ -| descrsetfunc | .. line-block:: | int | -| | | | -| | PyObject * | | -| | PyObject * | | -| | PyObject * | | -+-------------------+--------------------+-------------+ -| hashfunc | PyObject * | Py_hash_t | -+-------------------+--------------------+-------------+ -| richcmpfunc | .. line-block:: | PyObject * | -| | | | -| | PyObject * | | -| | PyObject * | | -| | int | | -+-------------------+--------------------+-------------+ -| getiterfunc | PyObject * | PyObject * | -+-------------------+--------------------+-------------+ -| iternextfunc | PyObject * | PyObject * | -+-------------------+--------------------+-------------+ -| lenfunc | PyObject * | Py_ssize_t | -+-------------------+--------------------+-------------+ -| getbufferproc | .. line-block:: | int | -| | | | -| | PyObject * | | -| | PyBuffer * | | -| | int | | -+-------------------+--------------------+-------------+ -| releasebufferproc | .. line-block:: | void | -| | | | -| | PyObject * | | -| | PyBuffer * | | -+-------------------+--------------------+-------------+ -| inquiry | void * | int | -+-------------------+--------------------+-------------+ -| unaryfunc | .. line-block:: | PyObject * | -| | | | -| | PyObject * | | -+-------------------+--------------------+-------------+ -| binaryfunc | .. line-block:: | PyObject * | -| | | | -| | PyObject * | | -| | PyObject * | | -+-------------------+--------------------+-------------+ -| ternaryfunc | .. line-block:: | PyObject * | -| | | | -| | PyObject * | | -| | PyObject * | | -| | PyObject * | | -+-------------------+--------------------+-------------+ -| ssizeargfunc | .. line-block:: | PyObject * | -| | | | -| | PyObject * | | -| | Py_ssize_t | | -+-------------------+--------------------+-------------+ -| ssizeobjargproc | .. line-block:: | int | -| | | | -| | PyObject * | | -| | Py_ssize_t | | -+-------------------+--------------------+-------------+ -| objobjproc | .. line-block:: | int | -| | | | -| | PyObject * | | -| | PyObject * | | -+-------------------+--------------------+-------------+ -| objobjargproc | .. line-block:: | int | -| | | | -| | PyObject * | | -| | PyObject * | | -| | PyObject * | | -+-------------------+--------------------+-------------+ ++-------------------+-----------------------------+----------------------+ +| typedef | Parameter Types | Return Type | ++===================+=============================+======================+ +| allocfunc | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyTypeObject` * | | +| | Py_ssize_t | | ++-------------------+-----------------------------+----------------------+ +| destructor | void * | void | ++-------------------+-----------------------------+----------------------+ +| freefunc | void * | void | ++-------------------+-----------------------------+----------------------+ +| traverseproc | .. line-block:: | int | +| | | | +| | void * | | +| | :c:type:`visitproc` | | +| | void * | | ++-------------------+-----------------------------+----------------------+ +| newfunc | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-------------------+-----------------------------+----------------------+ +| initproc | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-------------------+-----------------------------+----------------------+ +| reprfunc | :c:type:`PyObject` * | :c:type:`PyObject` * | ++-------------------+-----------------------------+----------------------+ +| printfunc | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | FILE * | | +| | int | | ++-------------------+-----------------------------+----------------------+ +| getattrfunc | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | const char * | | ++-------------------+-----------------------------+----------------------+ +| setattrfunc | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | const char * | | +| | :c:type:`PyObject` * | | ++-------------------+-----------------------------+----------------------+ +| descrgetfunc | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-------------------+-----------------------------+----------------------+ +| descrsetfunc | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-------------------+-----------------------------+----------------------+ +| hashfunc | :c:type:`PyObject` * | Py_hash_t | ++-------------------+-----------------------------+----------------------+ +| richcmpfunc | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | int | | ++-------------------+-----------------------------+----------------------+ +| getiterfunc | :c:type:`PyObject` * | :c:type:`PyObject` * | ++-------------------+-----------------------------+----------------------+ +| iternextfunc | :c:type:`PyObject` * | :c:type:`PyObject` * | ++-------------------+-----------------------------+----------------------+ +| lenfunc | :c:type:`PyObject` * | Py_ssize_t | ++-------------------+-----------------------------+----------------------+ +| getbufferproc | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:PyBuffer` * | | +| | int | | ++-------------------+-----------------------------+----------------------+ +| releasebufferproc | .. line-block:: | void | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyBuffer` * | | ++-------------------+-----------------------------+----------------------+ +| inquiry | void * | int | ++-------------------+-----------------------------+----------------------+ +| unaryfunc | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | ++-------------------+-----------------------------+----------------------+ +| binaryfunc | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-------------------+-----------------------------+----------------------+ +| ternaryfunc | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-------------------+-----------------------------+----------------------+ +| ssizeargfunc | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | Py_ssize_t | | ++-------------------+-----------------------------+----------------------+ +| ssizeobjargproc | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | Py_ssize_t | | ++-------------------+-----------------------------+----------------------+ +| objobjproc | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-------------------+-----------------------------+----------------------+ +| objobjargproc | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-------------------+-----------------------------+----------------------+ .. rubric:: Footnotes From 490b6abb7f6f629b1822512bf629cc7eac0339a7 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 17:09:12 -0600 Subject: [PATCH 08/43] Add missing markup. --- Doc/c-api/typeobj.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 3d8b31eae83f21..d99bf1cc39fe7c 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -940,9 +940,10 @@ value, that section is omitted. **Default:** - PyBaseObject_Type provides a tp_richcompare. However, if only - :attr:`tp_hash` is defined, not even this is used and instances - of the type will not be able to participate in any comparisons. + :c:type:`PyBaseObject_Type` provides a :attr:`tp_richcompare`. + However, if only :attr:`tp_hash` is defined, not even this is used + and instances of the type will not be able to participate in any + comparisons. The following macro is defined to ease writing rich comparison functions: @@ -1317,7 +1318,7 @@ value, that section is omitted. :c:func:`PyType_GenericAlloc`, to force a standard heap allocation strategy. - For static subtypes, PyBaseObject_Type uses + For static subtypes, :c:type:`PyBaseObject_Type` uses :c:func:`PyType_GenericAlloc`. That is the recommended value for all statically defined types. From ea81fc22a0b147a3e3cbe5616d86210675826613 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 17:12:04 -0600 Subject: [PATCH 09/43] Do not worry about tp_del. --- Doc/c-api/typeobj.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index d99bf1cc39fe7c..4b7607363b9a8c 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1501,9 +1501,6 @@ value, that section is omitted. This field is not inherited. -.. XXX missing tp_del? - - 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 From 0e591e6073520a59fbc7f4896cc87a83c09a6d93 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 17:14:49 -0600 Subject: [PATCH 10/43] Fix inheritance for tp_as_async. --- Doc/c-api/typeobj.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 4b7607363b9a8c..0511ecbf0687a6 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -406,7 +406,8 @@ value, that section is omitted. **Inheritance:** - This field is inherited by subtypes. + The :c:member:`~PyTypeObject.tp_as_async` field is not inherited, + but the contained fields are inherited individually. **Default:** From 46233dc048336f5fc9fcd0247421af9886e42c01 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 17:17:37 -0600 Subject: [PATCH 11/43] Fix inheritance for tp_hash. --- Doc/c-api/typeobj.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 0511ecbf0687a6..77db65c48e49fa 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -501,9 +501,6 @@ value, that section is omitted. normal return value; when an error occurs during the computation of the hash value, the function should set an exception and return ``-1``. - When this field is not set, an attempt to take the hash of the - object raises :exc:`TypeError`. - 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 From 414448f683becb8a2b8294ebd517bac84b4ffa98 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 17:37:35 -0600 Subject: [PATCH 12/43] Clarify tp_hash when NULL. --- Doc/c-api/typeobj.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 77db65c48e49fa..f9a68211dfe110 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -501,6 +501,10 @@ value, that section is omitted. normal return value; when an error occurs during the computation of the hash value, the function should set an exception and return ``-1``. + When this field is not set (*and* :attr:`tp_richcompare` is not set), + an attempt to take the hash of the object raises :exc:`TypeError`. + This is the same as setting it to :c:func:`PyObject_HashNotImplemented`. + 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 From 356012d69e7d79110ab26c1785aec4e8c5f34d8d Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 17:38:25 -0600 Subject: [PATCH 13/43] Do not refer to _Py_HashPointer. --- Doc/c-api/typeobj.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index f9a68211dfe110..435a2b0ed1319f 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -524,7 +524,8 @@ value, that section is omitted. **Default:** - :c:type:`PyBaseObject_Type` uses :c:func:`_Py_HashPointer`. + :c:type:`PyBaseObject_Type` uses a :c:type:`hashfunc` that hashes + the object's :attr:`id`. .. c:member:: ternaryfunc PyTypeObject.tp_call From f4d6500dbd3abbeed109717ec744812866fbcabb Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Tue, 5 Jun 2018 17:44:44 -0600 Subject: [PATCH 14/43] Drop duplicate info about PyGetSetDef. --- Doc/c-api/typeobj.rst | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 435a2b0ed1319f..418ae271eed2c1 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1088,21 +1088,6 @@ value, that section is omitted. 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. - .. 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 the attribute */ - char *doc; /* optional doc string */ - void *closure; /* optional additional data for getter and setter */ - } PyGetSetDef; - **Inheritance:** This field is not inherited by subtypes (computed attributes are inherited From a3021d12af24a502f4c9adbdd09642bfc33ae7a3 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 08:55:31 -0600 Subject: [PATCH 15/43] Fix the anchor for tp_as_async. --- Doc/c-api/typeobj.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 418ae271eed2c1..c44b73d206f785 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -395,7 +395,7 @@ value, that section is omitted. This field does not have a default. -.. c:member:: PyAsyncMethods* tp_as_async +.. c:member:: PyAsyncMethods* PyTypeObject.tp_as_async Pointer to an additional structure that contains fields relevant only to objects which implement :term:`awaitable` and :term:`asynchronous iterator` From 39a19c8c91705f9d97af2c7bd94eada0ebab7c12 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 08:59:33 -0600 Subject: [PATCH 16/43] Move the quick-ref table legend up below the table. --- Doc/c-api/typeobj.rst | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index c44b73d206f785..a642cf3ce139d4 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -133,6 +133,17 @@ Quick Reference | [:c:member:`~PyTypeObject.tp_next`] | .. | :c:type:`PyTypeObject` * | +---------------------------------------------+-------------------+-------------------------------+ +.. [#slots] A slot name in parentheses indicates it is (effectively) deprecated. + Names in square brackets are for internal use only. +.. [#inh] + The meaning of the markers in the "Inherited" column:: + + X - type slot is inherited via PyType_Ready() if defined with a *NULL* value. + * - the slots of the sub-struct are inherited individually. + G - inherited, but only in combination with other slots; see the slot's description. + L - not inherited but available through the normal attribute lookup chain. + ? - it's complicated; see the slot's description. + PyTypeObject Definition ----------------------- @@ -1995,17 +2006,3 @@ Slot Type typedefs | | :c:type:`PyObject` * | | | | :c:type:`PyObject` * | | +-------------------+-----------------------------+----------------------+ - - -.. rubric:: Footnotes - -.. [#slots] A slot name in parentheses indicates it is (effectively) deprecated. - Names in square brackets are for internal use only. -.. [#inh] - The meaning of the markers in the "Inherited" column:: - - X - type slot is inherited via PyType_Ready() if defined with a *NULL* value. - * - the slots of the sub-struct are inherited individually. - G - inherited, but only in combination with other slots; see the slot's description. - L - not inherited but available through the normal attribute lookup chain. - ? - it's complicated; see the slot's description. From 305468b9d29420357f286b338a722421214941bb Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 09:21:50 -0600 Subject: [PATCH 17/43] Add links to typedef names in the summary table. --- Doc/c-api/typeobj.rst | 251 +++++++++++++++++++++--------------------- 1 file changed, 127 insertions(+), 124 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index a642cf3ce139d4..7aefd0683f2600 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1882,127 +1882,130 @@ Async Object Structures Slot Type typedefs ================== -+-------------------+-----------------------------+----------------------+ -| typedef | Parameter Types | Return Type | -+===================+=============================+======================+ -| allocfunc | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyTypeObject` * | | -| | Py_ssize_t | | -+-------------------+-----------------------------+----------------------+ -| destructor | void * | void | -+-------------------+-----------------------------+----------------------+ -| freefunc | void * | void | -+-------------------+-----------------------------+----------------------+ -| traverseproc | .. line-block:: | int | -| | | | -| | void * | | -| | :c:type:`visitproc` | | -| | void * | | -+-------------------+-----------------------------+----------------------+ -| newfunc | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-------------------+-----------------------------+----------------------+ -| initproc | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-------------------+-----------------------------+----------------------+ -| reprfunc | :c:type:`PyObject` * | :c:type:`PyObject` * | -+-------------------+-----------------------------+----------------------+ -| printfunc | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | FILE * | | -| | int | | -+-------------------+-----------------------------+----------------------+ -| getattrfunc | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | const char * | | -+-------------------+-----------------------------+----------------------+ -| setattrfunc | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | const char * | | -| | :c:type:`PyObject` * | | -+-------------------+-----------------------------+----------------------+ -| descrgetfunc | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-------------------+-----------------------------+----------------------+ -| descrsetfunc | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-------------------+-----------------------------+----------------------+ -| hashfunc | :c:type:`PyObject` * | Py_hash_t | -+-------------------+-----------------------------+----------------------+ -| richcmpfunc | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | int | | -+-------------------+-----------------------------+----------------------+ -| getiterfunc | :c:type:`PyObject` * | :c:type:`PyObject` * | -+-------------------+-----------------------------+----------------------+ -| iternextfunc | :c:type:`PyObject` * | :c:type:`PyObject` * | -+-------------------+-----------------------------+----------------------+ -| lenfunc | :c:type:`PyObject` * | Py_ssize_t | -+-------------------+-----------------------------+----------------------+ -| getbufferproc | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:PyBuffer` * | | -| | int | | -+-------------------+-----------------------------+----------------------+ -| releasebufferproc | .. line-block:: | void | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyBuffer` * | | -+-------------------+-----------------------------+----------------------+ -| inquiry | void * | int | -+-------------------+-----------------------------+----------------------+ -| unaryfunc | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -+-------------------+-----------------------------+----------------------+ -| binaryfunc | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-------------------+-----------------------------+----------------------+ -| ternaryfunc | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-------------------+-----------------------------+----------------------+ -| ssizeargfunc | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | Py_ssize_t | | -+-------------------+-----------------------------+----------------------+ -| ssizeobjargproc | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | Py_ssize_t | | -+-------------------+-----------------------------+----------------------+ -| objobjproc | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-------------------+-----------------------------+----------------------+ -| objobjargproc | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-------------------+-----------------------------+----------------------+ ++-----------------------------+-----------------------------+----------------------+ +| typedef | Parameter Types | Return Type | ++=============================+=============================+======================+ +| :c:type:`allocfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyTypeObject` * | | +| | Py_ssize_t | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`destructor` | void * | void | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`freefunc` | void * | void | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`traverseproc` | .. line-block:: | int | +| | | | +| | void * | | +| | :c:type:`visitproc` | | +| | void * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`newfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`initproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`reprfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`printfunc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | FILE * | | +| | int | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`getattrfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | const char * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`setattrfunc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | const char * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`descrgetfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`descrsetfunc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`hashfunc` | :c:type:`PyObject` * | Py_hash_t | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`richcmpfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | int | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`getiterfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`iternextfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`lenfunc` | :c:type:`PyObject` * | Py_ssize_t | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`getbufferproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:PyBuffer` * | | +| | int | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`releasebufferproc` | .. line-block:: | void | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyBuffer` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`inquiry` | void * | int | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`unaryfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`binaryfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`ternaryfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`ssizeargfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | Py_ssize_t | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`ssizeobjargproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | Py_ssize_t | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`objobjproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`objobjargproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ + +.. c:type:: void (*destructor)(PyObject *) + From 221181c9dc39a3cb0ec78cf69df9bae4a4adb8ba Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 09:37:09 -0600 Subject: [PATCH 18/43] Move the slot typedefs table to the quick reference section. --- Doc/c-api/typeobj.rst | 478 ++++++++++++++++++++++-------------------- 1 file changed, 245 insertions(+), 233 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 7aefd0683f2600..b5fa76652ad219 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -20,118 +20,121 @@ 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. + +.. _tp-slots-table: + Quick Reference --------------- -+---------------------------------------------+-------------------+-------------------------------+ -| PyTypeObject Slot [#slots]_ | Inherited [#inh]_ | Type :ref:`slot-typedefs` | -+=============================================+===================+===============================+ -| :c:member:`~PyTypeObject.tp_name` | .. | const char * | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_basicsize` | X | Py_ssize_t | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_itemsize` | ? | Py_ssize_t | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_dealloc` | X | :c:type:`destructor` | -+---------------------------------------------+-------------------+-------------------------------+ -| (:c:member:`~PyTypeObject.tp_print`) | X | :c:type:`printfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| (:c:member:`~PyTypeObject.tp_getattr`) | X | :c:type:`getattrfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| (:c:member:`~PyTypeObject.tp_setattr`) | X | :c:type:`setattrfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_as_async` | \* | :c:type:`PyAsyncMethods` * | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_repr` | X | :c:type:`reprfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_as_number` | \* | :c:type:`PyNumberMethods` * | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_as_sequence` | \* | :c:type:`PySequenceMethods` * | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_as_mapping` | \* | :c:type:`PyMappingMethods` * | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_hash` | X | :c:type:`hashfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_call` | X | :c:type:`ternaryfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_str` | X | :c:type:`reprfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_getattro` | X | :c:type:`getattrofunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_setattro` | X | :c:type:`setattrofunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_as_buffer` | \* | :c:type:`PyBufferProcs` * | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_flags` | ? | unsigned long | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_doc` | .. | const char * | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_traverse` | X | :c:type:`traverseproc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_clear` | X | :c:type:`inquiry` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_richcompare` | X | :c:type:`richcmpfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_weaklistoffset` | X | Py_ssize_t | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_iter` | X | :c:type:`getiterfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_iternext` | X | :c:type:`iternextfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_methods` | L | :c:type:`PyMethodDef` [] | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_members` | L | :c:type:`PyMemberDef` [] | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_getset` | L | :c:type:`PyGetSetDef` [] | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_base` | .. | :c:type:`PyTypeObject` * | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_dict` | L | :c:type:`PyObject` * | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_descr_get` | X | :c:type:`descrgetfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_descr_set` | X | :c:type:`descrsetfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_dictoffset` | X | Py_ssize_t | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_init` | X | :c:type:`initproc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_alloc` | ? | :c:type:`allocfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_new` | ? | :c:type:`newfunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_free` | ? | :c:type:`freefunc` | -+---------------------------------------------+-------------------+-------------------------------+ -| :c:member:`~PyTypeObject.tp_is_gc` | X | :c:type:`inquiry` | -+---------------------------------------------+-------------------+-------------------------------+ -| [:c:member:`~PyTypeObject.tp_bases`] | .. | :c:type:`PyObject` * | -+---------------------------------------------+-------------------+-------------------------------+ -| [:c:member:`~PyTypeObject.tp_mro`] | .. | :c:type:`PyObject` * | -+---------------------------------------------+-------------------+-------------------------------+ -| [:c:member:`~PyTypeObject.tp_cache`] | .. | :c:type:`PyObject` * | -+---------------------------------------------+-------------------+-------------------------------+ -| [:c:member:`~PyTypeObject.tp_subclasses`] | .. | :c:type:`PyObject` * | -+---------------------------------------------+-------------------+-------------------------------+ -| [:c:member:`~PyTypeObject.tp_weaklist`] | .. | :c:type:`PyObject` * | -+---------------------------------------------+-------------------+-------------------------------+ -| -- | -+---------------------------------------------+-------------------+-------------------------------+ -| [(:c:member:`~PyTypeObject.tp_del`)] | .. | :c:type:`destructor` | -+---------------------------------------------+-------------------+-------------------------------+ -| [:c:member:`~PyTypeObject.tp_version_tag`] | .. | unsigned int | -+---------------------------------------------+-------------------+-------------------------------+ -| [:c:member:`~PyTypeObject.tp_finalize`] | .. | :c:type:`destructor` | -+---------------------------------------------+-------------------+-------------------------------+ -| [:c:member:`~PyTypeObject.tp_allocs`] | .. | Py_ssize_t | -+---------------------------------------------+-------------------+-------------------------------+ -| [:c:member:`~PyTypeObject.tp_frees`] | .. | Py_ssize_t | -+---------------------------------------------+-------------------+-------------------------------+ -| [:c:member:`~PyTypeObject.tp_maxalloc`] | .. | Py_ssize_t | -+---------------------------------------------+-------------------+-------------------------------+ -| [:c:member:`~PyTypeObject.tp_prev`] | .. | :c:type:`PyTypeObject` * | -+---------------------------------------------+-------------------+-------------------------------+ -| [:c:member:`~PyTypeObject.tp_next`] | .. | :c:type:`PyTypeObject` * | -+---------------------------------------------+-------------------+-------------------------------+ ++---------------------------------------------+-------------------+-----------------------------------+ +| PyTypeObject Slot [#slots]_ | Inherited [#inh]_ | :ref:`Type ` | ++=============================================+===================+===================================+ +| :c:member:`~PyTypeObject.tp_name` | .. | const char * | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_basicsize` | X | Py_ssize_t | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_itemsize` | ? | Py_ssize_t | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_dealloc` | X | :c:type:`destructor` | ++---------------------------------------------+-------------------+-----------------------------------+ +| (:c:member:`~PyTypeObject.tp_print`) | X | :c:type:`printfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| (:c:member:`~PyTypeObject.tp_getattr`) | X | :c:type:`getattrfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| (:c:member:`~PyTypeObject.tp_setattr`) | X | :c:type:`setattrfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_as_async` | \* | :c:type:`PyAsyncMethods` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_repr` | X | :c:type:`reprfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_as_number` | \* | :c:type:`PyNumberMethods` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_as_sequence` | \* | :c:type:`PySequenceMethods` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_as_mapping` | \* | :c:type:`PyMappingMethods` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_hash` | X | :c:type:`hashfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_call` | X | :c:type:`ternaryfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_str` | X | :c:type:`reprfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_getattro` | X | :c:type:`getattrofunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_setattro` | X | :c:type:`setattrofunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_as_buffer` | \* | :c:type:`PyBufferProcs` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_flags` | ? | unsigned long | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_doc` | .. | const char * | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_traverse` | X | :c:type:`traverseproc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_clear` | X | :c:type:`inquiry` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_richcompare` | X | :c:type:`richcmpfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_weaklistoffset` | X | Py_ssize_t | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_iter` | X | :c:type:`getiterfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_iternext` | X | :c:type:`iternextfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_methods` | L | :c:type:`PyMethodDef` [] | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_members` | L | :c:type:`PyMemberDef` [] | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_getset` | L | :c:type:`PyGetSetDef` [] | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_base` | .. | :c:type:`PyTypeObject` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_dict` | L | :c:type:`PyObject` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_descr_get` | X | :c:type:`descrgetfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_descr_set` | X | :c:type:`descrsetfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_dictoffset` | X | Py_ssize_t | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_init` | X | :c:type:`initproc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_alloc` | ? | :c:type:`allocfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_new` | ? | :c:type:`newfunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_free` | ? | :c:type:`freefunc` | ++---------------------------------------------+-------------------+-----------------------------------+ +| :c:member:`~PyTypeObject.tp_is_gc` | X | :c:type:`inquiry` | ++---------------------------------------------+-------------------+-----------------------------------+ +| [:c:member:`~PyTypeObject.tp_bases`] | .. | :c:type:`PyObject` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| [:c:member:`~PyTypeObject.tp_mro`] | .. | :c:type:`PyObject` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| [:c:member:`~PyTypeObject.tp_cache`] | .. | :c:type:`PyObject` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| [:c:member:`~PyTypeObject.tp_subclasses`] | .. | :c:type:`PyObject` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| [:c:member:`~PyTypeObject.tp_weaklist`] | .. | :c:type:`PyObject` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| -- | ++---------------------------------------------+-------------------+-----------------------------------+ +| [(:c:member:`~PyTypeObject.tp_del`)] | .. | :c:type:`destructor` | ++---------------------------------------------+-------------------+-----------------------------------+ +| [:c:member:`~PyTypeObject.tp_version_tag`] | .. | unsigned int | ++---------------------------------------------+-------------------+-----------------------------------+ +| [:c:member:`~PyTypeObject.tp_finalize`] | .. | :c:type:`destructor` | ++---------------------------------------------+-------------------+-----------------------------------+ +| [:c:member:`~PyTypeObject.tp_allocs`] | .. | Py_ssize_t | ++---------------------------------------------+-------------------+-----------------------------------+ +| [:c:member:`~PyTypeObject.tp_frees`] | .. | Py_ssize_t | ++---------------------------------------------+-------------------+-----------------------------------+ +| [:c:member:`~PyTypeObject.tp_maxalloc`] | .. | Py_ssize_t | ++---------------------------------------------+-------------------+-----------------------------------+ +| [:c:member:`~PyTypeObject.tp_prev`] | .. | :c:type:`PyTypeObject` * | ++---------------------------------------------+-------------------+-----------------------------------+ +| [:c:member:`~PyTypeObject.tp_next`] | .. | :c:type:`PyTypeObject` * | ++---------------------------------------------+-------------------+-----------------------------------+ .. [#slots] A slot name in parentheses indicates it is (effectively) deprecated. Names in square brackets are for internal use only. @@ -145,6 +148,139 @@ Quick Reference ? - it's complicated; see the slot's description. +.. _slot-typedefs-table: + +Slot typedefs +^^^^^^^^^^^^^ + ++-----------------------------+-----------------------------+----------------------+ +| typedef | Parameter Types | Return Type | ++=============================+=============================+======================+ +| :c:type:`allocfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyTypeObject` * | | +| | Py_ssize_t | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`destructor` | void * | void | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`freefunc` | void * | void | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`traverseproc` | .. line-block:: | int | +| | | | +| | void * | | +| | :c:type:`visitproc` | | +| | void * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`newfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`initproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`reprfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`printfunc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | FILE * | | +| | int | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`getattrfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | const char * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`setattrfunc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | const char * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`descrgetfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`descrsetfunc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`hashfunc` | :c:type:`PyObject` * | Py_hash_t | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`richcmpfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | int | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`getiterfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`iternextfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`lenfunc` | :c:type:`PyObject` * | Py_ssize_t | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`getbufferproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:PyBuffer` * | | +| | int | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`releasebufferproc` | .. line-block:: | void | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyBuffer` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`inquiry` | void * | int | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`unaryfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`binaryfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`ternaryfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`ssizeargfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | Py_ssize_t | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`ssizeobjargproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | Py_ssize_t | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`objobjproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`objobjargproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ + +See :ref:`slot-typedefs` below for more detail. + + PyTypeObject Definition ----------------------- @@ -1882,130 +2018,6 @@ Async Object Structures Slot Type typedefs ================== -+-----------------------------+-----------------------------+----------------------+ -| typedef | Parameter Types | Return Type | -+=============================+=============================+======================+ -| :c:type:`allocfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyTypeObject` * | | -| | Py_ssize_t | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`destructor` | void * | void | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`freefunc` | void * | void | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`traverseproc` | .. line-block:: | int | -| | | | -| | void * | | -| | :c:type:`visitproc` | | -| | void * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`newfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`initproc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`reprfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`printfunc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | FILE * | | -| | int | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`getattrfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | const char * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`setattrfunc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | const char * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`descrgetfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`descrsetfunc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`hashfunc` | :c:type:`PyObject` * | Py_hash_t | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`richcmpfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | int | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`getiterfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`iternextfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`lenfunc` | :c:type:`PyObject` * | Py_ssize_t | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`getbufferproc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:PyBuffer` * | | -| | int | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`releasebufferproc` | .. line-block:: | void | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyBuffer` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`inquiry` | void * | int | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`unaryfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`binaryfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`ternaryfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`ssizeargfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | Py_ssize_t | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`ssizeobjargproc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | Py_ssize_t | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`objobjproc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`objobjargproc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ .. c:type:: void (*destructor)(PyObject *) From c35b627c3725d0d5120c754aae6d7984783ddd93 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 09:55:26 -0600 Subject: [PATCH 19/43] Fix the table of contents. --- Doc/c-api/typeobj.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index b5fa76652ad219..cf2cb219d1bf35 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -21,11 +21,14 @@ section. The fields will be described in the order in which they occur in the structure. -.. _tp-slots-table: - Quick Reference --------------- +.. _tp-slots-table: + +"tp slots" +^^^^^^^^^^ + +---------------------------------------------+-------------------+-----------------------------------+ | PyTypeObject Slot [#slots]_ | Inherited [#inh]_ | :ref:`Type ` | +=============================================+===================+===================================+ @@ -150,7 +153,7 @@ Quick Reference .. _slot-typedefs-table: -Slot typedefs +slot typedefs ^^^^^^^^^^^^^ +-----------------------------+-----------------------------+----------------------+ From 6759ac71a95f7ea4ca734e3fe63ffa2e6f55311f Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 10:21:55 -0600 Subject: [PATCH 20/43] Add more "info" columns to the tp slots table. --- Doc/c-api/typeobj.rst | 227 +++++++++++++++++++++--------------------- 1 file changed, 116 insertions(+), 111 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index cf2cb219d1bf35..30be3c0fd90054 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -29,120 +29,125 @@ Quick Reference "tp slots" ^^^^^^^^^^ -+---------------------------------------------+-------------------+-----------------------------------+ -| PyTypeObject Slot [#slots]_ | Inherited [#inh]_ | :ref:`Type ` | -+=============================================+===================+===================================+ -| :c:member:`~PyTypeObject.tp_name` | .. | const char * | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_basicsize` | X | Py_ssize_t | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_itemsize` | ? | Py_ssize_t | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_dealloc` | X | :c:type:`destructor` | -+---------------------------------------------+-------------------+-----------------------------------+ -| (:c:member:`~PyTypeObject.tp_print`) | X | :c:type:`printfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| (:c:member:`~PyTypeObject.tp_getattr`) | X | :c:type:`getattrfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| (:c:member:`~PyTypeObject.tp_setattr`) | X | :c:type:`setattrfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_as_async` | \* | :c:type:`PyAsyncMethods` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_repr` | X | :c:type:`reprfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_as_number` | \* | :c:type:`PyNumberMethods` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_as_sequence` | \* | :c:type:`PySequenceMethods` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_as_mapping` | \* | :c:type:`PyMappingMethods` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_hash` | X | :c:type:`hashfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_call` | X | :c:type:`ternaryfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_str` | X | :c:type:`reprfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_getattro` | X | :c:type:`getattrofunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_setattro` | X | :c:type:`setattrofunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_as_buffer` | \* | :c:type:`PyBufferProcs` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_flags` | ? | unsigned long | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_doc` | .. | const char * | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_traverse` | X | :c:type:`traverseproc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_clear` | X | :c:type:`inquiry` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_richcompare` | X | :c:type:`richcmpfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_weaklistoffset` | X | Py_ssize_t | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_iter` | X | :c:type:`getiterfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_iternext` | X | :c:type:`iternextfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_methods` | L | :c:type:`PyMethodDef` [] | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_members` | L | :c:type:`PyMemberDef` [] | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_getset` | L | :c:type:`PyGetSetDef` [] | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_base` | .. | :c:type:`PyTypeObject` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_dict` | L | :c:type:`PyObject` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_descr_get` | X | :c:type:`descrgetfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_descr_set` | X | :c:type:`descrsetfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_dictoffset` | X | Py_ssize_t | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_init` | X | :c:type:`initproc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_alloc` | ? | :c:type:`allocfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_new` | ? | :c:type:`newfunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_free` | ? | :c:type:`freefunc` | -+---------------------------------------------+-------------------+-----------------------------------+ -| :c:member:`~PyTypeObject.tp_is_gc` | X | :c:type:`inquiry` | -+---------------------------------------------+-------------------+-----------------------------------+ -| [:c:member:`~PyTypeObject.tp_bases`] | .. | :c:type:`PyObject` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| [:c:member:`~PyTypeObject.tp_mro`] | .. | :c:type:`PyObject` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| [:c:member:`~PyTypeObject.tp_cache`] | .. | :c:type:`PyObject` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| [:c:member:`~PyTypeObject.tp_subclasses`] | .. | :c:type:`PyObject` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| [:c:member:`~PyTypeObject.tp_weaklist`] | .. | :c:type:`PyObject` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| -- | -+---------------------------------------------+-------------------+-----------------------------------+ -| [(:c:member:`~PyTypeObject.tp_del`)] | .. | :c:type:`destructor` | -+---------------------------------------------+-------------------+-----------------------------------+ -| [:c:member:`~PyTypeObject.tp_version_tag`] | .. | unsigned int | -+---------------------------------------------+-------------------+-----------------------------------+ -| [:c:member:`~PyTypeObject.tp_finalize`] | .. | :c:type:`destructor` | -+---------------------------------------------+-------------------+-----------------------------------+ -| [:c:member:`~PyTypeObject.tp_allocs`] | .. | Py_ssize_t | -+---------------------------------------------+-------------------+-----------------------------------+ -| [:c:member:`~PyTypeObject.tp_frees`] | .. | Py_ssize_t | -+---------------------------------------------+-------------------+-----------------------------------+ -| [:c:member:`~PyTypeObject.tp_maxalloc`] | .. | Py_ssize_t | -+---------------------------------------------+-------------------+-----------------------------------+ -| [:c:member:`~PyTypeObject.tp_prev`] | .. | :c:type:`PyTypeObject` * | -+---------------------------------------------+-------------------+-----------------------------------+ -| [:c:member:`~PyTypeObject.tp_next`] | .. | :c:type:`PyTypeObject` * | -+---------------------------------------------+-------------------+-----------------------------------+ ++---------------------------------------------+-----------------------------------+------------------+ +| PyTypeObject Slot [#slots]_ | :ref:`Type ` | Info [#columns]_ | +| | +----+----+---+----+ +| | | I | | | | ++=============================================+===================================+====+====+===+====+ +| :c:member:`~PyTypeObject.tp_name` | const char * | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | ? | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| (:c:member:`~PyTypeObject.tp_print`) | :c:type:`printfunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| (:c:member:`~PyTypeObject.tp_setattr`) | :c:type:`setattrfunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_as_async` | :c:type:`PyAsyncMethods` * | \* | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_repr` | :c:type:`reprfunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_as_number` | :c:type:`PyNumberMethods` * | \* | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_as_sequence` | :c:type:`PySequenceMethods` * | \* | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_as_mapping` | :c:type:`PyMappingMethods` * | \* | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_hash` | :c:type:`hashfunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_call` | :c:type:`ternaryfunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_str` | :c:type:`reprfunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_getattro` | :c:type:`getattrofunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_setattro` | :c:type:`setattrofunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_as_buffer` | :c:type:`PyBufferProcs` * | \* | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_flags` | unsigned long | ? | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_doc` | const char * | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_traverse` | :c:type:`traverseproc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_clear` | :c:type:`inquiry` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_richcompare` | :c:type:`richcmpfunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_iternext` | :c:type:`iternextfunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_methods` | :c:type:`PyMethodDef` [] | L | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_members` | :c:type:`PyMemberDef` [] | L | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_getset` | :c:type:`PyGetSetDef` [] | L | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_base` | :c:type:`PyTypeObject` * | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_dict` | :c:type:`PyObject` * | L | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_descr_get` | :c:type:`descrgetfunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_alloc` | :c:type:`allocfunc` | ? | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_new` | :c:type:`newfunc` | ? | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_free` | :c:type:`freefunc` | ? | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| :c:member:`~PyTypeObject.tp_is_gc` | :c:type:`inquiry` | X | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [:c:member:`~PyTypeObject.tp_bases`] | :c:type:`PyObject` * | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [:c:member:`~PyTypeObject.tp_mro`] | :c:type:`PyObject` * | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [:c:member:`~PyTypeObject.tp_cache`] | :c:type:`PyObject` * | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [:c:member:`~PyTypeObject.tp_subclasses`] | :c:type:`PyObject` * | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [:c:member:`~PyTypeObject.tp_weaklist`] | :c:type:`PyObject` * | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| -- | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [(:c:member:`~PyTypeObject.tp_del`)] | :c:type:`destructor` | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [:c:member:`~PyTypeObject.tp_version_tag`] | unsigned int | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [:c:member:`~PyTypeObject.tp_finalize`] | :c:type:`destructor` | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [:c:member:`~PyTypeObject.tp_allocs`] | Py_ssize_t | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [:c:member:`~PyTypeObject.tp_frees`] | Py_ssize_t | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [:c:member:`~PyTypeObject.tp_maxalloc`] | Py_ssize_t | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [:c:member:`~PyTypeObject.tp_prev`] | :c:type:`PyTypeObject` * | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ +| [:c:member:`~PyTypeObject.tp_next`] | :c:type:`PyTypeObject` * | .. | | | | ++---------------------------------------------+-----------------------------------+----+----+---+----+ .. [#slots] A slot name in parentheses indicates it is (effectively) deprecated. Names in square brackets are for internal use only. -.. [#inh] - The meaning of the markers in the "Inherited" column:: +.. [#columns] Columns: + + **"I"** (Inheritance): + + .. code-block:: none X - type slot is inherited via PyType_Ready() if defined with a *NULL* value. * - the slots of the sub-struct are inherited individually. From e4994d339453ed1c949dd380f014ca8a5c7e4edf Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 10:36:06 -0600 Subject: [PATCH 21/43] tp_finalize is not internal-only. --- Doc/c-api/typeobj.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 30be3c0fd90054..f289f32549d003 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -128,7 +128,7 @@ Quick Reference +---------------------------------------------+-----------------------------------+----+----+---+----+ | [:c:member:`~PyTypeObject.tp_version_tag`] | unsigned int | .. | | | | +---------------------------------------------+-----------------------------------+----+----+---+----+ -| [:c:member:`~PyTypeObject.tp_finalize`] | :c:type:`destructor` | .. | | | | +| :c:member:`~PyTypeObject.tp_finalize` | :c:type:`destructor` | X | | | | +---------------------------------------------+-----------------------------------+----+----+---+----+ | [:c:member:`~PyTypeObject.tp_allocs`] | Py_ssize_t | .. | | | | +---------------------------------------------+-----------------------------------+----+----+---+----+ From cd276bda85c2857485e91b05bdd791967715cf6b Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 10:36:41 -0600 Subject: [PATCH 22/43] Fix table info and add columns. --- Doc/c-api/typeobj.rst | 254 ++++++++++++++++++++++-------------------- 1 file changed, 134 insertions(+), 120 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index f289f32549d003..65a982028c44a0 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -29,132 +29,146 @@ Quick Reference "tp slots" ^^^^^^^^^^ -+---------------------------------------------+-----------------------------------+------------------+ -| PyTypeObject Slot [#slots]_ | :ref:`Type ` | Info [#columns]_ | -| | +----+----+---+----+ -| | | I | | | | -+=============================================+===================================+====+====+===+====+ -| :c:member:`~PyTypeObject.tp_name` | const char * | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | ? | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| (:c:member:`~PyTypeObject.tp_print`) | :c:type:`printfunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| (:c:member:`~PyTypeObject.tp_setattr`) | :c:type:`setattrfunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_as_async` | :c:type:`PyAsyncMethods` * | \* | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_repr` | :c:type:`reprfunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_as_number` | :c:type:`PyNumberMethods` * | \* | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_as_sequence` | :c:type:`PySequenceMethods` * | \* | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_as_mapping` | :c:type:`PyMappingMethods` * | \* | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_hash` | :c:type:`hashfunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_call` | :c:type:`ternaryfunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_str` | :c:type:`reprfunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_getattro` | :c:type:`getattrofunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_setattro` | :c:type:`setattrofunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_as_buffer` | :c:type:`PyBufferProcs` * | \* | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_flags` | unsigned long | ? | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_doc` | const char * | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_traverse` | :c:type:`traverseproc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_clear` | :c:type:`inquiry` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_richcompare` | :c:type:`richcmpfunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_iternext` | :c:type:`iternextfunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_methods` | :c:type:`PyMethodDef` [] | L | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_members` | :c:type:`PyMemberDef` [] | L | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_getset` | :c:type:`PyGetSetDef` [] | L | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_base` | :c:type:`PyTypeObject` * | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_dict` | :c:type:`PyObject` * | L | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_descr_get` | :c:type:`descrgetfunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_alloc` | :c:type:`allocfunc` | ? | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_new` | :c:type:`newfunc` | ? | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_free` | :c:type:`freefunc` | ? | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_is_gc` | :c:type:`inquiry` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| [:c:member:`~PyTypeObject.tp_bases`] | :c:type:`PyObject` * | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| [:c:member:`~PyTypeObject.tp_mro`] | :c:type:`PyObject` * | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| [:c:member:`~PyTypeObject.tp_cache`] | :c:type:`PyObject` * | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| [:c:member:`~PyTypeObject.tp_subclasses`] | :c:type:`PyObject` * | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| [:c:member:`~PyTypeObject.tp_weaklist`] | :c:type:`PyObject` * | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| -- | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| [(:c:member:`~PyTypeObject.tp_del`)] | :c:type:`destructor` | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| [:c:member:`~PyTypeObject.tp_version_tag`] | unsigned int | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| :c:member:`~PyTypeObject.tp_finalize` | :c:type:`destructor` | X | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| [:c:member:`~PyTypeObject.tp_allocs`] | Py_ssize_t | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| [:c:member:`~PyTypeObject.tp_frees`] | Py_ssize_t | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| [:c:member:`~PyTypeObject.tp_maxalloc`] | Py_ssize_t | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| [:c:member:`~PyTypeObject.tp_prev`] | :c:type:`PyTypeObject` * | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ -| [:c:member:`~PyTypeObject.tp_next`] | :c:type:`PyTypeObject` * | .. | | | | -+---------------------------------------------+-----------------------------------+----+----+---+----+ - -.. [#slots] A slot name in parentheses indicates it is (effectively) deprecated. +.. XXX Add column for corresponding Python special methods. + ++---------------------------------------------+-----------------------------------+---------------+ +| PyTypeObject Slot [#slots]_ | :ref:`Type ` | Info [#cols]_ | +| | +---+---+---+---+ +| | | O | T | D | I | ++=============================================+===================================+===+===+===+===+ +| \* :c:member:`~PyTypeObject.tp_name` | const char * | X | X | | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | X | X | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | | X | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | X | X | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| (:c:member:`~PyTypeObject.tp_print`) | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | | | | G | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| (:c:member:`~PyTypeObject.tp_setattr`) | :c:type:`setattrfunc` | | | | G | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_as_async` | :c:type:`PyAsyncMethods` * | | | | % | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_repr` | :c:type:`reprfunc` | X | X | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_as_number` | :c:type:`PyNumberMethods` * | | | | % | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_as_sequence` | :c:type:`PySequenceMethods` * | | | | % | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_as_mapping` | :c:type:`PyMappingMethods` * | | | | % | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_hash` | :c:type:`hashfunc` | X | | | G | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_call` | :c:type:`ternaryfunc` | | X | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_str` | :c:type:`reprfunc` | X | | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_getattro` | :c:type:`getattrofunc` | X | X | | G | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_setattro` | :c:type:`setattrofunc` | X | X | | G | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_as_buffer` | :c:type:`PyBufferProcs` * | | | | % | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_flags` | unsigned long | X | X | | ? | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_doc` | const char * | X | X | | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_traverse` | :c:type:`traverseproc` | | X | | G | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_clear` | :c:type:`inquiry` | | X | | G | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_richcompare` | :c:type:`richcmpfunc` | X | | | G | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | | X | | ? | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | | | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_iternext` | :c:type:`iternextfunc` | | | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_methods` | :c:type:`PyMethodDef` [] | X | X | | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_members` | :c:type:`PyMemberDef` [] | | X | | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_getset` | :c:type:`PyGetSetDef` [] | X | X | | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_base` | :c:type:`PyTypeObject` * | | | X | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_dict` | :c:type:`PyObject` * | | | ? | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_descr_get` | :c:type:`descrgetfunc` | | | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | | | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | | X | | ? | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | X | X | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_alloc` | :c:type:`allocfunc` | X | | ? | ? | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_new` | :c:type:`newfunc` | X | X | ? | ? | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_free` | :c:type:`freefunc` | X | X | ? | ? | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_is_gc` | :c:type:`inquiry` | | X | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| <:c:member:`~PyTypeObject.tp_bases`> | :c:type:`PyObject` * | | | ~ | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| <:c:member:`~PyTypeObject.tp_mro`> | :c:type:`PyObject` * | | | ~ | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| [:c:member:`~PyTypeObject.tp_cache`] | :c:type:`PyObject` * | | | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| [:c:member:`~PyTypeObject.tp_subclasses`] | :c:type:`PyObject` * | | | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| [:c:member:`~PyTypeObject.tp_weaklist`] | :c:type:`PyObject` * | | | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| (:c:member:`~PyTypeObject.tp_del`) | :c:type:`destructor` | | | | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| [:c:member:`~PyTypeObject.tp_version_tag`] | unsigned int | | | | ++---------------------------------------------+-----------------------------------+---+---+---+---+ +| :c:member:`~PyTypeObject.tp_finalize` | :c:type:`destructor` | | | | X | ++---------------------------------------------+-----------------------------------+---+---+---+---+ + +If :c:macro:`COUNT_ALLOCS` is defined then the following (internal-only) +fields exist as well: + +* :c:member:`~PyTypeObject.tp_allocs` +* :c:member:`~PyTypeObject.tp_frees` +* :c:member:`~PyTypeObject.tp_maxalloc` +* :c:member:`~PyTypeObject.tp_prev` +* :c:member:`~PyTypeObject.tp_next` + +.. [#slots] + A slot name in parentheses indicates it is (effectively) deprecated. + Names in angle brackets should be treated as read-only. Names in square brackets are for internal use only. -.. [#columns] Columns: + An asterisk means the field must be non-*NULL*. +.. [#cols] Columns: - **"I"** (Inheritance): + **"O"**: set on :c:type:`PyObject` + + **"T"**: set on :c:type:`PyTypeObject` + + **"D"**: default (if slot is set to *NULL*) + + .. code-block:: none + + X - :c:func:`PyType_Ready`() always sets this value (if *NULL*) + ~ - :c:func:`PyType_Ready`() always sets this value (it should be *NULL*) + ? - :c:func:`PyType_Ready`() may set this value depending on other slots + + **"I"**: inheritance .. code-block:: none - X - type slot is inherited via PyType_Ready() if defined with a *NULL* value. - * - the slots of the sub-struct are inherited individually. - G - inherited, but only in combination with other slots; see the slot's description. - L - not inherited but available through the normal attribute lookup chain. - ? - it's complicated; see the slot's description. + X - type slot is inherited via :c:func:`PyType_Ready`() if defined with a *NULL* value + % - the slots of the sub-struct are inherited individually + G - inherited, but only in combination with other slots; see the slot's description + ? - it's complicated; see the slot's description + L - not inherited but available through the normal attribute lookup chain .. _slot-typedefs-table: From df5f9aea5426b6cfb3a1feec1d5b26e0d82fc8fb Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 12:48:58 -0600 Subject: [PATCH 23/43] Fix table column widths. --- Doc/c-api/typeobj.rst | 201 +++++++++++++++++++++--------------------- 1 file changed, 102 insertions(+), 99 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 65a982028c44a0..a7774375d5bc8a 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -31,105 +31,108 @@ Quick Reference .. XXX Add column for corresponding Python special methods. -+---------------------------------------------+-----------------------------------+---------------+ -| PyTypeObject Slot [#slots]_ | :ref:`Type ` | Info [#cols]_ | -| | +---+---+---+---+ -| | | O | T | D | I | -+=============================================+===================================+===+===+===+===+ -| \* :c:member:`~PyTypeObject.tp_name` | const char * | X | X | | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | X | X | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | | X | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | X | X | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| (:c:member:`~PyTypeObject.tp_print`) | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | | | | G | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| (:c:member:`~PyTypeObject.tp_setattr`) | :c:type:`setattrfunc` | | | | G | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_as_async` | :c:type:`PyAsyncMethods` * | | | | % | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_repr` | :c:type:`reprfunc` | X | X | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_as_number` | :c:type:`PyNumberMethods` * | | | | % | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_as_sequence` | :c:type:`PySequenceMethods` * | | | | % | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_as_mapping` | :c:type:`PyMappingMethods` * | | | | % | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_hash` | :c:type:`hashfunc` | X | | | G | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_call` | :c:type:`ternaryfunc` | | X | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_str` | :c:type:`reprfunc` | X | | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_getattro` | :c:type:`getattrofunc` | X | X | | G | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_setattro` | :c:type:`setattrofunc` | X | X | | G | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_as_buffer` | :c:type:`PyBufferProcs` * | | | | % | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_flags` | unsigned long | X | X | | ? | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_doc` | const char * | X | X | | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_traverse` | :c:type:`traverseproc` | | X | | G | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_clear` | :c:type:`inquiry` | | X | | G | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_richcompare` | :c:type:`richcmpfunc` | X | | | G | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | | X | | ? | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | | | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_iternext` | :c:type:`iternextfunc` | | | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_methods` | :c:type:`PyMethodDef` [] | X | X | | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_members` | :c:type:`PyMemberDef` [] | | X | | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_getset` | :c:type:`PyGetSetDef` [] | X | X | | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_base` | :c:type:`PyTypeObject` * | | | X | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_dict` | :c:type:`PyObject` * | | | ? | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_descr_get` | :c:type:`descrgetfunc` | | | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | | | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | | X | | ? | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | X | X | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_alloc` | :c:type:`allocfunc` | X | | ? | ? | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_new` | :c:type:`newfunc` | X | X | ? | ? | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_free` | :c:type:`freefunc` | X | X | ? | ? | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_is_gc` | :c:type:`inquiry` | | X | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| <:c:member:`~PyTypeObject.tp_bases`> | :c:type:`PyObject` * | | | ~ | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| <:c:member:`~PyTypeObject.tp_mro`> | :c:type:`PyObject` * | | | ~ | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| [:c:member:`~PyTypeObject.tp_cache`] | :c:type:`PyObject` * | | | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| [:c:member:`~PyTypeObject.tp_subclasses`] | :c:type:`PyObject` * | | | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| [:c:member:`~PyTypeObject.tp_weaklist`] | :c:type:`PyObject` * | | | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| (:c:member:`~PyTypeObject.tp_del`) | :c:type:`destructor` | | | | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| [:c:member:`~PyTypeObject.tp_version_tag`] | unsigned int | | | | -+---------------------------------------------+-----------------------------------+---+---+---+---+ -| :c:member:`~PyTypeObject.tp_finalize` | :c:type:`destructor` | | | | X | -+---------------------------------------------+-----------------------------------+---+---+---+---+ +.. table:: + :widths: 20,20,5,5,5,5 + + +---------------------------------------------+-----------------------------------+---------------+ + | PyTypeObject Slot [#slots]_ | :ref:`Type ` | Info [#cols]_ | + | | +---+---+---+---+ + | | | O | T | D | I | + +=============================================+===================================+===+===+===+===+ + | \* :c:member:`~PyTypeObject.tp_name` | const char * | X | X | | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | X | X | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | | X | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | X | X | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | (:c:member:`~PyTypeObject.tp_print`) | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | | | | G | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | (:c:member:`~PyTypeObject.tp_setattr`) | :c:type:`setattrfunc` | | | | G | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_async` | :c:type:`PyAsyncMethods` * | | | | % | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_repr` | :c:type:`reprfunc` | X | X | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_number` | :c:type:`PyNumberMethods` * | | | | % | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_sequence` | :c:type:`PySequenceMethods` * | | | | % | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_mapping` | :c:type:`PyMappingMethods` * | | | | % | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_hash` | :c:type:`hashfunc` | X | | | G | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_call` | :c:type:`ternaryfunc` | | X | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_str` | :c:type:`reprfunc` | X | | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_getattro` | :c:type:`getattrofunc` | X | X | | G | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_setattro` | :c:type:`setattrofunc` | X | X | | G | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_buffer` | :c:type:`PyBufferProcs` * | | | | % | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_flags` | unsigned long | X | X | | ? | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_doc` | const char * | X | X | | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_traverse` | :c:type:`traverseproc` | | X | | G | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_clear` | :c:type:`inquiry` | | X | | G | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_richcompare` | :c:type:`richcmpfunc` | X | | | G | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | | X | | ? | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | | | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_iternext` | :c:type:`iternextfunc` | | | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_methods` | :c:type:`PyMethodDef` [] | X | X | | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_members` | :c:type:`PyMemberDef` [] | | X | | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_getset` | :c:type:`PyGetSetDef` [] | X | X | | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_base` | :c:type:`PyTypeObject` * | | | X | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_dict` | :c:type:`PyObject` * | | | ? | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_descr_get` | :c:type:`descrgetfunc` | | | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | | | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | | X | | ? | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | X | X | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_alloc` | :c:type:`allocfunc` | X | | ? | ? | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_new` | :c:type:`newfunc` | X | X | ? | ? | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_free` | :c:type:`freefunc` | X | X | ? | ? | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_is_gc` | :c:type:`inquiry` | | X | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | <:c:member:`~PyTypeObject.tp_bases`> | :c:type:`PyObject` * | | | ~ | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | <:c:member:`~PyTypeObject.tp_mro`> | :c:type:`PyObject` * | | | ~ | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | [:c:member:`~PyTypeObject.tp_cache`] | :c:type:`PyObject` * | | | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | [:c:member:`~PyTypeObject.tp_subclasses`] | :c:type:`PyObject` * | | | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | [:c:member:`~PyTypeObject.tp_weaklist`] | :c:type:`PyObject` * | | | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | (:c:member:`~PyTypeObject.tp_del`) | :c:type:`destructor` | | | | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | [:c:member:`~PyTypeObject.tp_version_tag`] | unsigned int | | | | + +---------------------------------------------+-----------------------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_finalize` | :c:type:`destructor` | | | | X | + +---------------------------------------------+-----------------------------------+---+---+---+---+ If :c:macro:`COUNT_ALLOCS` is defined then the following (internal-only) fields exist as well: From ce81b3860d92aad4335b94ee60764a2032bb2826 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 12:53:59 -0600 Subject: [PATCH 24/43] Fix the note about inheritance through attr lookup. --- Doc/c-api/typeobj.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index a7774375d5bc8a..65bcea7877fdbc 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -171,7 +171,8 @@ fields exist as well: G - inherited, but only in combination with other slots; see the slot's description ? - it's complicated; see the slot's description - L - not inherited but available through the normal attribute lookup chain + Note that some slots are effectively inherited through the normal + attribute lookup chain. .. _slot-typedefs-table: From 5264f37cdc448f66d7ebd260a485b0633da35873 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 12:56:20 -0600 Subject: [PATCH 25/43] Add a placeholder for common cases in the quick ref. --- Doc/c-api/typeobj.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 65bcea7877fdbc..8c6a359f7f04b0 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -306,6 +306,11 @@ slot typedefs See :ref:`slot-typedefs` below for more detail. +common cases +^^^^^^^^^^^^ + + + PyTypeObject Definition ----------------------- From 7f667030ad8f98c28d37c29979585985818db61c Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 13:43:21 -0600 Subject: [PATCH 26/43] Stub out the type slot typedefs. --- Doc/c-api/typeobj.rst | 114 +++++++++++++++++++++++++++++++++--------- 1 file changed, 91 insertions(+), 23 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 8c6a359f7f04b0..3a404e28154ae2 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -228,6 +228,17 @@ slot typedefs | | const char * | | | | :c:type:`PyObject` * | | +-----------------------------+-----------------------------+----------------------+ +| :c:type:`getattrofunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`setattrofunc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ | :c:type:`descrgetfunc` | .. line-block:: | :c:type:`PyObject` * | | | | | | | :c:type:`PyObject` * | | @@ -257,13 +268,13 @@ slot typedefs | :c:type:`getbufferproc` | .. line-block:: | int | | | | | | | :c:type:`PyObject` * | | -| | :c:type:PyBuffer` * | | +| | :c:type:`Py_buffer` * | | | | int | | +-----------------------------+-----------------------------+----------------------+ | :c:type:`releasebufferproc` | .. line-block:: | void | | | | | | | :c:type:`PyObject` * | | -| | :c:type:`PyBuffer` * | | +| | :c:type:`Py_buffer` * | | +-----------------------------+-----------------------------+----------------------+ | :c:type:`inquiry` | void * | int | +-----------------------------+-----------------------------+----------------------+ @@ -319,6 +330,8 @@ 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: +.. XXX Drop this? + .. literalinclude:: ../includes/typestruct.h @@ -531,9 +544,7 @@ value, that section is omitted. 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); + instead of a Python string object to give the attribute name. **Inheritance:** @@ -554,11 +565,7 @@ value, that section is omitted. 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. + instead of a Python string object to give the attribute name. **Inheritance:** @@ -1460,19 +1467,6 @@ value, that section is omitted. 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`. - **Inheritance:** This field is inherited by static subtypes, but not by dynamic @@ -2049,6 +2043,80 @@ Async Object Structures Slot Type typedefs ================== +.. c:type:: PyObject *(*allocfunc)(PyTypeObject *cls, 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`. + + This function should not do any other instance initialization, not even to + allocate additional memory; that should be done by :c:member:`~PyTypeObject.tp_new`. .. c:type:: void (*destructor)(PyObject *) +.. c:type:: void (*freefunc)(void) + +.. c:type:: PyObject *(*newfunc)(PyObject *, PyObject *, PyObject *) + +.. c:type:: int (*initproc)(PyObject *, PyObject *, PyObject *) + +.. c:type:: PyObject *(*reprfunc)(PyObject *) + +.. c:type:: int (*printfunc)(PyObject *, FILE *, int) + +.. c:type:: PyObject *(*getattrfunc)(PyObject *self, char *attr) + + Return the value of the named attribute for the object. + +.. c:type:: int (*setattrfunc)(PyObject *self, char *attr, PyObject *value) + + Set the value of the named attribute for the object. + The value argument is set to *NULL* to delete the attribute. + +.. c:type:: PyObject *(*getattrofunc)(PyObject *self, PyObject *attr) + + Return the value of the named attribute for the object. + +.. c:type:: int (*setattrofunc)(PyObject *self, PyObject *attr, PyObject *value) + + Set the value of the named attribute for the object. + The value argument is set to *NULL* to delete the attribute. + +.. c:type:: PyObject *(*descrgetfunc)(PyObject *, PyObject *, PyObject *) + +.. c:type:: int (*descrsetfunc)(PyObject *, PyObject *, PyObject *) + +.. c:type:: Py_hash_t (*hashfunc)(PyObject *) + +.. c:type:: PyObject *(*richcmpfunc)(PyObject *, PyObject *, int) + +.. c:type:: PyObject *(*getiterfunc)(PyObject *) + +.. c:type:: PyObject *(*iternextfunc)(PyObject *) + +.. c:type:: Py_ssize_t (*lenfunc)(PyObject *) + +.. c:type:: int (*getbufferproc)(PyObject *, Py_buffer *, int) + +.. c:type:: void (*releasebufferproc)(PyObject *, Py_buffer *) + +.. c:type:: PyObject *(*unaryfunc)(PyObject *) + +.. c:type:: PyObject *(*binaryfunc)(PyObject *, PyObject *) + +.. c:type:: PyObject *(*ternaryfunc)(PyObject *, PyObject *, PyObject *) + +.. c:type:: PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t) + +.. c:type:: int (*ssizeobjargproc)(PyObject *, Py_ssize_t) + +.. c:type:: int (*objobjproc)(PyObject *, PyObject *) + +.. c:type:: int (*objobjargproc)(PyObject *, PyObject *, PyObject *) + From 7ba9e24a1e9fb9f4ba0e1b2e361ba8221f125685 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 13:58:25 -0600 Subject: [PATCH 27/43] Add the missing type slot descriptions. --- Doc/c-api/typeobj.rst | 82 +++++++++++++++++++++++++++---------------- 1 file changed, 51 insertions(+), 31 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 3a404e28154ae2..f679a24f33559f 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -134,7 +134,7 @@ Quick Reference | :c:member:`~PyTypeObject.tp_finalize` | :c:type:`destructor` | | | | X | +---------------------------------------------+-----------------------------------+---+---+---+---+ -If :c:macro:`COUNT_ALLOCS` is defined then the following (internal-only) +If :const:`COUNT_ALLOCS` is defined then the following (internal-only) fields exist as well: * :c:member:`~PyTypeObject.tp_allocs` @@ -1593,12 +1593,53 @@ value, that section is omitted. :c:func:`PyType_Ready`. +.. c:member:: PyObject* PyTypeObject.tp_cache + + Unused. Internal use only. + + **Inheritance:** + + This field is not inherited. + + +.. c:member:: PyObject* PyTypeObject.tp_subclasses + + List of weak references to subclasses. Internal use only. + + **Inheritance:** + + This field is not inherited. + + +.. c:member:: PyObject* PyTypeObject.tp_weaklist + + Weak reference list head, for weak references to this type object. Not + inherited. Internal use only. + + **Inheritance:** + + This field is not inherited. + + +.. c:member:: destructor PyTypeObject.tp_del + + This field is deprecated. Use :c:member:`~PyTypeObject.tp_finalize` instead. + + +.. c:member:: unsigned int PyTypeObject.tp_version_tag + + Used to index into the method cache. Internal use only. + + **Inheritance:** + + This field is not inherited. + + .. c:member:: destructor PyTypeObject.tp_finalize - An optional pointer to an instance finalization function. Its signature is - :c:type:`destructor`:: + An optional pointer to an instance finalization function. Its signature is:: - void tp_finalize(PyObject *) + void tp_finalize(PyObject *self) If :c:member:`~PyTypeObject.tp_finalize` is set, the interpreter calls it once when finalizing an instance. It is called either from the garbage @@ -1627,6 +1668,8 @@ value, that section is omitted. For this field to be taken into account (even through inheritance), you must also set the :const:`Py_TPFLAGS_HAVE_FINALIZE` flags bit. + **Inheritance:** + This field is inherited by subtypes. .. versionadded:: 3.4 @@ -1634,33 +1677,6 @@ value, that section is omitted. .. seealso:: "Safe object finalization" (:pep:`442`) -.. c:member:: PyObject* PyTypeObject.tp_cache - - Unused. Internal use only. - - **Inheritance:** - - This field is not inherited. - - -.. c:member:: PyObject* PyTypeObject.tp_subclasses - - List of weak references to subclasses. Not inherited. Internal use only. - - **Inheritance:** - - This field is not inherited. - - -.. c:member:: PyObject* PyTypeObject.tp_weaklist - - Weak reference list head, for weak references to this type object. Not - inherited. Internal use only. - - **Inheritance:** - - This field is not inherited. - 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 @@ -1682,6 +1698,10 @@ subtypes. Maximum simultaneously allocated objects. +.. c:member:: PyTypeObject* PyTypeObject.tp_prev + + Pointer to the previous type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field. + .. c:member:: PyTypeObject* PyTypeObject.tp_next Pointer to the next type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field. From 8ad1cbe25d5460e458eb10535e761fbd3f6bf7ab Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 14:19:53 -0600 Subject: [PATCH 28/43] Drop the "Default" section from type slots that do not need it. --- Doc/c-api/typeobj.rst | 153 ++++++++---------------------------------- 1 file changed, 28 insertions(+), 125 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index f679a24f33559f..59b2730cf7117c 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -150,9 +150,9 @@ fields exist as well: An asterisk means the field must be non-*NULL*. .. [#cols] Columns: - **"O"**: set on :c:type:`PyObject` + **"O"**: set on :c:type:`PyBaseObject_Type` - **"T"**: set on :c:type:`PyTypeObject` + **"T"**: set on :c:type:`PyType_Type` **"D"**: default (if slot is set to *NULL*) @@ -414,9 +414,10 @@ PyVarObject Slots PyTypeObject Slots ------------------ -Each slot has a section describing inheritance and one for the default -value. If a slot does not have any information about the default -value, that section is omitted. +Each slot has a section describing inheritance. If :c:func:`PyType_Ready` +may set a value when the field is set to *NULL* then there will also be +a "Default" section. (Note that many fields set on :c:type:`PyBaseObject_Type` +and :c:type:`PyType_Type` effectively act as defaults.) .. c:member:: const char* PyTypeObject.tp_name @@ -443,15 +444,14 @@ value, that section is omitted. type will be impossible to pickle. Additionally, it will not be listed in module documentations created with pydoc. + This field must not be *NULL*. It is the only required field + in :c:func:`PyTypeObject` (other than potentially + :c:member:`~PyTypeObject.tp_itemsize`). + **Inheritance:** This field is not inherited by subtypes. - **Default:** - - This field does not have a default. It is the only required - field in :c:func:`PyTypeObject`. - .. c:member:: Py_ssize_t PyTypeObject.tp_basicsize Py_ssize_t PyTypeObject.tp_itemsize @@ -489,6 +489,8 @@ value, that section is omitted. :c:member:`~PyTypeObject.tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the alignment requirement for ``double``). + For any type with variable-length instances, this field must not be *NULL*. + **Inheritance:** These fields are inherited separately by subtypes. If the base type has a @@ -496,12 +498,6 @@ value, that section is omitted. :c:member:`~PyTypeObject.tp_itemsize` to a different non-zero value in a subtype (though this depends on the implementation of the base type). - **Default:** - - :c:type:`PyBaseObject_Type` uses ``sizeof(PyObject)`` for - :attr:`tp_basicsize`. However, :attr:`tp_itemsize` does not have - a default. - .. c:member:: destructor PyTypeObject.tp_dealloc @@ -528,10 +524,6 @@ value, that section is omitted. This field is inherited by subtypes. - **Default:** - - :c:type:`PyBaseObject_Type` provides a simple function. - .. c:member:: printfunc PyTypeObject.tp_print @@ -554,10 +546,6 @@ value, that section is omitted. 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*. - **Default:** - - This field does not have a default. - .. c:member:: setattrfunc PyTypeObject.tp_setattr @@ -575,10 +563,6 @@ value, that section is omitted. 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*. - **Default:** - - This field does not have a default. - .. c:member:: PyAsyncMethods* PyTypeObject.tp_as_async @@ -594,10 +578,6 @@ value, that section is omitted. The :c:member:`~PyTypeObject.tp_as_async` field is not inherited, but the contained fields are inherited individually. - **Default:** - - This field does not have a default. - .. c:member:: reprfunc PyTypeObject.tp_repr @@ -621,10 +601,6 @@ value, that section is omitted. This field is inherited by subtypes. - **Default:** - - :c:type:`PyBaseObject_Type` provides a simple function. - .. c:member:: PyNumberMethods* PyTypeObject.tp_as_number @@ -637,10 +613,6 @@ value, that section is omitted. The :c:member:`~PyTypeObject.tp_as_number` field is not inherited, but the contained fields are inherited individually. - **Default:** - - This field does not have a default. - .. c:member:: PySequenceMethods* PyTypeObject.tp_as_sequence @@ -653,10 +625,6 @@ value, that section is omitted. The :c:member:`~PyTypeObject.tp_as_sequence` field is not inherited, but the contained fields are inherited individually. - **Default:** - - This field does not have a default. - .. c:member:: PyMappingMethods* PyTypeObject.tp_as_mapping @@ -669,10 +637,6 @@ value, that section is omitted. The :c:member:`~PyTypeObject.tp_as_mapping` field is not inherited, but the contained fields are inherited individually. - **Default:** - - This field does not have a default. - .. c:member:: hashfunc PyTypeObject.tp_hash @@ -707,11 +671,6 @@ value, that section is omitted. :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*. - **Default:** - - :c:type:`PyBaseObject_Type` uses a :c:type:`hashfunc` that hashes - the object's :attr:`id`. - .. c:member:: ternaryfunc PyTypeObject.tp_call @@ -723,10 +682,6 @@ value, that section is omitted. This field is inherited by subtypes. - **Default:** - - This field does not have a default. - .. c:member:: reprfunc PyTypeObject.tp_str @@ -747,10 +702,6 @@ value, that section is omitted. This field is inherited by subtypes. - **Default:** - - :c:type:`PyBaseObject_Type` provides a simple function. - .. c:member:: getattrofunc PyTypeObject.tp_getattro @@ -806,10 +757,6 @@ value, that section is omitted. The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, but the contained fields are inherited individually. - **Default:** - - This field does not have a default. - .. c:member:: unsigned long PyTypeObject.tp_flags @@ -964,10 +911,6 @@ value, that section is omitted. This field is *not* inherited by subtypes. - **Default:** - - This field does not have a default. - .. c:member:: traverseproc PyTypeObject.tp_traverse @@ -1012,10 +955,6 @@ value, that section is omitted. :c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in the subtype. - **Default:** - - This field does not have a default. - .. c:member:: inquiry PyTypeObject.tp_clear @@ -1075,10 +1014,6 @@ value, that section is omitted. :c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in the subtype. - **Default:** - - This field does not have a default. - .. c:member:: richcmpfunc PyTypeObject.tp_richcompare @@ -1117,22 +1052,6 @@ value, that section is omitted. | :const:`Py_GE` | ``>=`` | +----------------+------------+ - **Inheritance:** - - Group: :attr:`tp_hash`, :attr:`tp_richcompare` - - 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*. - - **Default:** - - :c:type:`PyBaseObject_Type` provides a :attr:`tp_richcompare`. - However, if only :attr:`tp_hash` is defined, not even this is used - and instances of the type will not be able to participate in any - comparisons. - The following macro is defined to ease writing rich comparison functions: .. c:function:: PyObject \*Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op) @@ -1149,6 +1068,22 @@ value, that section is omitted. .. versionadded:: 3.7 + **Inheritance:** + + Group: :attr:`tp_hash`, :attr:`tp_richcompare` + + 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*. + + **Default:** + + :c:type:`PyBaseObject_Type` provides a :attr:`tp_richcompare`. + However, if only :attr:`tp_hash` is defined, not even this is used + and instances of the type will not be able to participate in any + comparisons. + .. c:member:: Py_ssize_t PyTypeObject.tp_weaklistoffset @@ -1183,10 +1118,6 @@ value, that section is omitted. :attr:`__weakref__`, the type inherits its :c:member:`~PyTypeObject.tp_weaklistoffset` from its base type. - **Default:** - - This field does not have a default. - .. c:member:: getiterfunc PyTypeObject.tp_iter @@ -1200,10 +1131,6 @@ value, that section is omitted. This field is inherited by subtypes. - **Default:** - - This field does not have a default. - .. c:member:: iternextfunc PyTypeObject.tp_iternext @@ -1223,10 +1150,6 @@ value, that section is omitted. This field is inherited by subtypes. - **Default:** - - This field does not have a default. - .. c:member:: struct PyMethodDef* PyTypeObject.tp_methods @@ -1241,10 +1164,6 @@ value, that section is omitted. This field is not inherited by subtypes (methods are inherited through a different mechanism). - **Default:** - - This field does not have a default. - .. c:member:: struct PyMemberDef* PyTypeObject.tp_members @@ -1260,10 +1179,6 @@ value, that section is omitted. This field is not inherited by subtypes (members are inherited through a different mechanism). - **Default:** - - This field does not have a default. - .. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset @@ -1278,10 +1193,6 @@ value, that section is omitted. This field is not inherited by subtypes (computed attributes are inherited through a different mechanism). - **Default:** - - This field does not have a default. - .. c:member:: PyTypeObject* PyTypeObject.tp_base @@ -1339,10 +1250,6 @@ value, that section is omitted. This field is inherited by subtypes. - **Default:** - - This field does not have a default. - .. c:member:: descrsetfunc PyTypeObject.tp_descr_set @@ -1361,10 +1268,6 @@ value, that section is omitted. This field is inherited by subtypes. - **Default:** - - This field does not have a default. - .. c:member:: Py_ssize_t PyTypeObject.tp_dictoffset From 95af724fc094ac1b524daafc3bda971aa06969c8 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 15:00:32 -0600 Subject: [PATCH 29/43] Add a column for corresponding special method names. --- Doc/c-api/typeobj.rst | 246 ++++++++++++++++++++++++------------------ 1 file changed, 143 insertions(+), 103 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 59b2730cf7117c..2d05805467719c 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -29,110 +29,150 @@ Quick Reference "tp slots" ^^^^^^^^^^ -.. XXX Add column for corresponding Python special methods. - .. table:: - :widths: 20,20,5,5,5,5 - - +---------------------------------------------+-----------------------------------+---------------+ - | PyTypeObject Slot [#slots]_ | :ref:`Type ` | Info [#cols]_ | - | | +---+---+---+---+ - | | | O | T | D | I | - +=============================================+===================================+===+===+===+===+ - | \* :c:member:`~PyTypeObject.tp_name` | const char * | X | X | | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | X | X | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | | X | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | X | X | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | (:c:member:`~PyTypeObject.tp_print`) | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | | | | G | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | (:c:member:`~PyTypeObject.tp_setattr`) | :c:type:`setattrfunc` | | | | G | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_async` | :c:type:`PyAsyncMethods` * | | | | % | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_repr` | :c:type:`reprfunc` | X | X | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_number` | :c:type:`PyNumberMethods` * | | | | % | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_sequence` | :c:type:`PySequenceMethods` * | | | | % | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_mapping` | :c:type:`PyMappingMethods` * | | | | % | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_hash` | :c:type:`hashfunc` | X | | | G | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_call` | :c:type:`ternaryfunc` | | X | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_str` | :c:type:`reprfunc` | X | | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_getattro` | :c:type:`getattrofunc` | X | X | | G | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_setattro` | :c:type:`setattrofunc` | X | X | | G | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_buffer` | :c:type:`PyBufferProcs` * | | | | % | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_flags` | unsigned long | X | X | | ? | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_doc` | const char * | X | X | | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_traverse` | :c:type:`traverseproc` | | X | | G | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_clear` | :c:type:`inquiry` | | X | | G | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_richcompare` | :c:type:`richcmpfunc` | X | | | G | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | | X | | ? | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | | | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_iternext` | :c:type:`iternextfunc` | | | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_methods` | :c:type:`PyMethodDef` [] | X | X | | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_members` | :c:type:`PyMemberDef` [] | | X | | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_getset` | :c:type:`PyGetSetDef` [] | X | X | | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_base` | :c:type:`PyTypeObject` * | | | X | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_dict` | :c:type:`PyObject` * | | | ? | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_descr_get` | :c:type:`descrgetfunc` | | | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | | | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | | X | | ? | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | X | X | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_alloc` | :c:type:`allocfunc` | X | | ? | ? | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_new` | :c:type:`newfunc` | X | X | ? | ? | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_free` | :c:type:`freefunc` | X | X | ? | ? | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_is_gc` | :c:type:`inquiry` | | X | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | <:c:member:`~PyTypeObject.tp_bases`> | :c:type:`PyObject` * | | | ~ | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | <:c:member:`~PyTypeObject.tp_mro`> | :c:type:`PyObject` * | | | ~ | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | [:c:member:`~PyTypeObject.tp_cache`] | :c:type:`PyObject` * | | | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | [:c:member:`~PyTypeObject.tp_subclasses`] | :c:type:`PyObject` * | | | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | [:c:member:`~PyTypeObject.tp_weaklist`] | :c:type:`PyObject` * | | | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | (:c:member:`~PyTypeObject.tp_del`) | :c:type:`destructor` | | | | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | [:c:member:`~PyTypeObject.tp_version_tag`] | unsigned int | | | | - +---------------------------------------------+-----------------------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_finalize` | :c:type:`destructor` | | | | X | - +---------------------------------------------+-----------------------------------+---+---+---+---+ + :widths: 6,6,6,1,1,1,1 + + +---------------------------------------------+-----------------------------------+-------------------+---------------+ + | PyTypeObject Slot [#slots]_ | :ref:`Type ` | special | Info [#cols]_ | + | | + methods/attrs +---+---+---+---+ + | | | | O | T | D | I | + +=============================================+===================================+===================+===+===+===+===+ + | \* :c:member:`~PyTypeObject.tp_name` | const char * | __name__ | X | X | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | | X | X | | X | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | | | X | | X | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | | X | X | | X | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | (:c:member:`~PyTypeObject.tp_print`) | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | __getattribute__, | | | | G | + | | | __getattr__ | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | (:c:member:`~PyTypeObject.tp_setattr`) | :c:type:`setattrfunc` | __setattr__, | | | | G | + | | | __delattr__ | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_async` | :c:type:`PyAsyncMethods` * | __await__ | | | | % | + | | | __aiter__ | | | | | + | | | __anext__ | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_repr` | :c:type:`reprfunc` | __repr__ | X | X | | X | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_number` | :c:type:`PyNumberMethods` * | __(ri)add__ | | | | % | + | | | __(ri)sub__ | | | | | + | | | __(ri)mul__ | | | | | + | | | __(ri)mod__ | | | | | + | | | __(r)divmod__ | | | | | + | | | __(ri)pow__ | | | | | + | | | __neg__ | | | | | + | | | __pos__ | | | | | + | | | __abs__ | | | | | + | | | __bool__ | | | | | + | | | __invert__ | | | | | + | | | __(ri)lshift__ | | | | | + | | | __(ri)rshift__ | | | | | + | | | __(ri)and__ | | | | | + | | | __(ri)xor__ | | | | | + | | | __(ri)or__ | | | | | + | | | __int__ | | | | | + | | | __float__ | | | | | + | | | __(i)floordiv__ | | | | | + | | | __(i)truediv__ | | | | | + | | | __index__ | | | | | + | | | __(ri)matmul__ | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_sequence` | :c:type:`PySequenceMethods` * | __len__ | | | | % | + | | | __(i)add__ | | | | | + | | | __(ri)mul__ | | | | | + | | | __getitem__ | | | | | + | | | __setitem__ | | | | | + | | | __delitem__ | | | | | + | | | __contains__ | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_mapping` | :c:type:`PyMappingMethods` * | __len__ | | | | % | + | | | __getitem__ | | | | | + | | | __setitem__ | | | | | + | | | __delitem__ | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_hash` | :c:type:`hashfunc` | __hash__ | X | | | G | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_call` | :c:type:`ternaryfunc` | __call__ | | X | | X | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_str` | :c:type:`reprfunc` | __str__ | X | | | X | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_getattro` | :c:type:`getattrofunc` | __getattribute__, | X | X | | G | + | | | __getattr__ | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_setattro` | :c:type:`setattrofunc` | __setattr__, | X | X | | G | + | | | __delattr__ | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_buffer` | :c:type:`PyBufferProcs` * | | | | | % | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_flags` | unsigned long | | X | X | | ? | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_doc` | const char * | __doc__ | X | X | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_traverse` | :c:type:`traverseproc` | | | X | | G | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_clear` | :c:type:`inquiry` | | | X | | G | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_richcompare` | :c:type:`richcmpfunc` | __lt__, | X | | | G | + | | | __le__, | | | | | + | | | __eq__, | | | | | + | | | __ne__, | | | | | + | | | __gt__, | | | | | + | | | __ge__ | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | | | X | | ? | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | __iter__ | | | | X | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_iternext` | :c:type:`iternextfunc` | __next__ | | | | X | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_methods` | :c:type:`PyMethodDef` [] | | X | X | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_members` | :c:type:`PyMemberDef` [] | | | X | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_getset` | :c:type:`PyGetSetDef` [] | | X | X | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_base` | :c:type:`PyTypeObject` * | __base__ | | | X | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_dict` | :c:type:`PyObject` * | __dict__ | | | ? | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_descr_get` | :c:type:`descrgetfunc` | __get__ | | | | X | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | __set__, | | | | X | + | | | __delete__ | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | | | X | | ? | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | __init__ | X | X | | X | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_alloc` | :c:type:`allocfunc` | | X | | ? | ? | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_new` | :c:type:`newfunc` | __new__ | X | X | ? | ? | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_free` | :c:type:`freefunc` | | X | X | ? | ? | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_is_gc` | :c:type:`inquiry` | | | X | | X | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | <:c:member:`~PyTypeObject.tp_bases`> | :c:type:`PyObject` * | __bases__ | | | ~ | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | <:c:member:`~PyTypeObject.tp_mro`> | :c:type:`PyObject` * | __mro__ | | | ~ | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | [:c:member:`~PyTypeObject.tp_cache`] | :c:type:`PyObject` * | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | [:c:member:`~PyTypeObject.tp_subclasses`] | :c:type:`PyObject` * | __subclasses__ | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | [:c:member:`~PyTypeObject.tp_weaklist`] | :c:type:`PyObject` * | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | (:c:member:`~PyTypeObject.tp_del`) | :c:type:`destructor` | | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | [:c:member:`~PyTypeObject.tp_version_tag`] | unsigned int | | | | | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_finalize` | :c:type:`destructor` | __del__ | | | | X | + +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ If :const:`COUNT_ALLOCS` is defined then the following (internal-only) fields exist as well: From bbbbae079feb0bd15d08739a9f4dcbb3eedf7dfc Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 16:17:27 -0600 Subject: [PATCH 30/43] Add a table for the "sub-slots". --- Doc/c-api/typeobj.rst | 222 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 184 insertions(+), 38 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 2d05805467719c..e33c1c0179780a 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -30,11 +30,11 @@ Quick Reference ^^^^^^^^^^ .. table:: - :widths: 6,6,6,1,1,1,1 + :widths: 18,18,18,1,1,1,1 +---------------------------------------------+-----------------------------------+-------------------+---------------+ | PyTypeObject Slot [#slots]_ | :ref:`Type ` | special | Info [#cols]_ | - | | + methods/attrs +---+---+---+---+ + | | | methods/attrs +---+---+---+---+ | | | | O | T | D | I | +=============================================+===================================+===================+===+===+===+===+ | \* :c:member:`~PyTypeObject.tp_name` | const char * | __name__ | X | X | | | @@ -53,47 +53,15 @@ Quick Reference | (:c:member:`~PyTypeObject.tp_setattr`) | :c:type:`setattrfunc` | __setattr__, | | | | G | | | | __delattr__ | | | | | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_async` | :c:type:`PyAsyncMethods` * | __await__ | | | | % | - | | | __aiter__ | | | | | - | | | __anext__ | | | | | + | :c:member:`~PyTypeObject.tp_as_async` | :c:type:`PyAsyncMethods` * | :ref:`sub-slots` | | | | % | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ | :c:member:`~PyTypeObject.tp_repr` | :c:type:`reprfunc` | __repr__ | X | X | | X | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_number` | :c:type:`PyNumberMethods` * | __(ri)add__ | | | | % | - | | | __(ri)sub__ | | | | | - | | | __(ri)mul__ | | | | | - | | | __(ri)mod__ | | | | | - | | | __(r)divmod__ | | | | | - | | | __(ri)pow__ | | | | | - | | | __neg__ | | | | | - | | | __pos__ | | | | | - | | | __abs__ | | | | | - | | | __bool__ | | | | | - | | | __invert__ | | | | | - | | | __(ri)lshift__ | | | | | - | | | __(ri)rshift__ | | | | | - | | | __(ri)and__ | | | | | - | | | __(ri)xor__ | | | | | - | | | __(ri)or__ | | | | | - | | | __int__ | | | | | - | | | __float__ | | | | | - | | | __(i)floordiv__ | | | | | - | | | __(i)truediv__ | | | | | - | | | __index__ | | | | | - | | | __(ri)matmul__ | | | | | + | :c:member:`~PyTypeObject.tp_as_number` | :c:type:`PyNumberMethods` * | :ref:`sub-slots` | | | | % | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_sequence` | :c:type:`PySequenceMethods` * | __len__ | | | | % | - | | | __(i)add__ | | | | | - | | | __(ri)mul__ | | | | | - | | | __getitem__ | | | | | - | | | __setitem__ | | | | | - | | | __delitem__ | | | | | - | | | __contains__ | | | | | + | :c:member:`~PyTypeObject.tp_as_sequence` | :c:type:`PySequenceMethods` * | :ref:`sub-slots` | | | | % | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_mapping` | :c:type:`PyMappingMethods` * | __len__ | | | | % | - | | | __getitem__ | | | | | - | | | __setitem__ | | | | | - | | | __delitem__ | | | | | + | :c:member:`~PyTypeObject.tp_as_mapping` | :c:type:`PyMappingMethods` * | :ref:`sub-slots` | | | | % | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ | :c:member:`~PyTypeObject.tp_hash` | :c:type:`hashfunc` | __hash__ | X | | | G | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ @@ -214,6 +182,145 @@ fields exist as well: Note that some slots are effectively inherited through the normal attribute lookup chain. +.. _sub-slots: + +sub-slots +^^^^^^^^^ + +.. table:: + :widths: 26,17,12 + + +---------------------------------------------------------+-----------------------------------+--------------+ + | Slot | :ref:`Type ` | special | + | | | methods | + +=========================================================+===================================+==============+ + | :c:member:`~PyAsyncMethods.am_await` | :c:type:`unaryfunc` | __await__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyAsyncMethods.am_aiter` | :c:type:`unaryfunc` | __aiter__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyAsyncMethods.am_anext` | :c:type:`unaryfunc` | __anext__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_add` | :c:type:`binaryfunc` | __add__ | + | | | __radd__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_add` | :c:type:`binaryfunc` | __iadd__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_subtract` | :c:type:`binaryfunc` | __sub__ | + | | | __rsub__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_subtract` | :c:type:`binaryfunc` | __sub__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_multiply` | :c:type:`binaryfunc` | __mul__ | + | | | __rmul__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_multiply` | :c:type:`binaryfunc` | __mul__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_remainder` | :c:type:`binaryfunc` | __mod__ | + | | | __rmod__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_remainder` | :c:type:`binaryfunc` | __mod__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_divmod` | :c:type:`binaryfunc` | __divmod__ | + | | | __rdivmod__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_power` | :c:type:`ternaryfunc` | __pow__ | + | | | __rpow__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_power` | :c:type:`ternaryfunc` | __pow__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_negative` | :c:type:`unaryfunc` | __neg__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_positive` | :c:type:`unaryfunc` | __pos__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_absolute` | :c:type:`unaryfunc` | __abs__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_bool` | :c:type:`inquiry` | __bool__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_invert` | :c:type:`unaryfunc` | __invert__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_lshift` | :c:type:`binaryfunc` | __lshift__ | + | | | __rlshift__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_lshift` | :c:type:`binaryfunc` | __lshift__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_rshift` | :c:type:`binaryfunc` | __rshift__ | + | | | __rrshift__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_rshift` | :c:type:`binaryfunc` | __rshift__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_and` | :c:type:`binaryfunc` | __and__ | + | | | __rand__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_and` | :c:type:`binaryfunc` | __and__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_xor` | :c:type:`binaryfunc` | __xor__ | + | | | __rxor__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_xor` | :c:type:`binaryfunc` | __xor__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_or` | :c:type:`binaryfunc` | __or__ | + | | | __ror__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_or` | :c:type:`binaryfunc` | __or__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_int` | :c:type:`unaryfunc` | __int__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_reserved` | void * | | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_float` | :c:type:`unaryfunc` | __float__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_floor_divide` | :c:type:`binaryfunc` | __floordiv__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_floor_divide` | :c:type:`binaryfunc` | __floordiv__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_true_divide` | :c:type:`binaryfunc` | __truediv__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_true_divide` | :c:type:`binaryfunc` | __truediv__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_index` | :c:type:`binaryfunc` | __index__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_matrix_multiply` | :c:type:`binaryfunc` | __matmul__ | + | | | __rmatmul__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_matrix_multiply` | :c:type:`binaryfunc` | __matmul__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyMappingMethods.mp_length` | :c:type:`lenfunc` | __len__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyMappingMethods.mp_subscript` | :c:type:`binaryfunc` | __getitem__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyMappingMethods.mp_ass_subscript` | :c:type:`objobjargproc` | __setitem__, | + | | | __delitem__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_length` | :c:type:`lenfunc` | __len__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_concat` | :c:type:`binaryfunc` | __add__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_repeat` | :c:type:`ssizeargfunc` | __mul__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_item` | :c:type:`ssizeargfunc` | __getitem__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_ass_item` | :c:type:`ssizeobjargproc` | __setitem__ | + | | | __delitem__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_contains` | :c:type:`objobjproc` | __contains__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_inplace_concat` | :c:type:`binaryfunc` | __iadd__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_inplace_repeat` | :c:type:`ssizeargfunc` | __imul__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyBufferProcs.bf_getbuffer` | :c:func:`getbufferproc` | | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyBufferProcs.bf_releasebuffer` | :c:func:`releasebufferproc` | | + +---------------------------------------------------------+-----------------------------------+--------------+ + .. _slot-typedefs-table: slot typedefs @@ -1674,6 +1781,8 @@ Number Object Structures implement the number protocol. Each function is used by the function of similar name documented in the :ref:`number` section. + .. XXX Drop the definition? + Here is the structure definition:: typedef struct { @@ -1734,6 +1843,43 @@ Number Object Structures was previously called :c:data:`nb_long`, and was renamed in Python 3.0.1. +.. c:member:: binaryfunc PyNumberMethods.nb_add +.. c:member:: binaryfunc PyNumberMethods.nb_subtract +.. c:member:: binaryfunc PyNumberMethods.nb_multiply +.. c:member:: binaryfunc PyNumberMethods.nb_remainder +.. c:member:: binaryfunc PyNumberMethods.nb_divmod +.. c:member:: ternaryfunc PyNumberMethods.nb_power +.. c:member:: unaryfunc PyNumberMethods.nb_negative +.. c:member:: unaryfunc PyNumberMethods.nb_positive +.. c:member:: unaryfunc PyNumberMethods.nb_absolute +.. c:member:: inquiry PyNumberMethods.nb_bool +.. c:member:: unaryfunc PyNumberMethods.nb_invert +.. c:member:: binaryfunc PyNumberMethods.nb_lshift +.. c:member:: binaryfunc PyNumberMethods.nb_rshift +.. c:member:: binaryfunc PyNumberMethods.nb_and +.. c:member:: binaryfunc PyNumberMethods.nb_xor +.. c:member:: binaryfunc PyNumberMethods.nb_or +.. c:member:: unaryfunc PyNumberMethods.nb_int +.. c:member:: void *PyNumberMethods.nb_reserved +.. c:member:: unaryfunc PyNumberMethods.nb_float +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_add +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_subtract +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_multiply +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_remainder +.. c:member:: ternaryfunc PyNumberMethods.nb_inplace_power +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_lshift +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_rshift +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_and +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_xor +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_or +.. c:member:: binaryfunc PyNumberMethods.nb_floor_divide +.. c:member:: binaryfunc PyNumberMethods.nb_true_divide +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_floor_divide +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_true_divide +.. c:member:: unaryfunc PyNumberMethods.nb_index +.. c:member:: binaryfunc PyNumberMethods.nb_matrix_multiply +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_matrix_multiply + .. _mapping-structs: From c67b7044961dd6e159b75499632ec77edad3e117 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 16:22:29 -0600 Subject: [PATCH 31/43] minor cleanup --- Doc/c-api/typeobj.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index e33c1c0179780a..3f2f5f37812a51 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1732,22 +1732,18 @@ The remaining fields are only defined if the feature test macro 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_prev Pointer to the previous type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field. @@ -1756,7 +1752,7 @@ subtypes. 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 +Also, note that, in a garbage collected Python, :c:member:`~PyTypeObject.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 From 3b7c3122a629c31ef3c2f509c31321701407ae7b Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 18:19:41 -0600 Subject: [PATCH 32/43] Fill out the slot typedef descriptions. --- Doc/c-api/typeobj.rst | 169 +++++++++++++++++++++++++++++------------- 1 file changed, 116 insertions(+), 53 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 3f2f5f37812a51..27877731b1dc8c 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -650,7 +650,9 @@ and :c:type:`PyType_Type` effectively act as defaults.) 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 case for the singletons ``None`` and ``Ellipsis``). The function signature is:: + + void tp_dealloc(PyObject *self); 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, @@ -733,21 +735,27 @@ and :c:type:`PyType_Type` effectively act as defaults.) 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 + The signature is the same as for :c:func:`PyObject_Repr`:: + + PyObject *tp_repr(PyObject *self); + + The function 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. - **Inheritance:** This field is inherited by subtypes. + **Default:** + + 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. + .. c:member:: PyNumberMethods* PyTypeObject.tp_as_number @@ -792,8 +800,11 @@ and :c:type:`PyType_Type` effectively act as defaults.) 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 - value of the type Py_hash_t. The value ``-1`` should not be returned as a + The signature is the same as for :c:func:`PyObject_Hash`:: + + Py_hash_t tp_hash(PyObject *); + + 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``. @@ -823,7 +834,9 @@ and :c:type:`PyType_Type` effectively act as defaults.) 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`. + for :c:func:`PyObject_Call`:: + + PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs); **Inheritance:** @@ -837,26 +850,34 @@ and :c:type:`PyType_Type` effectively act as defaults.) 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 + The signature is the same as for :c:func:`PyObject_Str`:: + + PyObject *tp_str(PyObject *self); + + The function must return a string or a Unicode object. It should be a "friendly" string representation of the object, as this is the representation that will be used, among other things, by the :func:`print` function. - When this field is not set, :c:func:`PyObject_Repr` is called to return a string - representation. - **Inheritance:** This field is inherited by subtypes. + **Default:** + + When this field is not set, :c:func:`PyObject_Repr` is called to return a string + representation. + .. 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. + The signature is the same as for :c:func:`PyObject_GetAttr`:: + + PyObject *tp_getattro(PyObject *self, PyObject *attr); + + It is usually convenient to set this field to :c:func:`PyObject_GenericGetAttr`, + which implements the normal way of looking for object attributes. **Inheritance:** @@ -875,10 +896,14 @@ and :c:type:`PyType_Type` effectively act as defaults.) 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. + The signature is the same as for :c:func:`PyObject_SetAttr`:: + + PyObject *tp_setattro(PyObject *self, PyObject *attr, PyObject *value); + + In addition, setting *value* 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. **Inheritance:** @@ -1062,9 +1087,12 @@ and :c:type:`PyType_Type` effectively act as defaults.) .. 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`. + only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is:: + + int tp_traverse(PyObject *self, visitproc visit, void *arg); + + 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 @@ -1106,7 +1134,9 @@ and :c:type:`PyType_Type` effectively act as defaults.) .. 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. + used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is:: + + int tp_clear(PyObject *); 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` @@ -1164,10 +1194,12 @@ and :c:type:`PyType_Type` effectively act as defaults.) .. 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 first - parameter is guaranteed to be an instance of the type that is defined - by :c:type:`PyTypeObject`. + An optional pointer to the rich comparison function, whose signature is:: + + PyObject *tp_richcompare(PyObject *self, PyObject *other, int op); + + The first parameter is guaranteed to be an instance of the type + that is defined by :c:type:`PyTypeObject`. The function should return the result of the comparison (usually ``Py_True`` or ``Py_False``). If the comparison is undefined, it must return @@ -1272,7 +1304,9 @@ and :c:type:`PyType_Type` effectively act as defaults.) presence normally signals that the instances of this type are iterable (although sequences may be iterable without this function). - This function has the same signature as :c:func:`PyObject_GetIter`. + This function has the same signature as :c:func:`PyObject_GetIter`:: + + PyObject *tp_iter(PyObject *self); **Inheritance:** @@ -1282,6 +1316,10 @@ and :c:type:`PyType_Type` effectively act as defaults.) .. c:member:: iternextfunc PyTypeObject.tp_iternext An optional pointer to a function that returns the next item in an iterator. + The signature is:: + + PyObject *tp_iternext(PyObject *self); + 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 signals that the instances of this type are @@ -1387,11 +1425,11 @@ and :c:type:`PyType_Type` effectively act as defaults.) An optional pointer to a "descriptor get" function. - The function signature is :: + The function signature is:: PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type); - .. XXX explain. + .. XXX explain more? **Inheritance:** @@ -1403,13 +1441,13 @@ and :c:type:`PyType_Type` effectively act as defaults.) An optional pointer to a function for setting and deleting a descriptor's value. - The function signature is :: + 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. - .. XXX explain. + .. XXX explain more? **Inheritance:** @@ -1485,9 +1523,9 @@ and :c:type:`PyType_Type` effectively act as defaults.) :meth:`__init__`, and it is possible to reinitialize an instance by calling its :meth:`__init__` method again. - The function signature is :: + The function signature is:: - int tp_init(PyObject *self, PyObject *args, PyObject *kwds) + 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 @@ -1513,9 +1551,9 @@ and :c:type:`PyType_Type` effectively act as defaults.) An optional pointer to an instance allocation function. - The function signature is :: + The function signature is:: - PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems) + PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems); **Inheritance:** @@ -1537,9 +1575,9 @@ and :c:type:`PyType_Type` effectively act as defaults.) An optional pointer to an instance creation function. - The function signature is :: + The function signature is:: - PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds) + 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 @@ -1568,12 +1606,11 @@ and :c:type:`PyType_Type` effectively act as defaults.) instances, like a factory function. -.. c:member:: destructor PyTypeObject.tp_free +.. c:member:: freefunc PyTypeObject.tp_free - An optional pointer to an instance deallocation function. Its signature is - :c:type:`freefunc`:: + An optional pointer to an instance deallocation function. Its signature is:: - void tp_free(void *) + void tp_free(void *self); An initializer that is compatible with this signature is :c:func:`PyObject_Free`. @@ -1601,9 +1638,9 @@ and :c:type:`PyType_Type` effectively act as defaults.) 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 :: + ``0`` for a non-collectible instance. The signature is:: - int tp_is_gc(PyObject *self) + 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 @@ -1689,7 +1726,7 @@ and :c:type:`PyType_Type` effectively act as defaults.) An optional pointer to an instance finalization function. Its signature is:: - void tp_finalize(PyObject *self) + void tp_finalize(PyObject *self); If :c:member:`~PyTypeObject.tp_finalize` is set, the interpreter calls it once when finalizing an instance. It is called either from the garbage @@ -2115,7 +2152,7 @@ Async Object Structures The signature of this function is:: - PyObject *am_await(PyObject *self) + PyObject *am_await(PyObject *self); The returned object must be an iterator, i.e. :c:func:`PyIter_Check` must return ``1`` for it. @@ -2126,7 +2163,7 @@ Async Object Structures The signature of this function is:: - PyObject *am_aiter(PyObject *self) + PyObject *am_aiter(PyObject *self); Must return an :term:`awaitable` object. See :meth:`__anext__` for details. @@ -2137,7 +2174,7 @@ Async Object Structures The signature of this function is:: - PyObject *am_anext(PyObject *self) + PyObject *am_anext(PyObject *self); Must return an :term:`awaitable` object. See :meth:`__anext__` for details. This slot may be set to *NULL*. @@ -2165,16 +2202,26 @@ Slot Type typedefs .. c:type:: void (*destructor)(PyObject *) -.. c:type:: void (*freefunc)(void) +.. c:type:: void (*freefunc)(void *) + + See :c:member:`~PyTypeObject.tp_free`. .. c:type:: PyObject *(*newfunc)(PyObject *, PyObject *, PyObject *) + See :c:member:`~PyTypeObject.tp_new`. + .. c:type:: int (*initproc)(PyObject *, PyObject *, PyObject *) + See :c:member:`~PyTypeObject.tp_init`. + .. c:type:: PyObject *(*reprfunc)(PyObject *) + See :c:member:`~PyTypeObject.tp_repr`. + .. c:type:: int (*printfunc)(PyObject *, FILE *, int) + This is hidden if :const:`PY_LIMITED_API` is set. + .. c:type:: PyObject *(*getattrfunc)(PyObject *self, char *attr) Return the value of the named attribute for the object. @@ -2188,23 +2235,39 @@ Slot Type typedefs Return the value of the named attribute for the object. + See :c:member:`~PyTypeObject.tp_getattro`. + .. c:type:: int (*setattrofunc)(PyObject *self, PyObject *attr, PyObject *value) Set the value of the named attribute for the object. The value argument is set to *NULL* to delete the attribute. + See :c:member:`~PyTypeObject.tp_setattro`. + .. c:type:: PyObject *(*descrgetfunc)(PyObject *, PyObject *, PyObject *) + See :c:member:`~PyTypeObject.tp_descrget`. + .. c:type:: int (*descrsetfunc)(PyObject *, PyObject *, PyObject *) + See :c:member:`~PyTypeObject.tp_descrset`. + .. c:type:: Py_hash_t (*hashfunc)(PyObject *) + See :c:member:`~PyTypeObject.tp_hash`. + .. c:type:: PyObject *(*richcmpfunc)(PyObject *, PyObject *, int) + See :c:member:`~PyTypeObject.tp_richcompare`. + .. c:type:: PyObject *(*getiterfunc)(PyObject *) + See :c:member:`~PyTypeObject.tp_iter`. + .. c:type:: PyObject *(*iternextfunc)(PyObject *) + See :c:member:`~PyTypeObject.tp_iternext`. + .. c:type:: Py_ssize_t (*lenfunc)(PyObject *) .. c:type:: int (*getbufferproc)(PyObject *, Py_buffer *, int) From 00852e52189babf369be6db86f207c9cea56354a Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 6 Jun 2018 18:53:12 -0600 Subject: [PATCH 33/43] Drop trailing parens in pseudo-call. --- Doc/c-api/typeobj.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 27877731b1dc8c..263f32e201dbd4 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -166,15 +166,15 @@ fields exist as well: .. code-block:: none - X - :c:func:`PyType_Ready`() always sets this value (if *NULL*) - ~ - :c:func:`PyType_Ready`() always sets this value (it should be *NULL*) - ? - :c:func:`PyType_Ready`() may set this value depending on other slots + X - :c:func:`PyType_Ready` always sets this value (if *NULL*) + ~ - :c:func:`PyType_Ready` always sets this value (it should be *NULL*) + ? - :c:func:`PyType_Ready` may set this value depending on other slots **"I"**: inheritance .. code-block:: none - X - type slot is inherited via :c:func:`PyType_Ready`() if defined with a *NULL* value + X - type slot is inherited via :c:func:`PyType_Ready` if defined with a *NULL* value % - the slots of the sub-struct are inherited individually G - inherited, but only in combination with other slots; see the slot's description ? - it's complicated; see the slot's description From 9d0268720ff7b3aa01a79eaea68a6840ee2af24a Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Thu, 7 Jun 2018 08:26:12 -0600 Subject: [PATCH 34/43] Do not use a ref in a code block. --- Doc/c-api/typeobj.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 263f32e201dbd4..24ee0995a71040 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -166,15 +166,15 @@ fields exist as well: .. code-block:: none - X - :c:func:`PyType_Ready` always sets this value (if *NULL*) - ~ - :c:func:`PyType_Ready` always sets this value (it should be *NULL*) - ? - :c:func:`PyType_Ready` may set this value depending on other slots + X - *PyType_Ready* always sets this value (if *NULL*) + ~ - *PyType_Ready* always sets this value (it should be *NULL*) + ? - *PyType_Ready* may set this value depending on other slots **"I"**: inheritance .. code-block:: none - X - type slot is inherited via :c:func:`PyType_Ready` if defined with a *NULL* value + X - type slot is inherited via *PyType_Ready* if defined with a *NULL* value % - the slots of the sub-struct are inherited individually G - inherited, but only in combination with other slots; see the slot's description ? - it's complicated; see the slot's description From 71dfb1d9236928e9034ef66fce5ebe4561ce4c5c Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Thu, 7 Jun 2018 08:34:15 -0600 Subject: [PATCH 35/43] Add a NEWS entry. --- .../Documentation/2018-06-07-08-33-45.bpo-17045.ZNx6KU.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2018-06-07-08-33-45.bpo-17045.ZNx6KU.rst diff --git a/Misc/NEWS.d/next/Documentation/2018-06-07-08-33-45.bpo-17045.ZNx6KU.rst b/Misc/NEWS.d/next/Documentation/2018-06-07-08-33-45.bpo-17045.ZNx6KU.rst new file mode 100644 index 00000000000000..0f3836c10d389d --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2018-06-07-08-33-45.bpo-17045.ZNx6KU.rst @@ -0,0 +1,3 @@ +Improve the C-API doc for PyTypeObject. This includes adding several quick- +reference tables and a lot of missing slot/typedef entries. The existing +entries were also cleaned up with a slightly more consistent format. From 3d74a2cc0dc29e17240a7a54c61c6e1f5a9db9bf Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Fri, 8 Jun 2018 11:04:21 -0600 Subject: [PATCH 36/43] Add examples. --- Doc/c-api/typeobj.rst | 145 ++++++++++++++++++++++++++++++++++++- Doc/extending/newtypes.rst | 2 + 2 files changed, 143 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 24ee0995a71040..fabc7c473f4ea3 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -464,10 +464,145 @@ slot typedefs See :ref:`slot-typedefs` below for more detail. -common cases -^^^^^^^^^^^^ - - +Examples +^^^^^^^^ + +A definition of a basic static type:: + + typedef struct { + PyObject_HEAD + const char *data; + } MyObject; + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyObject", + .tp_basicsize = sizeof(MyObject), + .tp_doc = "My objects", + .tp_new = myobj_new, + .tp_dealloc = (destructor)myobj_dealloc, + .tp_repr = (reprfunc)myobj_repr, + }; + +You may also find older code (especially in the CPython code base) +with a more verbose initializer:: + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + "mymod.MyObject", /* tp_name */ + sizeof(MyObject), /* tp_basicsize */ + 0, /* tp_itemsize */ + (destructor)myobj_dealloc, /* tp_dealloc */ + 0, /* tp_print */ + 0, /* tp_getattr */ + 0, /* tp_setattr */ + 0, /* tp_as_async */ + (reprfunc)myobj_repr, /* tp_repr */ + 0, /* tp_as_number */ + 0, /* tp_as_sequence */ + 0, /* tp_as_mapping */ + 0, /* tp_hash */ + 0, /* tp_call */ + 0, /* tp_str */ + 0, /* tp_getattro */ + 0, /* tp_setattro */ + 0, /* tp_as_buffer */ + 0, /* tp_flags */ + "My objects", /* tp_doc */ + 0, /* tp_traverse */ + 0, /* tp_clear */ + 0, /* tp_richcompare */ + 0, /* tp_weaklistoffset */ + 0, /* tp_iter */ + 0, /* tp_iternext */ + 0, /* tp_methods */ + 0, /* tp_members */ + 0, /* tp_getset */ + 0, /* tp_base */ + 0, /* tp_dict */ + 0, /* tp_descr_get */ + 0, /* tp_descr_set */ + 0, /* tp_dictoffset */ + 0, /* tp_init */ + 0, /* tp_alloc */ + myobj_new, /* tp_new */ + }; + +A type that supports weakrefs, instance dicts, and hashing:: + + typedef struct { + PyObject_HEAD + const char *data; + PyObject *inst_dict; + PyObject *weakreflist; + } MyObject; + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyObject", + .tp_basicsize = sizeof(MyObject), + .tp_doc = "My objects", + .tp_weaklistoffset = offsetof(MyObject, weakreflist), + .tp_dictoffset = offsetof(MyObject, inst_dict), + .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, + .tp_new = myobj_new, + .tp_traverse = (traverseproc)myobj_traverse, + .tp_clear = (inquiry)myobj_clear, + .tp_alloc = PyType_GenericNew, + .tp_dealloc = (destructor)myobj_dealloc, + .tp_repr = (reprfunc)myobj_repr, + .tp_hash = (hashfunc)myobj_hash, + .tp_richcompare = PyBaseObject_Type.tp_richcompare, + }; + +A str subclass that cannot be subclassed and cannot be called +to create instances (e.g. uses a separate factory func):: + + typedef struct { + PyUnicodeObject raw; + char *extra; + } MyStr; + + static PyTypeObject MyStr_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyStr", + .tp_basicsize = sizeof(MyStr), + .tp_base = NULL, // set to &PyUnicode_Type in module init + .tp_doc = "my custom str", + .tp_flags = Py_TPFLAGS_DEFAULT, + .tp_new = NULL, + .tp_repr = (reprfunc)myobj_repr, + }; + +The simplest static type (with fixed-length instances):: + + typedef struct { + PyObject_HEAD + } MyObject; + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyObject", + }; + +The simplest static type (with variable-length instances):: + + typedef struct { + PyObject_VAR_HEAD + const char *data[1]; + } MyObject; + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyObject", + .tp_basicsize = sizeof(MyObject) - sizeof(char *), + .tp_itemsize = sizeof(char *), + }; + +For more examples, practical info, and a tutorial, see +:ref:`defining-new-types` and :ref:`new-types-topics`. For +information about dynamically created (aka heap) types, see +:c:func:`PyType_FromSpec`. PyTypeObject Definition @@ -2288,3 +2423,5 @@ Slot Type typedefs .. c:type:: int (*objobjargproc)(PyObject *, PyObject *, PyObject *) + +.. XXX Add a section about heap types (see PyType_FromSpec)? diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index d0d2ec1f88207c..8b9549d7e39e2e 100644 --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -1,5 +1,7 @@ .. highlightlang:: c +.. _new-types-topics: + ***************************************** Defining Extension Types: Assorted Topics ***************************************** From c30dec32a82608e69f4308c12a926b9161e3a1d0 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Fri, 8 Jun 2018 11:04:45 -0600 Subject: [PATCH 37/43] Move the examples to the bottom. --- Doc/c-api/typeobj.rst | 286 +++++++++++++++++++++--------------------- 1 file changed, 145 insertions(+), 141 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index fabc7c473f4ea3..1d7bd3680fa917 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -20,6 +20,10 @@ 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. +In addition to the following quick reference, the :ref:`examples` +section provides at-a-glance insight into the meaning and use of +:c:type:`PyTypeObject`. + Quick Reference --------------- @@ -464,146 +468,6 @@ slot typedefs See :ref:`slot-typedefs` below for more detail. -Examples -^^^^^^^^ - -A definition of a basic static type:: - - typedef struct { - PyObject_HEAD - const char *data; - } MyObject; - - static PyTypeObject MyObject_Type = { - PyVarObject_HEAD_INIT(NULL, 0) - .tp_name = "mymod.MyObject", - .tp_basicsize = sizeof(MyObject), - .tp_doc = "My objects", - .tp_new = myobj_new, - .tp_dealloc = (destructor)myobj_dealloc, - .tp_repr = (reprfunc)myobj_repr, - }; - -You may also find older code (especially in the CPython code base) -with a more verbose initializer:: - - static PyTypeObject MyObject_Type = { - PyVarObject_HEAD_INIT(NULL, 0) - "mymod.MyObject", /* tp_name */ - sizeof(MyObject), /* tp_basicsize */ - 0, /* tp_itemsize */ - (destructor)myobj_dealloc, /* tp_dealloc */ - 0, /* tp_print */ - 0, /* tp_getattr */ - 0, /* tp_setattr */ - 0, /* tp_as_async */ - (reprfunc)myobj_repr, /* tp_repr */ - 0, /* tp_as_number */ - 0, /* tp_as_sequence */ - 0, /* tp_as_mapping */ - 0, /* tp_hash */ - 0, /* tp_call */ - 0, /* tp_str */ - 0, /* tp_getattro */ - 0, /* tp_setattro */ - 0, /* tp_as_buffer */ - 0, /* tp_flags */ - "My objects", /* tp_doc */ - 0, /* tp_traverse */ - 0, /* tp_clear */ - 0, /* tp_richcompare */ - 0, /* tp_weaklistoffset */ - 0, /* tp_iter */ - 0, /* tp_iternext */ - 0, /* tp_methods */ - 0, /* tp_members */ - 0, /* tp_getset */ - 0, /* tp_base */ - 0, /* tp_dict */ - 0, /* tp_descr_get */ - 0, /* tp_descr_set */ - 0, /* tp_dictoffset */ - 0, /* tp_init */ - 0, /* tp_alloc */ - myobj_new, /* tp_new */ - }; - -A type that supports weakrefs, instance dicts, and hashing:: - - typedef struct { - PyObject_HEAD - const char *data; - PyObject *inst_dict; - PyObject *weakreflist; - } MyObject; - - static PyTypeObject MyObject_Type = { - PyVarObject_HEAD_INIT(NULL, 0) - .tp_name = "mymod.MyObject", - .tp_basicsize = sizeof(MyObject), - .tp_doc = "My objects", - .tp_weaklistoffset = offsetof(MyObject, weakreflist), - .tp_dictoffset = offsetof(MyObject, inst_dict), - .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, - .tp_new = myobj_new, - .tp_traverse = (traverseproc)myobj_traverse, - .tp_clear = (inquiry)myobj_clear, - .tp_alloc = PyType_GenericNew, - .tp_dealloc = (destructor)myobj_dealloc, - .tp_repr = (reprfunc)myobj_repr, - .tp_hash = (hashfunc)myobj_hash, - .tp_richcompare = PyBaseObject_Type.tp_richcompare, - }; - -A str subclass that cannot be subclassed and cannot be called -to create instances (e.g. uses a separate factory func):: - - typedef struct { - PyUnicodeObject raw; - char *extra; - } MyStr; - - static PyTypeObject MyStr_Type = { - PyVarObject_HEAD_INIT(NULL, 0) - .tp_name = "mymod.MyStr", - .tp_basicsize = sizeof(MyStr), - .tp_base = NULL, // set to &PyUnicode_Type in module init - .tp_doc = "my custom str", - .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_new = NULL, - .tp_repr = (reprfunc)myobj_repr, - }; - -The simplest static type (with fixed-length instances):: - - typedef struct { - PyObject_HEAD - } MyObject; - - static PyTypeObject MyObject_Type = { - PyVarObject_HEAD_INIT(NULL, 0) - .tp_name = "mymod.MyObject", - }; - -The simplest static type (with variable-length instances):: - - typedef struct { - PyObject_VAR_HEAD - const char *data[1]; - } MyObject; - - static PyTypeObject MyObject_Type = { - PyVarObject_HEAD_INIT(NULL, 0) - .tp_name = "mymod.MyObject", - .tp_basicsize = sizeof(MyObject) - sizeof(char *), - .tp_itemsize = sizeof(char *), - }; - -For more examples, practical info, and a tutorial, see -:ref:`defining-new-types` and :ref:`new-types-topics`. For -information about dynamically created (aka heap) types, see -:c:func:`PyType_FromSpec`. - PyTypeObject Definition ----------------------- @@ -2424,4 +2288,144 @@ Slot Type typedefs .. c:type:: int (*objobjargproc)(PyObject *, PyObject *, PyObject *) -.. XXX Add a section about heap types (see PyType_FromSpec)? +.. _examples: + +Examples +======== + +The following are simple examples of Python type definitions. They +include common usage you may encounter. Some demonstrate tricky corner +cases. For more examples, practical info, and a tutorial, see +:ref:`defining-new-types` and :ref:`new-types-topics`. + +A basic static type:: + + typedef struct { + PyObject_HEAD + const char *data; + } MyObject; + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyObject", + .tp_basicsize = sizeof(MyObject), + .tp_doc = "My objects", + .tp_new = myobj_new, + .tp_dealloc = (destructor)myobj_dealloc, + .tp_repr = (reprfunc)myobj_repr, + }; + +You may also find older code (especially in the CPython code base) +with a more verbose initializer:: + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + "mymod.MyObject", /* tp_name */ + sizeof(MyObject), /* tp_basicsize */ + 0, /* tp_itemsize */ + (destructor)myobj_dealloc, /* tp_dealloc */ + 0, /* tp_print */ + 0, /* tp_getattr */ + 0, /* tp_setattr */ + 0, /* tp_as_async */ + (reprfunc)myobj_repr, /* tp_repr */ + 0, /* tp_as_number */ + 0, /* tp_as_sequence */ + 0, /* tp_as_mapping */ + 0, /* tp_hash */ + 0, /* tp_call */ + 0, /* tp_str */ + 0, /* tp_getattro */ + 0, /* tp_setattro */ + 0, /* tp_as_buffer */ + 0, /* tp_flags */ + "My objects", /* tp_doc */ + 0, /* tp_traverse */ + 0, /* tp_clear */ + 0, /* tp_richcompare */ + 0, /* tp_weaklistoffset */ + 0, /* tp_iter */ + 0, /* tp_iternext */ + 0, /* tp_methods */ + 0, /* tp_members */ + 0, /* tp_getset */ + 0, /* tp_base */ + 0, /* tp_dict */ + 0, /* tp_descr_get */ + 0, /* tp_descr_set */ + 0, /* tp_dictoffset */ + 0, /* tp_init */ + 0, /* tp_alloc */ + myobj_new, /* tp_new */ + }; + +A type that supports weakrefs, instance dicts, and hashing:: + + typedef struct { + PyObject_HEAD + const char *data; + PyObject *inst_dict; + PyObject *weakreflist; + } MyObject; + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyObject", + .tp_basicsize = sizeof(MyObject), + .tp_doc = "My objects", + .tp_weaklistoffset = offsetof(MyObject, weakreflist), + .tp_dictoffset = offsetof(MyObject, inst_dict), + .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, + .tp_new = myobj_new, + .tp_traverse = (traverseproc)myobj_traverse, + .tp_clear = (inquiry)myobj_clear, + .tp_alloc = PyType_GenericNew, + .tp_dealloc = (destructor)myobj_dealloc, + .tp_repr = (reprfunc)myobj_repr, + .tp_hash = (hashfunc)myobj_hash, + .tp_richcompare = PyBaseObject_Type.tp_richcompare, + }; + +A str subclass that cannot be subclassed and cannot be called +to create instances (e.g. uses a separate factory func):: + + typedef struct { + PyUnicodeObject raw; + char *extra; + } MyStr; + + static PyTypeObject MyStr_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyStr", + .tp_basicsize = sizeof(MyStr), + .tp_base = NULL, // set to &PyUnicode_Type in module init + .tp_doc = "my custom str", + .tp_flags = Py_TPFLAGS_DEFAULT, + .tp_new = NULL, + .tp_repr = (reprfunc)myobj_repr, + }; + +The simplest static type (with fixed-length instances):: + + typedef struct { + PyObject_HEAD + } MyObject; + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyObject", + }; + +The simplest static type (with variable-length instances):: + + typedef struct { + PyObject_VAR_HEAD + const char *data[1]; + } MyObject; + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyObject", + .tp_basicsize = sizeof(MyObject) - sizeof(char *), + .tp_itemsize = sizeof(char *), + }; From ae3ad3dc55c8092cec50fe5fb3ba2994bd388efd Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Fri, 8 Jun 2018 11:05:26 -0600 Subject: [PATCH 38/43] Add a section about heap types. --- Doc/c-api/typeobj.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 1d7bd3680fa917..88a4b4563f3c5e 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1799,6 +1799,18 @@ objects on the thread which called tp_dealloc will not violate any assumptions of the library. +Heap Types +---------- + +In addition to defining Python types statically, you can define them +dynamically (i.e. to the heap) using :c:func:`PyType_FromSpec` and +:c:func:`PyType_FromSpecWithBases`. + +.. XXX Explain how to use PyType_FromSpec(). + +.. XXX Document PyType_Spec. + + .. _number-structs: Number Object Structures From 349e2452344210d89abdea603797c184fc5d8a17 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Fri, 8 Jun 2018 11:25:15 -0600 Subject: [PATCH 39/43] Add a note about tp_base initialization. --- Doc/c-api/typeobj.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 88a4b4563f3c5e..dc3e7207ce433b 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1384,6 +1384,24 @@ and :c:type:`PyType_Type` effectively act as defaults.) this level, only single inheritance is supported; multiple inheritance require dynamically creating a type object by calling the metatype. + .. note:: + + .. from Modules/xxmodule.c + + Slot initialization is subject to the rules of initializing globals. + C99 requires the initializers to be "address constants". Function + designators like :c:func:`PyType_GenericNew`, with implicit conversion + to a pointer, are valid C99 address constants. + + However, the unary '&' operator applied to a non-static variable + like :c:func:`PyBaseObject_Type` is not required to produce an address + constant. Compilers may support this (gcc does), MSVC does not. + Both compilers are strictly standard conforming in this particular + behavior. + + Consequently, :c:member:`~PyTypeObject.tp_base` should be set in + the extension module's init function. + **Inheritance:** This field is not inherited by subtypes (obviously). From cef58ea7bce02a098426a3c9609bdb41505b7a2c Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 13 Jun 2018 09:12:55 -0600 Subject: [PATCH 40/43] Use a better convention for required type slots in the table. --- Doc/c-api/typeobj.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index dc3e7207ce433b..ca77e341abb07c 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -41,7 +41,7 @@ Quick Reference | | | methods/attrs +---+---+---+---+ | | | | O | T | D | I | +=============================================+===================================+===================+===+===+===+===+ - | \* :c:member:`~PyTypeObject.tp_name` | const char * | __name__ | X | X | | | + | :c:member:`~PyTypeObject.tp_name` | const char * | __name__ | X | X | | | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ | :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | | X | X | | X | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ @@ -159,7 +159,7 @@ fields exist as well: A slot name in parentheses indicates it is (effectively) deprecated. Names in angle brackets should be treated as read-only. Names in square brackets are for internal use only. - An asterisk means the field must be non-*NULL*. + "" (as a prefix) means the field is required (must be non-*NULL*). .. [#cols] Columns: **"O"**: set on :c:type:`PyBaseObject_Type` From 6af25b76cb0ae342de3fb1acce37a36861b3c336 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 13 Jun 2018 09:17:49 -0600 Subject: [PATCH 41/43] Use less confusing phrasing in the table legend. --- Doc/c-api/typeobj.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index ca77e341abb07c..ca17a37dc6b23f 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -170,10 +170,12 @@ fields exist as well: .. code-block:: none - X - *PyType_Ready* always sets this value (if *NULL*) + X - *PyType_Ready* sets this value if it is *NULL* ~ - *PyType_Ready* always sets this value (it should be *NULL*) ? - *PyType_Ready* may set this value depending on other slots + Also see the inheritance column ("I"). + **"I"**: inheritance .. code-block:: none From 8d685e71034f13dee4920798fd0a20b5f6f21486 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 13 Jun 2018 09:25:35 -0600 Subject: [PATCH 42/43] Fix accidental upper-cases. --- Doc/c-api/typeobj.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index ca17a37dc6b23f..c25ff1aa154ed2 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -912,7 +912,7 @@ and :c:type:`PyType_Type` effectively act as defaults.) 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*. + the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*. **Default:** From f2df61db45a4fe907fbb27d58d118ec556c4f1e0 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Wed, 13 Jun 2018 09:30:52 -0600 Subject: [PATCH 43/43] Use less awkward working for the tp_richcompare default. --- Doc/c-api/typeobj.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index c25ff1aa154ed2..5615f59514b9de 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1259,8 +1259,9 @@ and :c:type:`PyType_Type` effectively act as defaults.) **Default:** - :c:type:`PyBaseObject_Type` provides a :attr:`tp_richcompare`. - However, if only :attr:`tp_hash` is defined, not even this is used + :c:type:`PyBaseObject_Type` provides a :attr:`tp_richcompare` + implementation, which may be inherited. However, if only + :attr:`tp_hash` is defined, not even the inherited function is used and instances of the type will not be able to participate in any comparisons.