\code{\&PyType_Type}; in Python 2.2.1 and later it will be
initialized to the \member{ob_type} field of the base class.
\cfunction{PyType_Ready()} will not change this field if it is
- nonzero.
+ non-zero.
In Python 2.2, this field is not inherited by subtypes. In 2.2.1,
and in 2.3 and beyond, it is inherited by subtypes.
references which the instance owns, free all memory buffers owned by
the instance (using the freeing function corresponding to the
allocation function used to allocate the buffer), and finally (as
- its last action) call the type's \member{tp_free} slot. If the type
- is not subtypable (doesn't have the \constant{Py_TPFLAGS_BASETYPE}
- flag bit set), it is permissible to call the object deallocator
- directly instead of via \member{tp_free}. The object deallocator
- should be the one used to allocate the instance; this is normally
- \cfunction{PyObject_Del()} if the instance was allocated using
- \cfunction{PyObject_New()} or \cfunction{PyOject_VarNew()}, or
- \cfunction{PyObject_GC_Del()} if the instance was allocated using
- \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}.
+ its last action) call the type's \member{tp_free} function. If the
+ type is not subtypable (doesn't have the
+ \constant{Py_TPFLAGS_BASETYPE} flag bit set), it is permissible to
+ call the object deallocator directly instead of via
+ \member{tp_free}. The object deallocator should be the one used to
+ allocate the instance; this is normally \cfunction{PyObject_Del()}
+ if the instance was allocated using \cfunction{PyObject_New()} or
+ \cfunction{PyOject_VarNew()}, or \cfunction{PyObject_GC_Del()} if
+ the instance was allocated using \cfunction{PyObject_GC_New()} or
+ \cfunction{PyObject_GC_VarNew()}.
This field is inherited by subtypes.
\end{cmemberdesc}
together using the \code{|} operator to form the value of the
\member{tp_flags} field. The macro \cfunction{PyType_HasFeature()}
takes a type and a flags value, \var{tp} and \var{f}, and checks
- whether \code{\var{tp}->tp_flags \& \var{f}} is nonzero.
+ whether \code{\var{tp}->tp_flags \& \var{f}} is non-zero.
\begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
If this bit is set, the \ctype{PyBufferProcs} struct referenced by
\begin{cmemberdesc}{PyTypeObject}{char*}{tp_doc}
An optional pointer to a NUL-terminated C string giving the
- docstring for this type object.
+ docstring for this type object. This is exposed as the
+ \member{__doc__} attribute on the type and instances of the type.
This field is \emph{not} inherited by subtypes.
\end{cmemberdesc}
\end{cmemberdesc}
The next field only exists if the \constant{Py_TPFLAGS_HAVE_WEAKREFS}
-flag bit is set. (XXX ???)
+flag bit is set.
+
+\begin{cmemberdesc}{PyTypeObject}{long}{tp_weaklistoffset}
+ If the instances of this type are weakly referenceable, this field
+ is greater than zero and contains the offset in the instance
+ structure of the weak reference list head (ignoring the GC header,
+ if present); this offset is used by
+ \cfunction{PyObject_ClearWeakRefs()} and the
+ \cfunction{PyWeakref_*()} functions. The instance structure needs
+ to include a field of type \ctype{PyObject*} which is initialized to
+ \NULL.
+
+ Do not confuse this field with \member{tp_weaklist}; that is the
+ list head for weak references to the type object itself.
+
+ This field is inherited by subtypes, but see the rules listed below.
+ A subtype may override this offset; this means that the subtype uses
+ a different weak reference list head than the base type. Since the
+ list head is always found via \member{tp_weaklistoffset}, this
+ should not be a problem.
+
+ When a type defined by a class statement has no \member{__slots__}
+ declaration, and none of its base types are weakly referenceable,
+ the type is made weakly referenceable by adding a weak reference
+ list head slot to the instance layout and setting the
+ \member{tp_weaklistoffset} of that slot's offset.
+
+ When a type's \member{__slots__} declaration contains a slot named
+ \member{__weakref__}, that slot becomes the weak reference list head
+ for instances of the type, and the slot's offset is stored in the
+ type's \member{tp_weaklistoffset}.
+
+ When a type's \member{__slots__} declaration does not contain a slot
+ named \member{__weakref__}, the type inherits its
+ \member{tp_weaklistoffset} from its base type.
+\end{cmemberdesc}
-long tp_weaklistoffset;
+The next two fields only exist if the
+\constant{Py_TPFLAGS_HAVE_CLASS} flag bit is set.
- XXX
+\begin{cmemberdesc}{PyTypeObject}{getiterfunc}{tp_iter}
+ An optional pointer to a function that returns an iterator for the
+ object. Its presence normally signals that the instances of this
+ type are iterable (although sequences may be iterable without this
+ function, and classic instances always have this function, even if
+ they don't define an \method{__iter__()} method).
+ This function has the same signature as
+ \cfunction{PyObject_GetIter()}.
-The remaining fields only exist if the
-\constant{Py_TPFLAGS_HAVE_CLASS} flag bit is set.
+ This field is inherited by subtypes.
+\end{cmemberdesc}
-/* Added in release 2.2 */
-/* Iterators */
-getiterfunc tp_iter;
+\begin{cmemberdesc}{PyTypeObject}{iternextfunc}{tp_iternext}
+ An optional pointer to a function that returns the next item in an
+ iterator, or raises \exception{StopIteration} when the iterator is
+ exhausted. Its presence normally signals that the instances of this
+ type are iterators (although classic instances always have this
+ function, even if they don't define a \method{next()} method).
- XXX
+ Iterator types should also define the \member{tp_iter} function, and
+ that function should return the iterator instance itself (not a new
+ iterator instance).
-iternextfunc tp_iternext;
+ This function has the same signature as \cfunction{PyIter_Next()}.
- XXX
+ This field is inherited by subtypes.
+\end{cmemberdesc}
+
+The next fields, up to and including \member{tp_weaklist}, only exist
+if the \constant{Py_TPFLAGS_HAVE_CLASS} flag bit is set.
+
+\begin{cmemberdesc}{PyTypeObject}{struct PyMethodDef*}{tp_methods}
+ An optional pointer to a static \NULL-terminated array of
+ \ctype{PyMethodDef} structures, declaring regular methods of this
+ type.
+
+ For each entry in the array, an entry is added to the type's
+ dictionary (see \member{tp_dict} below) containing a method
+ descriptor.
+
+ This field is not inherited by subtypes (methods are
+ inherited through a different mechanism).
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{struct PyMemberDef*}{tp_members}
+ An optional pointer to a static \NULL-terminated array of
+ \ctype{PyMemberDef} structures, declaring regular data members
+ (fields or slots) of instances of this type.
+
+ For each entry in the array, an entry is added to the type's
+ dictionary (see \member{tp_dict} below) containing a member
+ descriptor.
+
+ This field is not inherited by subtypes (members are inherited
+ through a different mechanism).
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{struct PyGetSetDef*}{tp_getset}
+ An optional pointer to a static \NULL-terminated array of
+ \ctype{PyGetSetDef} structures, declaring computed attributes of
+ instances of this type.
+
+ For each entry in the array, an entry is added to the type's
+ dictionary (see \member{tp_dict} below) containing a getset
+ descriptor.
+
+ This field is not inherited by subtypes (computed attributes are
+ inherited through a different mechanism).
+
+ Docs for PyGetSetDef (XXX belong elsewhere):
+
+\begin{verbatim}
+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;
+\end{verbatim}
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyTypeObject*}{tp_base}
+ An optional pointer to a base type from which type properties are
+ inherited. At this level, only single inheritance is supported;
+ multiple inheritance require dynamically creating a type object by
+ calling the metatype.
+
+ This field is not inherited by subtypes (obviously), but it defaults
+ to \code{\&PyBaseObject_Type} (which to Python programmers is known
+ as the type \class{object}).
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_dict}
+ The type's dictionary is stored here by \cfunction{PyType_Ready()}.
+
+ This field should normally be initialized to \NULL{} before
+ PyType_Ready is called; it may also be initialized to a dictionary
+ containing initial attributes for the type. Once
+ \cfunction{PyType_Ready()} has initialized the type, extra
+ attributes for the type may be added to this dictionary only if they
+ don't correspond to overloaded operations (like \method{__add__()}).
+
+ This field is not inherited by subtypes (though the attributes
+ defined in here are inherited through a different mechanism).
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{descrgetfunc}{tp_descr_get}
+ An optional pointer to a "descriptor get" function.
+
+ XXX blah, blah.
+
+ This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{descrsetfunc}{tp_descr_set}
+ An optional pointer to a "descriptor set" function.
+
+ XXX blah, blah.
+
+ This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{long}{tp_dictoffset}
+ If the instances of this type have a dictionary containing instance
+ variables, this field is non-zero and contains the offset in the
+ instances of the type of the instance variable dictionary; this
+ offset is used by \cfunction{PyObject_GenericGetAttr()}.
+
+ Do not confuse this field with \member{tp_dict}; that is the
+ dictionary for attributes of the type object itself.
+
+ If the value of this field is greater than zero, it specifies the
+ offset from the start of the instance structure. If the value is
+ less than zero, it specifies the offset from the *end* of the
+ instance structure. A negative offset is more expensive to use, and
+ should only be used when the instance structure contains a
+ variable-length part. This is used for example to add an instance
+ variable dictionary to subtypes of \class{str} or \class{tuple}.
+ Note that the \member{tp_basicsize} field should account for the
+ dictionary added to the end in that case, even though the dictionary
+ is not included in the basic object layout. On a system with a
+ pointer size of 4 bytes, \member{tp_dictoffset} should be set to
+ \code{-4} to indicate that the dictionary is at the very end of the
+ structure.
+
+ The real dictionary offset in an instance can be computed from a
+ negative \member{tp_dictoffset} as follows:
+
+\begin{verbatim}
+dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
+if dictoffset is not aligned on sizeof(void*):
+ round up to sizeof(void*)
+\end{verbatim}
+
+ where \member{tp_basicsize}, \member{tp_itemsize} and
+ \member{tp_dictoffset} are taken from the type object, and
+ \member{ob_size} is taken from the instance. The absolute value is
+ taken because long ints use the sign of \member{ob_size} to store
+ the sign of the number. (There's never a need to do this
+ calculation yourself; it is done for you by
+ \cfunction{_PyObject_GetDictPtr()}.)
+
+ This field is inherited by subtypes, but see the rules listed below.
+ A subtype may override this offset; this means that the subtype
+ instances store the dictionary at a difference offset than the base
+ type. Since the dictionary is always found via
+ \member{tp_dictoffset}, this should not be a problem.
+
+ When a type defined by a class statement has no \member{__slots__}
+ declaration, and none of its base types has an instance variable
+ dictionary, a dictionary slot is added to the instance layout and
+ the \member{tp_dictoffset} is set to that slot's offset.
+
+ When a type defined by a class statement has a \member{__slots__}
+ declaration, the type inherits its \member{tp_dictoffset} from its
+ base type.
+
+ (Adding a slot named \member{__dict__} to the \member{__slots__}
+ declaration does not have the expected effect, it just causes
+ confusion. Maybe this should be added as a feature just like
+ \member{__weakref__} though.)
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{initproc}{tp_init}
+ An optional pointer to an instance initialization function.
+
+ This function corresponds to the \method{__init__()} method of
+ classes. Like \method{__init__()}, it is possible to create an
+ instance without calling \method{__init__()}, and it is possible to
+ reinitialize an instance by calling its \method{__init__()} method
+ again.
+
+ The function signature is
+
+\begin{verbatim}
+tp_init(PyObject *self, PyObject *args, PyObject *kwds)
+\end{verbatim}
+
+ The self argument is the instance to be initialized; the \var{args}
+ and \var{kwds} arguments represent positional and keyword arguments
+ of the call to \method{__init__()}.
+
+ The \member{tp_init} function, if not \NULL, is called when an
+ instance is created normally by calling its type, after the type's
+ \member{tp_new} function has returned an instance of the type. If
+ the \member{tp_new} function returns an instance of some other type
+ that is not a subtype of the original type, no \member{tp_init}
+ function is called; if \member{tp_new} returns an instance of a
+ subtype of the original type, the subtype's \member{tp_init} is
+ called. (VERSION NOTE: described here is what is implemented in
+ Python 2.2.1 and later. In Python 2.2, the \member{tp_init} of the
+ type of the object returned by \member{tp_new} was always called, if
+ not \NULL.)
+
+ This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{allocfunc}{tp_alloc}
+ An optional pointer to an instance allocation function.
+
+ The function signature is
+
+\begin{verbatim}
+tp_alloc(PyTypeObject *self, int nitems)
+\end{verbatim}
+
+ 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 \member{ob_refcnt} set to \code{1}
+ and \member{ob_type} set to the type argument. If the type's
+ \member{tp_itemsize} is non-zero, the object's \member{ob_size} field
+ should be initialized to \var{nitems} and the length of the
+ allocated memory block should be \code{tp_basicsize +
+ \var{nitems}*tp_itemsize}, rounded up to a multiple of
+ \code{sizeof(void*)}; otherwise, \var{nitems} is not used and the
+ length of the block should be \member{tp_basicsize}.
+
+ Do not use this function to do any other instance initialization,
+ not even to allocate additional memory; that should be done by
+ \member{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 \cfunction{PyType_GenericAlloc()}, to
+ force a standard heap allocation strategy. That is also the
+ recommended value for statically defined types.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{newfunc}{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
+
+\begin{verbatim}
+tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)
+\end{verbatim}
+
+ The subtype argument is the type of the object being created; the
+ \var{args} and \var{kwds} arguments represent positional and keyword
+ arguments of the call to the type. Note that subtype doesn't have
+ to equal the type whose \member{tp_new} function is called; it may
+ be a subtype of that type (but not an unrelated type).
+
+ The \member{tp_new} function should call
+ \code{\var{subtype}->tp_alloc(\var{subtype}, \var{nitems})} to
+ allocate space for the object, and then do only as much further
+ initialization as is absolutely necessary. Initialization that can
+ safely be ignored or repeated should be placed in the
+ \member{tp_init} handler. A good rule of thumb is that for
+ immutable types, all initialization should take place in
+ \member{tp_new}, while for mutable types, most initialization should
+ be deferred to \member{tp_init}.
+
+ This field is inherited by subtypes, except it is not inherited by
+ static types whose \member{tp_base} is \NULL{} or
+ \code{\&PyBaseObject_Type}. The latter exception is a precaution so
+ that old extension types don't become callable simply by being
+ linked with Python 2.2.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{destructor}{tp_free}
+ An optional pointer to an instance deallocation function.
+
+ The signature of this function has changed slightly: in Python
+ 2.2 and 2.2.1, its signature is \ctype{destructor}:
+
+\begin{verbatim}
+void tp_free(PyObject *)
+\end{verbatim}
+
+ In Python 2.3 and beyond, its signature is \ctype{freefunc}:
+
+\begin{verbatim}
+void tp_free(void *)
+\end{verbatim}
+
+ The only initializer that is compatible with both versions is
+ \code{_PyObject_Del}, whose definition has suitably adapted in
+ Python 2.3.
+
+ This field is inherited by static subtypes, but not by dynamic
+ subtypes (subtypes created by a class statement); in the latter,
+ this field is set to a deallocator suitable to match
+ \cfunction{PyType_GenericAlloc()} and the value of the
+ \constant{Py_TPFLAGS_HAVE_GC} flag bit.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{inquiry}{tp_is_gc}
+ An optional pointer to a function called by the garbage collector.
+
+ The garbage collector needs to know whether a particular object is
+ collectible or not. Normally, it is sufficient to look at the
+ object's type's \member{tp_flags} field, and check the
+ \constant{Py_TPFLAGS_HAVE_GC} flag bit. But some types have a
+ mixture of statically and dynamically allocated instances, and the
+ statically allocated instances are not collectible. Such types
+ should define this function; it should return \code{1} for a
+ collectible instance, and \code{0} for a non-collectible instance.
+ The signature is
+
+\begin{verbatim}
+int tp_is_gc(PyObject *self)
+\end{verbatim}
+
+ (The only example of this are types themselves. The metatype,
+ \cdata{PyType_Type}, defines this function to distinguish between
+ statically and dynamically allocated types.)
+
+ This field is inherited by subtypes. (VERSION NOTE: in Python
+ 2.2, it was not inherited. It is inherited in 2.2.1 and later
+ versions.)
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_bases}
+ Tuple of base types.
+
+ This is set for types created by a class statement. It should be
+ \NULL{} for statically defined types.
+
+ This field is not inherited.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_mro}
+ Tuple containing the expanded set of base types, starting with the
+ type itself and ending with \class{object}, in Method Resolution
+ Order.
+
+ This field is not inherited; it is calculated fresh by
+ \cfunction{PyType_Ready()}.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_cache}
+ Unused. Not inherited. Internal use only.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_subclasses}
+ List of weak references to subclasses. Not inherited. Internal
+ use only.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_weaklist}
+ Weak reference list head, for weak references to this type
+ object. Not inherited. Internal use only.
+\end{cmemberdesc}
+
+The remaining fields are only defined if the feature test macro
+\constant{COUNT_ALLOCS} is defined, and are for internal use only.
+They are documented here for completion. None of these fields are
+inherited by subtypes.
+
+\begin{cmemberdesc}{PyTypeObject}{int}{tp_allocs}
+ Number of allocations.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{int}{tp_frees}
+ Number of frees.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{int}{tp_maxalloc}
+ Maximum simultaneously allocated objects.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{PyTypeObject*}{tp_next}
+ Pointer to the next type object with a non-zero \member{tp_allocs}
+ field.
+\end{cmemberdesc}
\section{Mapping Object Structures \label{mapping-structs}}
projects / python / commitdiff