1716 lines
73 KiB
TeX
1716 lines
73 KiB
TeX
\chapter{Object Implementation Support \label{newTypes}}
|
|
|
|
|
|
This chapter describes the functions, types, and macros used when
|
|
defining new object types.
|
|
|
|
|
|
\section{Allocating Objects on the Heap
|
|
\label{allocating-objects}}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, int size}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{PyObject_Init}{PyObject *op,
|
|
PyTypeObject *type}
|
|
Initialize a newly-allocated object \var{op} with its type and
|
|
initial reference. Returns the initialized object. If \var{type}
|
|
indicates that the object participates in the cyclic garbage
|
|
detector, it is added to the detector's set of observed objects.
|
|
Other fields of the object are not affected.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyVarObject*}{PyObject_InitVar}{PyVarObject *op,
|
|
PyTypeObject *type, int size}
|
|
This does everything \cfunction{PyObject_Init()} does, and also
|
|
initializes the length information for a variable-size object.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_New}{TYPE, PyTypeObject *type}
|
|
Allocate a new Python object using the C structure type \var{TYPE}
|
|
and the Python type object \var{type}. Fields not defined by the
|
|
Python object header are not initialized; the object's reference
|
|
count will be one. The size of the memory
|
|
allocation is determined from the \member{tp_basicsize} field of the
|
|
type object.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NewVar}{TYPE, PyTypeObject *type,
|
|
int size}
|
|
Allocate a new Python object using the C structure type \var{TYPE}
|
|
and the Python type object \var{type}. Fields not defined by the
|
|
Python object header are not initialized. The allocated memory
|
|
allows for the \var{TYPE} structure plus \var{size} fields of the
|
|
size given by the \member{tp_itemsize} field of \var{type}. This is
|
|
useful for implementing objects like tuples, which are able to
|
|
determine their size at construction time. Embedding the array of
|
|
fields into the same allocation decreases the number of allocations,
|
|
improving the memory management efficiency.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyObject_Del}{PyObject *op}
|
|
Releases memory allocated to an object using
|
|
\cfunction{PyObject_New()} or \cfunction{PyObject_NewVar()}. This
|
|
is normally called from the \member{tp_dealloc} handler specified in
|
|
the object's type. The fields of the object should not be accessed
|
|
after this call as the memory is no longer a valid Python object.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW}{TYPE, PyTypeObject *type}
|
|
Macro version of \cfunction{PyObject_New()}, to gain performance at
|
|
the expense of safety. This does not check \var{type} for a \NULL{}
|
|
value.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW_VAR}{TYPE, PyTypeObject *type,
|
|
int size}
|
|
Macro version of \cfunction{PyObject_NewVar()}, to gain performance
|
|
at the expense of safety. This does not check \var{type} for a
|
|
\NULL{} value.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op}
|
|
Macro version of \cfunction{PyObject_Del()}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{Py_InitModule}{char *name,
|
|
PyMethodDef *methods}
|
|
Create a new module object based on a name and table of functions,
|
|
returning the new module object.
|
|
|
|
\versionchanged[Older versions of Python did not support \NULL{} as
|
|
the value for the \var{methods} argument]{2.3}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{Py_InitModule3}{char *name,
|
|
PyMethodDef *methods,
|
|
char *doc}
|
|
Create a new module object based on a name and table of functions,
|
|
returning the new module object. If \var{doc} is non-\NULL, it will
|
|
be used to define the docstring for the module.
|
|
|
|
\versionchanged[Older versions of Python did not support \NULL{} as
|
|
the value for the \var{methods} argument]{2.3}
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{Py_InitModule4}{char *name,
|
|
PyMethodDef *methods,
|
|
char *doc, PyObject *self,
|
|
int apiver}
|
|
Create a new module object based on a name and table of functions,
|
|
returning the new module object. If \var{doc} is non-\NULL, it will
|
|
be used to define the docstring for the module. If \var{self} is
|
|
non-\NULL, it will passed to the functions of the module as their
|
|
(otherwise \NULL) first parameter. (This was added as an
|
|
experimental feature, and there are no known uses in the current
|
|
version of Python.) For \var{apiver}, the only value which should
|
|
be passed is defined by the constant \constant{PYTHON_API_VERSION}.
|
|
|
|
\note{Most uses of this function should probably be using
|
|
the \cfunction{Py_InitModule3()} instead; only use this if you are
|
|
sure you need it.}
|
|
|
|
\versionchanged[Older versions of Python did not support \NULL{} as
|
|
the value for the \var{methods} argument]{2.3}
|
|
\end{cfuncdesc}
|
|
|
|
DL_IMPORT
|
|
|
|
\begin{cvardesc}{PyObject}{_Py_NoneStruct}
|
|
Object which is visible in Python as \code{None}. This should only
|
|
be accessed using the \code{Py_None} macro, which evaluates to a
|
|
pointer to this object.
|
|
\end{cvardesc}
|
|
|
|
|
|
\section{Common Object Structures \label{common-structs}}
|
|
|
|
There are a large number of structures which are used in the
|
|
definition of object types for Python. This section describes these
|
|
structures and how they are used.
|
|
|
|
All Python objects ultimately share a small number of fields at the
|
|
beginning of the object's representation in memory. These are
|
|
represented by the \ctype{PyObject} and \ctype{PyVarObject} types,
|
|
which are defined, in turn, by the expansions of some macros also
|
|
used, whether directly or indirectly, in the definition of all other
|
|
Python objects.
|
|
|
|
\begin{ctypedesc}{PyObject}
|
|
All object types are extensions of this type. This is a type which
|
|
contains the information Python needs to treat a pointer to an
|
|
object as an object. In a normal ``release'' build, it contains
|
|
only the objects reference count and a pointer to the corresponding
|
|
type object. It corresponds to the fields defined by the
|
|
expansion of the \code{PyObject_HEAD} macro.
|
|
\end{ctypedesc}
|
|
|
|
\begin{ctypedesc}{PyVarObject}
|
|
This is an extension of \ctype{PyObject} that adds the
|
|
\member{ob_size} field. This is only used for objects that have
|
|
some notion of \emph{length}. This type does not often appear in
|
|
the Python/C API. It corresponds to the fields defined by the
|
|
expansion of the \code{PyObject_VAR_HEAD} macro.
|
|
\end{ctypedesc}
|
|
|
|
These macros are used in the definition of \ctype{PyObject} and
|
|
\ctype{PyVarObject}:
|
|
|
|
\begin{csimplemacrodesc}{PyObject_HEAD}
|
|
This is a macro which expands to the declarations of the fields of
|
|
the \ctype{PyObject} type; it is used when declaring new types which
|
|
represent objects without a varying length. The specific fields it
|
|
expands to depend on the definition of
|
|
\csimplemacro{Py_TRACE_REFS}. By default, that macro is not
|
|
defined, and \csimplemacro{PyObject_HEAD} expands to:
|
|
\begin{verbatim}
|
|
int ob_refcnt;
|
|
PyTypeObject *ob_type;
|
|
\end{verbatim}
|
|
When \csimplemacro{Py_TRACE_REFS} is defined, it expands to:
|
|
\begin{verbatim}
|
|
PyObject *_ob_next, *_ob_prev;
|
|
int ob_refcnt;
|
|
PyTypeObject *ob_type;
|
|
\end{verbatim}
|
|
\end{csimplemacrodesc}
|
|
|
|
\begin{csimplemacrodesc}{PyObject_VAR_HEAD}
|
|
This is a macro which expands to the declarations of the fields of
|
|
the \ctype{PyVarObject} type; it is used when declaring new types which
|
|
represent objects with a length that varies from instance to
|
|
instance. This macro always expands to:
|
|
\begin{verbatim}
|
|
PyObject_HEAD
|
|
int ob_size;
|
|
\end{verbatim}
|
|
Note that \csimplemacro{PyObject_HEAD} is part of the expansion, and
|
|
that its own expansion varies depending on the definition of
|
|
\csimplemacro{Py_TRACE_REFS}.
|
|
\end{csimplemacrodesc}
|
|
|
|
PyObject_HEAD_INIT
|
|
|
|
\begin{ctypedesc}{PyCFunction}
|
|
Type of the functions used to implement most Python callables in C.
|
|
Functions of this type take two \ctype{PyObject*} parameters and
|
|
return one such value. If the return value is \NULL, an exception
|
|
shall have been set. If not \NULL, the return value is interpreted
|
|
as the return value of the function as exposed in Python. The
|
|
function must return a new reference.
|
|
\end{ctypedesc}
|
|
|
|
\begin{ctypedesc}{PyMethodDef}
|
|
Structure used to describe a method of an extension type. This
|
|
structure has four fields:
|
|
|
|
\begin{tableiii}{l|l|l}{member}{Field}{C Type}{Meaning}
|
|
\lineiii{ml_name}{char *}{name of the method}
|
|
\lineiii{ml_meth}{PyCFunction}{pointer to the C implementation}
|
|
\lineiii{ml_flags}{int}{flag bits indicating how the call should be
|
|
constructed}
|
|
\lineiii{ml_doc}{char *}{points to the contents of the docstring}
|
|
\end{tableiii}
|
|
\end{ctypedesc}
|
|
|
|
The \member{ml_meth} is a C function pointer. The functions may be of
|
|
different types, but they always return \ctype{PyObject*}. If the
|
|
function is not of the \ctype{PyCFunction}, the compiler will require
|
|
a cast in the method table. Even though \ctype{PyCFunction} defines
|
|
the first parameter as \ctype{PyObject*}, it is common that the method
|
|
implementation uses a the specific C type of the \var{self} object.
|
|
|
|
The \member{ml_flags} field is a bitfield which can include the
|
|
following flags. The individual flags indicate either a calling
|
|
convention or a binding convention. Of the calling convention flags,
|
|
only \constant{METH_VARARGS} and \constant{METH_KEYWORDS} can be
|
|
combined (but note that \constant{METH_KEYWORDS} alone is equivalent
|
|
to \code{\constant{METH_VARARGS} | \constant{METH_KEYWORDS}}).
|
|
Any of the calling convention flags can be combined with a
|
|
binding flag.
|
|
|
|
\begin{datadesc}{METH_VARARGS}
|
|
This is the typical calling convention, where the methods have the
|
|
type \ctype{PyCFunction}. The function expects two
|
|
\ctype{PyObject*} values. The first one is the \var{self} object for
|
|
methods; for module functions, it has the value given to
|
|
\cfunction{Py_InitModule4()} (or \NULL{} if
|
|
\cfunction{Py_InitModule()} was used). The second parameter
|
|
(often called \var{args}) is a tuple object representing all
|
|
arguments. This parameter is typically processed using
|
|
\cfunction{PyArg_ParseTuple()} or \cfunction{PyArg_UnpackTuple}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{METH_KEYWORDS}
|
|
Methods with these flags must be of type
|
|
\ctype{PyCFunctionWithKeywords}. The function expects three
|
|
parameters: \var{self}, \var{args}, and a dictionary of all the
|
|
keyword arguments. The flag is typically combined with
|
|
\constant{METH_VARARGS}, and the parameters are typically processed
|
|
using \cfunction{PyArg_ParseTupleAndKeywords()}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{METH_NOARGS}
|
|
Methods without parameters don't need to check whether arguments are
|
|
given if they are listed with the \constant{METH_NOARGS} flag. They
|
|
need to be of type \ctype{PyCFunction}. When used with object
|
|
methods, the first parameter is typically named \code{self} and will
|
|
hold a reference to the object instance. In all cases the second
|
|
parameter will be \NULL.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{METH_O}
|
|
Methods with a single object argument can be listed with the
|
|
\constant{METH_O} flag, instead of invoking
|
|
\cfunction{PyArg_ParseTuple()} with a \code{"O"} argument. They have
|
|
the type \ctype{PyCFunction}, with the \var{self} parameter, and a
|
|
\ctype{PyObject*} parameter representing the single argument.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{METH_OLDARGS}
|
|
This calling convention is deprecated. The method must be of type
|
|
\ctype{PyCFunction}. The second argument is \NULL{} if no arguments
|
|
are given, a single object if exactly one argument is given, and a
|
|
tuple of objects if more than one argument is given. There is no
|
|
way for a function using this convention to distinguish between a
|
|
call with multiple arguments and a call with a tuple as the only
|
|
argument.
|
|
\end{datadesc}
|
|
|
|
These two constants are not used to indicate the calling convention
|
|
but the binding when use with methods of classes. These may not be
|
|
used for functions defined for modules. At most one of these flags
|
|
may be set for any given method.
|
|
|
|
\begin{datadesc}{METH_CLASS}
|
|
The method will be passed the type object as the first parameter
|
|
rather than an instance of the type. This is used to create
|
|
\emph{class methods}, similar to what is created when using the
|
|
\function{classmethod()}\bifuncindex{classmethod} built-in
|
|
function.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{METH_STATIC}
|
|
The method will be passed \NULL{} as the first parameter rather than
|
|
an instance of the type. This is used to create \emph{static
|
|
methods}, similar to what is created when using the
|
|
\function{staticmethod()}\bifuncindex{staticmethod} built-in
|
|
function.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
One other constant controls whether a method is loaded in place of
|
|
another definition with the same method name.
|
|
|
|
\begin{datadesc}{METH_COEXIST}
|
|
The method will be loaded in place of existing definitions. Without
|
|
\var{METH_COEXIST}, the default is to skip repeated definitions. Since
|
|
slot wrappers are loaded before the method table, the existence of a
|
|
\var{sq_contains} slot, for example, would generate a wrapped method
|
|
named \method{__contains__()} and preclude the loading of a
|
|
corresponding PyCFunction with the same name. With the flag defined,
|
|
the PyCFunction will be loaded in place of the wrapper object and will
|
|
co-exist with the slot. This is helpful because calls to PyCFunctions
|
|
are optimized more than wrapper object calls.
|
|
\versionadded{2.4}
|
|
\end{datadesc}
|
|
|
|
\begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef table[],
|
|
PyObject *ob, char *name}
|
|
Return a bound method object for an extension type implemented in
|
|
C. This can be useful in the implementation of a
|
|
\member{tp_getattro} or \member{tp_getattr} handler that does not
|
|
use the \cfunction{PyObject_GenericGetAttr()} function.
|
|
\end{cfuncdesc}
|
|
|
|
|
|
\section{Type Objects \label{type-structs}}
|
|
|
|
Perhaps one of the most important structures of the Python object
|
|
system is the structure that defines a new type: the
|
|
\ctype{PyTypeObject} structure. Type objects can be handled using any
|
|
of the \cfunction{PyObject_*()} or \cfunction{PyType_*()} functions,
|
|
but do not offer much that's interesting to most Python applications.
|
|
These objects are fundamental to how objects behave, so they are very
|
|
important to the interpreter itself and to any extension module that
|
|
implements new types.
|
|
|
|
Type objects are fairly large compared to most of the standard types.
|
|
The reason for the size is that each type object stores a large number
|
|
of values, mostly C function pointers, each of which implements a
|
|
small part of the type's functionality. The fields of the type object
|
|
are examined in detail in this section. The fields will be described
|
|
in the order in which they occur in the structure.
|
|
|
|
Typedefs:
|
|
unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
|
|
intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
|
|
destructor, freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc,
|
|
setattrofunc, cmpfunc, reprfunc, hashfunc
|
|
|
|
The structure definition for \ctype{PyTypeObject} can be found in
|
|
\file{Include/object.h}. For convenience of reference, this repeats
|
|
the definition found there:
|
|
|
|
\verbatiminput{typestruct.h}
|
|
|
|
The type object structure extends the \ctype{PyVarObject} structure.
|
|
The \member{ob_size} field is used for dynamic types (created
|
|
by \function{type_new()}, usually called from a class statement).
|
|
Note that \cdata{PyType_Type} (the metatype) initializes
|
|
\member{tp_itemsize}, which means that its instances (i.e. type
|
|
objects) \emph{must} have the \member{ob_size} field.
|
|
|
|
\begin{cmemberdesc}{PyObject}{PyObject*}{_ob_next}
|
|
\cmemberline{PyObject}{PyObject*}{_ob_prev}
|
|
These fields are only present when the macro \code{Py_TRACE_REFS} is
|
|
defined. Their initialization to \NULL{} is taken care of by the
|
|
\code{PyObject_HEAD_INIT} macro. For statically allocated objects,
|
|
these fields always remain \NULL. For dynamically allocated
|
|
objects, these two fields are used to link the object into a
|
|
doubly-linked list of \emph{all} live objects on the heap. This
|
|
could be used for various debugging purposes; currently the only use
|
|
is to print the objects that are still alive at the end of a run
|
|
when the environment variable \envvar{PYTHONDUMPREFS} is set.
|
|
|
|
These fields are not inherited by subtypes.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyObject}{int}{ob_refcnt}
|
|
This is the type object's reference count, initialized to \code{1}
|
|
by the \code{PyObject_HEAD_INIT} macro. Note that for statically
|
|
allocated type objects, the type's instances (objects whose
|
|
\member{ob_type} points back to the type) do \emph{not} count as
|
|
references. But for dynamically allocated type objects, the
|
|
instances \emph{do} count as references.
|
|
|
|
This field is not inherited by subtypes.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyObject}{PyTypeObject*}{ob_type}
|
|
This is the type's type, in other words its metatype. It is
|
|
initialized by the argument to the \code{PyObject_HEAD_INIT} macro,
|
|
and its value should normally be \code{\&PyType_Type}. However, for
|
|
dynamically loadable extension modules that must be usable on
|
|
Windows (at least), the compiler complains that this is not a valid
|
|
initializer. Therefore, the convention is to pass \NULL{} to the
|
|
\code{PyObject_HEAD_INIT} macro and to initialize this field
|
|
explicitly at the start of the module's initialization function,
|
|
before doing anything else. This is typically done like this:
|
|
|
|
\begin{verbatim}
|
|
Foo_Type.ob_type = &PyType_Type;
|
|
\end{verbatim}
|
|
|
|
This should be done before any instances of the type are created.
|
|
\cfunction{PyType_Ready()} checks if \member{ob_type} is \NULL, and
|
|
if so, initializes it: in Python 2.2, it is set to
|
|
\code{\&PyType_Type}; in Python 2.2.1 and later it is
|
|
initialized to the \member{ob_type} field of the base class.
|
|
\cfunction{PyType_Ready()} will not change this field if it is
|
|
non-zero.
|
|
|
|
In Python 2.2, this field is not inherited by subtypes. In 2.2.1,
|
|
and in 2.3 and beyond, it is inherited by subtypes.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyVarObject}{int}{ob_size}
|
|
For statically allocated type objects, this should be initialized
|
|
to zero. For dynamically allocated type objects, this field has a
|
|
special internal meaning.
|
|
|
|
This field is not inherited by subtypes.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{char*}{tp_name}
|
|
Pointer to a NUL-terminated string containing the name of the type.
|
|
For types that are accessible as module globals, the string should
|
|
be the full module name, followed by a dot, followed by the type
|
|
name; for built-in types, it should be just the type name. If the
|
|
module is a submodule of a package, the full package name is part of
|
|
the full module name. For example, a type named \class{T} defined
|
|
in module \module{M} in subpackage \module{Q} in package \module{P}
|
|
should have the \member{tp_name} initializer \code{"P.Q.M.T"}.
|
|
|
|
For dynamically allocated type objects, this should just be the type
|
|
name, and the module name explicitly stored in the type dict as the
|
|
value for key \code{'__module__'}.
|
|
|
|
For statically allocated type objects, the tp_name field should
|
|
contain a dot. Everything before the last dot is made accessible as
|
|
the \member{__module__} attribute, and everything after the last dot
|
|
is made accessible as the \member{__name__} attribute.
|
|
|
|
If no dot is present, the entire \member{tp_name} field is made
|
|
accessible as the \member{__name__} attribute, and the
|
|
\member{__module__} attribute is undefined (unless explicitly set in
|
|
the dictionary, as explained above). This means your type will be
|
|
impossible to pickle.
|
|
|
|
This field is not inherited by subtypes.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{int}{tp_basicsize}
|
|
\cmemberline{PyTypeObject}{int}{tp_itemsize}
|
|
These fields allow calculating the size in bytes of instances of
|
|
the type.
|
|
|
|
There are two kinds of types: types with fixed-length instances have
|
|
a zero \member{tp_itemsize} field, types with variable-length
|
|
instances have a non-zero \member{tp_itemsize} field. For a type
|
|
with fixed-length instances, all instances have the same size,
|
|
given in \member{tp_basicsize}.
|
|
|
|
For a type with variable-length instances, the instances must have
|
|
an \member{ob_size} field, and the instance size is
|
|
\member{tp_basicsize} plus N times \member{tp_itemsize}, where N is
|
|
the ``length'' of the object. The value of N is typically stored in
|
|
the instance's \member{ob_size} field. There are exceptions: for
|
|
example, long ints use a negative \member{ob_size} to indicate a
|
|
negative number, and N is \code{abs(\member{ob_size})} there. Also,
|
|
the presence of an \member{ob_size} field in the instance layout
|
|
doesn't mean that the instance structure is variable-length (for
|
|
example, the structure for the list type has fixed-length instances,
|
|
yet those instances have a meaningful \member{ob_size} field).
|
|
|
|
The basic size includes the fields in the instance declared by the
|
|
macro \csimplemacro{PyObject_HEAD} or
|
|
\csimplemacro{PyObject_VAR_HEAD} (whichever is used to declare the
|
|
instance struct) and this in turn includes the \member{_ob_prev} and
|
|
\member{_ob_next} fields if they are present. This means that the
|
|
only correct way to get an initializer for the \member{tp_basicsize}
|
|
is to use the \keyword{sizeof} operator on the struct used to
|
|
declare the instance layout. The basic size does not include the GC
|
|
header size (this is new in Python 2.2; in 2.1 and 2.0, the GC
|
|
header size was included in \member{tp_basicsize}).
|
|
|
|
These fields are inherited separately by subtypes. If the base type
|
|
has a non-zero \member{tp_itemsize}, it is generally not safe to set
|
|
\member{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
|
|
\member{tp_basicsize}. Example: suppose a type implements an array
|
|
of \code{double}. \member{tp_itemsize} is \code{sizeof(double)}.
|
|
It is the programmer's responsibility that \member{tp_basicsize} is
|
|
a multiple of \code{sizeof(double)} (assuming this is the alignment
|
|
requirement for \code{double}).
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{destructor}{tp_dealloc}
|
|
A pointer to the instance destructor function. This function must
|
|
be defined unless the type guarantees that its instances will never
|
|
be deallocated (as is the case for the singletons \code{None} and
|
|
\code{Ellipsis}).
|
|
|
|
The destructor function is called by the \cfunction{Py_DECREF()} and
|
|
\cfunction{Py_XDECREF()} macros when the new reference count is
|
|
zero. At this point, the instance is still in existence, but there
|
|
are no references to it. The destructor function should free all
|
|
references which the instance owns, free all memory buffers owned by
|
|
the instance (using the freeing function corresponding to the
|
|
allocation function used to allocate the buffer), and finally (as
|
|
its last action) call the type's \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}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{printfunc}{tp_print}
|
|
An optional pointer to the instance print function.
|
|
|
|
The print function is only called when the instance is printed to a
|
|
\emph{real} file; when it is printed to a pseudo-file (like a
|
|
\class{StringIO} instance), the instance's \member{tp_repr} or
|
|
\member{tp_str} function is called to convert it to a string. These
|
|
are also called when the type's \member{tp_print} field is \NULL. A
|
|
type should never implement \member{tp_print} in a way that produces
|
|
different output than \member{tp_repr} or \member{tp_str} would.
|
|
|
|
The print function is called with the same signature as
|
|
\cfunction{PyObject_Print()}: \code{int tp_print(PyObject *self, FILE
|
|
*file, int flags)}. The \var{self} argument is the instance to be
|
|
printed. The \var{file} argument is the stdio file to which it is
|
|
to be printed. The \var{flags} argument is composed of flag bits.
|
|
The only flag bit currently defined is \constant{Py_PRINT_RAW}.
|
|
When the \constant{Py_PRINT_RAW} flag bit is set, the instance
|
|
should be printed the same way as \member{tp_str} would format it;
|
|
when the \constant{Py_PRINT_RAW} flag bit is clear, the instance
|
|
should be printed the same was as \member{tp_repr} would format it.
|
|
It should return \code{-1} and set an exception condition when an
|
|
error occurred during the comparison.
|
|
|
|
It is possible that the \member{tp_print} field will be deprecated.
|
|
In any case, it is recommended not to define \member{tp_print}, but
|
|
instead to rely on \member{tp_repr} and \member{tp_str} for
|
|
printing.
|
|
|
|
This field is inherited by subtypes.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{getattrfunc}{tp_getattr}
|
|
An optional pointer to the get-attribute-string function.
|
|
|
|
This field is deprecated. When it is defined, it should point to a
|
|
function that acts the same as the \member{tp_getattro} function,
|
|
but taking a C string instead of a Python string object to give the
|
|
attribute name. The signature is the same as for
|
|
\cfunction{PyObject_GetAttrString()}.
|
|
|
|
This field is inherited by subtypes together with
|
|
\member{tp_getattro}: a subtype inherits both \member{tp_getattr}
|
|
and \member{tp_getattro} from its base type when the subtype's
|
|
\member{tp_getattr} and \member{tp_getattro} are both \NULL.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{setattrfunc}{tp_setattr}
|
|
An optional pointer to the set-attribute-string function.
|
|
|
|
This field is deprecated. When it is defined, it should point to a
|
|
function that acts the same as the \member{tp_setattro} function,
|
|
but taking a C string instead of a Python string object to give the
|
|
attribute name. The signature is the same as for
|
|
\cfunction{PyObject_SetAttrString()}.
|
|
|
|
This field is inherited by subtypes together with
|
|
\member{tp_setattro}: a subtype inherits both \member{tp_setattr}
|
|
and \member{tp_setattro} from its base type when the subtype's
|
|
\member{tp_setattr} and \member{tp_setattro} are both \NULL.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{cmpfunc}{tp_compare}
|
|
An optional pointer to the three-way comparison function.
|
|
|
|
The signature is the same as for \cfunction{PyObject_Compare()}.
|
|
The function should return \code{1} if \var{self} greater than
|
|
\var{other}, \code{0} if \var{self} is equal to \var{other}, and
|
|
\code{-1} if \var{self} less than \var{other}. It should return
|
|
\code{-1} and set an exception condition when an error occurred
|
|
during the comparison.
|
|
|
|
This field is inherited by subtypes together with
|
|
\member{tp_richcompare} and \member{tp_hash}: a subtypes inherits
|
|
all three of \member{tp_compare}, \member{tp_richcompare}, and
|
|
\member{tp_hash} when the subtype's \member{tp_compare},
|
|
\member{tp_richcompare}, and \member{tp_hash} are all \NULL.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{reprfunc}{tp_repr}
|
|
An optional pointer to a function that implements the built-in
|
|
function \function{repr()}.\bifuncindex{repr}
|
|
|
|
The signature is the same as for \cfunction{PyObject_Repr()}; it
|
|
must return a string or a Unicode object. Ideally, this function
|
|
should return a string that, when passed to \function{eval()}, given
|
|
a suitable environment, returns an object with the same value. If
|
|
this is not feasible, it should return a string starting with
|
|
\character{\textless} and ending with \character{\textgreater} 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 \samp{<\%s object
|
|
at \%p>} is returned, where \code{\%s} is replaced by the type name,
|
|
and \code{\%p} by the object's memory address.
|
|
|
|
This field is inherited by subtypes.
|
|
\end{cmemberdesc}
|
|
|
|
PyNumberMethods *tp_as_number;
|
|
|
|
XXX
|
|
|
|
PySequenceMethods *tp_as_sequence;
|
|
|
|
XXX
|
|
|
|
PyMappingMethods *tp_as_mapping;
|
|
|
|
XXX
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{hashfunc}{tp_hash}
|
|
An optional pointer to a function that implements the built-in
|
|
function \function{hash()}.\bifuncindex{hash}
|
|
|
|
The signature is the same as for \cfunction{PyObject_Hash()}; it
|
|
must return a C long. The value \code{-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
|
|
\code{-1}.
|
|
|
|
When this field is not set, two possibilities exist: if the
|
|
\member{tp_compare} and \member{tp_richcompare} fields are both
|
|
\NULL, a default hash value based on the object's address is
|
|
returned; otherwise, a \exception{TypeError} is raised.
|
|
|
|
This field is inherited by subtypes together with
|
|
\member{tp_richcompare} and \member{tp_compare}: a subtypes inherits
|
|
all three of \member{tp_compare}, \member{tp_richcompare}, and
|
|
\member{tp_hash}, when the subtype's \member{tp_compare},
|
|
\member{tp_richcompare} and \member{tp_hash} are all \NULL.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{ternaryfunc}{tp_call}
|
|
An optional pointer to a function that implements calling the
|
|
object. This should be \NULL{} if the object is not callable. The
|
|
signature is the same as for \cfunction{PyObject_Call()}.
|
|
|
|
This field is inherited by subtypes.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{reprfunc}{tp_str}
|
|
An optional pointer to a function that implements the built-in
|
|
operation \function{str()}. (Note that \class{str} is a type now,
|
|
and \function{str()} calls the constructor for that type. This
|
|
constructor calls \cfunction{PyObject_Str()} to do the actual work,
|
|
and \cfunction{PyObject_Str()} will call this handler.)
|
|
|
|
The signature is the same as for \cfunction{PyObject_Str()}; it must
|
|
return a string or a Unicode object. This function should return a
|
|
``friendly'' string representation of the object, as this is the
|
|
representation that will be used by the print statement.
|
|
|
|
When this field is not set, \cfunction{PyObject_Repr()} is called to
|
|
return a string representation.
|
|
|
|
This field is inherited by subtypes.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{getattrofunc}{tp_getattro}
|
|
An optional pointer to the get-attribute function.
|
|
|
|
The signature is the same as for \cfunction{PyObject_GetAttr()}. It
|
|
is usually convenient to set this field to
|
|
\cfunction{PyObject_GenericGetAttr()}, which implements the normal
|
|
way of looking for object attributes.
|
|
|
|
This field is inherited by subtypes together with
|
|
\member{tp_getattr}: a subtype inherits both \member{tp_getattr} and
|
|
\member{tp_getattro} from its base type when the subtype's
|
|
\member{tp_getattr} and \member{tp_getattro} are both \NULL.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{setattrofunc}{tp_setattro}
|
|
An optional pointer to the set-attribute function.
|
|
|
|
The signature is the same as for \cfunction{PyObject_SetAttr()}. It
|
|
is usually convenient to set this field to
|
|
\cfunction{PyObject_GenericSetAttr()}, which implements the normal
|
|
way of setting object attributes.
|
|
|
|
This field is inherited by subtypes together with
|
|
\member{tp_setattr}: a subtype inherits both \member{tp_setattr} and
|
|
\member{tp_setattro} from its base type when the subtype's
|
|
\member{tp_setattr} and \member{tp_setattro} are both \NULL.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{PyBufferProcs*}{tp_as_buffer}
|
|
Pointer to an additional structure that contains fields relevant only to
|
|
objects which implement the buffer interface. These fields are
|
|
documented in ``Buffer Object Structures'' (section
|
|
\ref{buffer-structs}).
|
|
|
|
The \member{tp_as_buffer} field is not inherited, but the contained
|
|
fields are inherited individually.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{long}{tp_flags}
|
|
This field is a bit mask of various flags. Some flags indicate
|
|
variant semantics for certain situations; others are used to
|
|
indicate that certain fields in the type object (or in the extension
|
|
structures referenced via \member{tp_as_number},
|
|
\member{tp_as_sequence}, \member{tp_as_mapping}, and
|
|
\member{tp_as_buffer}) that were historically not always present are
|
|
valid; if such a flag bit is clear, the type fields it guards must
|
|
not be accessed and must be considered to have a zero or \NULL{}
|
|
value instead.
|
|
|
|
Inheritance of this field is complicated. Most flag bits are
|
|
inherited individually, i.e. if the base type has a flag bit set,
|
|
the subtype inherits this flag bit. The flag bits that pertain to
|
|
extension structures are strictly inherited if the extension
|
|
structure is inherited, i.e. the base type's value of the flag bit
|
|
is copied into the subtype together with a pointer to the extension
|
|
structure. The \constant{Py_TPFLAGS_HAVE_GC} flag bit is inherited
|
|
together with the \member{tp_traverse} and \member{tp_clear} fields,
|
|
i.e. if the \constant{Py_TPFLAGS_HAVE_GC} flag bit is clear in the
|
|
subtype and the \member{tp_traverse} and \member{tp_clear} fields in
|
|
the subtype exist (as indicated by the
|
|
\constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit) and have \NULL{}
|
|
values.
|
|
|
|
The following bit masks are currently defined; these can be or-ed
|
|
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 non-zero.
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
|
|
If this bit is set, the \ctype{PyBufferProcs} struct referenced by
|
|
\member{tp_as_buffer} has the \member{bf_getcharbuffer} field.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_HAVE_SEQUENCE_IN}
|
|
If this bit is set, the \ctype{PySequenceMethods} struct
|
|
referenced by \member{tp_as_sequence} has the \member{sq_contains}
|
|
field.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_GC}
|
|
This bit is obsolete. The bit it used to name is no longer in
|
|
use. The symbol is now defined as zero.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_HAVE_INPLACEOPS}
|
|
If this bit is set, the \ctype{PySequenceMethods} struct
|
|
referenced by \member{tp_as_sequence} and the
|
|
\ctype{PyNumberMethods} structure referenced by
|
|
\member{tp_as_number} contain the fields for in-place operators.
|
|
In particular, this means that the \ctype{PyNumberMethods}
|
|
structure has the fields \member{nb_inplace_add},
|
|
\member{nb_inplace_subtract}, \member{nb_inplace_multiply},
|
|
\member{nb_inplace_divide}, \member{nb_inplace_remainder},
|
|
\member{nb_inplace_power}, \member{nb_inplace_lshift},
|
|
\member{nb_inplace_rshift}, \member{nb_inplace_and},
|
|
\member{nb_inplace_xor}, and \member{nb_inplace_or}; and the
|
|
\ctype{PySequenceMethods} struct has the fields
|
|
\member{sq_inplace_concat} and \member{sq_inplace_repeat}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_CHECKTYPES}
|
|
If this bit is set, the binary and ternary operations in the
|
|
\ctype{PyNumberMethods} structure referenced by
|
|
\member{tp_as_number} accept arguments of arbitrary object types,
|
|
and do their own type conversions if needed. If this bit is
|
|
clear, those operations require that all arguments have the
|
|
current type as their type, and the caller is supposed to perform
|
|
a coercion operation first. This applies to \member{nb_add},
|
|
\member{nb_subtract}, \member{nb_multiply}, \member{nb_divide},
|
|
\member{nb_remainder}, \member{nb_divmod}, \member{nb_power},
|
|
\member{nb_lshift}, \member{nb_rshift}, \member{nb_and},
|
|
\member{nb_xor}, and \member{nb_or}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_HAVE_RICHCOMPARE}
|
|
If this bit is set, the type object has the
|
|
\member{tp_richcompare} field, as well as the \member{tp_traverse}
|
|
and the \member{tp_clear} fields.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_HAVE_WEAKREFS}
|
|
If this bit is set, the \member{tp_weaklistoffset} field is
|
|
defined. Instances of a type are weakly referenceable if the
|
|
type's \member{tp_weaklistoffset} field has a value greater than
|
|
zero.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_HAVE_ITER}
|
|
If this bit is set, the type object has the \member{tp_iter} and
|
|
\member{tp_iternext} fields.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_HAVE_CLASS}
|
|
If this bit is set, the type object has several new fields defined
|
|
starting in Python 2.2: \member{tp_methods}, \member{tp_members},
|
|
\member{tp_getset}, \member{tp_base}, \member{tp_dict},
|
|
\member{tp_descr_get}, \member{tp_descr_set},
|
|
\member{tp_dictoffset}, \member{tp_init}, \member{tp_alloc},
|
|
\member{tp_new}, \member{tp_free}, \member{tp_is_gc},
|
|
\member{tp_bases}, \member{tp_mro}, \member{tp_cache},
|
|
\member{tp_subclasses}, and \member{tp_weaklist}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_HEAPTYPE}
|
|
This bit is set when the type object itself is allocated on the
|
|
heap. In this case, the \member{ob_type} field of its instances
|
|
is considered a reference to the type, and the type object is
|
|
INCREF'ed when a new instance is created, and DECREF'ed when an
|
|
instance is destroyed (this does not apply to instances of
|
|
subtypes; only the type referenced by the instance's ob_type gets
|
|
INCREF'ed or DECREF'ed).
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_BASETYPE}
|
|
This bit is set when the type can be used as the base type of
|
|
another type. If this bit is clear, the type cannot be subtyped
|
|
(similar to a "final" class in Java).
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_READY}
|
|
This bit is set when the type object has been fully initialized by
|
|
\cfunction{PyType_Ready()}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_READYING}
|
|
This bit is set while \cfunction{PyType_Ready()} is in the process
|
|
of initializing the type object.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_HAVE_GC}
|
|
This bit is set when the object supports garbage collection. If
|
|
this bit is set, instances must be created using
|
|
\cfunction{PyObject_GC_New()} and destroyed using
|
|
\cfunction{PyObject_GC_Del()}. More information in section XXX
|
|
about garbage collection. This bit also implies that the
|
|
GC-related fields \member{tp_traverse} and \member{tp_clear} are
|
|
present in the type object; but those fields also exist when
|
|
\constant{Py_TPFLAGS_HAVE_GC} is clear but
|
|
\constant{Py_TPFLAGS_HAVE_RICHCOMPARE} is set.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_DEFAULT}
|
|
This is a bitmask of all the bits that pertain to the existence of
|
|
certain fields in the type object and its extension structures.
|
|
Currently, it includes the following bits:
|
|
\constant{Py_TPFLAGS_HAVE_GETCHARBUFFER},
|
|
\constant{Py_TPFLAGS_HAVE_SEQUENCE_IN},
|
|
\constant{Py_TPFLAGS_HAVE_INPLACEOPS},
|
|
\constant{Py_TPFLAGS_HAVE_RICHCOMPARE},
|
|
\constant{Py_TPFLAGS_HAVE_WEAKREFS},
|
|
\constant{Py_TPFLAGS_HAVE_ITER}, and
|
|
\constant{Py_TPFLAGS_HAVE_CLASS}.
|
|
\end{datadesc}
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{char*}{tp_doc}
|
|
An optional pointer to a NUL-terminated C string giving the
|
|
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}
|
|
|
|
The following three fields only exist if the
|
|
\constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit is set.
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{traverseproc}{tp_traverse}
|
|
An optional pointer to a traversal function for the garbage
|
|
collector. This is only used if the \constant{Py_TPFLAGS_HAVE_GC}
|
|
flag bit is set. More information in section
|
|
\ref{supporting-cycle-detection} about garbage collection.
|
|
|
|
This field is inherited by subtypes together with \member{tp_clear}
|
|
and the \constant{Py_TPFLAGS_HAVE_GC} flag bit: the flag bit,
|
|
\member{tp_traverse}, and \member{tp_clear} are all inherited from
|
|
the base type if they are all zero in the subtype \emph{and} the
|
|
subtype has the \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit set.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{inquiry}{tp_clear}
|
|
An optional pointer to a clear function for the garbage collector.
|
|
This is only used if the \constant{Py_TPFLAGS_HAVE_GC} flag bit is
|
|
set. More information in section
|
|
\ref{supporting-cycle-detection} about garbage collection.
|
|
|
|
This field is inherited by subtypes together with \member{tp_clear}
|
|
and the \constant{Py_TPFLAGS_HAVE_GC} flag bit: the flag bit,
|
|
\member{tp_traverse}, and \member{tp_clear} are all inherited from
|
|
the base type if they are all zero in the subtype \emph{and} the
|
|
subtype has the \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit set.
|
|
\end{cmemberdesc}
|
|
|
|
\begin{cmemberdesc}{PyTypeObject}{richcmpfunc}{tp_richcompare}
|
|
An optional pointer to the rich comparison function.
|
|
|
|
The signature is the same as for \cfunction{PyObject_RichCompare()}.
|
|
The function should return \code{1} if the requested comparison
|
|
returns true, \code{0} if it returns false. It should return
|
|
\code{-1} and set an exception condition when an error occurred
|
|
during the comparison.
|
|
|
|
This field is inherited by subtypes together with
|
|
\member{tp_compare} and \member{tp_hash}: a subtype inherits all
|
|
three of \member{tp_compare}, \member{tp_richcompare}, and
|
|
\member{tp_hash}, when the subtype's \member{tp_compare},
|
|
\member{tp_richcompare}, and \member{tp_hash} are all \NULL.
|
|
|
|
The following constants are defined to be used as the third argument
|
|
for \member{tp_richcompare} and for \cfunction{PyObject_RichCompare()}:
|
|
|
|
\begin{tableii}{l|c}{constant}{Constant}{Comparison}
|
|
\lineii{Py_LT}{\code{<}}
|
|
\lineii{Py_LE}{\code{<=}}
|
|
\lineii{Py_EQ}{\code{==}}
|
|
\lineii{Py_NE}{\code{!=}}
|
|
\lineii{Py_GT}{\code{>}}
|
|
\lineii{Py_GE}{\code{>=}}
|
|
\end{tableii}
|
|
\end{cmemberdesc}
|
|
|
|
The next field only exists if the \constant{Py_TPFLAGS_HAVE_WEAKREFS}
|
|
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}
|
|
|
|
The next two fields only exist if the
|
|
\constant{Py_TPFLAGS_HAVE_CLASS} flag bit is set.
|
|
|
|
\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()}.
|
|
|
|
This field is inherited by subtypes.
|
|
\end{cmemberdesc}
|
|
|
|
\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).
|
|
|
|
Iterator types should also define the \member{tp_iter} function, and
|
|
that function should return the iterator instance itself (not a new
|
|
iterator instance).
|
|
|
|
This function has the same signature as \cfunction{PyIter_Next()}.
|
|
|
|
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.
|
|
|
|
|
|
The function signature is
|
|
|
|
\begin{verbatim}
|
|
PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
|
|
\end{verbatim}
|
|
|
|
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.
|
|
|
|
The function signature is
|
|
|
|
\begin{verbatim}
|
|
int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
|
|
\end{verbatim}
|
|
|
|
This field is inherited by subtypes.
|
|
|
|
XXX blah, blah.
|
|
|
|
\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 \emph{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}
|
|
int 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}
|
|
PyObject *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}
|
|
PyObject *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 completeness. 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}
|
|
|
|
Also, note that, in a garbage collected Python, tp_dealloc may be
|
|
called from any Python thread, not just the thread which created the
|
|
object (if the object becomes part of a refcount cycle, that cycle
|
|
might be collected by a garbage collection on any thread). This is
|
|
not a problem for Python API calls, since the thread on which
|
|
tp_dealloc is called will own the Global Interpreter Lock (GIL).
|
|
However, if the object being destroyed in turn destroys objects from
|
|
some other C or \Cpp{} library, care should be taken to ensure that
|
|
destroying those objects on the thread which called tp_dealloc will
|
|
not violate any assumptions of the library.
|
|
|
|
\section{Mapping Object Structures \label{mapping-structs}}
|
|
|
|
\begin{ctypedesc}{PyMappingMethods}
|
|
Structure used to hold pointers to the functions used to implement
|
|
the mapping protocol for an extension type.
|
|
\end{ctypedesc}
|
|
|
|
|
|
\section{Number Object Structures \label{number-structs}}
|
|
|
|
\begin{ctypedesc}{PyNumberMethods}
|
|
Structure used to hold pointers to the functions an extension type
|
|
uses to implement the number protocol.
|
|
\end{ctypedesc}
|
|
|
|
|
|
\section{Sequence Object Structures \label{sequence-structs}}
|
|
|
|
\begin{ctypedesc}{PySequenceMethods}
|
|
Structure used to hold pointers to the functions which an object
|
|
uses to implement the sequence protocol.
|
|
\end{ctypedesc}
|
|
|
|
|
|
\section{Buffer Object Structures \label{buffer-structs}}
|
|
\sectionauthor{Greg J. Stein}{greg@lyra.org}
|
|
|
|
The buffer interface exports a model where an object can expose its
|
|
internal data as a set of chunks of data, where each chunk is
|
|
specified as a pointer/length pair. These chunks are called
|
|
\dfn{segments} and are presumed to be non-contiguous in memory.
|
|
|
|
If an object does not export the buffer interface, then its
|
|
\member{tp_as_buffer} member in the \ctype{PyTypeObject} structure
|
|
should be \NULL. Otherwise, the \member{tp_as_buffer} will point to
|
|
a \ctype{PyBufferProcs} structure.
|
|
|
|
\note{It is very important that your \ctype{PyTypeObject} structure
|
|
uses \constant{Py_TPFLAGS_DEFAULT} for the value of the
|
|
\member{tp_flags} member rather than \code{0}. This tells the Python
|
|
runtime that your \ctype{PyBufferProcs} structure contains the
|
|
\member{bf_getcharbuffer} slot. Older versions of Python did not have
|
|
this member, so a new Python interpreter using an old extension needs
|
|
to be able to test for its presence before using it.}
|
|
|
|
\begin{ctypedesc}{PyBufferProcs}
|
|
Structure used to hold the function pointers which define an
|
|
implementation of the buffer protocol.
|
|
|
|
The first slot is \member{bf_getreadbuffer}, of type
|
|
\ctype{getreadbufferproc}. If this slot is \NULL, then the object
|
|
does not support reading from the internal data. This is
|
|
non-sensical, so implementors should fill this in, but callers
|
|
should test that the slot contains a non-\NULL{} value.
|
|
|
|
The next slot is \member{bf_getwritebuffer} having type
|
|
\ctype{getwritebufferproc}. This slot may be \NULL{} if the object
|
|
does not allow writing into its returned buffers.
|
|
|
|
The third slot is \member{bf_getsegcount}, with type
|
|
\ctype{getsegcountproc}. This slot must not be \NULL{} and is used
|
|
to inform the caller how many segments the object contains. Simple
|
|
objects such as \ctype{PyString_Type} and \ctype{PyBuffer_Type}
|
|
objects contain a single segment.
|
|
|
|
The last slot is \member{bf_getcharbuffer}, of type
|
|
\ctype{getcharbufferproc}. This slot will only be present if the
|
|
\constant{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the
|
|
\member{tp_flags} field of the object's \ctype{PyTypeObject}.
|
|
Before using this slot, the caller should test whether it is present
|
|
by using the
|
|
\cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()}
|
|
function. If present, it may be \NULL, indicating that the object's
|
|
contents cannot be used as \emph{8-bit characters}.
|
|
The slot function may also raise an error if the object's contents
|
|
cannot be interpreted as 8-bit characters. For example, if the
|
|
object is an array which is configured to hold floating point
|
|
values, an exception may be raised if a caller attempts to use
|
|
\member{bf_getcharbuffer} to fetch a sequence of 8-bit characters.
|
|
This notion of exporting the internal buffers as ``text'' is used to
|
|
distinguish between objects that are binary in nature, and those
|
|
which have character-based content.
|
|
|
|
\note{The current policy seems to state that these characters
|
|
may be multi-byte characters. This implies that a buffer size of
|
|
\var{N} does not mean there are \var{N} characters present.}
|
|
\end{ctypedesc}
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
|
|
Flag bit set in the type structure to indicate that the
|
|
\member{bf_getcharbuffer} slot is known. This being set does not
|
|
indicate that the object supports the buffer interface or that the
|
|
\member{bf_getcharbuffer} slot is non-\NULL.
|
|
\end{datadesc}
|
|
|
|
\begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc)
|
|
(PyObject *self, int segment, void **ptrptr)}
|
|
Return a pointer to a readable segment of the buffer. This function
|
|
is allowed to raise an exception, in which case it must return
|
|
\code{-1}. The \var{segment} which is passed must be zero or
|
|
positive, and strictly less than the number of segments returned by
|
|
the \member{bf_getsegcount} slot function. On success, it returns
|
|
the length of the buffer memory, and sets \code{*\var{ptrptr}} to a
|
|
pointer to that memory.
|
|
\end{ctypedesc}
|
|
|
|
\begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc)
|
|
(PyObject *self, int segment, void **ptrptr)}
|
|
Return a pointer to a writable memory buffer in
|
|
\code{*\var{ptrptr}}, and the length of that segment as the function
|
|
return value. The memory buffer must correspond to buffer segment
|
|
\var{segment}. Must return \code{-1} and set an exception on
|
|
error. \exception{TypeError} should be raised if the object only
|
|
supports read-only buffers, and \exception{SystemError} should be
|
|
raised when \var{segment} specifies a segment that doesn't exist.
|
|
% Why doesn't it raise ValueError for this one?
|
|
% GJS: because you shouldn't be calling it with an invalid
|
|
% segment. That indicates a blatant programming error in the C
|
|
% code.
|
|
\end{ctypedesc}
|
|
|
|
\begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc)
|
|
(PyObject *self, int *lenp)}
|
|
Return the number of memory segments which comprise the buffer. If
|
|
\var{lenp} is not \NULL, the implementation must report the sum of
|
|
the sizes (in bytes) of all segments in \code{*\var{lenp}}.
|
|
The function cannot fail.
|
|
\end{ctypedesc}
|
|
|
|
\begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc)
|
|
(PyObject *self, int segment, const char **ptrptr)}
|
|
Return the size of the memory buffer in \var{ptrptr} for segment
|
|
\var{segment}. \code{*\var{ptrptr}} is set to the memory buffer.
|
|
\end{ctypedesc}
|
|
|
|
|
|
\section{Supporting the Iterator Protocol
|
|
\label{supporting-iteration}}
|
|
|
|
|
|
\section{Supporting Cyclic Garbage Collection
|
|
\label{supporting-cycle-detection}}
|
|
|
|
Python's support for detecting and collecting garbage which involves
|
|
circular references requires support from object types which are
|
|
``containers'' for other objects which may also be containers. Types
|
|
which do not store references to other objects, or which only store
|
|
references to atomic types (such as numbers or strings), do not need
|
|
to provide any explicit support for garbage collection.
|
|
|
|
An example showing the use of these interfaces can be found in
|
|
``\ulink{Supporting the Cycle
|
|
Collector}{../ext/example-cycle-support.html}'' in
|
|
\citetitle[../ext/ext.html]{Extending and Embedding the Python
|
|
Interpreter}.
|
|
|
|
To create a container type, the \member{tp_flags} field of the type
|
|
object must include the \constant{Py_TPFLAGS_HAVE_GC} and provide an
|
|
implementation of the \member{tp_traverse} handler. If instances of the
|
|
type are mutable, a \member{tp_clear} implementation must also be
|
|
provided.
|
|
|
|
\begin{datadesc}{Py_TPFLAGS_HAVE_GC}
|
|
Objects with a type with this flag set must conform with the rules
|
|
documented here. For convenience these objects will be referred to
|
|
as container objects.
|
|
\end{datadesc}
|
|
|
|
Constructors for container types must conform to two rules:
|
|
|
|
\begin{enumerate}
|
|
\item The memory for the object must be allocated using
|
|
\cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}.
|
|
|
|
\item Once all the fields which may contain references to other
|
|
containers are initialized, it must call
|
|
\cfunction{PyObject_GC_Track()}.
|
|
\end{enumerate}
|
|
|
|
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_New}{TYPE, PyTypeObject *type}
|
|
Analogous to \cfunction{PyObject_New()} but for container objects with
|
|
the \constant{Py_TPFLAGS_HAVE_GC} flag set.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_NewVar}{TYPE, PyTypeObject *type,
|
|
int size}
|
|
Analogous to \cfunction{PyObject_NewVar()} but for container objects
|
|
with the \constant{Py_TPFLAGS_HAVE_GC} flag set.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{PyVarObject *}{PyObject_GC_Resize}{PyVarObject *op, int}
|
|
Resize an object allocated by \cfunction{PyObject_NewVar()}. Returns
|
|
the resized object or \NULL{} on failure.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyObject_GC_Track}{PyObject *op}
|
|
Adds the object \var{op} to the set of container objects tracked by
|
|
the collector. The collector can run at unexpected times so objects
|
|
must be valid while being tracked. This should be called once all
|
|
the fields followed by the \member{tp_traverse} handler become valid,
|
|
usually near the end of the constructor.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{_PyObject_GC_TRACK}{PyObject *op}
|
|
A macro version of \cfunction{PyObject_GC_Track()}. It should not be
|
|
used for extension modules.
|
|
\end{cfuncdesc}
|
|
|
|
Similarly, the deallocator for the object must conform to a similar
|
|
pair of rules:
|
|
|
|
\begin{enumerate}
|
|
\item Before fields which refer to other containers are invalidated,
|
|
\cfunction{PyObject_GC_UnTrack()} must be called.
|
|
|
|
\item The object's memory must be deallocated using
|
|
\cfunction{PyObject_GC_Del()}.
|
|
\end{enumerate}
|
|
|
|
\begin{cfuncdesc}{void}{PyObject_GC_Del}{PyObject *op}
|
|
Releases memory allocated to an object using
|
|
\cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_NewVar()}.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{PyObject_GC_UnTrack}{PyObject *op}
|
|
Remove the object \var{op} from the set of container objects tracked
|
|
by the collector. Note that \cfunction{PyObject_GC_Track()} can be
|
|
called again on this object to add it back to the set of tracked
|
|
objects. The deallocator (\member{tp_dealloc} handler) should call
|
|
this for the object before any of the fields used by the
|
|
\member{tp_traverse} handler become invalid.
|
|
\end{cfuncdesc}
|
|
|
|
\begin{cfuncdesc}{void}{_PyObject_GC_UNTRACK}{PyObject *op}
|
|
A macro version of \cfunction{PyObject_GC_UnTrack()}. It should not be
|
|
used for extension modules.
|
|
\end{cfuncdesc}
|
|
|
|
The \member{tp_traverse} handler accepts a function parameter of this
|
|
type:
|
|
|
|
\begin{ctypedesc}[visitproc]{int (*visitproc)(PyObject *object, void *arg)}
|
|
Type of the visitor function passed to the \member{tp_traverse}
|
|
handler. The function should be called with an object to traverse
|
|
as \var{object} and the third parameter to the \member{tp_traverse}
|
|
handler as \var{arg}. The Python core uses several visitor functions
|
|
to implement cyclic garbage detection; it's not expected that users will
|
|
need to write their own visitor functions.
|
|
\end{ctypedesc}
|
|
|
|
The \member{tp_traverse} handler must have the following type:
|
|
|
|
\begin{ctypedesc}[traverseproc]{int (*traverseproc)(PyObject *self,
|
|
visitproc visit, void *arg)}
|
|
Traversal function for a container object. Implementations must
|
|
call the \var{visit} function for each object directly contained by
|
|
\var{self}, with the parameters to \var{visit} being the contained
|
|
object and the \var{arg} value passed to the handler. The \var{visit}
|
|
function must not be called with a \NULL{} object argument. If
|
|
\var{visit} returns a non-zero value
|
|
that value should be returned immediately.
|
|
\end{ctypedesc}
|
|
|
|
To simplify writing \member{tp_traverse} handlers, a
|
|
\cfunction{Py_VISIT()} macro is provided. In order to use this macro,
|
|
the \member{tp_traverse} implementation must name its arguments
|
|
exactly \var{visit} and \var{arg}:
|
|
|
|
\begin{cfuncdesc}{void}{Py_VISIT}{PyObject *o}
|
|
Call the \var{visit} callback, with arguments \var{o} and \var{arg}.
|
|
If \var{visit} returns a non-zero value, then return it. Using this
|
|
macro, \member{tp_traverse} handlers look like:
|
|
|
|
\begin{verbatim}
|
|
static int
|
|
my_traverse(Noddy *self, visitproc visit, void *arg)
|
|
{
|
|
Py_VISIT(self->foo);
|
|
Py_VISIT(self->bar);
|
|
return 0;
|
|
}
|
|
\end{verbatim}
|
|
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
The \member{tp_clear} handler must be of the \ctype{inquiry} type, or
|
|
\NULL{} if the object is immutable.
|
|
|
|
\begin{ctypedesc}[inquiry]{int (*inquiry)(PyObject *self)}
|
|
Drop references that may have created reference cycles. Immutable
|
|
objects do not have to define this method since they can never
|
|
directly create reference cycles. Note that the object must still
|
|
be valid after calling this method (don't just call
|
|
\cfunction{Py_DECREF()} on a reference). The collector will call
|
|
this method if it detects that this object is involved in a
|
|
reference cycle.
|
|
\end{ctypedesc}
|