[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.117.2.7,1.117.2.8
Fred L. Drake
fdrake@users.sourceforge.net
Tue, 10 Jul 2001 09:11:12 -0700
Update of /cvsroot/python/python/dist/src/Doc/api
In directory usw-pr-cvs1:/tmp/cvs-serv7167/api
Modified Files:
Tag: release21-maint
api.tex
Log Message:
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
PyObject_InitVar(), PyObject_Del(), PyObject_NEW(),
PyObject_NEW_VAR(), and PyObject_DEL().
Add notes to PyMem_Malloc() and PyMem_New() about the memory buffers
not being initialized.
This fixes SF bug #439012.
Added explicit return value information for PyList_SetItem(),
PyDict_SetItem(), and PyDict_SetItemString(). Corrected return type
for PyList_SET_ITEM().
Fixed index entries in the descriptions of PyLong_AsLong() and
PyLong_AsUnignedLong().
This fixes the API manual portion of SF bug #440037.
Note that the headers properly declare everything as 'extern "C"' for
C++ users.
Document _Py_NoneStruct.
Added links to the Extending & Embedding manual for PyArg_ParseTuple()
and PyArg_ParseTupleAndKeywords().
Added note that PyArg_Parse() should not be used in new code.
Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
translation more difficult, as well as reading the English more
difficult for non-native speakers.
Index: api.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.117.2.7
retrieving revision 1.117.2.8
diff -C2 -r1.117.2.7 -r1.117.2.8
*** api.tex 2001/07/09 14:34:16 1.117.2.7
--- api.tex 2001/07/10 16:11:09 1.117.2.8
***************
*** 108,112 ****
--- 108,117 ----
\envvar{exec_prefix}.
+ \Cpp{} users should note that though the API is defined entirely using
+ C, the header files do properly declare the entry points to be
+ \code{extern "C"}, so there is no need to do anything special to use
+ the API from \Cpp.
+
\section{Objects, Types and Reference Counts \label{objects}}
***************
*** 306,315 ****
object. Therefore, the generic functions that return object
references, like \cfunction{PyObject_GetItem()} and
! \cfunction{PySequence_GetItem()}, always return a new reference (i.e.,
! the caller becomes the owner of the reference).
It is important to realize that whether you own a reference returned
by a function depends on which function you call only --- \emph{the
! plumage} (i.e., the type of the type of the object passed as an
argument to the function) \emph{doesn't enter into it!} Thus, if you
extract an item from a list using \cfunction{PyList_GetItem()}, you
--- 311,320 ----
object. Therefore, the generic functions that return object
references, like \cfunction{PyObject_GetItem()} and
! \cfunction{PySequence_GetItem()}, always return a new reference (the
! caller becomes the owner of the reference).
It is important to realize that whether you own a reference returned
by a function depends on which function you call only --- \emph{the
! plumage} (the type of the type of the object passed as an
argument to the function) \emph{doesn't enter into it!} Thus, if you
extract an item from a list using \cfunction{PyList_GetItem()}, you
***************
*** 876,880 ****
that class. Do not pass an invalid exception type or value.
(Violating these rules will cause subtle problems later.) This call
! takes away a reference to each object, i.e.\ you must own a reference
to each object before the call and after the call you no longer own
these references. (If you don't understand this, don't use this
--- 881,885 ----
that class. Do not pass an invalid exception type or value.
(Violating these rules will cause subtle problems later.) This call
! takes away a reference to each object: you must own a reference
to each object before the call and after the call you no longer own
these references. (If you don't understand this, don't use this
***************
*** 1220,1224 ****
\cfunction{PyImport_ImportModuleEx()} below, leaving the
\var{globals} and \var{locals} arguments set to \NULL{}. When the
! \var{name} argument contains a dot (i.e., when it specifies a
submodule of a package), the \var{fromlist} argument is set to the
list \code{['*']} so that the return value is the named module rather
--- 1225,1229 ----
\cfunction{PyImport_ImportModuleEx()} below, leaving the
\var{globals} and \var{locals} arguments set to \NULL{}. When the
! \var{name} argument contains a dot (when it specifies a
submodule of a package), the \var{fromlist} argument is set to the
list \code{['*']} so that the return value is the named module rather
***************
*** 3256,3259 ****
--- 3261,3265 ----
PyObject *item}
Sets the item at index \var{index} in list to \var{item}.
+ Returns \code{0} on success or \code{-1} on failure.
\strong{Note:} This function ``steals'' a reference to \var{item} and
discards a reference to an item already in the list at the affected
***************
*** 3261,3271 ****
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{PyList_SET_ITEM}{PyObject *list, int i,
PyObject *o}
Macro form of \cfunction{PyList_SetItem()} without error checking.
\strong{Note:} This function ``steals'' a reference to \var{item},
and, unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a
! reference to any item that it being replaced. This is normally only
! used to fill in new lists where there is no previous content..
\end{cfuncdesc}
--- 3267,3278 ----
\end{cfuncdesc}
! \begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, int i,
PyObject *o}
Macro form of \cfunction{PyList_SetItem()} without error checking.
\strong{Note:} This function ``steals'' a reference to \var{item},
and, unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a
! reference to any item that it being replaced; any reference in
! \var{list} at position \var{i} will be leaked. This is normally only
! used to fill in new lists where there is no previous content.
\end{cfuncdesc}
***************
*** 3357,3363 ****
\begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key,
PyObject *val}
! Inserts \var{value} into the dictionary with a key of \var{key}.
\var{key} must be hashable; if it isn't, \exception{TypeError} will be
raised.
\end{cfuncdesc}
--- 3364,3371 ----
\begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key,
PyObject *val}
! Inserts \var{value} into the dictionary \var{p} with a key of \var{key}.
\var{key} must be hashable; if it isn't, \exception{TypeError} will be
raised.
+ Returns \code{0} on success or \code{-1} on failure.
\end{cfuncdesc}
***************
*** 3365,3371 ****
char *key,
PyObject *val}
! Inserts \var{value} into the dictionary using \var{key}
as a key. \var{key} should be a \ctype{char*}. The key object is
created using \code{PyString_FromString(\var{key})}.
\ttindex{PyString_FromString()}
\end{cfuncdesc}
--- 3373,3380 ----
char *key,
PyObject *val}
! Inserts \var{value} into the dictionary \var{p} using \var{key}
as a key. \var{key} should be a \ctype{char*}. The key object is
created using \code{PyString_FromString(\var{key})}.
+ Returns \code{0} on success or \code{-1} on failure.
\ttindex{PyString_FromString()}
\end{cfuncdesc}
***************
*** 3380,3383 ****
--- 3389,3393 ----
Removes the entry in dictionary \var{p} which has a key
specified by the string \var{key}.
+ Returns \code{0} on success or \code{-1} on failure.
\end{cfuncdesc}
***************
*** 3549,3553 ****
\var{pylong}. If \var{pylong} is greater than
\constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError} is
! raised.\withsubitem{(built-in exception)}{OverflowError}
\end{cfuncdesc}
--- 3559,3563 ----
\var{pylong}. If \var{pylong} is greater than
\constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError} is
! raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
\end{cfuncdesc}
***************
*** 3556,3560 ****
\var{pylong}. If \var{pylong} is greater than
\constant{ULONG_MAX}\ttindex{ULONG_MAX}, an \exception{OverflowError}
! is raised.\withsubitem{(built-in exception)}{OverflowError}
\end{cfuncdesc}
--- 3566,3570 ----
\var{pylong}. If \var{pylong} is greater than
\constant{ULONG_MAX}\ttindex{ULONG_MAX}, an \exception{OverflowError}
! is raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
\end{cfuncdesc}
***************
*** 4541,4545 ****
\begin{csimplemacrodesc}{Py_BLOCK_THREADS}
! This macro expands to \samp{PyEval_RestoreThread(_save);} i.e. it
is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
brace. It is a no-op when thread support is disabled at compile
--- 4551,4555 ----
\begin{csimplemacrodesc}{Py_BLOCK_THREADS}
! This macro expands to \samp{PyEval_RestoreThread(_save);}: it
is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
brace. It is a no-op when thread support is disabled at compile
***************
*** 4548,4552 ****
\begin{csimplemacrodesc}{Py_UNBLOCK_THREADS}
! This macro expands to \samp{_save = PyEval_SaveThread();} i.e. it is
equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
and variable declaration. It is a no-op when thread support is
--- 4558,4562 ----
\begin{csimplemacrodesc}{Py_UNBLOCK_THREADS}
! This macro expands to \samp{_save = PyEval_SaveThread();}: it is
equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
and variable declaration. It is a no-op when thread support is
***************
*** 4700,4705 ****
\begin{cfuncdesc}{void*}{PyMem_Malloc}{size_t n}
Allocates \var{n} bytes and returns a pointer of type \ctype{void*} to
! the allocated memory, or \NULL{} if the request fails. Requesting zero
bytes returns a non-\NULL{} pointer.
\end{cfuncdesc}
--- 4710,4716 ----
\begin{cfuncdesc}{void*}{PyMem_Malloc}{size_t n}
Allocates \var{n} bytes and returns a pointer of type \ctype{void*} to
! the allocated memory, or \NULL{} if the request fails. Requesting zero
bytes returns a non-\NULL{} pointer.
+ The memory will not have been initialized in any way.
\end{cfuncdesc}
***************
*** 4708,4715 ****
contents will be unchanged to the minimum of the old and the new
sizes. If \var{p} is \NULL{}, the call is equivalent to
! \cfunction{PyMem_Malloc(\var{n})}; if \var{n} is equal to zero, the memory block
! is resized but is not freed, and the returned pointer is non-\NULL{}.
! Unless \var{p} is \NULL{}, it must have been returned by a previous
! call to \cfunction{PyMem_Malloc()} or \cfunction{PyMem_Realloc()}.
\end{cfuncdesc}
--- 4719,4727 ----
contents will be unchanged to the minimum of the old and the new
sizes. If \var{p} is \NULL{}, the call is equivalent to
! \cfunction{PyMem_Malloc(\var{n})}; if \var{n} is equal to zero, the
! memory block is resized but is not freed, and the returned pointer is
! non-\NULL{}. Unless \var{p} is \NULL{}, it must have been returned by
! a previous call to \cfunction{PyMem_Malloc()} or
! \cfunction{PyMem_Realloc()}.
\end{cfuncdesc}
***************
*** 4729,4732 ****
--- 4741,4745 ----
sizeof(\var{TYPE}))} bytes of memory. Returns a pointer cast to
\ctype{\var{TYPE}*}.
+ The memory will not have been initialized in any way.
\end{cfuncdesc}
***************
*** 4825,4853 ****
\begin{cfuncdesc}{PyObject*}{PyObject_Init}{PyObject *op,
! PyTypeObject *type}
\end{cfuncdesc}
\begin{cfuncdesc}{PyVarObject*}{PyObject_InitVar}{PyVarObject *op,
! PyTypeObject *type, int size}
\end{cfuncdesc}
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_New}{TYPE, PyTypeObject *type}
\end{cfuncdesc}
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NewVar}{TYPE, PyTypeObject *type,
int size}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyObject_Del}{PyObject *op}
\end{cfuncdesc}
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW}{TYPE, PyTypeObject *type}
\end{cfuncdesc}
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW_VAR}{TYPE, PyTypeObject *type,
int size}
\end{cfuncdesc}
\begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op}
\end{cfuncdesc}
--- 4838,4900 ----
\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 it 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}
***************
*** 4884,4888 ****
\end{cfuncdesc}
! PyArg_ParseTupleAndKeywords, PyArg_ParseTuple, PyArg_Parse
Py_BuildValue
--- 4931,4957 ----
\end{cfuncdesc}
! \begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format,
! \moreargs}
! Parse the parameters of a function that takes only positional
! parameters into local variables. See
! \citetitle[../ext/parseTuple.html]{Extending and Embedding the
! Python Interpreter} for more information.
! \end{cfuncdesc}
!
! \begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
! PyObject *kw, char *format, char *keywords[], \moreargs}
! Parse the parameters of a function that takes both positional and
! keyword parameters into local variables. See
! \citetitle[../ext/parseTupleAndKeywords.html]{Extending and
! Embedding the Python Interpreter} for more information.
! \end{cfuncdesc}
!
! \begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, char *format, \moreargs}
! Function used to deconstruct the argument lists of ``old-style''
! functions --- these are functions which use the
! \constant{METH_OLDARGS} parameter parsing method. This is not
! recommended for new code, and most code in the standard interpreter
! has been modified to no longer use this.
! \end{cfuncdesc}
Py_BuildValue
***************
*** 4890,4894 ****
DL_IMPORT
! _Py_NoneStruct
--- 4959,4967 ----
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}
***************
*** 5165,5169 ****
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 (i.e., 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
--- 5238,5242 ----
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