traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Integrate a bunch of new text from Guido.

This commit is contained in:
Fred Drake 2002-04-12 22:47:18 +00:00
parent 56cdf11922
commit 4d2a95dfe7
1 changed files with 262 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

268
Doc/api/newtypes.tex
View File

@ -188,12 +188,6 @@ These macros are used in the definition of \ctype{PyObject} and
PyObject_HEAD_INIT
Typedefs:
unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
setattrofunc, cmpfunc, reprfunc, hashfunc
\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
@ -311,6 +305,268 @@ may be set for any given method.
\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,
though it does not actually need the the \member{ob_size} field. The
inclusion of this field is a historical accident that must be
maintained to ensure binary compatibility between new versions of
Python and older compiled extensions.
\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 will be
initialized to the \member{ob_type} field of the base class.
\cfunction{PyType_Ready()} will not change this field if it is
nonzero.
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 may be just the type
name, if the module name is explicitly stored in the type dict as
the value for key \code{'__module__'}.
If the tp_name field contains 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 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 byte 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 type is variable-length (for example, 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 by subtypes.
\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 existance, 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} slot. If the type
is not subtypable (doesn't have the \constant{Py_TPFLAGS_BASETYPE}
flag bit set), it is permissible to call the object deallocator
directly instead of via \member{tp_free}. The object deallocator
should be the one used to allocate the instance; this is normally
\cfunction{PyObject_Del()} if the instance was allocated using
\cfunction{PyObject_New()} or \cfunction{PyOject_VarNew()}, or
\cfunction{PyObject_GC_Del()} if the instance was allocated using
\cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}.
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.
The print function is called with the same signature as
\cfunction{PyObject_Print()}: \code{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 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}
\section{Mapping Object Structures \label{mapping-structs}}
\begin{ctypedesc}{PyMappingMethods}