From bab2965c7c28ab56c4075ae990b349196cce38c2 Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Tue, 10 Jul 2001 16:10:08 +0000 Subject: [PATCH] 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. --- Doc/api/api.tex | 121 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 97 insertions(+), 24 deletions(-) diff --git a/Doc/api/api.tex b/Doc/api/api.tex index 44a3d35ee05..fa683fe2770 100644 --- a/Doc/api/api.tex +++ b/Doc/api/api.tex @@ -107,6 +107,11 @@ multi-platform builds since the platform independent headers under \envvar{prefix} include the platform specific headers from \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}} @@ -305,12 +310,12 @@ The reason is simple: in many cases, the returned object is created on the fly, and the reference you get is the only reference to the 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). +\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} (i.e., the type of the type of the object passed as an +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 don't own the reference --- but if you obtain the same item from the @@ -875,7 +880,7 @@ and non-\NULL{} value or traceback. The exception type should be a string or class; if it is a class, the value should be an instance of 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 +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 function. I warned you.) \strong{Note:} This function is normally @@ -1219,7 +1224,7 @@ by \var{func}. This is a simplified interface to \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 +\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 than the top-level package containing it as would otherwise be the @@ -3314,18 +3319,20 @@ Macro form of \cfunction{PyList_GetItem()} without error checking. \begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index, 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 position. \end{cfuncdesc} -\begin{cfuncdesc}{PyObject*}{PyList_SET_ITEM}{PyObject *list, int i, +\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. This is normally only -used to fill in new lists where there is no previous content.. +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} \begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index, @@ -3415,17 +3422,19 @@ Empties an existing dictionary of all key-value pairs. \begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key, PyObject *val} -Inserts \var{value} into the dictionary with a key of \var{key}. +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} \begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p, char *key, PyObject *val} -Inserts \var{value} into the dictionary using \var{key} +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} @@ -3438,6 +3447,7 @@ raised. \begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject *p, char *key} 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} \begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyObject *p, PyObject *key} @@ -3607,14 +3617,14 @@ Returns a new \ctype{PyLongObject} object from the integer part of Returns a C \ctype{long} representation of the contents of \var{pylong}. If \var{pylong} is greater than \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError} is -raised.\withsubitem{(built-in exception)}{OverflowError} +raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}} \end{cfuncdesc} \begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong} Returns a C \ctype{unsigned long} representation of the contents of \var{pylong}. If \var{pylong} is greater than \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an \exception{OverflowError} -is raised.\withsubitem{(built-in exception)}{OverflowError} +is raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}} \end{cfuncdesc} \begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong} @@ -4599,14 +4609,14 @@ disabled at compile time. \end{csimplemacrodesc} \begin{csimplemacrodesc}{Py_BLOCK_THREADS} -This macro expands to \samp{PyEval_RestoreThread(_save);} i.e. it +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 time. \end{csimplemacrodesc} \begin{csimplemacrodesc}{Py_UNBLOCK_THREADS} -This macro expands to \samp{_save = PyEval_SaveThread();} i.e. it is +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 disabled at compile time. @@ -4758,18 +4768,20 @@ available for allocating and releasing memory from the Python heap: \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 +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} \begin{cfuncdesc}{void*}{PyMem_Realloc}{void *p, size_t n} Resizes the memory block pointed to by \var{p} to \var{n} bytes. The 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()}. +\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} \begin{cfuncdesc}{void}{PyMem_Free}{void *p} @@ -4787,6 +4799,7 @@ that \var{TYPE} refers to any C type. Same as \cfunction{PyMem_Malloc()}, but allocates \code{(\var{n} * 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} \begin{cfuncdesc}{\var{TYPE}*}{PyMem_Resize}{void *p, TYPE, size_t n} @@ -4883,31 +4896,65 @@ implementing new object types in C. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyObject_Init}{PyObject *op, - PyTypeObject *type} + 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} + 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, @@ -4942,13 +4989,39 @@ implementing new object types in C. sure you need it. \end{cfuncdesc} -PyArg_ParseTupleAndKeywords, PyArg_ParseTuple, PyArg_Parse +\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 DL_IMPORT -_Py_NoneStruct +\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}} @@ -5223,7 +5296,7 @@ The \member{tp_clear} handler must be of the \ctype{inquiry} type, or 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 (i.e., don't just call + 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.