| \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 it's 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. |
| |
| 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} |
| 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}. |
| \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. If |
| \var{visit} returns a non-zero value then an error has occurred and |
| that value should be returned immediately. |
| \end{ctypedesc} |
| |
| 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} |