Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 4d2a95d

Browse files
freddrakefreddrake
committed
Integrate a bunch of new text from Guido.
1 parent 56cdf11 commit 4d2a95d

1 file changed

Lines changed: 262 additions & 6 deletions

File tree

‎Doc/api/newtypes.tex‎

Lines changed: 262 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -188,12 +188,6 @@ \section{Common Object Structures \label{common-structs}}
188188

189189
PyObject_HEAD_INIT
190190

191-
Typedefs:
192-
unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
193-
intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
194-
destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
195-
setattrofunc, cmpfunc, reprfunc, hashfunc
196-
197191
\begin{ctypedesc}{PyCFunction}
198192
Type of the functions used to implement most Python callables in C.
199193
Functions of this type take two \ctype{PyObject*} parameters and
@@ -311,6 +305,268 @@ \section{Common Object Structures \label{common-structs}}
311305
\end{cfuncdesc}
312306

313307

308+
\section{Type Objects \label{type-structs}}
309+
310+
Perhaps one of the most important structures of the Python object
311+
system is the structure that defines a new type: the
312+
\ctype{PyTypeObject} structure. Type objects can be handled using any
313+
of the \cfunction{PyObject_*()} or \cfunction{PyType_*()} functions,
314+
but do not offer much that's interesting to most Python applications.
315+
These objects are fundamental to how objects behave, so they are very
316+
important to the interpreter itself and to any extension module that
317+
implements new types.
318+
319+
Type objects are fairly large compared to most of the standard types.
320+
The reason for the size is that each type object stores a large number
321+
of values, mostly C function pointers, each of which implements a
322+
small part of the type's functionality. The fields of the type object
323+
are examined in detail in this section. The fields will be described
324+
in the order in which they occur in the structure.
325+
326+
Typedefs:
327+
unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
328+
intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
329+
destructor, freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc,
330+
setattrofunc, cmpfunc, reprfunc, hashfunc
331+
332+
The structure definition for \ctype{PyTypeObject} can be found in
333+
\file{Include/object.h}. For convenience of reference, this repeats
334+
the definition found there:
335+
336+
\verbatiminput{typestruct.h}
337+
338+
The type object structure extends the \ctype{PyVarObject} structure,
339+
though it does not actually need the the \member{ob_size} field. The
340+
inclusion of this field is a historical accident that must be
341+
maintained to ensure binary compatibility between new versions of
342+
Python and older compiled extensions.
343+
344+
\begin{cmemberdesc}{PyObject}{PyObject*}{_ob_next}
345+
\cmemberline{PyObject}{PyObject*}{_ob_prev}
346+
These fields are only present when the macro \code{Py_TRACE_REFS} is
347+
defined. Their initialization to \NULL{} is taken care of by the
348+
\code{PyObject_HEAD_INIT} macro. For statically allocated objects,
349+
these fields always remain \NULL. For dynamically allocated
350+
objects, these two fields are used to link the object into a
351+
doubly-linked list of \emph{all} live objects on the heap. This
352+
could be used for various debugging purposes; currently the only use
353+
is to print the objects that are still alive at the end of a run
354+
when the environment variable \envvar{PYTHONDUMPREFS} is set.
355+
356+
These fields are not inherited by subtypes.
357+
\end{cmemberdesc}
358+
359+
\begin{cmemberdesc}{PyObject}{int}{ob_refcnt}
360+
This is the type object's reference count, initialized to \code{1}
361+
by the \code{PyObject_HEAD_INIT} macro. Note that for statically
362+
allocated type objects, the type's instances (objects whose
363+
\member{ob_type} points back to the type) do \emph{not} count as
364+
references. But for dynamically allocated type objects, the
365+
instances \emph{do} count as references.
366+
367+
This field is not inherited by subtypes.
368+
\end{cmemberdesc}
369+
370+
\begin{cmemberdesc}{PyObject}{PyTypeObject*}{ob_type}
371+
This is the type's type, in other words its metatype. It is
372+
initialized by the argument to the \code{PyObject_HEAD_INIT} macro,
373+
and its value should normally be \code{\&PyType_Type}. However, for
374+
dynamically loadable extension modules that must be usable on
375+
Windows (at least), the compiler complains that this is not a valid
376+
initializer. Therefore, the convention is to pass \NULL{} to the
377+
\code{PyObject_HEAD_INIT} macro and to initialize this field
378+
explicitly at the start of the module's initialization function,
379+
before doing anything else. This is typically done like this:
380+
381+
\begin{verbatim}
382+
Foo_Type.ob_type = &PyType_Type;
383+
\end{verbatim}
384+
385+
This should be done before any instances of the type are created.
386+
\cfunction{PyType_Ready()} checks if \member{ob_type} is \NULL, and
387+
if so, initializes it: in Python 2.2, it is set to
388+
\code{\&PyType_Type}; in Python 2.2.1 and later it will be
389+
initialized to the \member{ob_type} field of the base class.
390+
\cfunction{PyType_Ready()} will not change this field if it is
391+
nonzero.
392+
393+
In Python 2.2, this field is not inherited by subtypes. In 2.2.1,
394+
and in 2.3 and beyond, it is inherited by subtypes.
395+
\end{cmemberdesc}
396+
397+
\begin{cmemberdesc}{PyVarObject}{int}{ob_size}
398+
For statically allocated type objects, this should be initialized
399+
to zero. For dynamically allocated type objects, this field has a
400+
special internal meaning.
401+
402+
This field is not inherited by subtypes.
403+
\end{cmemberdesc}
404+
405+
\begin{cmemberdesc}{PyTypeObject}{char*}{tp_name}
406+
Pointer to a NUL-terminated string containing the name of the type.
407+
For types that are accessible as module globals, the string should
408+
be the full module name, followed by a dot, followed by the type
409+
name; for built-in types, it should be just the type name. If the
410+
module is a submodule of a package, the full package name is part of
411+
the full module name. For example, a type named \class{T} defined
412+
in module \module{M} in subpackage \module{Q} in package \module{P}
413+
should have the \member{tp_name} initializer \code{"P.Q.M.T"}.
414+
415+
For dynamically allocated type objects, this may be just the type
416+
name, if the module name is explicitly stored in the type dict as
417+
the value for key \code{'__module__'}.
418+
419+
If the tp_name field contains a dot, everything before the last dot
420+
is made accessible as the \member{__module__} attribute, and
421+
everything after the last dot is made accessible as the
422+
\member{__name__} attribute. If no dot is present, the entire
423+
\member{tp_name} field is made accessible as the \member{__name__}
424+
attribute, and the \member{__module__} attribute is undefined
425+
(unless explicitly set in the dictionary, as explained above).
426+
427+
This field is not inherited by subtypes.
428+
\end{cmemberdesc}
429+
430+
\begin{cmemberdesc}{PyTypeObject}{int}{tp_basicsize}
431+
\cmemberline{PyTypeObject}{int}{tp_itemsize}
432+
These fields allow calculating the size in byte of instances of
433+
the type.
434+
435+
There are two kinds of types: types with fixed-length instances have
436+
a zero \member{tp_itemsize} field, types with variable-length
437+
instances have a non-zero \member{tp_itemsize} field. For a type
438+
with fixed-length instances, all instances have the same size,
439+
given in \member{tp_basicsize}.
440+
441+
For a type with variable-length instances, the instances must have
442+
an \member{ob_size} field, and the instance size is
443+
\member{tp_basicsize} plus N times \member{tp_itemsize}, where N is
444+
the ``length'' of the object. The value of N is typically stored in
445+
the instance's \member{ob_size} field. There are exceptions: for
446+
example, long ints use a negative \member{ob_size} to indicate a
447+
negative number, and N is \code{abs(\member{ob_size})} there. Also,
448+
the presence of an \member{ob_size} field in the instance layout
449+
doesn't mean that the type is variable-length (for example, the list
450+
type has fixed-length instances, yet those instances have a
451+
meaningful \member{ob_size} field).
452+
453+
The basic size includes the fields in the instance declared by the
454+
macro \csimplemacro{PyObject_HEAD} or
455+
\csimplemacro{PyObject_VAR_HEAD} (whichever is used to declare the
456+
instance struct) and this in turn includes the \member{_ob_prev} and
457+
\member{_ob_next} fields if they are present. This means that the
458+
only correct way to get an initializer for the \member{tp_basicsize}
459+
is to use the \keyword{sizeof} operator on the struct used to
460+
declare the instance layout. The basic size does not include the GC
461+
header size (this is new in Python 2.2; in 2.1 and 2.0, the GC
462+
header size was included in \member{tp_basicsize}).
463+
464+
These fields are inherited by subtypes.
465+
\end{cmemberdesc}
466+
467+
\begin{cmemberdesc}{PyTypeObject}{destructor}{tp_dealloc}
468+
A pointer to the instance destructor function. This function must
469+
be defined unless the type guarantees that its instances will never
470+
be deallocated (as is the case for the singletons \code{None} and
471+
\code{Ellipsis}).
472+
473+
The destructor function is called by the \cfunction{Py_DECREF()} and
474+
\cfunction{Py_XDECREF()} macros when the new reference count is
475+
zero. At this point, the instance is still in existance, but there
476+
are no references to it. The destructor function should free all
477+
references which the instance owns, free all memory buffers owned by
478+
the instance (using the freeing function corresponding to the
479+
allocation function used to allocate the buffer), and finally (as
480+
its last action) call the type's \member{tp_free} slot. If the type
481+
is not subtypable (doesn't have the \constant{Py_TPFLAGS_BASETYPE}
482+
flag bit set), it is permissible to call the object deallocator
483+
directly instead of via \member{tp_free}. The object deallocator
484+
should be the one used to allocate the instance; this is normally
485+
\cfunction{PyObject_Del()} if the instance was allocated using
486+
\cfunction{PyObject_New()} or \cfunction{PyOject_VarNew()}, or
487+
\cfunction{PyObject_GC_Del()} if the instance was allocated using
488+
\cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}.
489+
490+
This field is inherited by subtypes.
491+
\end{cmemberdesc}
492+
493+
\begin{cmemberdesc}{PyTypeObject}{printfunc}{tp_print}
494+
An optional pointer to the instance print function.
495+
496+
The print function is only called when the instance is printed to a
497+
\emph{real} file; when it is printed to a pseudo-file (like a
498+
\class{StringIO} instance), the instance's \member{tp_repr} or
499+
\member{tp_str} function is called to convert it to a string. These
500+
are also called when the type's \member{tp_print} field is \NULL.
501+
502+
The print function is called with the same signature as
503+
\cfunction{PyObject_Print()}: \code{tp_print(PyObject *self, FILE
504+
*file, int flags)}. The \var{self} argument is the instance to be
505+
printed. The \var{file} argument is the stdio file to which it is
506+
to be printed. The \var{flags} argument is composed of flag bits.
507+
The only flag bit currently defined is \constant{Py_PRINT_RAW}.
508+
When the \constant{Py_PRINT_RAW} flag bit is set, the instance
509+
should be printed the same way as \member{tp_str} would format it;
510+
when the \constant{Py_PRINT_RAW} flag bit is clear, the instance
511+
should be printed the same was as \member{tp_repr} would format it.
512+
513+
It is possible that the \member{tp_print} field will be deprecated.
514+
In any case, it is recommended not to define \member{tp_print}, but
515+
instead to rely on \member{tp_repr} and \member{tp_str} for
516+
printing.
517+
518+
This field is inherited by subtypes.
519+
\end{cmemberdesc}
520+
521+
\begin{cmemberdesc}{PyTypeObject}{getattrfunc}{tp_getattr}
522+
An optional pointer to the get-attribute-string function.
523+
524+
This field is deprecated. When it is defined, it should point to a
525+
function that acts the same as the \member{tp_getattro} function,
526+
but taking a C string instead of a Python string object to give the
527+
attribute name. The signature is the same as for
528+
\cfunction{PyObject_GetAttrString()}.
529+
530+
This field is inherited by subtypes together with
531+
\member{tp_getattro}: a subtype inherits both \member{tp_getattr}
532+
and \member{tp_getattro} from its base type when the subtype's
533+
\member{tp_getattr} and \member{tp_getattro} are both \NULL.
534+
\end{cmemberdesc}
535+
536+
\begin{cmemberdesc}{PyTypeObject}{setattrfunc}{tp_setattr}
537+
An optional pointer to the set-attribute-string function.
538+
539+
This field is deprecated. When it is defined, it should point to a
540+
function that acts the same as the \member{tp_setattro} function,
541+
but taking a C string instead of a Python string object to give the
542+
attribute name. The signature is the same as for
543+
\cfunction{PyObject_SetAttrString()}.
544+
545+
This field is inherited by subtypes together with
546+
\member{tp_setattro}: a subtype inherits both \member{tp_setattr}
547+
and \member{tp_setattro} from its base type when the subtype's
548+
\member{tp_setattr} and \member{tp_setattro} are both \NULL.
549+
\end{cmemberdesc}
550+
551+
\begin{cmemberdesc}{PyTypeObject}{cmpfunc}{tp_compare}
552+
An optional pointer to the three-way comparison function.
553+
554+
The signature is the same as for \cfunction{PyObject_Compare()}.
555+
The function should return \code{1} if \var{self} greater than
556+
\var{other}, \code{0} if \var{self} is equal to \var{other}, and
557+
\code{-1} if \var{self} less than \var{other}. It should return
558+
\code{-1} and set an exception condition when an error occurred
559+
during the comparison.
560+
561+
This field is inherited by subtypes together with
562+
\member{tp_richcompare} and \member{tp_hash}: a subtypes inherits
563+
all three of \member{tp_compare}, \member{tp_richcompare}, and
564+
\member{tp_hash} when the subtype's \member{tp_compare},
565+
\member{tp_richcompare}, and \member{tp_hash} are all \NULL.
566+
\end{cmemberdesc}
567+
568+
569+
314570
\section{Mapping Object Structures \label{mapping-structs}}
315571

316572
\begin{ctypedesc}{PyMappingMethods}

0 commit comments

Comments
 (0)