[Python-checkins] python/dist/src/Doc/api newtypes.tex,1.5,1.6
fdrake@sourceforge.net
fdrake@sourceforge.net
Tue, 09 Apr 2002 14:22:09 -0700
Update of /cvsroot/python/python/dist/src/Doc/api
In directory usw-pr-cvs1:/tmp/cvs-serv6582/api
Modified Files:
newtypes.tex
Log Message:
Started filling in the information about some of the basic types and macros
used to define Python objects.
Index: newtypes.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/newtypes.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** newtypes.tex 5 Apr 2002 23:01:14 -0000 1.5
--- newtypes.tex 9 Apr 2002 21:22:07 -0000 1.6
***************
*** 123,129 ****
\section{Common Object Structures \label{common-structs}}
! PyObject, PyVarObject
! PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD
Typedefs:
--- 123,191 ----
\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_VAR_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 depends 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
Typedefs:
***************
*** 135,138 ****
--- 197,205 ----
\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}