diff options
Diffstat (limited to 'Doc/api')
| -rw-r--r-- | Doc/api/abstract.tex | 842 | ||||
| -rw-r--r-- | Doc/api/api.tex | 6150 | ||||
| -rw-r--r-- | Doc/api/concrete.tex | 2342 | ||||
| -rw-r--r-- | Doc/api/exceptions.tex | 353 | ||||
| -rw-r--r-- | Doc/api/init.tex | 774 | ||||
| -rw-r--r-- | Doc/api/intro.tex | 558 | ||||
| -rw-r--r-- | Doc/api/memory.tex | 201 | ||||
| -rw-r--r-- | Doc/api/newtypes.tex | 578 | ||||
| -rw-r--r-- | Doc/api/refcounting.tex | 48 | ||||
| -rw-r--r-- | Doc/api/utilities.tex | 320 | ||||
| -rw-r--r-- | Doc/api/veryhigh.tex | 141 |
11 files changed, 6171 insertions, 6136 deletions
diff --git a/Doc/api/abstract.tex b/Doc/api/abstract.tex new file mode 100644 index 0000000..8d271df --- /dev/null +++ b/Doc/api/abstract.tex @@ -0,0 +1,842 @@ +\chapter{Abstract Objects Layer \label{abstract}} + +The functions in this chapter interact with Python objects regardless +of their type, or with wide classes of object types (e.g. all +numerical types, or all sequence types). When used on object types +for which they do not apply, they will raise a Python exception. + + +\section{Object Protocol \label{object}} + +\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags} + Print an object \var{o}, on file \var{fp}. Returns \code{-1} on + error. The flags argument is used to enable certain printing + options. The only option currently supported is + \constant{Py_PRINT_RAW}; if given, the \function{str()} of the + object is written instead of the \function{repr()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name} + Returns \code{1} if \var{o} has the attribute \var{attr_name}, and + \code{0} otherwise. This is equivalent to the Python expression + \samp{hasattr(\var{o}, \var{attr_name})}. This function always + succeeds. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, + char *attr_name} + Retrieve an attribute named \var{attr_name} from object \var{o}. + Returns the attribute value on success, or \NULL{} on failure. + This is the equivalent of the Python expression + \samp{\var{o}.\var{attr_name}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name} + Returns \code{1} if \var{o} has the attribute \var{attr_name}, and + \code{0} otherwise. This is equivalent to the Python expression + \samp{hasattr(\var{o}, \var{attr_name})}. This function always + succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, + PyObject *attr_name} + Retrieve an attribute named \var{attr_name} from object \var{o}. + Returns the attribute value on success, or \NULL{} on failure. This + is the equivalent of the Python expression + \samp{\var{o}.\var{attr_name}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, + char *attr_name, PyObject *v} + Set the value of the attribute named \var{attr_name}, for object + \var{o}, to the value \var{v}. Returns \code{-1} on failure. This + is the equivalent of the Python statement + \samp{\var{o}.\var{attr_name} = \var{v}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, + PyObject *attr_name, PyObject *v} + Set the value of the attribute named \var{attr_name}, for object + \var{o}, to the value \var{v}. Returns \code{-1} on failure. This + is the equivalent of the Python statement + \samp{\var{o}.\var{attr_name} = \var{v}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name} + Delete attribute named \var{attr_name}, for object \var{o}. Returns + \code{-1} on failure. This is the equivalent of the Python + statement: \samp{del \var{o}.\var{attr_name}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name} + Delete attribute named \var{attr_name}, for object \var{o}. Returns + \code{-1} on failure. This is the equivalent of the Python + statement \samp{del \var{o}.\var{attr_name}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result} + Compare the values of \var{o1} and \var{o2} using a routine provided + by \var{o1}, if one exists, otherwise with a routine provided by + \var{o2}. The result of the comparison is returned in + \var{result}. Returns \code{-1} on failure. This is the equivalent + of the Python statement\bifuncindex{cmp} \samp{\var{result} = + cmp(\var{o1}, \var{o2})}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2} + Compare the values of \var{o1} and \var{o2} using a routine provided + by \var{o1}, if one exists, otherwise with a routine provided by + \var{o2}. Returns the result of the comparison on success. On + error, the value returned is undefined; use + \cfunction{PyErr_Occurred()} to detect an error. This is equivalent + to the Python expression\bifuncindex{cmp} \samp{cmp(\var{o1}, + \var{o2})}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o} + Compute a string representation of object \var{o}. Returns the + string representation on success, \NULL{} on failure. This is the + equivalent of the Python expression \samp{repr(\var{o})}. Called by + the \function{repr()}\bifuncindex{repr} built-in function and by + reverse quotes. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o} + Compute a string representation of object \var{o}. Returns the + string representation on success, \NULL{} on failure. This is the + equivalent of the Python expression \samp{str(\var{o})}. Called by + the \function{str()}\bifuncindex{str} built-in function and by the + \keyword{print} statement. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_Unicode}{PyObject *o} + Compute a Unicode string representation of object \var{o}. Returns + the Unicode string representation on success, \NULL{} on failure. + This is the equivalent of the Python expression + \samp{unistr(\var{o})}. Called by the + \function{unistr()}\bifuncindex{unistr} built-in function. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls} + Return \code{1} if \var{inst} is an instance of the class \var{cls} + or a subclass of \var{cls}. If \var{cls} is a type object rather + than a class object, \cfunction{PyObject_IsInstance()} returns + \code{1} if \var{inst} is of type \var{cls}. If \var{inst} is not a + class instance and \var{cls} is neither a type object or class + object, \var{inst} must have a \member{__class__} attribute --- the + class relationship of the value of that attribute with \var{cls} + will be used to determine the result of this function. + \versionadded{2.1} +\end{cfuncdesc} + +Subclass determination is done in a fairly straightforward way, but +includes a wrinkle that implementors of extensions to the class system +may want to be aware of. If \class{A} and \class{B} are class +objects, \class{B} is a subclass of \class{A} if it inherits from +\class{A} either directly or indirectly. If either is not a class +object, a more general mechanism is used to determine the class +relationship of the two objects. When testing if \var{B} is a +subclass of \var{A}, if \var{A} is \var{B}, +\cfunction{PyObject_IsSubclass()} returns true. If \var{A} and +\var{B} are different objects, \var{B}'s \member{__bases__} attribute +is searched in a depth-first fashion for \var{A} --- the presence of +the \member{__bases__} attribute is considered sufficient for this +determination. + +\begin{cfuncdesc}{int}{PyObject_IsSubclass}{PyObject *derived, + PyObject *cls} + Returns \code{1} if the class \var{derived} is identical to or + derived from the class \var{cls}, otherwise returns \code{0}. In + case of an error, returns \code{-1}. If either \var{derived} or + \var{cls} is not an actual class object, this function uses the + generic algorithm described above. + \versionadded{2.1} +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o} + Determine if the object \var{o} is callable. Return \code{1} if the + object is callable and \code{0} otherwise. This function always + succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, + PyObject *args} + Call a callable Python object \var{callable_object}, with arguments + given by the tuple \var{args}. If no arguments are needed, then + \var{args} may be \NULL. Returns the result of the call on + success, or \NULL{} on failure. This is the equivalent of the + Python expression \samp{apply(\var{callable_object}, \var{args})} or + \samp{\var{callable_object}(*\var{args})}. + \bifuncindex{apply} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, + char *format, ...} + Call a callable Python object \var{callable_object}, with a variable + number of C arguments. The C arguments are described using a + \cfunction{Py_BuildValue()} style format string. The format may be + \NULL, indicating that no arguments are provided. Returns the + result of the call on success, or \NULL{} on failure. This is the + equivalent of the Python expression + \samp{apply(\var{callable_object}\var{args})} or + \samp{\var{callable_object}(*\var{args})}. + \bifuncindex{apply} +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, + char *method, char *format, ...} + Call the method named \var{m} of object \var{o} with a variable + number of C arguments. The C arguments are described by a + \cfunction{Py_BuildValue()} format string. The format may be \NULL, + indicating that no arguments are provided. Returns the result of the + call on success, or \NULL{} on failure. This is the equivalent of + the Python expression \samp{\var{o}.\var{method}(\var{args})}. Note + that special method names, such as \method{__add__()}, + \method{__getitem__()}, and so on are not supported. The specific + abstract-object routines for these must be used. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o} + Compute and return the hash value of an object \var{o}. On failure, + return \code{-1}. This is the equivalent of the Python expression + \samp{hash(\var{o})}.\bifuncindex{hash} +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o} + Returns \code{1} if the object \var{o} is considered to be true, and + \code{0} otherwise. This is equivalent to the Python expression + \samp{not not \var{o}}. This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o} + When \var{o} is non-\NULL, returns a type object corresponding to + the object type of object \var{o}. On failure, raises + \exception{SystemError} and returns \NULL. This is equivalent to + the Python expression \code{type(\var{o})}. + \bifuncindex{type} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyObject_TypeCheck}{PyObject *o, PyTypeObject *type} + Return true if the object \var{o} is of type \var{type} or a subtype + of \var{type}. Both parameters must be non-\NULL. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o} + Return the length of object \var{o}. If the object \var{o} provides + both sequence and mapping protocols, the sequence length is + returned. On error, \code{-1} is returned. This is the equivalent + to the Python expression \samp{len(\var{o})}.\bifuncindex{len} +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key} + Return element of \var{o} corresponding to the object \var{key} or + \NULL{} on failure. This is the equivalent of the Python expression + \samp{\var{o}[\var{key}]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, + PyObject *key, PyObject *v} + Map the object \var{key} to the value \var{v}. Returns \code{-1} on + failure. This is the equivalent of the Python statement + \samp{\var{o}[\var{key}] = \var{v}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key} + Delete the mapping for \var{key} from \var{o}. Returns \code{-1} on + failure. This is the equivalent of the Python statement \samp{del + \var{o}[\var{key}]}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o} + Derives a file-descriptor from a Python object. If the object is an + integer or long integer, its value is returned. If not, the + object's \method{fileno()} method is called if it exists; the method + must return an integer or long integer, which is returned as the + file descriptor value. Returns \code{-1} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyObject_Dir}{PyObject *o} + This is equivalent to the Python expression \samp{dir(\var{o})}, + returning a (possibly empty) list of strings appropriate for the + object argument, or \NULL{} if there was an error. If the argument + is \NULL, this is like the Python \samp{dir()}, returning the names + of the current locals; in this case, if no execution frame is active + then \NULL{} is returned but \cfunction{PyErr_Occurred()} will + return false. +\end{cfuncdesc} + + +\section{Number Protocol \label{number}} + +\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o} + Returns \code{1} if the object \var{o} provides numeric protocols, + and false otherwise. This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2} + Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on + failure. This is the equivalent of the Python expression + \samp{\var{o1} + \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2} + Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{} + on failure. This is the equivalent of the Python expression + \samp{\var{o1} - \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2} + Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} + on failure. This is the equivalent of the Python expression + \samp{\var{o1} * \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2} + Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on + failure. This is the equivalent of the Python expression + \samp{\var{o1} / \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_FloorDivide}{PyObject *o1, PyObject *o2} + Return the floor of \var{o1} divided by \var{o2}, or \NULL{} on + failure. This is equivalent to the ``classic'' division of + integers. + \versionadded{2.2} +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_TrueDivide}{PyObject *o1, PyObject *o2} + Return a reasonable approximation for the mathematical value of + \var{o1} divided by \var{o2}, or \NULL{} on failure. The return + value is ``approximate'' because binary floating point numbers are + approximate; it is not possible to represent all real numbers in + base two. This function can return a floating point value when + passed two integers. + \versionadded{2.2} +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2} + Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} + on failure. This is the equivalent of the Python expression + \samp{\var{o1} \%\ \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2} + See the built-in function \function{divmod()}\bifuncindex{divmod}. + Returns \NULL{} on failure. This is the equivalent of the Python + expression \samp{divmod(\var{o1}, \var{o2})}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, + PyObject *o2, PyObject *o3} + See the built-in function \function{pow()}\bifuncindex{pow}. + Returns \NULL{} on failure. This is the equivalent of the Python + expression \samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3} + is optional. If \var{o3} is to be ignored, pass \cdata{Py_None} in + its place (passing \NULL{} for \var{o3} would cause an illegal + memory access). +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o} + Returns the negation of \var{o} on success, or \NULL{} on failure. + This is the equivalent of the Python expression \samp{-\var{o}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o} + Returns \var{o} on success, or \NULL{} on failure. This is the + equivalent of the Python expression \samp{+\var{o}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o} + Returns the absolute value of \var{o}, or \NULL{} on failure. This + is the equivalent of the Python expression \samp{abs(\var{o})}. + \bifuncindex{abs} +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o} + Returns the bitwise negation of \var{o} on success, or \NULL{} on + failure. This is the equivalent of the Python expression + \samp{\~\var{o}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2} + Returns the result of left shifting \var{o1} by \var{o2} on success, + or \NULL{} on failure. This is the equivalent of the Python + expression \samp{\var{o1} <\code{<} \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2} + Returns the result of right shifting \var{o1} by \var{o2} on + success, or \NULL{} on failure. This is the equivalent of the + Python expression \samp{\var{o1} >\code{>} \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2} + Returns the ``bitwise and'' of \var{o2} and \var{o2} on success and + \NULL{} on failure. This is the equivalent of the Python expression + \samp{\var{o1} \&\ \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2} + Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on + success, or \NULL{} on failure. This is the equivalent of the + Python expression \samp{\var{o1} \textasciicircum{} \var{o2}}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2} + Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or + \NULL{} on failure. This is the equivalent of the Python expression + \samp{\var{o1} | \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAdd}{PyObject *o1, PyObject *o2} + Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on + failure. The operation is done \emph{in-place} when \var{o1} + supports it. This is the equivalent of the Python statement + \samp{\var{o1} += \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1, + PyObject *o2} + Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{} + on failure. The operation is done \emph{in-place} when \var{o1} + supports it. This is the equivalent of the Python statement + \samp{\var{o1} -= \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1, + PyObject *o2} + Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} + on failure. The operation is done \emph{in-place} when \var{o1} + supports it. This is the equivalent of the Python statement + \samp{\var{o1} *= \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1, + PyObject *o2} + Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on + failure. The operation is done \emph{in-place} when \var{o1} + supports it. This is the equivalent of the Python statement + \samp{\var{o1} /= \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceFloorDivide}{PyObject *o1, + PyObject *o2} + Returns the mathematical of dividing \var{o1} by \var{o2}, or + \NULL{} on failure. The operation is done \emph{in-place} when + \var{o1} supports it. This is the equivalent of the Python + statement \samp{\var{o1} //= \var{o2}}. + \versionadded{2.2} +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceTrueDivide}{PyObject *o1, + PyObject *o2} + Return a reasonable approximation for the mathematical value of + \var{o1} divided by \var{o2}, or \NULL{} on failure. The return + value is ``approximate'' because binary floating point numbers are + approximate; it is not possible to represent all real numbers in + base two. This function can return a floating point value when + passed two integers. The operation is done \emph{in-place} when + \var{o1} supports it. + \versionadded{2.2} +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1, + PyObject *o2} + Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} + on failure. The operation is done \emph{in-place} when \var{o1} + supports it. This is the equivalent of the Python statement + \samp{\var{o1} \%= \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1, + PyObject *o2, PyObject *o3} + See the built-in function \function{pow()}.\bifuncindex{pow} + Returns \NULL{} on failure. The operation is done \emph{in-place} + when \var{o1} supports it. This is the equivalent of the Python + statement \samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None}, + or an in-place variant of \samp{pow(\var{o1}, \var{o2}, \var{o3})} + otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its + place (passing \NULL{} for \var{o3} would cause an illegal memory + access). +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1, + PyObject *o2} + Returns the result of left shifting \var{o1} by \var{o2} on success, + or \NULL{} on failure. The operation is done \emph{in-place} when + \var{o1} supports it. This is the equivalent of the Python + statement \samp{\var{o1} <\code{<=} \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1, + PyObject *o2} + Returns the result of right shifting \var{o1} by \var{o2} on + success, or \NULL{} on failure. The operation is done + \emph{in-place} when \var{o1} supports it. This is the equivalent + of the Python statement \samp{\var{o1} >\code{>=} \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAnd}{PyObject *o1, PyObject *o2} + Returns the ``bitwise and'' of \var{o1} and \var{o2} on success and + \NULL{} on failure. The operation is done \emph{in-place} when + \var{o1} supports it. This is the equivalent of the Python + statement \samp{\var{o1} \&= \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2} + Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on + success, or \NULL{} on failure. The operation is done + \emph{in-place} when \var{o1} supports it. This is the equivalent + of the Python statement \samp{\var{o1} \textasciicircum= \var{o2}}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2} + Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or + \NULL{} on failure. The operation is done \emph{in-place} when + \var{o1} supports it. This is the equivalent of the Python + statement \samp{\var{o1} |= \var{o2}}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyNumber_Coerce}{PyObject **p1, PyObject **p2} + This function takes the addresses of two variables of type + \ctype{PyObject*}. If the objects pointed to by \code{*\var{p1}} + and \code{*\var{p2}} have the same type, increment their reference + count and return \code{0} (success). If the objects can be converted + to a common numeric type, replace \code{*p1} and \code{*p2} by their + converted value (with 'new' reference counts), and return \code{0}. + If no conversion is possible, or if some other error occurs, return + \code{-1} (failure) and don't increment the reference counts. The + call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python + statement \samp{\var{o1}, \var{o2} = coerce(\var{o1}, \var{o2})}. + \bifuncindex{coerce} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o} + Returns the \var{o} converted to an integer object on success, or + \NULL{} on failure. This is the equivalent of the Python expression + \samp{int(\var{o})}.\bifuncindex{int} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o} + Returns the \var{o} converted to a long integer object on success, + or \NULL{} on failure. This is the equivalent of the Python + expression \samp{long(\var{o})}.\bifuncindex{long} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o} + Returns the \var{o} converted to a float object on success, or + \NULL{} on failure. This is the equivalent of the Python expression + \samp{float(\var{o})}.\bifuncindex{float} +\end{cfuncdesc} + + +\section{Sequence Protocol \label{sequence}} + +\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o} + Return \code{1} if the object provides sequence protocol, and + \code{0} otherwise. This function always succeeds. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_Size}{PyObject *o} + Returns the number of objects in sequence \var{o} on success, and + \code{-1} on failure. For objects that do not provide sequence + protocol, this is equivalent to the Python expression + \samp{len(\var{o})}.\bifuncindex{len} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_Length}{PyObject *o} + Alternate name for \cfunction{PySequence_Size()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2} + Return the concatenation of \var{o1} and \var{o2} on success, and + \NULL{} on failure. This is the equivalent of the Python + expression \samp{\var{o1} + \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count} + Return the result of repeating sequence object \var{o} \var{count} + times, or \NULL{} on failure. This is the equivalent of the Python + expression \samp{\var{o} * \var{count}}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1, + PyObject *o2} + Return the concatenation of \var{o1} and \var{o2} on success, and + \NULL{} on failure. The operation is done \emph{in-place} when + \var{o1} supports it. This is the equivalent of the Python + expression \samp{\var{o1} += \var{o2}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, int count} + Return the result of repeating sequence object \var{o} \var{count} + times, or \NULL{} on failure. The operation is done \emph{in-place} + when \var{o} supports it. This is the equivalent of the Python + expression \samp{\var{o} *= \var{count}}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i} + Return the \var{i}th element of \var{o}, or \NULL{} on failure. + This is the equivalent of the Python expression + \samp{\var{o}[\var{i}]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2} + Return the slice of sequence object \var{o} between \var{i1} and + \var{i2}, or \NULL{} on failure. This is the equivalent of the + Python expression \samp{\var{o}[\var{i1}:\var{i2}]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v} + Assign object \var{v} to the \var{i}th element of \var{o}. Returns + \code{-1} on failure. This is the equivalent of the Python + statement \samp{\var{o}[\var{i}] = \var{v}}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i} + Delete the \var{i}th element of object \var{o}. Returns \code{-1} + on failure. This is the equivalent of the Python statement + \samp{del \var{o}[\var{i}]}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, + int i2, PyObject *v} + Assign the sequence object \var{v} to the slice in sequence object + \var{o} from \var{i1} to \var{i2}. This is the equivalent of the + Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2} + Delete the slice in sequence object \var{o} from \var{i1} to + \var{i2}. Returns \code{-1} on failure. This is the equivalent of + the Python statement \samp{del \var{o}[\var{i1}:\var{i2}]}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o} + Returns the \var{o} as a tuple on success, and \NULL{} on failure. + This is equivalent to the Python expression \samp{tuple(\var{o})}. + \bifuncindex{tuple} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value} + Return the number of occurrences of \var{value} in \var{o}, that is, + return the number of keys for which \code{\var{o}[\var{key}] == + \var{value}}. On failure, return \code{-1}. This is equivalent to + the Python expression \samp{\var{o}.count(\var{value})}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_Contains}{PyObject *o, PyObject *value} + Determine if \var{o} contains \var{value}. If an item in \var{o} is + equal to \var{value}, return \code{1}, otherwise return \code{0}. + On error, return \code{-1}. This is equivalent to the Python + expression \samp{\var{value} in \var{o}}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value} + Return the first index \var{i} for which \code{\var{o}[\var{i}] == + \var{value}}. On error, return \code{-1}. This is equivalent to + the Python expression \samp{\var{o}.index(\var{value})}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o} + Return a list object with the same contents as the arbitrary + sequence \var{o}. The returned list is guaranteed to be new. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o} + Return a tuple object with the same contents as the arbitrary + sequence \var{o}. If \var{o} is a tuple, a new reference will be + returned, otherwise a tuple will be constructed with the appropriate + contents. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PySequence_Fast}{PyObject *o, const char *m} + Returns the sequence \var{o} as a tuple, unless it is already a + tuple or list, in which case \var{o} is returned. Use + \cfunction{PySequence_Fast_GET_ITEM()} to access the members of the + result. Returns \NULL{} on failure. If the object is not a + sequence, raises \exception{TypeError} with \var{m} as the message + text. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, int i} + Return the \var{i}th element of \var{o}, assuming that \var{o} was + returned by \cfunction{PySequence_Fast()}, and that \var{i} is + within bounds. The caller is expected to get the length of the + sequence by calling \cfunction{PySequence_Size()} on \var{o}, since + lists and tuples are guaranteed to always return their true length. +\end{cfuncdesc} + + +\section{Mapping Protocol \label{mapping}} + +\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o} + Return \code{1} if the object provides mapping protocol, and + \code{0} otherwise. This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o} + Returns the number of keys in object \var{o} on success, and + \code{-1} on failure. For objects that do not provide mapping + protocol, this is equivalent to the Python expression + \samp{len(\var{o})}.\bifuncindex{len} +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key} + Remove the mapping for object \var{key} from the object \var{o}. + Return \code{-1} on failure. This is equivalent to the Python + statement \samp{del \var{o}[\var{key}]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key} + Remove the mapping for object \var{key} from the object \var{o}. + Return \code{-1} on failure. This is equivalent to the Python + statement \samp{del \var{o}[\var{key}]}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key} + On success, return \code{1} if the mapping object has the key + \var{key} and \code{0} otherwise. This is equivalent to the Python + expression \samp{\var{o}.has_key(\var{key})}. This function always + succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key} + Return \code{1} if the mapping object has the key \var{key} and + \code{0} otherwise. This is equivalent to the Python expression + \samp{\var{o}.has_key(\var{key})}. This function always succeeds. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o} + On success, return a list of the keys in object \var{o}. On + failure, return \NULL. This is equivalent to the Python expression + \samp{\var{o}.keys()}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o} + On success, return a list of the values in object \var{o}. On + failure, return \NULL. This is equivalent to the Python expression + \samp{\var{o}.values()}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o} + On success, return a list of the items in object \var{o}, where each + item is a tuple containing a key-value pair. On failure, return + \NULL. This is equivalent to the Python expression + \samp{\var{o}.items()}. +\end{cfuncdesc} + + +\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key} + Return element of \var{o} corresponding to the object \var{key} or + \NULL{} on failure. This is the equivalent of the Python expression + \samp{\var{o}[\var{key}]}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key, + PyObject *v} + Map the object \var{key} to the value \var{v} in object \var{o}. + Returns \code{-1} on failure. This is the equivalent of the Python + statement \samp{\var{o}[\var{key}] = \var{v}}. +\end{cfuncdesc} + + +\section{Iterator Protocol \label{iterator}} + +\versionadded{2.2} + +There are only a couple of functions specifically for working with +iterators. + +\begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o} + Return true if the object \var{o} supports the iterator protocol. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyIter_Next}{PyObject *o} + Return the next value from the iteration \var{o}. If the object is + an iterator, this retrieves the next value from the iteration, and + returns \NULL{} with no exception set if there are no remaining + items. If the object is not an iterator, \exception{TypeError} is + raised, or if there is an error in retrieving the item, returns + \NULL{} and passes along the exception. +\end{cfuncdesc} + +To write a loop which iterates over an iterator, the C code should +look something like this: + +\begin{verbatim} +PyObject *iterator = ...; +PyObject *item; + +while (item = PyIter_Next(iter)) { + /* do something with item */ +} +if (PyErr_Occurred()) { + /* propogate error */ +} +else { + /* continue doing useful work */ +} +\end{verbatim} diff --git a/Doc/api/api.tex b/Doc/api/api.tex index 2e2c63e..6fa8c41 100644 --- a/Doc/api/api.tex +++ b/Doc/api/api.tex @@ -26,6148 +26,26 @@ want to write extension modules or embed Python. It is a companion to Interpreter}, which describes the general principles of extension writing but does not document the API functions in detail. -\strong{Warning:} The current version of this document is incomplete. -I hope that it is nevertheless useful. I will continue to work on it, -and release new versions from time to time, independent from Python -source code releases. +\warning{The current version of this document is incomplete. I hope +that it is nevertheless useful. I will continue to work on it, and +release new versions from time to time, independent from Python source +code releases.} \end{abstract} \tableofcontents -% XXX Consider moving all this back to ext.tex and giving api.tex -% XXX a *really* short intro only. -\chapter{Introduction \label{intro}} - -The Application Programmer's Interface to Python gives C and -\Cpp{} programmers access to the Python interpreter at a variety of -levels. The API is equally usable from \Cpp{}, but for brevity it is -generally referred to as the Python/C API. There are two -fundamentally different reasons for using the Python/C API. The first -reason is to write \emph{extension modules} for specific purposes; -these are C modules that extend the Python interpreter. This is -probably the most common use. The second reason is to use Python as a -component in a larger application; this technique is generally -referred to as \dfn{embedding} Python in an application. - -Writing an extension module is a relatively well-understood process, -where a ``cookbook'' approach works well. There are several tools -that automate the process to some extent. While people have embedded -Python in other applications since its early existence, the process of -embedding Python is less straightforward than writing an extension. - -Many API functions are useful independent of whether you're embedding -or extending Python; moreover, most applications that embed Python -will need to provide a custom extension as well, so it's probably a -good idea to become familiar with writing an extension before -attempting to embed Python in a real application. - - -\section{Include Files \label{includes}} - -All function, type and macro definitions needed to use the Python/C -API are included in your code by the following line: - -\begin{verbatim} -#include "Python.h" -\end{verbatim} - -This implies inclusion of the following standard headers: -\code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, -\code{<limits.h>}, and \code{<stdlib.h>} (if available). -Since Python may define some pre-processor definitions which affect -the standard headers on some systems, you must include \file{Python.h} -before any standard headers are included. - -All user visible names defined by Python.h (except those defined by -the included standard headers) have one of the prefixes \samp{Py} or -\samp{_Py}. Names beginning with \samp{_Py} are for internal use by -the Python implementation and should not be used by extension writers. -Structure member names do not have a reserved prefix. - -\strong{Important:} user code should never define names that begin -with \samp{Py} or \samp{_Py}. This confuses the reader, and -jeopardizes the portability of the user code to future Python -versions, which may define additional names beginning with one of -these prefixes. - -The header files are typically installed with Python. On \UNIX, these -are located in the directories -\file{\envvar{prefix}/include/python\var{version}/} and -\file{\envvar{exec_prefix}/include/python\var{version}/}, where -\envvar{prefix} and \envvar{exec_prefix} are defined by the -corresponding parameters to Python's \program{configure} script and -\var{version} is \code{sys.version[:3]}. On Windows, the headers are -installed in \file{\envvar{prefix}/include}, where \envvar{prefix} is -the installation directory specified to the installer. - -To include the headers, place both directories (if different) on your -compiler's search path for includes. Do \emph{not} place the parent -directories on the search path and then use -\samp{\#include <python\shortversion/Python.h>}; this will break on -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}} - -Most Python/C API functions have one or more arguments as well as a -return value of type \ctype{PyObject*}. This type is a pointer -to an opaque data type representing an arbitrary Python -object. Since all Python object types are treated the same way by the -Python language in most situations (e.g., assignments, scope rules, -and argument passing), it is only fitting that they should be -represented by a single C type. Almost all Python objects live on the -heap: you never declare an automatic or static variable of type -\ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can -be declared. The sole exception are the type objects\obindex{type}; -since these must never be deallocated, they are typically static -\ctype{PyTypeObject} objects. - -All Python objects (even Python integers) have a \dfn{type} and a -\dfn{reference count}. An object's type determines what kind of object -it is (e.g., an integer, a list, or a user-defined function; there are -many more as explained in the \citetitle[../ref/ref.html]{Python -Reference Manual}). For each of the well-known types there is a macro -to check whether an object is of that type; for instance, -\samp{PyList_Check(\var{a})} is true if (and only if) the object -pointed to by \var{a} is a Python list. - - -\subsection{Reference Counts \label{refcounts}} - -The reference count is important because today's computers have a -finite (and often severely limited) memory size; it counts how many -different places there are that have a reference to an object. Such a -place could be another object, or a global (or static) C variable, or -a local variable in some C function. When an object's reference count -becomes zero, the object is deallocated. If it contains references to -other objects, their reference count is decremented. Those other -objects may be deallocated in turn, if this decrement makes their -reference count become zero, and so on. (There's an obvious problem -with objects that reference each other here; for now, the solution is -``don't do that.'') - -Reference counts are always manipulated explicitly. The normal way is -to use the macro \cfunction{Py_INCREF()}\ttindex{Py_INCREF()} to -increment an object's reference count by one, and -\cfunction{Py_DECREF()}\ttindex{Py_DECREF()} to decrement it by -one. The \cfunction{Py_DECREF()} macro is considerably more complex -than the incref one, since it must check whether the reference count -becomes zero and then cause the object's deallocator to be called. -The deallocator is a function pointer contained in the object's type -structure. The type-specific deallocator takes care of decrementing -the reference counts for other objects contained in the object if this -is a compound object type, such as a list, as well as performing any -additional finalization that's needed. There's no chance that the -reference count can overflow; at least as many bits are used to hold -the reference count as there are distinct memory locations in virtual -memory (assuming \code{sizeof(long) >= sizeof(char*)}). Thus, the -reference count increment is a simple operation. - -It is not necessary to increment an object's reference count for every -local variable that contains a pointer to an object. In theory, the -object's reference count goes up by one when the variable is made to -point to it and it goes down by one when the variable goes out of -scope. However, these two cancel each other out, so at the end the -reference count hasn't changed. The only real reason to use the -reference count is to prevent the object from being deallocated as -long as our variable is pointing to it. If we know that there is at -least one other reference to the object that lives at least as long as -our variable, there is no need to increment the reference count -temporarily. An important situation where this arises is in objects -that are passed as arguments to C functions in an extension module -that are called from Python; the call mechanism guarantees to hold a -reference to every argument for the duration of the call. - -However, a common pitfall is to extract an object from a list and -hold on to it for a while without incrementing its reference count. -Some other operation might conceivably remove the object from the -list, decrementing its reference count and possible deallocating it. -The real danger is that innocent-looking operations may invoke -arbitrary Python code which could do this; there is a code path which -allows control to flow back to the user from a \cfunction{Py_DECREF()}, -so almost any operation is potentially dangerous. - -A safe approach is to always use the generic operations (functions -whose name begins with \samp{PyObject_}, \samp{PyNumber_}, -\samp{PySequence_} or \samp{PyMapping_}). These operations always -increment the reference count of the object they return. This leaves -the caller with the responsibility to call -\cfunction{Py_DECREF()} when they are done with the result; this soon -becomes second nature. - - -\subsubsection{Reference Count Details \label{refcountDetails}} - -The reference count behavior of functions in the Python/C API is best -explained in terms of \emph{ownership of references}. Note that we -talk of owning references, never of owning objects; objects are always -shared! When a function owns a reference, it has to dispose of it -properly --- either by passing ownership on (usually to its caller) or -by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}. When -a function passes ownership of a reference on to its caller, the -caller is said to receive a \emph{new} reference. When no ownership -is transferred, the caller is said to \emph{borrow} the reference. -Nothing needs to be done for a borrowed reference. - -Conversely, when a calling function passes it a reference to an -object, there are two possibilities: the function \emph{steals} a -reference to the object, or it does not. Few functions steal -references; the two notable exceptions are -\cfunction{PyList_SetItem()}\ttindex{PyList_SetItem()} and -\cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which -steal a reference to the item (but not to the tuple or list into which -the item is put!). These functions were designed to steal a reference -because of a common idiom for populating a tuple or list with newly -created objects; for example, the code to create the tuple \code{(1, -2, "three")} could look like this (forgetting about error handling for -the moment; a better way to code this is shown below): - -\begin{verbatim} -PyObject *t; - -t = PyTuple_New(3); -PyTuple_SetItem(t, 0, PyInt_FromLong(1L)); -PyTuple_SetItem(t, 1, PyInt_FromLong(2L)); -PyTuple_SetItem(t, 2, PyString_FromString("three")); -\end{verbatim} - -Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to -set tuple items; \cfunction{PySequence_SetItem()} and -\cfunction{PyObject_SetItem()} refuse to do this since tuples are an -immutable data type. You should only use -\cfunction{PyTuple_SetItem()} for tuples that you are creating -yourself. - -Equivalent code for populating a list can be written using -\cfunction{PyList_New()} and \cfunction{PyList_SetItem()}. Such code -can also use \cfunction{PySequence_SetItem()}; this illustrates the -difference between the two (the extra \cfunction{Py_DECREF()} calls): - -\begin{verbatim} -PyObject *l, *x; - -l = PyList_New(3); -x = PyInt_FromLong(1L); -PySequence_SetItem(l, 0, x); Py_DECREF(x); -x = PyInt_FromLong(2L); -PySequence_SetItem(l, 1, x); Py_DECREF(x); -x = PyString_FromString("three"); -PySequence_SetItem(l, 2, x); Py_DECREF(x); -\end{verbatim} - -You might find it strange that the ``recommended'' approach takes more -code. However, in practice, you will rarely use these ways of -creating and populating a tuple or list. There's a generic function, -\cfunction{Py_BuildValue()}, that can create most common objects from -C values, directed by a \dfn{format string}. For example, the -above two blocks of code could be replaced by the following (which -also takes care of the error checking): - -\begin{verbatim} -PyObject *t, *l; - -t = Py_BuildValue("(iis)", 1, 2, "three"); -l = Py_BuildValue("[iis]", 1, 2, "three"); -\end{verbatim} - -It is much more common to use \cfunction{PyObject_SetItem()} and -friends with items whose references you are only borrowing, like -arguments that were passed in to the function you are writing. In -that case, their behaviour regarding reference counts is much saner, -since you don't have to increment a reference count so you can give a -reference away (``have it be stolen''). For example, this function -sets all items of a list (actually, any mutable sequence) to a given -item: - -\begin{verbatim} -int set_all(PyObject *target, PyObject *item) -{ - int i, n; - - n = PyObject_Length(target); - if (n < 0) - return -1; - for (i = 0; i < n; i++) { - if (PyObject_SetItem(target, i, item) < 0) - return -1; - } - return 0; -} -\end{verbatim} -\ttindex{set_all()} - -The situation is slightly different for function return values. -While passing a reference to most functions does not change your -ownership responsibilities for that reference, many functions that -return a referece to an object give you ownership of the reference. -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 (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 -don't own the reference --- but if you obtain the same item from the -same list using \cfunction{PySequence_GetItem()} (which happens to -take exactly the same arguments), you do own a reference to the -returned object. - -Here is an example of how you could write a function that computes the -sum of the items in a list of integers; once using -\cfunction{PyList_GetItem()}\ttindex{PyList_GetItem()}, and once using -\cfunction{PySequence_GetItem()}\ttindex{PySequence_GetItem()}. - -\begin{verbatim} -long sum_list(PyObject *list) -{ - int i, n; - long total = 0; - PyObject *item; - - n = PyList_Size(list); - if (n < 0) - return -1; /* Not a list */ - for (i = 0; i < n; i++) { - item = PyList_GetItem(list, i); /* Can't fail */ - if (!PyInt_Check(item)) continue; /* Skip non-integers */ - total += PyInt_AsLong(item); - } - return total; -} -\end{verbatim} -\ttindex{sum_list()} - -\begin{verbatim} -long sum_sequence(PyObject *sequence) -{ - int i, n; - long total = 0; - PyObject *item; - n = PySequence_Length(sequence); - if (n < 0) - return -1; /* Has no length */ - for (i = 0; i < n; i++) { - item = PySequence_GetItem(sequence, i); - if (item == NULL) - return -1; /* Not a sequence, or other failure */ - if (PyInt_Check(item)) - total += PyInt_AsLong(item); - Py_DECREF(item); /* Discard reference ownership */ - } - return total; -} -\end{verbatim} -\ttindex{sum_sequence()} - - -\subsection{Types \label{types}} - -There are few other data types that play a significant role in -the Python/C API; most are simple C types such as \ctype{int}, -\ctype{long}, \ctype{double} and \ctype{char*}. A few structure types -are used to describe static tables used to list the functions exported -by a module or the data attributes of a new object type, and another -is used to describe the value of a complex number. These will -be discussed together with the functions that use them. - - -\section{Exceptions \label{exceptions}} - -The Python programmer only needs to deal with exceptions if specific -error handling is required; unhandled exceptions are automatically -propagated to the caller, then to the caller's caller, and so on, until -they reach the top-level interpreter, where they are reported to the -user accompanied by a stack traceback. - -For C programmers, however, error checking always has to be explicit. -All functions in the Python/C API can raise exceptions, unless an -explicit claim is made otherwise in a function's documentation. In -general, when a function encounters an error, it sets an exception, -discards any object references that it owns, and returns an -error indicator --- usually \NULL{} or \code{-1}. A few functions -return a Boolean true/false result, with false indicating an error. -Very few functions return no explicit error indicator or have an -ambiguous return value, and require explicit testing for errors with -\cfunction{PyErr_Occurred()}\ttindex{PyErr_Occurred()}. - -Exception state is maintained in per-thread storage (this is -equivalent to using global storage in an unthreaded application). A -thread can be in one of two states: an exception has occurred, or not. -The function \cfunction{PyErr_Occurred()} can be used to check for -this: it returns a borrowed reference to the exception type object -when an exception has occurred, and \NULL{} otherwise. There are a -number of functions to set the exception state: -\cfunction{PyErr_SetString()}\ttindex{PyErr_SetString()} is the most -common (though not the most general) function to set the exception -state, and \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} clears the -exception state. - -The full exception state consists of three objects (all of which can -be \NULL{}): the exception type, the corresponding exception -value, and the traceback. These have the same meanings as the Python -\withsubitem{(in module sys)}{ - \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} -objects \code{sys.exc_type}, \code{sys.exc_value}, and -\code{sys.exc_traceback}; however, they are not the same: the Python -objects represent the last exception being handled by a Python -\keyword{try} \ldots\ \keyword{except} statement, while the C level -exception state only exists while an exception is being passed on -between C functions until it reaches the Python bytecode interpreter's -main loop, which takes care of transferring it to \code{sys.exc_type} -and friends. - -Note that starting with Python 1.5, the preferred, thread-safe way to -access the exception state from Python code is to call the function -\withsubitem{(in module sys)}{\ttindex{exc_info()}} -\function{sys.exc_info()}, which returns the per-thread exception state -for Python code. Also, the semantics of both ways to access the -exception state have changed so that a function which catches an -exception will save and restore its thread's exception state so as to -preserve the exception state of its caller. This prevents common bugs -in exception handling code caused by an innocent-looking function -overwriting the exception being handled; it also reduces the often -unwanted lifetime extension for objects that are referenced by the -stack frames in the traceback. - -As a general principle, a function that calls another function to -perform some task should check whether the called function raised an -exception, and if so, pass the exception state on to its caller. It -should discard any object references that it owns, and return an -error indicator, but it should \emph{not} set another exception --- -that would overwrite the exception that was just raised, and lose -important information about the exact cause of the error. - -A simple example of detecting exceptions and passing them on is shown -in the \cfunction{sum_sequence()}\ttindex{sum_sequence()} example -above. It so happens that that example doesn't need to clean up any -owned references when it detects an error. The following example -function shows some error cleanup. First, to remind you why you like -Python, we show the equivalent Python code: - -\begin{verbatim} -def incr_item(dict, key): - try: - item = dict[key] - except KeyError: - item = 0 - dict[key] = item + 1 -\end{verbatim} -\ttindex{incr_item()} - -Here is the corresponding C code, in all its glory: - -\begin{verbatim} -int incr_item(PyObject *dict, PyObject *key) -{ - /* Objects all initialized to NULL for Py_XDECREF */ - PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL; - int rv = -1; /* Return value initialized to -1 (failure) */ - - item = PyObject_GetItem(dict, key); - if (item == NULL) { - /* Handle KeyError only: */ - if (!PyErr_ExceptionMatches(PyExc_KeyError)) - goto error; - - /* Clear the error and use zero: */ - PyErr_Clear(); - item = PyInt_FromLong(0L); - if (item == NULL) - goto error; - } - const_one = PyInt_FromLong(1L); - if (const_one == NULL) - goto error; - - incremented_item = PyNumber_Add(item, const_one); - if (incremented_item == NULL) - goto error; - - if (PyObject_SetItem(dict, key, incremented_item) < 0) - goto error; - rv = 0; /* Success */ - /* Continue with cleanup code */ - - error: - /* Cleanup code, shared by success and failure path */ - - /* Use Py_XDECREF() to ignore NULL references */ - Py_XDECREF(item); - Py_XDECREF(const_one); - Py_XDECREF(incremented_item); - - return rv; /* -1 for error, 0 for success */ -} -\end{verbatim} -\ttindex{incr_item()} - -This example represents an endorsed use of the \keyword{goto} statement -in C! It illustrates the use of -\cfunction{PyErr_ExceptionMatches()}\ttindex{PyErr_ExceptionMatches()} and -\cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} to -handle specific exceptions, and the use of -\cfunction{Py_XDECREF()}\ttindex{Py_XDECREF()} to -dispose of owned references that may be \NULL{} (note the -\character{X} in the name; \cfunction{Py_DECREF()} would crash when -confronted with a \NULL{} reference). It is important that the -variables used to hold owned references are initialized to \NULL{} for -this to work; likewise, the proposed return value is initialized to -\code{-1} (failure) and only set to success after the final call made -is successful. - - -\section{Embedding Python \label{embedding}} - -The one important task that only embedders (as opposed to extension -writers) of the Python interpreter have to worry about is the -initialization, and possibly the finalization, of the Python -interpreter. Most functionality of the interpreter can only be used -after the interpreter has been initialized. - -The basic initialization function is -\cfunction{Py_Initialize()}\ttindex{Py_Initialize()}. -This initializes the table of loaded modules, and creates the -fundamental modules \module{__builtin__}\refbimodindex{__builtin__}, -\module{__main__}\refbimodindex{__main__}, \module{sys}\refbimodindex{sys}, -and \module{exceptions}.\refbimodindex{exceptions} It also initializes -the module search path (\code{sys.path}).% -\indexiii{module}{search}{path} -\withsubitem{(in module sys)}{\ttindex{path}} - -\cfunction{Py_Initialize()} does not set the ``script argument list'' -(\code{sys.argv}). If this variable is needed by Python code that -will be executed later, it must be set explicitly with a call to -\code{PySys_SetArgv(\var{argc}, -\var{argv})}\ttindex{PySys_SetArgv()} subsequent to the call to -\cfunction{Py_Initialize()}. - -On most systems (in particular, on \UNIX{} and Windows, although the -details are slightly different), -\cfunction{Py_Initialize()} calculates the module search path based -upon its best guess for the location of the standard Python -interpreter executable, assuming that the Python library is found in a -fixed location relative to the Python interpreter executable. In -particular, it looks for a directory named -\file{lib/python\shortversion} relative to the parent directory where -the executable named \file{python} is found on the shell command -search path (the environment variable \envvar{PATH}). - -For instance, if the Python executable is found in -\file{/usr/local/bin/python}, it will assume that the libraries are in -\file{/usr/local/lib/python\shortversion}. (In fact, this particular path -is also the ``fallback'' location, used when no executable file named -\file{python} is found along \envvar{PATH}.) The user can override -this behavior by setting the environment variable \envvar{PYTHONHOME}, -or insert additional directories in front of the standard path by -setting \envvar{PYTHONPATH}. - -The embedding application can steer the search by calling -\code{Py_SetProgramName(\var{file})}\ttindex{Py_SetProgramName()} \emph{before} calling -\cfunction{Py_Initialize()}. Note that \envvar{PYTHONHOME} still -overrides this and \envvar{PYTHONPATH} is still inserted in front of -the standard path. An application that requires total control has to -provide its own implementation of -\cfunction{Py_GetPath()}\ttindex{Py_GetPath()}, -\cfunction{Py_GetPrefix()}\ttindex{Py_GetPrefix()}, -\cfunction{Py_GetExecPrefix()}\ttindex{Py_GetExecPrefix()}, and -\cfunction{Py_GetProgramFullPath()}\ttindex{Py_GetProgramFullPath()} (all -defined in \file{Modules/getpath.c}). - -Sometimes, it is desirable to ``uninitialize'' Python. For instance, -the application may want to start over (make another call to -\cfunction{Py_Initialize()}) or the application is simply done with its -use of Python and wants to free all memory allocated by Python. This -can be accomplished by calling \cfunction{Py_Finalize()}. The function -\cfunction{Py_IsInitialized()}\ttindex{Py_IsInitialized()} returns -true if Python is currently in the initialized state. More -information about these functions is given in a later chapter. - - -\chapter{The Very High Level Layer \label{veryhigh}} - -The functions in this chapter will let you execute Python source code -given in a file or a buffer, but they will not let you interact in a -more detailed way with the interpreter. - -Several of these functions accept a start symbol from the grammar as a -parameter. The available start symbols are \constant{Py_eval_input}, -\constant{Py_file_input}, and \constant{Py_single_input}. These are -described following the functions which accept them as parameters. - -Note also that several of these functions take \ctype{FILE*} -parameters. On particular issue which needs to be handled carefully -is that the \ctype{FILE} structure for different C libraries can be -different and incompatible. Under Windows (at least), it is possible -for dynamically linked extensions to actually use different libraries, -so care should be taken that \ctype{FILE*} parameters are only passed -to these functions if it is certain that they were created by the same -library that the Python runtime is using. - -\begin{cfuncdesc}{int}{Py_Main}{int argc, char **argv} - The main program for the standard interpreter. This is made - available for programs which embed Python. The \var{argc} and - \var{argv} parameters should be prepared exactly as those which are - passed to a C program's \cfunction{main()} function. It is - important to note that the argument list may be modified (but the - contents of the strings pointed to by the argument list are not). - The return value will be the integer passed to the - \function{sys.exit()} function, \code{1} if the interpreter exits - due to an exception, or \code{2} if the parameter list does not - represent a valid Python command line. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename} - If \var{fp} refers to a file associated with an interactive device - (console or terminal input or \UNIX{} pseudo-terminal), return the - value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the - result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is - \NULL{}, this function uses \code{"???"} as the filename. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command} - Executes the Python source code from \var{command} in the - \module{__main__} module. If \module{__main__} does not already - exist, it is created. Returns \code{0} on success or \code{-1} if - an exception was raised. If there was an error, there is no way to - get the exception information. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename} - Similar to \cfunction{PyRun_SimpleString()}, but the Python source - code is read from \var{fp} instead of an in-memory string. - \var{filename} should be the name of the file. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename} - Read and execute a single statement from a file associated with an - interactive device. If \var{filename} is \NULL, \code{"???"} is - used instead. The user will be prompted using \code{sys.ps1} and - \code{sys.ps2}. Returns \code{0} when the input was executed - successfully, \code{-1} if there was an exception, or an error code - from the \file{errcode.h} include file distributed as part of Python - in case of a parse error. (Note that \file{errcode.h} is not - included by \file{Python.h}, so must be included specifically if - needed.) -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename} - Read and execute statements from a file associated with an - interactive device until \EOF{} is reached. If \var{filename} is - \NULL, \code{"???"} is used instead. The user will be prompted - using \code{sys.ps1} and \code{sys.ps2}. Returns \code{0} at \EOF. -\end{cfuncdesc} - -\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str, - int start} - Parse Python source code from \var{str} using the start token - \var{start}. The result can be used to create a code object which - can be evaluated efficiently. This is useful if a code fragment - must be evaluated many times. -\end{cfuncdesc} - -\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp, - char *filename, int start} - Similar to \cfunction{PyParser_SimpleParseString()}, but the Python - source code is read from \var{fp} instead of an in-memory string. - \var{filename} should be the name of the file. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start, - PyObject *globals, - PyObject *locals} - Execute Python source code from \var{str} in the context specified - by the dictionaries \var{globals} and \var{locals}. The parameter - \var{start} specifies the start token that should be used to parse - the source code. - - Returns the result of executing the code as a Python object, or - \NULL{} if an exception was raised. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename, - int start, PyObject *globals, - PyObject *locals} - Similar to \cfunction{PyRun_String()}, but the Python source code is - read from \var{fp} instead of an in-memory string. - \var{filename} should be the name of the file. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename, - int start} - Parse and compile the Python source code in \var{str}, returning the - resulting code object. The start token is given by \var{start}; - this can be used to constrain the code which can be compiled and should - be \constant{Py_eval_input}, \constant{Py_file_input}, or - \constant{Py_single_input}. The filename specified by - \var{filename} is used to construct the code object and may appear - in tracebacks or \exception{SyntaxError} exception messages. This - returns \NULL{} if the code cannot be parsed or compiled. -\end{cfuncdesc} - -\begin{cvardesc}{int}{Py_eval_input} - The start symbol from the Python grammar for isolated expressions; - for use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. -\end{cvardesc} - -\begin{cvardesc}{int}{Py_file_input} - The start symbol from the Python grammar for sequences of statements - as read from a file or other source; for use with - \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. This is - the symbol to use when compiling arbitrarily long Python source code. -\end{cvardesc} - -\begin{cvardesc}{int}{Py_single_input} - The start symbol from the Python grammar for a single statement; for - use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. - This is the symbol used for the interactive interpreter loop. -\end{cvardesc} - - -\chapter{Reference Counting \label{countingRefs}} - -The macros in this section are used for managing reference counts -of Python objects. - -\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o} -Increment the reference count for object \var{o}. The object must -not be \NULL{}; if you aren't sure that it isn't \NULL{}, use -\cfunction{Py_XINCREF()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o} -Increment the reference count for object \var{o}. The object may be -\NULL{}, in which case the macro has no effect. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o} -Decrement the reference count for object \var{o}. The object must -not be \NULL{}; if you aren't sure that it isn't \NULL{}, use -\cfunction{Py_XDECREF()}. If the reference count reaches zero, the -object's type's deallocation function (which must not be \NULL{}) is -invoked. - -\strong{Warning:} The deallocation function can cause arbitrary Python -code to be invoked (e.g. when a class instance with a -\method{__del__()} method is deallocated). While exceptions in such -code are not propagated, the executed code has free access to all -Python global variables. This means that any object that is reachable -from a global variable should be in a consistent state before -\cfunction{Py_DECREF()} is invoked. For example, code to delete an -object from a list should copy a reference to the deleted object in a -temporary variable, update the list data structure, and then call -\cfunction{Py_DECREF()} for the temporary variable. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o} -Decrement the reference count for object \var{o}. The object may be -\NULL{}, in which case the macro has no effect; otherwise the effect -is the same as for \cfunction{Py_DECREF()}, and the same warning -applies. -\end{cfuncdesc} - -The following functions or macros are only for use within the -interpreter core: \cfunction{_Py_Dealloc()}, -\cfunction{_Py_ForgetReference()}, \cfunction{_Py_NewReference()}, as -well as the global variable \cdata{_Py_RefTotal}. - - -\chapter{Exception Handling \label{exceptionHandling}} - -The functions described in this chapter will let you handle and raise Python -exceptions. It is important to understand some of the basics of -Python exception handling. It works somewhat like the -\UNIX{} \cdata{errno} variable: there is a global indicator (per -thread) of the last error that occurred. Most functions don't clear -this on success, but will set it to indicate the cause of the error on -failure. Most functions also return an error indicator, usually -\NULL{} if they are supposed to return a pointer, or \code{-1} if they -return an integer (exception: the \cfunction{PyArg_Parse*()} functions -return \code{1} for success and \code{0} for failure). When a -function must fail because some function it called failed, it -generally doesn't set the error indicator; the function it called -already set it. - -The error indicator consists of three Python objects corresponding to -\withsubitem{(in module sys)}{ - \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} -the Python variables \code{sys.exc_type}, \code{sys.exc_value} and -\code{sys.exc_traceback}. API functions exist to interact with the -error indicator in various ways. There is a separate error indicator -for each thread. - -% XXX Order of these should be more thoughtful. -% Either alphabetical or some kind of structure. - -\begin{cfuncdesc}{void}{PyErr_Print}{} -Print a standard traceback to \code{sys.stderr} and clear the error -indicator. Call this function only when the error indicator is set. -(Otherwise it will cause a fatal error!) -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{} -Test whether the error indicator is set. If set, return the exception -\emph{type} (the first argument to the last call to one of the -\cfunction{PyErr_Set*()} functions or to \cfunction{PyErr_Restore()}). If -not set, return \NULL{}. You do not own a reference to the return -value, so you do not need to \cfunction{Py_DECREF()} it. -\strong{Note:} Do not compare the return value to a specific -exception; use \cfunction{PyErr_ExceptionMatches()} instead, shown -below. (The comparison could easily fail since the exception may be -an instance instead of a class, in the case of a class exception, or -it may the a subclass of the expected exception.) -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc} -Equivalent to -\samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}. -This should only be called when an exception is actually set; a memory -access violation will occur if no exception has been raised. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc} -Return true if the \var{given} exception matches the exception in -\var{exc}. If \var{exc} is a class object, this also returns true -when \var{given} is an instance of a subclass. If \var{exc} is a tuple, all -exceptions in the tuple (and recursively in subtuples) are searched -for a match. If \var{given} is \NULL, a memory access violation will -occur. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb} -Under certain circumstances, the values returned by -\cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that -\code{*\var{exc}} is a class object but \code{*\var{val}} is not an -instance of the same class. This function can be used to instantiate -the class in that case. If the values are already normalized, nothing -happens. The delayed normalization is implemented to improve -performance. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyErr_Clear}{} -Clear the error indicator. If the error indicator is not set, there -is no effect. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue, - PyObject **ptraceback} -Retrieve the error indicator into three variables whose addresses are -passed. If the error indicator is not set, set all three variables to -\NULL{}. If it is set, it will be cleared and you own a reference to -each object retrieved. The value and traceback object may be -\NULL{} even when the type object is not. \strong{Note:} This -function is normally only used by code that needs to handle exceptions -or by code that needs to save and restore the error indicator -temporarily. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value, - PyObject *traceback} -Set the error indicator from the three objects. If the error -indicator is already set, it is cleared first. If the objects are -\NULL{}, the error indicator is cleared. Do not pass a \NULL{} type -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: 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 -only used by code that needs to save and restore the error indicator -temporarily. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message} -This is the most common way to set the error indicator. The first -argument specifies the exception type; it is normally one of the -standard exceptions, e.g. \cdata{PyExc_RuntimeError}. You need not -increment its reference count. The second argument is an error -message; it is converted to a string object. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value} -This function is similar to \cfunction{PyErr_SetString()} but lets you -specify an arbitrary Python object for the ``value'' of the exception. -You need not increment its reference count. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception, - const char *format, \moreargs} -This function sets the error indicator. \var{exception} should be a -Python exception (string or class, not an instance). -\var{format} should be a string, containing format codes, similar to -\cfunction{printf}. The \code{width.precision} before a format code -is parsed, but the width part is ignored. - -\begin{tableii}{c|l}{character}{Character}{Meaning} - \lineii{c}{Character, as an \ctype{int} parameter} - \lineii{d}{Number in decimal, as an \ctype{int} parameter} - \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter} - \lineii{x}{A string, as a \ctype{char *} parameter} -\end{tableii} - -An unrecognized format character causes all the rest of -the format string to be copied as-is to the result string, -and any extra arguments discarded. - -A new reference is returned, which is owned by the caller. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type} -This is a shorthand for \samp{PyErr_SetObject(\var{type}, Py_None)}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyErr_BadArgument}{} -This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError, -\var{message})}, where \var{message} indicates that a built-in operation -was invoked with an illegal argument. It is mostly for internal use. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{} -This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it -returns \NULL{} so an object allocation function can write -\samp{return PyErr_NoMemory();} when it runs out of memory. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type} -This is a convenience function to raise an exception when a C library -function has returned an error and set the C variable \cdata{errno}. -It constructs a tuple object whose first item is the integer -\cdata{errno} value and whose second item is the corresponding error -message (gotten from \cfunction{strerror()}\ttindex{strerror()}), and -then calls -\samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX{}, when -the \cdata{errno} value is \constant{EINTR}, indicating an interrupted -system call, this calls \cfunction{PyErr_CheckSignals()}, and if that set -the error indicator, leaves it set to that. The function always -returns \NULL{}, so a wrapper function around a system call can write -\samp{return PyErr_SetFromErrno();} when the system call returns an -error. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type, - char *filename} -Similar to \cfunction{PyErr_SetFromErrno()}, with the additional -behavior that if \var{filename} is not \NULL, it is passed to the -constructor of \var{type} as a third parameter. In the case of -exceptions such as \exception{IOError} and \exception{OSError}, this -is used to define the \member{filename} attribute of the exception -instance. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyErr_BadInternalCall}{} -This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError, -\var{message})}, where \var{message} indicates that an internal -operation (e.g. a Python/C API function) was invoked with an illegal -argument. It is mostly for internal use. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message} -Issue a warning message. The \var{category} argument is a warning -category (see below) or \NULL; the \var{message} argument is a message -string. - -This function normally prints a warning message to \var{sys.stderr}; -however, it is also possible that the user has specified that warnings -are to be turned into errors, and in that case this will raise an -exception. It is also possible that the function raises an exception -because of a problem with the warning machinery (the implementation -imports the \module{warnings} module to do the heavy lifting). The -return value is \code{0} if no exception is raised, or \code{-1} if -an exception is raised. (It is not possible to determine whether a -warning message is actually printed, nor what the reason is for the -exception; this is intentional.) If an exception is raised, the -caller should do its normal exception handling -(e.g. \cfunction{Py_DECREF()} owned references and return an error -value). - -Warning categories must be subclasses of \cdata{Warning}; the default -warning category is \cdata{RuntimeWarning}. The standard Python -warning categories are available as global variables whose names are -\samp{PyExc_} followed by the Python exception name. These have the -type \ctype{PyObject*}; they are all class objects. Their names are -\cdata{PyExc_Warning}, \cdata{PyExc_UserWarning}, -\cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, and -\cdata{PyExc_RuntimeWarning}. \cdata{PyExc_Warning} is a subclass of -\cdata{PyExc_Exception}; the other warning categories are subclasses -of \cdata{PyExc_Warning}. - -For information about warning control, see the documentation for the -\module{warnings} module and the \programopt{-W} option in the command -line documentation. There is no C API for warning control. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message, -char *filename, int lineno, char *module, PyObject *registry} -Issue a warning message with explicit control over all warning -attributes. This is a straightforward wrapper around the Python -function \function{warnings.warn_explicit()}, see there for more -information. The \var{module} and \var{registry} arguments may be -set to \code{NULL} to get the default effect described there. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyErr_CheckSignals}{} -This function interacts with Python's signal handling. It checks -whether a signal has been sent to the processes and if so, invokes the -corresponding signal handler. If the -\module{signal}\refbimodindex{signal} module is supported, this can -invoke a signal handler written in Python. In all cases, the default -effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the -\withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} -\exception{KeyboardInterrupt} exception. If an exception is raised the -error indicator is set and the function returns \code{1}; otherwise -the function returns \code{0}. The error indicator may or may not be -cleared if it was previously set. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyErr_SetInterrupt}{} -This function is obsolete. It simulates the effect of a -\constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time -\cfunction{PyErr_CheckSignals()} is called, -\withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} -\exception{KeyboardInterrupt} will be raised. -It may be called without holding the interpreter lock. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name, - PyObject *base, - PyObject *dict} -This utility function creates and returns a new exception object. The -\var{name} argument must be the name of the new exception, a C string -of the form \code{module.class}. The \var{base} and -\var{dict} arguments are normally \NULL{}. This creates a -class object derived from the root for all exceptions, the built-in -name \exception{Exception} (accessible in C as -\cdata{PyExc_Exception}). The \member{__module__} attribute of the -new class is set to the first part (up to the last dot) of the -\var{name} argument, and the class name is set to the last part (after -the last dot). The \var{base} argument can be used to specify an -alternate base class. The \var{dict} argument can be used to specify -a dictionary of class variables and methods. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj} -This utility function prints a warning message to \var{sys.stderr} -when an exception has been set but it is impossible for the -interpreter to actually raise the exception. It is used, for example, -when an exception occurs in an \member{__del__} method. - -The function is called with a single argument \var{obj} that -identifies where the context in which the unraisable exception -occurred. The repr of \var{obj} will be printed in the warning -message. -\end{cfuncdesc} - -\section{Standard Exceptions \label{standardExceptions}} - -All standard Python exceptions are available as global variables whose -names are \samp{PyExc_} followed by the Python exception name. These -have the type \ctype{PyObject*}; they are all class objects. For -completeness, here are all the variables: - -\begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes} - \lineiii{PyExc_Exception}{\exception{Exception}}{(1)} - \lineiii{PyExc_StandardError}{\exception{StandardError}}{(1)} - \lineiii{PyExc_ArithmeticError}{\exception{ArithmeticError}}{(1)} - \lineiii{PyExc_LookupError}{\exception{LookupError}}{(1)} - \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{} - \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{} - \lineiii{PyExc_EOFError}{\exception{EOFError}}{} - \lineiii{PyExc_EnvironmentError}{\exception{EnvironmentError}}{(1)} - \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{} - \lineiii{PyExc_IOError}{\exception{IOError}}{} - \lineiii{PyExc_ImportError}{\exception{ImportError}}{} - \lineiii{PyExc_IndexError}{\exception{IndexError}}{} - \lineiii{PyExc_KeyError}{\exception{KeyError}}{} - \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{} - \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{} - \lineiii{PyExc_NameError}{\exception{NameError}}{} - \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{} - \lineiii{PyExc_OSError}{\exception{OSError}}{} - \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{} - \lineiii{PyExc_ReferenceError}{\exception{ReferenceError}}{(2)} - \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{} - \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{} - \lineiii{PyExc_SystemError}{\exception{SystemError}}{} - \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{} - \lineiii{PyExc_TypeError}{\exception{TypeError}}{} - \lineiii{PyExc_ValueError}{\exception{ValueError}}{} - \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(3)} - \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{} -\end{tableiii} - -\noindent -Notes: -\begin{description} -\item[(1)] - This is a base class for other standard exceptions. - -\item[(2)] - This is the same as \exception{weakref.ReferenceError}. - -\item[(3)] - Only defined on Windows; protect code that uses this by testing that - the preprocessor macro \code{MS_WINDOWS} is defined. -\end{description} - - -\section{Deprecation of String Exceptions} - -All exceptions built into Python or provided in the standard library -are derived from \exception{Exception}. -\withsubitem{(built-in exception)}{\ttindex{Exception}} - -String exceptions are still supported in the interpreter to allow -existing code to run unmodified, but this will also change in a future -release. - - -\chapter{Utilities \label{utilities}} - -The functions in this chapter perform various utility tasks, ranging -from helping C code be more portable across platforms, using Python -modules from C, and parsing function arguments and constructing Python -values from C values. - - -\section{Operating System Utilities \label{os}} - -\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename} -Return true (nonzero) if the standard I/O file \var{fp} with name -\var{filename} is deemed interactive. This is the case for files for -which \samp{isatty(fileno(\var{fp}))} is true. If the global flag -\cdata{Py_InteractiveFlag} is true, this function also returns true if -the \var{filename} pointer is \NULL{} or if the name is equal to one of -the strings \code{'<stdin>'} or \code{'???'}. -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename} -Return the time of last modification of the file \var{filename}. -The result is encoded in the same way as the timestamp returned by -the standard C library function \cfunction{time()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyOS_AfterFork}{} -Function to update some internal state after a process fork; this -should be called in the new process if the Python interpreter will -continue to be used. If a new executable is loaded into the new -process, this function does not need to be called. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyOS_CheckStack}{} -Return true when the interpreter runs out of stack space. This is a -reliable check, but is only available when \code{USE_STACKCHECK} is -defined (currently on Windows using the Microsoft Visual C++ compiler -and on the Macintosh). \code{USE_CHECKSTACK} will be defined -automatically; you should never change the definition in your own -code. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_getsig}{int i} -Return the current signal handler for signal \var{i}. -This is a thin wrapper around either \cfunction{sigaction} or -\cfunction{signal}. Do not call those functions directly! -\ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void (*)(int)}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_setsig}{int i, PyOS_sighandler_t h} -Set the signal handler for signal \var{i} to be \var{h}; -return the old signal handler. -This is a thin wrapper around either \cfunction{sigaction} or -\cfunction{signal}. Do not call those functions directly! -\ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void (*)(int)}. -\end{cfuncdesc} - - -\section{Process Control \label{processControl}} - -\begin{cfuncdesc}{void}{Py_FatalError}{char *message} -Print a fatal error message and kill the process. No cleanup is -performed. This function should only be invoked when a condition is -detected that would make it dangerous to continue using the Python -interpreter; e.g., when the object administration appears to be -corrupted. On \UNIX{}, the standard C library function -\cfunction{abort()}\ttindex{abort()} is called which will attempt to -produce a \file{core} file. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{Py_Exit}{int status} -Exit the current process. This calls -\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and -then calls the standard C library function -\code{exit(\var{status})}\ttindex{exit()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()} -Register a cleanup function to be called by -\cfunction{Py_Finalize()}\ttindex{Py_Finalize()}. -The cleanup function will be called with no arguments and should -return no value. At most 32 \index{cleanup functions}cleanup -functions can be registered. -When the registration is successful, \cfunction{Py_AtExit()} returns -\code{0}; on failure, it returns \code{-1}. The cleanup function -registered last is called first. Each cleanup function will be called -at most once. Since Python's internal finallization will have -completed before the cleanup function, no Python APIs should be called -by \var{func}. -\end{cfuncdesc} - - -\section{Importing Modules \label{importing}} - -\begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{char *name} -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 (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 -case. (Unfortunately, this has an additional side effect when -\var{name} in fact specifies a subpackage instead of a submodule: the -submodules specified in the package's \code{__all__} variable are -\index{package variable!\code{__all__}} -\withsubitem{(package variable)}{\ttindex{__all__}}loaded.) Return a -new reference to the imported module, or -\NULL{} with an exception set on failure (the module may still be -created in this case --- examine \code{sys.modules} to find out). -\withsubitem{(in module sys)}{\ttindex{modules}} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, - PyObject *globals, PyObject *locals, PyObject *fromlist} -Import a module. This is best described by referring to the built-in -Python function \function{__import__()}\bifuncindex{__import__}, as -the standard \function{__import__()} function calls this function -directly. - -The return value is a new reference to the imported module or -top-level package, or \NULL{} with an exception set on failure -(the module may still be created in this case). Like for -\function{__import__()}, the return value when a submodule of a -package was requested is normally the top-level package, unless a -non-empty \var{fromlist} was given. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyImport_Import}{PyObject *name} -This is a higher-level interface that calls the current ``import hook -function''. It invokes the \function{__import__()} function from the -\code{__builtins__} of the current globals. This means that the -import is done using whatever import hooks are installed in the -current environment, e.g. by \module{rexec}\refstmodindex{rexec} or -\module{ihooks}\refstmodindex{ihooks}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyImport_ReloadModule}{PyObject *m} -Reload a module. This is best described by referring to the built-in -Python function \function{reload()}\bifuncindex{reload}, as the standard -\function{reload()} function calls this function directly. Return a -new reference to the reloaded module, or \NULL{} with an exception set -on failure (the module still exists in this case). -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyImport_AddModule}{char *name} -Return the module object corresponding to a module name. The -\var{name} argument may be of the form \code{package.module}). First -check the modules dictionary if there's one there, and if not, create -a new one and insert in in the modules dictionary. -Warning: this function does not load or import the module; if the -module wasn't already loaded, you will get an empty module object. -Use \cfunction{PyImport_ImportModule()} or one of its variants to -import a module. -Return \NULL{} with an exception set on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyImport_ExecCodeModule}{char *name, PyObject *co} -Given a module name (possibly of the form \code{package.module}) and a -code object read from a Python bytecode file or obtained from the -built-in function \function{compile()}\bifuncindex{compile}, load the -module. Return a new reference to the module object, or \NULL{} with -an exception set if an error occurred (the module may still be created -in this case). (This function would reload the module if it was -already imported.) -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{} -Return the magic number for Python bytecode files (a.k.a. -\file{.pyc} and \file{.pyo} files). The magic number should be -present in the first four bytes of the bytecode file, in little-endian -byte order. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyImport_GetModuleDict}{} -Return the dictionary used for the module administration -(a.k.a. \code{sys.modules}). Note that this is a per-interpreter -variable. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{_PyImport_Init}{} -Initialize the import mechanism. For internal use only. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyImport_Cleanup}{} -Empty the module table. For internal use only. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{_PyImport_Fini}{} -Finalize the import mechanism. For internal use only. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *} -For internal use only. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *} -For internal use only. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name} -Load a frozen module named \var{name}. Return \code{1} for success, -\code{0} if the module is not found, and \code{-1} with an exception -set if the initialization failed. To access the imported module on a -successful load, use \cfunction{PyImport_ImportModule()}. -(Note the misnomer --- this function would reload the module if it was -already imported.) -\end{cfuncdesc} - -\begin{ctypedesc}[_frozen]{struct _frozen} -This is the structure type definition for frozen module descriptors, -as generated by the \program{freeze}\index{freeze utility} utility -(see \file{Tools/freeze/} in the Python source distribution). Its -definition, found in \file{Include/import.h}, is: - -\begin{verbatim} -struct _frozen { - char *name; - unsigned char *code; - int size; -}; -\end{verbatim} -\end{ctypedesc} - -\begin{cvardesc}{struct _frozen*}{PyImport_FrozenModules} -This pointer is initialized to point to an array of \ctype{struct -_frozen} records, terminated by one whose members are all -\NULL{} or zero. When a frozen module is imported, it is searched in -this table. Third-party code could play tricks with this to provide a -dynamically created collection of frozen modules. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name, - void (*initfunc)(void)} -Add a single module to the existing table of built-in modules. This -is a convenience wrapper around \cfunction{PyImport_ExtendInittab()}, -returning \code{-1} if the table could not be extended. The new -module can be imported by the name \var{name}, and uses the function -\var{initfunc} as the initialization function called on the first -attempted import. This should be called before -\cfunction{Py_Initialize()}. -\end{cfuncdesc} - -\begin{ctypedesc}[_inittab]{struct _inittab} -Structure describing a single entry in the list of built-in modules. -Each of these structures gives the name and initialization function -for a module built into the interpreter. Programs which embed Python -may use an array of these structures in conjunction with -\cfunction{PyImport_ExtendInittab()} to provide additional built-in -modules. The structure is defined in \file{Include/import.h} as: - -\begin{verbatim} -struct _inittab { - char *name; - void (*initfunc)(void); -}; -\end{verbatim} -\end{ctypedesc} - -\begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab} -Add a collection of modules to the table of built-in modules. The -\var{newtab} array must end with a sentinel entry which contains -\NULL{} for the \member{name} field; failure to provide the sentinel -value can result in a memory fault. Returns \code{0} on success or -\code{-1} if insufficient memory could be allocated to extend the -internal table. In the event of failure, no modules are added to the -internal table. This should be called before -\cfunction{Py_Initialize()}. -\end{cfuncdesc} - - -\section{Parsing arguments and building values - \label{arg-parsing}} - -These functions are useful when creating your own extensions functions -and methods. Additional information and examples are available in -\citetitle[../ext/ext.html]{Extending and Embedding the Python -Interpreter}. - -\begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format, - \moreargs} - Parse the parameters of a function that takes only positional - parameters into local variables. Returns true on success; on - failure, it returns false and raises the appropriate exception. 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. Returns true on success; - on failure, it returns false and raises the appropriate exception. - 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 use in parameter parsing in new code, and most code - in the standard interpreter has been modified to no longer use this - for that purpose. It does remain a convenient way to decompose - other tuples, however, and may continue to be used for that - purpose. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{Py_BuildValue}{char *format, - \moreargs} - Create a new value based on a format string similar to those - accepted by the \cfunction{PyArg_Parse*()} family of functions and a - sequence of values. Returns the value or \NULL{} in the case of an - error; an exception will be raised if \NULL{} is returned. For more - information on the format string and additional parameters, see - \citetitle[../ext/buildValue.html]{Extending and Embedding the - Python Interpreter}. -\end{cfuncdesc} - - - -\chapter{Abstract Objects Layer \label{abstract}} - -The functions in this chapter interact with Python objects regardless -of their type, or with wide classes of object types (e.g. all -numerical types, or all sequence types). When used on object types -for which they do not apply, they will raise a Python exception. - -\section{Object Protocol \label{object}} - -\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags} -Print an object \var{o}, on file \var{fp}. Returns \code{-1} on error. -The flags argument is used to enable certain printing options. The -only option currently supported is \constant{Py_PRINT_RAW}; if given, -the \function{str()} of the object is written instead of the -\function{repr()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name} -Returns \code{1} if \var{o} has the attribute \var{attr_name}, and -\code{0} otherwise. This is equivalent to the Python expression -\samp{hasattr(\var{o}, \var{attr_name})}. -This function always succeeds. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, - char *attr_name} -Retrieve an attribute named \var{attr_name} from object \var{o}. -Returns the attribute value on success, or \NULL{} on failure. -This is the equivalent of the Python expression -\samp{\var{o}.\var{attr_name}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name} -Returns \code{1} if \var{o} has the attribute \var{attr_name}, and -\code{0} otherwise. This is equivalent to the Python expression -\samp{hasattr(\var{o}, \var{attr_name})}. -This function always succeeds. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, - PyObject *attr_name} -Retrieve an attribute named \var{attr_name} from object \var{o}. -Returns the attribute value on success, or \NULL{} on failure. -This is the equivalent of the Python expression -\samp{\var{o}.\var{attr_name}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, - char *attr_name, PyObject *v} -Set the value of the attribute named \var{attr_name}, for object -\var{o}, to the value \var{v}. Returns \code{-1} on failure. This is -the equivalent of the Python statement \samp{\var{o}.\var{attr_name} = -\var{v}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, - PyObject *attr_name, PyObject *v} -Set the value of the attribute named \var{attr_name}, for -object \var{o}, -to the value \var{v}. Returns \code{-1} on failure. This is -the equivalent of the Python statement \samp{\var{o}.\var{attr_name} = -\var{v}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name} -Delete attribute named \var{attr_name}, for object \var{o}. Returns -\code{-1} on failure. This is the equivalent of the Python -statement: \samp{del \var{o}.\var{attr_name}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name} -Delete attribute named \var{attr_name}, for object \var{o}. Returns -\code{-1} on failure. This is the equivalent of the Python -statement \samp{del \var{o}.\var{attr_name}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result} -Compare the values of \var{o1} and \var{o2} using a routine provided -by \var{o1}, if one exists, otherwise with a routine provided by -\var{o2}. The result of the comparison is returned in \var{result}. -Returns \code{-1} on failure. This is the equivalent of the Python -statement\bifuncindex{cmp} \samp{\var{result} = cmp(\var{o1}, \var{o2})}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2} -Compare the values of \var{o1} and \var{o2} using a routine provided -by \var{o1}, if one exists, otherwise with a routine provided by -\var{o2}. Returns the result of the comparison on success. On error, -the value returned is undefined; use \cfunction{PyErr_Occurred()} to -detect an error. This is equivalent to the Python -expression\bifuncindex{cmp} \samp{cmp(\var{o1}, \var{o2})}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o} -Compute a string representation of object \var{o}. Returns the -string representation on success, \NULL{} on failure. This is -the equivalent of the Python expression \samp{repr(\var{o})}. -Called by the \function{repr()}\bifuncindex{repr} built-in function -and by reverse quotes. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o} -Compute a string representation of object \var{o}. Returns the -string representation on success, \NULL{} on failure. This is -the equivalent of the Python expression \samp{str(\var{o})}. -Called by the \function{str()}\bifuncindex{str} built-in function and -by the \keyword{print} statement. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyObject_Unicode}{PyObject *o} -Compute a Unicode string representation of object \var{o}. Returns the -Unicode string representation on success, \NULL{} on failure. This is -the equivalent of the Python expression \samp{unistr(\var{o})}. -Called by the \function{unistr()}\bifuncindex{unistr} built-in function. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls} -Return \code{1} if \var{inst} is an instance of the class \var{cls} or -a subclass of \var{cls}. If \var{cls} is a type object rather than a -class object, \cfunction{PyObject_IsInstance()} returns \code{1} if -\var{inst} is of type \var{cls}. If \var{inst} is not a class -instance and \var{cls} is neither a type object or class object, -\var{inst} must have a \member{__class__} attribute --- the class -relationship of the value of that attribute with \var{cls} will be -used to determine the result of this function. -\versionadded{2.1} -\end{cfuncdesc} - -Subclass determination is done in a fairly straightforward way, but -includes a wrinkle that implementors of extensions to the class system -may want to be aware of. If \class{A} and \class{B} are class -objects, \class{B} is a subclass of \class{A} if it inherits from -\class{A} either directly or indirectly. If either is not a class -object, a more general mechanism is used to determine the class -relationship of the two objects. When testing if \var{B} is a -subclass of \var{A}, if \var{A} is \var{B}, -\cfunction{PyObject_IsSubclass()} returns true. If \var{A} and -\var{B} are different objects, \var{B}'s \member{__bases__} attribute -is searched in a depth-first fashion for \var{A} --- the presence of -the \member{__bases__} attribute is considered sufficient for this -determination. - -\begin{cfuncdesc}{int}{PyObject_IsSubclass}{PyObject *derived, - PyObject *cls} -Returns \code{1} if the class \var{derived} is identical to or derived -from the class \var{cls}, otherwise returns \code{0}. In case of an -error, returns \code{-1}. If either \var{derived} or \var{cls} is not -an actual class object, this function uses the generic algorithm -described above. -\versionadded{2.1} -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o} -Determine if the object \var{o} is callable. Return \code{1} if the -object is callable and \code{0} otherwise. -This function always succeeds. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, - PyObject *args} -Call a callable Python object \var{callable_object}, with -arguments given by the tuple \var{args}. If no arguments are -needed, then \var{args} may be \NULL{}. Returns the result of the -call on success, or \NULL{} on failure. This is the equivalent -of the Python expression \samp{apply(\var{callable_object}, -\var{args})} or \samp{\var{callable_object}(*\var{args})}. -\bifuncindex{apply} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, - char *format, ...} -Call a callable Python object \var{callable_object}, with a -variable number of C arguments. The C arguments are described -using a \cfunction{Py_BuildValue()} style format string. The format may -be \NULL{}, indicating that no arguments are provided. Returns the -result of the call on success, or \NULL{} on failure. This is -the equivalent of the Python expression -\samp{apply(\var{callable_object}\var{args})} or -\samp{\var{callable_object}(*\var{args})}. -\bifuncindex{apply} -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, - char *method, char *format, ...} -Call the method named \var{m} of object \var{o} with a variable number -of C arguments. The C arguments are described by a -\cfunction{Py_BuildValue()} format string. The format may be \NULL{}, -indicating that no arguments are provided. Returns the result of the -call on success, or \NULL{} on failure. This is the equivalent of the -Python expression \samp{\var{o}.\var{method}(\var{args})}. -Note that special method names, such as \method{__add__()}, -\method{__getitem__()}, and so on are not supported. The specific -abstract-object routines for these must be used. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o} -Compute and return the hash value of an object \var{o}. On -failure, return \code{-1}. This is the equivalent of the Python -expression \samp{hash(\var{o})}.\bifuncindex{hash} -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o} -Returns \code{1} if the object \var{o} is considered to be true, and -\code{0} otherwise. This is equivalent to the Python expression -\samp{not not \var{o}}. -This function always succeeds. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o} -When \var{o} is non-\NULL, returns a type object corresponding to the -object type of object \var{o}. On failure, raises -\exception{SystemError} and returns \NULL. This is equivalent to the -Python expression \code{type(\var{o})}. -\bifuncindex{type} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyObject_TypeCheck}{PyObject *o, PyTypeObject *type} -Return true if the object \var{o} is of type \var{type} or a subtype -of \var{type}. Both parameters must be non-\NULL. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o} -Return the length of object \var{o}. If the object \var{o} provides -both sequence and mapping protocols, the sequence length is -returned. On error, \code{-1} is returned. This is the equivalent -to the Python expression \samp{len(\var{o})}.\bifuncindex{len} -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key} -Return element of \var{o} corresponding to the object \var{key} or -\NULL{} on failure. This is the equivalent of the Python expression -\samp{\var{o}[\var{key}]}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, - PyObject *key, PyObject *v} -Map the object \var{key} to the value \var{v}. -Returns \code{-1} on failure. This is the equivalent -of the Python statement \samp{\var{o}[\var{key}] = \var{v}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key} -Delete the mapping for \var{key} from \var{o}. Returns \code{-1} on -failure. This is the equivalent of the Python statement \samp{del -\var{o}[\var{key}]}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o} -Derives a file-descriptor from a Python object. If the object -is an integer or long integer, its value is returned. If not, the -object's \method{fileno()} method is called if it exists; the method -must return an integer or long integer, which is returned as the file -descriptor value. Returns \code{-1} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyObject_Dir}{PyObject *o} -This is equivalent to the Python expression \samp{dir(\var{o})}, -returning a (possibly empty) list of strings appropriate for the -object argument, or \NULL{} in case of error. -If the argument is \NULL{}, this is like the Python \samp{dir()}, -returning the names of the current locals; in this case, if no -execution frame is active then \NULL{} is returned but -\cfunction{PyErr_Occurred()} will return false. -\end{cfuncdesc} - - -\section{Number Protocol \label{number}} - -\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o} -Returns \code{1} if the object \var{o} provides numeric protocols, and -false otherwise. -This function always succeeds. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2} -Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on -failure. This is the equivalent of the Python expression -\samp{\var{o1} + \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2} -Returns the result of subtracting \var{o2} from \var{o1}, or -\NULL{} on failure. This is the equivalent of the Python expression -\samp{\var{o1} - \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2} -Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on -failure. This is the equivalent of the Python expression -\samp{\var{o1} * \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2} -Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on -failure. -This is the equivalent of the Python expression \samp{\var{o1} / -\var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_FloorDivide}{PyObject *o1, PyObject *o2} -Return the floor of \var{o1} divided by \var{o2}, or \NULL{} on -failure. This is equivalent to the ``classic'' division of integers. -\versionadded{2.2} -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_TrueDivide}{PyObject *o1, PyObject *o2} -Return a reasonable approximation for the mathematical value of -\var{o1} divided by \var{o2}, or \NULL{} on failure. The return value -is ``approximate'' because binary floating point numbers are -approximate; it is not possible to represent all real numbers in base -two. This function can return a floating point value when passed two -integers. -\versionadded{2.2} -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2} -Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on -failure. This is the equivalent of the Python expression -\samp{\var{o1} \%\ \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2} -See the built-in function \function{divmod()}\bifuncindex{divmod}. -Returns \NULL{} on failure. This is the equivalent of the Python -expression \samp{divmod(\var{o1}, \var{o2})}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, - PyObject *o2, PyObject *o3} -See the built-in function \function{pow()}\bifuncindex{pow}. Returns -\NULL{} on failure. This is the equivalent of the Python expression -\samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3} is optional. -If \var{o3} is to be ignored, pass \cdata{Py_None} in its place -(passing \NULL{} for \var{o3} would cause an illegal memory access). -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o} -Returns the negation of \var{o} on success, or \NULL{} on failure. -This is the equivalent of the Python expression \samp{-\var{o}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o} -Returns \var{o} on success, or \NULL{} on failure. -This is the equivalent of the Python expression \samp{+\var{o}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o} -Returns the absolute value of \var{o}, or \NULL{} on failure. This is -the equivalent of the Python expression \samp{abs(\var{o})}. -\bifuncindex{abs} -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o} -Returns the bitwise negation of \var{o} on success, or \NULL{} on -failure. This is the equivalent of the Python expression -\samp{\~\var{o}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2} -Returns the result of left shifting \var{o1} by \var{o2} on success, -or \NULL{} on failure. This is the equivalent of the Python -expression \samp{\var{o1} <\code{<} \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2} -Returns the result of right shifting \var{o1} by \var{o2} on success, -or \NULL{} on failure. This is the equivalent of the Python -expression \samp{\var{o1} >\code{>} \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2} -Returns the ``bitwise and'' of \var{o2} and \var{o2} on success and -\NULL{} on failure. This is the equivalent of the Python expression -\samp{\var{o1} \&\ \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2} -Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on success, -or \NULL{} on failure. This is the equivalent of the Python -expression \samp{\var{o1} \textasciicircum{} \var{o2}}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2} -Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or -\NULL{} on failure. This is the equivalent of the Python expression -\samp{\var{o1} | \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAdd}{PyObject *o1, PyObject *o2} -Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on -failure. The operation is done \emph{in-place} when \var{o1} supports -it. This is the equivalent of the Python statement \samp{\var{o1} += -\var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1, - PyObject *o2} -Returns the result of subtracting \var{o2} from \var{o1}, or -\NULL{} on failure. The operation is done \emph{in-place} when -\var{o1} supports it. This is the equivalent of the Python statement -\samp{\var{o1} -= \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1, - PyObject *o2} -Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on -failure. The operation is done \emph{in-place} when \var{o1} supports it. -This is the equivalent of the Python statement \samp{\var{o1} *= \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1, - PyObject *o2} -Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on -failure. The operation is done \emph{in-place} when \var{o1} supports -it. This is the equivalent of the Python statement \samp{\var{o1} /= -\var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceFloorDivide}{PyObject *o1, - PyObject *o2} -Returns the mathematical of dividing \var{o1} by \var{o2}, or \NULL{} -on failure. The operation is done \emph{in-place} when \var{o1} -supports it. This is the equivalent of the Python statement -\samp{\var{o1} //= \var{o2}}. -\versionadded{2.2} -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceTrueDivide}{PyObject *o1, - PyObject *o2} -Return a reasonable approximation for the mathematical value of -\var{o1} divided by \var{o2}, or \NULL{} on failure. The return value -is ``approximate'' because binary floating point numbers are -approximate; it is not possible to represent all real numbers in base -two. This function can return a floating point value when passed two -integers. The operation is done \emph{in-place} when \var{o1} -supports it. -\versionadded{2.2} -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1, - PyObject *o2} -Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on -failure. The operation is done \emph{in-place} when \var{o1} supports it. -This is the equivalent of the Python statement \samp{\var{o1} \%= \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1, - PyObject *o2, PyObject *o3} -See the built-in function \function{pow()}.\bifuncindex{pow} Returns -\NULL{} on failure. The operation is done \emph{in-place} when -\var{o1} supports it. This is the equivalent of the Python statement -\samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None}, or an -in-place variant of \samp{pow(\var{o1}, \var{o2}, \var{o3})} -otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its -place (passing \NULL{} for \var{o3} would cause an illegal memory -access). -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1, - PyObject *o2} -Returns the result of left shifting \var{o1} by \var{o2} on success, -or \NULL{} on failure. The operation is done \emph{in-place} when -\var{o1} supports it. This is the equivalent of the Python statement -\samp{\var{o1} <\code{<=} \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1, - PyObject *o2} -Returns the result of right shifting \var{o1} by \var{o2} on success, -or \NULL{} on failure. The operation is done \emph{in-place} when -\var{o1} supports it. This is the equivalent of the Python statement -\samp{\var{o1} >\code{>=} \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAnd}{PyObject *o1, PyObject *o2} -Returns the ``bitwise and'' of \var{o1} and \var{o2} on success -and \NULL{} on failure. The operation is done \emph{in-place} when -\var{o1} supports it. This is the equivalent of the Python statement -\samp{\var{o1} \&= \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2} -Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on -success, or \NULL{} on failure. The operation is done \emph{in-place} -when \var{o1} supports it. This is the equivalent of the Python -statement \samp{\var{o1} \textasciicircum= \var{o2}}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2} -Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or -\NULL{} on failure. The operation is done \emph{in-place} when -\var{o1} supports it. This is the equivalent of the Python statement -\samp{\var{o1} |= \var{o2}}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyNumber_Coerce}{PyObject **p1, PyObject **p2} -This function takes the addresses of two variables of type -\ctype{PyObject*}. If the objects pointed to by \code{*\var{p1}} and -\code{*\var{p2}} have the same type, increment their reference count -and return \code{0} (success). If the objects can be converted to a -common numeric type, replace \code{*p1} and \code{*p2} by their -converted value (with 'new' reference counts), and return \code{0}. -If no conversion is possible, or if some other error occurs, return -\code{-1} (failure) and don't increment the reference counts. The -call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python -statement \samp{\var{o1}, \var{o2} = coerce(\var{o1}, \var{o2})}. -\bifuncindex{coerce} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o} -Returns the \var{o} converted to an integer object on success, or -\NULL{} on failure. This is the equivalent of the Python -expression \samp{int(\var{o})}.\bifuncindex{int} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o} -Returns the \var{o} converted to a long integer object on success, -or \NULL{} on failure. This is the equivalent of the Python -expression \samp{long(\var{o})}.\bifuncindex{long} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o} -Returns the \var{o} converted to a float object on success, or -\NULL{} on failure. This is the equivalent of the Python expression -\samp{float(\var{o})}.\bifuncindex{float} -\end{cfuncdesc} - - -\section{Sequence Protocol \label{sequence}} - -\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o} -Return \code{1} if the object provides sequence protocol, and -\code{0} otherwise. This function always succeeds. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySequence_Size}{PyObject *o} -Returns the number of objects in sequence \var{o} on success, and -\code{-1} on failure. For objects that do not provide sequence -protocol, this is equivalent to the Python expression -\samp{len(\var{o})}.\bifuncindex{len} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySequence_Length}{PyObject *o} -Alternate name for \cfunction{PySequence_Size()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2} -Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on -failure. This is the equivalent of the Python -expression \samp{\var{o1} + \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count} -Return the result of repeating sequence object -\var{o} \var{count} times, or \NULL{} on failure. This is the -equivalent of the Python expression \samp{\var{o} * \var{count}}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1, - PyObject *o2} -Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on -failure. The operation is done \emph{in-place} when \var{o1} supports it. -This is the equivalent of the Python expression \samp{\var{o1} += \var{o2}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, int count} -Return the result of repeating sequence object \var{o} \var{count} times, or -\NULL{} on failure. The operation is done \emph{in-place} when \var{o} -supports it. This is the equivalent of the Python expression \samp{\var{o} -*= \var{count}}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i} -Return the \var{i}th element of \var{o}, or \NULL{} on failure. This -is the equivalent of the Python expression \samp{\var{o}[\var{i}]}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2} -Return the slice of sequence object \var{o} between \var{i1} and -\var{i2}, or \NULL{} on failure. This is the equivalent of the Python -expression \samp{\var{o}[\var{i1}:\var{i2}]}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v} -Assign object \var{v} to the \var{i}th element of \var{o}. -Returns \code{-1} on failure. This is the equivalent of the Python -statement \samp{\var{o}[\var{i}] = \var{v}}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i} -Delete the \var{i}th element of object \var{o}. Returns -\code{-1} on failure. This is the equivalent of the Python -statement \samp{del \var{o}[\var{i}]}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, - int i2, PyObject *v} -Assign the sequence object \var{v} to the slice in sequence -object \var{o} from \var{i1} to \var{i2}. This is the equivalent of -the Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2} -Delete the slice in sequence object \var{o} from \var{i1} to \var{i2}. -Returns \code{-1} on failure. This is the equivalent of the Python -statement \samp{del \var{o}[\var{i1}:\var{i2}]}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o} -Returns the \var{o} as a tuple on success, and \NULL{} on failure. -This is equivalent to the Python expression \samp{tuple(\var{o})}. -\bifuncindex{tuple} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value} -Return the number of occurrences of \var{value} in \var{o}, that is, -return the number of keys for which \code{\var{o}[\var{key}] == -\var{value}}. On failure, return \code{-1}. This is equivalent to -the Python expression \samp{\var{o}.count(\var{value})}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySequence_Contains}{PyObject *o, PyObject *value} -Determine if \var{o} contains \var{value}. If an item in \var{o} is -equal to \var{value}, return \code{1}, otherwise return \code{0}. On -error, return \code{-1}. This is equivalent to the Python expression -\samp{\var{value} in \var{o}}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value} -Return the first index \var{i} for which \code{\var{o}[\var{i}] == -\var{value}}. On error, return \code{-1}. This is equivalent to -the Python expression \samp{\var{o}.index(\var{value})}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o} -Return a list object with the same contents as the arbitrary sequence -\var{o}. The returned list is guaranteed to be new. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o} -Return a tuple object with the same contents as the arbitrary sequence -\var{o}. If \var{o} is a tuple, a new reference will be returned, -otherwise a tuple will be constructed with the appropriate contents. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PySequence_Fast}{PyObject *o, const char *m} -Returns the sequence \var{o} as a tuple, unless it is already a -tuple or list, in which case \var{o} is returned. Use -\cfunction{PySequence_Fast_GET_ITEM()} to access the members of the -result. Returns \NULL{} on failure. If the object is not a sequence, -raises \exception{TypeError} with \var{m} as the message text. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, int i} -Return the \var{i}th element of \var{o}, assuming that \var{o} was -returned by \cfunction{PySequence_Fast()}, and that \var{i} is within -bounds. The caller is expected to get the length of the sequence by -calling \cfunction{PySequence_Size()} on \var{o}, since lists and tuples -are guaranteed to always return their true length. -\end{cfuncdesc} - - -\section{Mapping Protocol \label{mapping}} - -\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o} -Return \code{1} if the object provides mapping protocol, and -\code{0} otherwise. This function always succeeds. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o} -Returns the number of keys in object \var{o} on success, and -\code{-1} on failure. For objects that do not provide mapping -protocol, this is equivalent to the Python expression -\samp{len(\var{o})}.\bifuncindex{len} -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key} -Remove the mapping for object \var{key} from the object \var{o}. -Return \code{-1} on failure. This is equivalent to -the Python statement \samp{del \var{o}[\var{key}]}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key} -Remove the mapping for object \var{key} from the object \var{o}. -Return \code{-1} on failure. This is equivalent to -the Python statement \samp{del \var{o}[\var{key}]}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key} -On success, return \code{1} if the mapping object has the key -\var{key} and \code{0} otherwise. This is equivalent to the Python -expression \samp{\var{o}.has_key(\var{key})}. -This function always succeeds. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key} -Return \code{1} if the mapping object has the key \var{key} and -\code{0} otherwise. This is equivalent to the Python expression -\samp{\var{o}.has_key(\var{key})}. -This function always succeeds. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o} -On success, return a list of the keys in object \var{o}. On -failure, return \NULL{}. This is equivalent to the Python -expression \samp{\var{o}.keys()}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o} -On success, return a list of the values in object \var{o}. On -failure, return \NULL{}. This is equivalent to the Python -expression \samp{\var{o}.values()}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o} -On success, return a list of the items in object \var{o}, where -each item is a tuple containing a key-value pair. On -failure, return \NULL{}. This is equivalent to the Python -expression \samp{\var{o}.items()}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key} -Return element of \var{o} corresponding to the object \var{key} or -\NULL{} on failure. This is the equivalent of the Python expression -\samp{\var{o}[\var{key}]}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key, - PyObject *v} -Map the object \var{key} to the value \var{v} in object \var{o}. -Returns \code{-1} on failure. This is the equivalent of the Python -statement \samp{\var{o}[\var{key}] = \var{v}}. -\end{cfuncdesc} - - -\section{Iterator Protocol \label{iterator}} - -\versionadded{2.2} - -There are only a couple of functions specifically for working with -iterators. - -\begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o} - Return true if the object \var{o} supports the iterator protocol. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyIter_Next}{PyObject *o} - Return the next value from the iteration \var{o}. If the object is - an iterator, this retrieves the next value from the iteration, and - returns \NULL{} with no exception set if there are no remaining - items. If the object is not an iterator, \exception{TypeError} is - raised, or if there is an error in retrieving the item, returns - \NULL{} and passes along the exception. -\end{cfuncdesc} - -To write a loop which iterates over an iterator, the C code should -look something like this: - -\begin{verbatim} -PyObject *iterator = ...; -PyObject *item; - -while (item = PyIter_Next(iter)) { - /* do something with item */ -} -if (PyErr_Occurred()) { - /* propogate error */ -} -else { - /* continue doing useful work */ -} -\end{verbatim} - - -\chapter{Concrete Objects Layer \label{concrete}} - -The functions in this chapter are specific to certain Python object -types. Passing them an object of the wrong type is not a good idea; -if you receive an object from a Python program and you are not sure -that it has the right type, you must perform a type check first; -for example, to check that an object is a dictionary, use -\cfunction{PyDict_Check()}. The chapter is structured like the -``family tree'' of Python object types. - -\strong{Warning:} -While the functions described in this chapter carefully check the type -of the objects which are passed in, many of them do not check for -\NULL{} being passed instead of a valid object. Allowing \NULL{} to -be passed in can cause memory access violations and immediate -termination of the interpreter. - - -\section{Fundamental Objects \label{fundamental}} - -This section describes Python type objects and the singleton object -\code{None}. - - -\subsection{Type Objects \label{typeObjects}} - -\obindex{type} -\begin{ctypedesc}{PyTypeObject} -The C structure of the objects used to describe built-in types. -\end{ctypedesc} - -\begin{cvardesc}{PyObject*}{PyType_Type} -This is the type object for type objects; it is the same object as -\code{types.TypeType} in the Python layer. -\withsubitem{(in module types)}{\ttindex{TypeType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyType_Check}{PyObject *o} -Returns true is the object \var{o} is a type object. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature} -Returns true if the type object \var{o} sets the feature -\var{feature}. Type features are denoted by single bit flags. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyType_IsSubtype}{PyTypeObject *a, PyTypeObject *b} -Returns true if \var{a} is a subtype of \var{b}. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type, - int nitems} -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyType_GenericNew}{PyTypeObject *type, - PyObject *args, PyObject *kwds} -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyType_Ready}{PyTypeObject *type} -\versionadded{2.2} -\end{cfuncdesc} - - -\subsection{The None Object \label{noneObject}} - -\obindex{None@\texttt{None}} -Note that the \ctype{PyTypeObject} for \code{None} is not directly -exposed in the Python/C API. Since \code{None} is a singleton, -testing for object identity (using \samp{==} in C) is sufficient. -There is no \cfunction{PyNone_Check()} function for the same reason. - -\begin{cvardesc}{PyObject*}{Py_None} -The Python \code{None} object, denoting lack of value. This object has -no methods. -\end{cvardesc} - - -\section{Numeric Objects \label{numericObjects}} - -\obindex{numeric} - - -\subsection{Plain Integer Objects \label{intObjects}} - -\obindex{integer} -\begin{ctypedesc}{PyIntObject} -This subtype of \ctype{PyObject} represents a Python integer object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyInt_Type} -This instance of \ctype{PyTypeObject} represents the Python plain -integer type. This is the same object as \code{types.IntType}. -\withsubitem{(in modules types)}{\ttindex{IntType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o} -Returns true if \var{o} is of type \cdata{PyInt_Type} or a subtype of -\cdata{PyInt_Type}. -\versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject* o} -Returns true if \var{o} is of type \cdata{PyInt_Type}, but not a -subtype of \cdata{PyInt_Type}. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival} -Creates a new integer object with a value of \var{ival}. - -The current implementation keeps an array of integer objects for all -integers between \code{-1} and \code{100}, when you create an int in -that range you actually just get back a reference to the existing -object. So it should be possible to change the value of \code{1}. I -suspect the behaviour of Python in this case is undefined. :-) -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io} -Will first attempt to cast the object to a \ctype{PyIntObject}, if -it is not already one, and then return its value. -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io} -Returns the value of the object \var{io}. No error checking is -performed. -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyInt_GetMax}{} -Returns the system's idea of the largest integer it can handle -(\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system -header files). -\end{cfuncdesc} - - -\subsection{Long Integer Objects \label{longObjects}} - -\obindex{long integer} -\begin{ctypedesc}{PyLongObject} -This subtype of \ctype{PyObject} represents a Python long integer -object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyLong_Type} -This instance of \ctype{PyTypeObject} represents the Python long -integer type. This is the same object as \code{types.LongType}. -\withsubitem{(in modules types)}{\ttindex{LongType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p} -Returns true if its argument is a \ctype{PyLongObject} or a subtype of -\ctype{PyLongObject}. -\versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p} -Returns true if its argument is a \ctype{PyLongObject}, but not a -subtype of \ctype{PyLongObject}. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v} -Returns a new \ctype{PyLongObject} object from \var{v}, or \NULL{} on -failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v} -Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned -long}, or \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{long long v} -Returns a new \ctype{PyLongObject} object from a C \ctype{long long}, -or \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned long long v} -Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned -long long}, or \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v} -Returns a new \ctype{PyLongObject} object from the integer part of -\var{v}, or \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend, - int base} -Return a new \ctype{PyLongObject} based on the string value in -\var{str}, which is interpreted according to the radix in \var{base}. -If \var{pend} is non-\NULL, \code{*\var{pend}} will point to the first -character in \var{str} which follows the representation of the -number. If \var{base} is \code{0}, the radix will be determined base -on the leading characters of \var{str}: if \var{str} starts with -\code{'0x'} or \code{'0X'}, radix 16 will be used; if \var{str} starts -with \code{'0'}, radix 8 will be used; otherwise radix 10 will be -used. If \var{base} is not \code{0}, it must be between \code{2} and -\code{36}, inclusive. Leading spaces are ignored. If there are no -digits, \exception{ValueError} will be raised. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromUnicode}{Py_UNICODE *u, - int length, int base} -Convert a sequence of Unicode digits to a Python long integer value. -The first parameter, \var{u}, points to the first character of the -Unicode string, \var{length} gives the number of characters, and -\var{base} is the radix for the conversion. The radix must be in the -range [2, 36]; if it is out of range, \exception{ValueError} will be -raised. -\versionadded{1.6} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyLong_FromVoidPtr}{void *p} -Create a Python integer or long integer from the pointer \var{p}. The -pointer value can be retrieved from the resulting value using -\cfunction{PyLong_AsVoidPtr()}. -\versionadded{1.5.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong} -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)}{\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)}{\ttindex{OverflowError}} -\end{cfuncdesc} - -\begin{cfuncdesc}{long long}{PyLong_AsLongLong}{PyObject *pylong} -Return a C \ctype{long long} from a Python long integer. If -\var{pylong} cannot be represented as a \ctype{long long}, an -\exception{OverflowError} will be raised. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{unsigned long long}{PyLong_AsUnsignedLongLong}{PyObject - *pylong} -Return a C \ctype{unsigned long long} from a Python long integer. If -\var{pylong} cannot be represented as an \ctype{unsigned long long}, -an \exception{OverflowError} will be raised if the value is positive, -or a \exception{TypeError} will be raised if the value is negative. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong} -Returns a C \ctype{double} representation of the contents of -\var{pylong}. If \var{pylong} cannot be approximately represented as -a \ctype{double}, an \exception{OverflowError} exception is raised and -\code{-1.0} will be returned. -\end{cfuncdesc} - -\begin{cfuncdesc}{void*}{PyLong_AsVoidPtr}{PyObject *pylong} -Convert a Python integer or long integer \var{pylong} to a C -\ctype{void} pointer. If \var{pylong} cannot be converted, an -\exception{OverflowError} will be raised. This is only assured to -produce a usable \ctype{void} pointer for values created with -\cfunction{PyLong_FromVoidPtr()}. -\versionadded{1.5.2} -\end{cfuncdesc} - - -\subsection{Floating Point Objects \label{floatObjects}} - -\obindex{floating point} -\begin{ctypedesc}{PyFloatObject} -This subtype of \ctype{PyObject} represents a Python floating point -object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyFloat_Type} -This instance of \ctype{PyTypeObject} represents the Python floating -point type. This is the same object as \code{types.FloatType}. -\withsubitem{(in modules types)}{\ttindex{FloatType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p} -Returns true if its argument is a \ctype{PyFloatObject} or a subtype -of \ctype{PyFloatObject}. -\versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p} -Returns true if its argument is a \ctype{PyFloatObject}, but not a -subtype of \ctype{PyFloatObject}. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v} -Creates a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on -failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat} -Returns a C \ctype{double} representation of the contents of \var{pyfloat}. -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat} -Returns a C \ctype{double} representation of the contents of -\var{pyfloat}, but without error checking. -\end{cfuncdesc} - - -\subsection{Complex Number Objects \label{complexObjects}} - -\obindex{complex number} -Python's complex number objects are implemented as two distinct types -when viewed from the C API: one is the Python object exposed to -Python programs, and the other is a C structure which represents the -actual complex number value. The API provides functions for working -with both. - -\subsubsection{Complex Numbers as C Structures} - -Note that the functions which accept these structures as parameters -and return them as results do so \emph{by value} rather than -dereferencing them through pointers. This is consistent throughout -the API. - -\begin{ctypedesc}{Py_complex} -The C structure which corresponds to the value portion of a Python -complex number object. Most of the functions for dealing with complex -number objects use structures of this type as input or output values, -as appropriate. It is defined as: - -\begin{verbatim} -typedef struct { - double real; - double imag; -} Py_complex; -\end{verbatim} -\end{ctypedesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right} -Return the sum of two complex numbers, using the C -\ctype{Py_complex} representation. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right} -Return the difference between two complex numbers, using the C -\ctype{Py_complex} representation. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex} -Return the negation of the complex number \var{complex}, using the C -\ctype{Py_complex} representation. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right} -Return the product of two complex numbers, using the C -\ctype{Py_complex} representation. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend, - Py_complex divisor} -Return the quotient of two complex numbers, using the C -\ctype{Py_complex} representation. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp} -Return the exponentiation of \var{num} by \var{exp}, using the C -\ctype{Py_complex} representation. -\end{cfuncdesc} - - -\subsubsection{Complex Numbers as Python Objects} - -\begin{ctypedesc}{PyComplexObject} -This subtype of \ctype{PyObject} represents a Python complex number object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyComplex_Type} -This instance of \ctype{PyTypeObject} represents the Python complex -number type. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p} -Returns true if its argument is a \ctype{PyComplexObject} or a subtype -of \ctype{PyComplexObject}. -\versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p} -Returns true if its argument is a \ctype{PyComplexObject}, but not a -subtype of \ctype{PyComplexObject}. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v} -Create a new Python complex number object from a C -\ctype{Py_complex} value. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag} -Returns a new \ctype{PyComplexObject} object from \var{real} and \var{imag}. -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op} -Returns the real part of \var{op} as a C \ctype{double}. -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op} -Returns the imaginary part of \var{op} as a C \ctype{double}. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op} -Returns the \ctype{Py_complex} value of the complex number \var{op}. -\end{cfuncdesc} - - - -\section{Sequence Objects \label{sequenceObjects}} - -\obindex{sequence} -Generic operations on sequence objects were discussed in the previous -chapter; this section deals with the specific kinds of sequence -objects that are intrinsic to the Python language. - - -\subsection{String Objects \label{stringObjects}} - -These functions raise \exception{TypeError} when expecting a string -parameter and are called with a non-string parameter. - -\obindex{string} -\begin{ctypedesc}{PyStringObject} -This subtype of \ctype{PyObject} represents a Python string object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyString_Type} -This instance of \ctype{PyTypeObject} represents the Python string -type; it is the same object as \code{types.TypeType} in the Python -layer.\withsubitem{(in module types)}{\ttindex{StringType}}. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o} -Returns true if the object \var{o} is a string object or an instance -of a subtype of the string type. -\versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o} -Returns true if the object \var{o} is a string object, but not an -instance of a subtype of the string type. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v} -Returns a new string object with the value \var{v} on success, and -\NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v, - int len} -Returns a new string object with the value \var{v} and length -\var{len} on success, and \NULL{} on failure. If \var{v} is \NULL{}, -the contents of the string are uninitialized. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...} -Takes a C \code{printf}-style \var{format} string and a variable -number of arguments, calculates the size of the resulting Python -string and returns a string with the values formatted into it. The -variable arguments must be C types and must correspond exactly to the -format characters in the \var{format} string. The following format -characters are allowed: -\begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment} - \lineiii{\%\%}{\emph{n/a}}{The literal \% character.} - \lineiii{\%c}{int}{A single character, represented as an C int.} - \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.} - \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.} - \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.} - \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.} - \lineiii{\%s}{char*}{A null-terminated C character array.} - \lineiii{\%p}{void*}{The hex representation of a C pointer. - Mostly equivalent to \code{printf("\%p")} except that it is - guaranteed to start with the literal \code{0x} regardless of - what the platform's \code{printf} yields.} -\end{tableiii} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_FromFormatV}{const char *format, - va_list vargs} -Identical to \function{PyString_FromFormat()} except that it takes -exactly two arguments. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string} -Returns the length of the string in string object \var{string}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string} -Macro form of \cfunction{PyString_Size()} but without error -checking. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string} -Returns a null-terminated representation of the contents of -\var{string}. The pointer refers to the internal buffer of -\var{string}, not a copy. The data must not be modified in any way, -unless the string was just created using -\code{PyString_FromStringAndSize(NULL, \var{size})}. -It must not be deallocated. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string} -Macro form of \cfunction{PyString_AsString()} but without error -checking. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj, - char **buffer, - int *length} -Returns a null-terminated representation of the contents of the object -\var{obj} through the output variables \var{buffer} and \var{length}. - -The function accepts both string and Unicode objects as input. For -Unicode objects it returns the default encoded version of the object. -If \var{length} is set to \NULL{}, the resulting buffer may not contain -null characters; if it does, the function returns -1 and a -TypeError is raised. - -The buffer refers to an internal string buffer of \var{obj}, not a -copy. The data must not be modified in any way, unless the string was -just created using \code{PyString_FromStringAndSize(NULL, -\var{size})}. It must not be deallocated. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string, - PyObject *newpart} -Creates a new string object in \var{*string} containing the -contents of \var{newpart} appended to \var{string}; the caller will -own the new reference. The reference to the old value of \var{string} -will be stolen. If the new string -cannot be created, the old reference to \var{string} will still be -discarded and the value of \var{*string} will be set to -\NULL{}; the appropriate exception will be set. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string, - PyObject *newpart} -Creates a new string object in \var{*string} containing the contents -of \var{newpart} appended to \var{string}. This version decrements -the reference count of \var{newpart}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize} -A way to resize a string object even though it is ``immutable''. -Only use this to build up a brand new string object; don't use this if -the string may already be known in other parts of the code. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format, - PyObject *args} -Returns a new string object from \var{format} and \var{args}. Analogous -to \code{\var{format} \%\ \var{args}}. The \var{args} argument must be -a tuple. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string} -Intern the argument \var{*string} in place. The argument must be the -address of a pointer variable pointing to a Python string object. -If there is an existing interned string that is the same as -\var{*string}, it sets \var{*string} to it (decrementing the reference -count of the old string object and incrementing the reference count of -the interned string object), otherwise it leaves \var{*string} alone -and interns it (incrementing its reference count). (Clarification: -even though there is a lot of talk about reference counts, think of -this function as reference-count-neutral; you own the object after -the call if and only if you owned it before the call.) -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v} -A combination of \cfunction{PyString_FromString()} and -\cfunction{PyString_InternInPlace()}, returning either a new string object -that has been interned, or a new (``owned'') reference to an earlier -interned string object with the same value. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s, - int size, - const char *encoding, - const char *errors} -Creates an object by decoding \var{size} bytes of the encoded -buffer \var{s} using the codec registered -for \var{encoding}. \var{encoding} and \var{errors} have the same meaning -as the parameters of the same name in the unicode() builtin -function. The codec to be used is looked up using the Python codec -registry. Returns \NULL{} in case an exception was raised by the -codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str, - const char *encoding, - const char *errors} -Decodes a string object by passing it to the codec registered -for \var{encoding} and returns the result as Python -object. \var{encoding} and \var{errors} have the same meaning as the -parameters of the same name in the string .encode() method. The codec -to be used is looked up using the Python codec registry. Returns -\NULL{} in case an exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s, - int size, - const char *encoding, - const char *errors} -Encodes the \ctype{char} buffer of the given size by passing it to -the codec registered for \var{encoding} and returns a Python object. -\var{encoding} and \var{errors} have the same -meaning as the parameters of the same name in the string .encode() -method. The codec to be used is looked up using the Python codec -registry. Returns \NULL{} in case an exception was raised by the -codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str, - const char *encoding, - const char *errors} -Encodes a string object using the codec registered -for \var{encoding} and returns the result as Python -object. \var{encoding} and \var{errors} have the same meaning as the -parameters of the same name in the string .encode() method. The codec -to be used is looked up using the Python codec registry. Returns -\NULL{} in case an exception was raised by the codec. -\end{cfuncdesc} - - -\subsection{Unicode Objects \label{unicodeObjects}} -\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com} - -%--- Unicode Type ------------------------------------------------------- - -These are the basic Unicode object types used for the Unicode -implementation in Python: - -\begin{ctypedesc}{Py_UNICODE} -This type represents a 16-bit unsigned storage type which is used by -Python internally as basis for holding Unicode ordinals. On platforms -where \ctype{wchar_t} is available and also has 16-bits, -\ctype{Py_UNICODE} is a typedef alias for \ctype{wchar_t} to enhance -native platform compatibility. On all other platforms, -\ctype{Py_UNICODE} is a typedef alias for \ctype{unsigned short}. -\end{ctypedesc} - -\begin{ctypedesc}{PyUnicodeObject} -This subtype of \ctype{PyObject} represents a Python Unicode object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyUnicode_Type} -This instance of \ctype{PyTypeObject} represents the Python Unicode type. -\end{cvardesc} - -%--- These are really C macros... is there a macrodesc TeX macro ? - -The following APIs are really C macros and can be used to do fast -checks and to access internal read-only data of Unicode objects: - -\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o} -Returns true if the object \var{o} is a Unicode object or an instance -of a Unicode subtype. -\versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o} -Returns true if the object \var{o} is a Unicode object, but not an -instance of a subtype. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o} -Returns the size of the object. o has to be a -PyUnicodeObject (not checked). -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyUnicode_GET_DATA_SIZE}{PyObject *o} -Returns the size of the object's internal buffer in bytes. o has to be -a PyUnicodeObject (not checked). -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o} -Returns a pointer to the internal Py_UNICODE buffer of the object. o -has to be a PyUnicodeObject (not checked). -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o} -Returns a (const char *) pointer to the internal buffer of the object. -o has to be a PyUnicodeObject (not checked). -\end{cfuncdesc} - -% --- Unicode character properties --------------------------------------- - -Unicode provides many different character properties. The most often -needed ones are available through these macros which are mapped to C -functions depending on the Python configuration. - -\begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch} -Returns 1/0 depending on whether \var{ch} is a whitespace character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch} -Returns 1/0 depending on whether \var{ch} is a lowercase character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch} -Returns 1/0 depending on whether \var{ch} is an uppercase character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch} -Returns 1/0 depending on whether \var{ch} is a titlecase character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch} -Returns 1/0 depending on whether \var{ch} is a linebreak character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch} -Returns 1/0 depending on whether \var{ch} is a decimal character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch} -Returns 1/0 depending on whether \var{ch} is a digit character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch} -Returns 1/0 depending on whether \var{ch} is a numeric character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch} -Returns 1/0 depending on whether \var{ch} is an alphabetic character. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch} -Returns 1/0 depending on whether \var{ch} is an alphanumeric character. -\end{cfuncdesc} - -These APIs can be used for fast direct character conversions: - -\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch} -Returns the character \var{ch} converted to lower case. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch} -Returns the character \var{ch} converted to upper case. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch} -Returns the character \var{ch} converted to title case. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch} -Returns the character \var{ch} converted to a decimal positive integer. -Returns -1 in case this is not possible. Does not raise exceptions. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch} -Returns the character \var{ch} converted to a single digit integer. -Returns -1 in case this is not possible. Does not raise exceptions. -\end{cfuncdesc} - -\begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch} -Returns the character \var{ch} converted to a (positive) double. -Returns -1.0 in case this is not possible. Does not raise exceptions. -\end{cfuncdesc} - -% --- Plain Py_UNICODE --------------------------------------------------- - -To create Unicode objects and access their basic sequence properties, -use these APIs: - -\begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u, - int size} - -Create a Unicode Object from the Py_UNICODE buffer \var{u} of the -given size. \var{u} may be \NULL{} which causes the contents to be -undefined. It is the user's responsibility to fill in the needed data. -The buffer is copied into the new object. If the buffer is not \NULL{}, -the return value might be a shared object. Therefore, modification of -the resulting Unicode Object is only allowed when \var{u} is \NULL{}. -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode} -Return a read-only pointer to the Unicode object's internal -\ctype{Py_UNICODE} buffer. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode} -Return the length of the Unicode object. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj, - const char *encoding, - const char *errors} - -Coerce an encoded object obj to an Unicode object and return a -reference with incremented refcount. - -Coercion is done in the following way: -\begin{enumerate} -\item Unicode objects are passed back as-is with incremented - refcount. Note: these cannot be decoded; passing a non-NULL - value for encoding will result in a TypeError. - -\item String and other char buffer compatible objects are decoded - according to the given encoding and using the error handling - defined by errors. Both can be NULL to have the interface use - the default values (see the next section for details). - -\item All other objects cause an exception. -\end{enumerate} -The API returns NULL in case of an error. The caller is responsible -for decref'ing the returned objects. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj} - -Shortcut for PyUnicode_FromEncodedObject(obj, NULL, ``strict'') -which is used throughout the interpreter whenever coercion to -Unicode is needed. -\end{cfuncdesc} - -% --- wchar_t support for platforms which support it --------------------- - -If the platform supports \ctype{wchar_t} and provides a header file -wchar.h, Python can interface directly to this type using the -following functions. Support is optimized if Python's own -\ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}. - -\begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w, - int size} -Create a Unicode Object from the \ctype{whcar_t} buffer \var{w} of the -given size. Returns \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode, - wchar_t *w, - int size} -Copies the Unicode Object contents into the \ctype{whcar_t} buffer -\var{w}. At most \var{size} \ctype{whcar_t} characters are copied. -Returns the number of \ctype{whcar_t} characters copied or -1 in case -of an error. -\end{cfuncdesc} - - -\subsubsection{Builtin Codecs \label{builtinCodecs}} - -Python provides a set of builtin codecs which are written in C -for speed. All of these codecs are directly usable via the -following functions. - -Many of the following APIs take two arguments encoding and -errors. These parameters encoding and errors have the same semantics -as the ones of the builtin unicode() Unicode object constructor. - -Setting encoding to NULL causes the default encoding to be used which -is \ASCII{}. The file system calls should use -\var{Py_FileSystemDefaultEncoding} as the encoding for file -names. This variable should be treated as read-only: On some systems, -it will be a pointer to a static string, on others, it will change at -run-time, e.g. when the application invokes setlocale. - -Error handling is set by errors which may also be set to NULL meaning -to use the default handling defined for the codec. Default error -handling for all builtin codecs is ``strict'' (ValueErrors are raised). - -The codecs all use a similar interface. Only deviation from the -following generic ones are documented for simplicity. - -% --- Generic Codecs ----------------------------------------------------- - -These are the generic codec APIs: - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s, - int size, - const char *encoding, - const char *errors} -Create a Unicode object by decoding \var{size} bytes of the encoded -string \var{s}. \var{encoding} and \var{errors} have the same meaning -as the parameters of the same name in the unicode() builtin -function. The codec to be used is looked up using the Python codec -registry. Returns \NULL{} in case an exception was raised by the -codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s, - int size, - const char *encoding, - const char *errors} -Encodes the \ctype{Py_UNICODE} buffer of the given size and returns a -Python string object. \var{encoding} and \var{errors} have the same -meaning as the parameters of the same name in the Unicode .encode() -method. The codec to be used is looked up using the Python codec -registry. Returns \NULL{} in case an exception was raised by the -codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode, - const char *encoding, - const char *errors} -Encodes a Unicode object and returns the result as Python string -object. \var{encoding} and \var{errors} have the same meaning as the -parameters of the same name in the Unicode .encode() method. The codec -to be used is looked up using the Python codec registry. Returns -\NULL{} in case an exception was raised by the codec. -\end{cfuncdesc} - -% --- UTF-8 Codecs ------------------------------------------------------- - -These are the UTF-8 codec APIs: - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s, - int size, - const char *errors} -Creates a Unicode object by decoding \var{size} bytes of the UTF-8 -encoded string \var{s}. Returns \NULL{} in case an exception was -raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s, - int size, - const char *errors} -Encodes the \ctype{Py_UNICODE} buffer of the given size using UTF-8 -and returns a Python string object. Returns \NULL{} in case an -exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode} -Encodes a Unicode objects using UTF-8 and returns the result as Python -string object. Error handling is ``strict''. Returns -\NULL{} in case an exception was raised by the codec. -\end{cfuncdesc} - -% --- UTF-16 Codecs ------------------------------------------------------ */ - -These are the UTF-16 codec APIs: - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s, - int size, - const char *errors, - int *byteorder} -Decodes \var{length} bytes from a UTF-16 encoded buffer string and -returns the corresponding Unicode object. - -\var{errors} (if non-NULL) defines the error handling. It defaults -to ``strict''. - -If \var{byteorder} is non-\NULL{}, the decoder starts decoding using -the given byte order: - -\begin{verbatim} - *byteorder == -1: little endian - *byteorder == 0: native order - *byteorder == 1: big endian -\end{verbatim} - -and then switches according to all byte order marks (BOM) it finds in -the input data. BOM marks are not copied into the resulting Unicode -string. After completion, \var{*byteorder} is set to the current byte -order at the end of input data. - -If \var{byteorder} is \NULL{}, the codec starts in native order mode. - -Returns \NULL{} in case an exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s, - int size, - const char *errors, - int byteorder} -Returns a Python string object holding the UTF-16 encoded value of the -Unicode data in \var{s}. - -If \var{byteorder} is not \code{0}, output is written according to the -following byte order: - -\begin{verbatim} - byteorder == -1: little endian - byteorder == 0: native byte order (writes a BOM mark) - byteorder == 1: big endian -\end{verbatim} - -If byteorder is \code{0}, the output string will always start with the -Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark is -prepended. - -Note that \ctype{Py_UNICODE} data is being interpreted as UTF-16 -reduced to UCS-2. This trick makes it possible to add full UTF-16 -capabilities at a later point without comprimising the APIs. - -Returns \NULL{} in case an exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode} -Returns a Python string using the UTF-16 encoding in native byte -order. The string always starts with a BOM mark. Error handling is -``strict''. Returns \NULL{} in case an exception was raised by the -codec. -\end{cfuncdesc} - -% --- Unicode-Escape Codecs ---------------------------------------------- - -These are the ``Unicode Esacpe'' codec APIs: - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s, - int size, - const char *errors} -Creates a Unicode object by decoding \var{size} bytes of the Unicode-Esacpe -encoded string \var{s}. Returns \NULL{} in case an exception was -raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s, - int size, - const char *errors} -Encodes the \ctype{Py_UNICODE} buffer of the given size using Unicode-Escape -and returns a Python string object. Returns \NULL{} in case an -exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode} -Encodes a Unicode objects using Unicode-Escape and returns the result -as Python string object. Error handling is ``strict''. Returns -\NULL{} in case an exception was raised by the codec. -\end{cfuncdesc} - -% --- Raw-Unicode-Escape Codecs ------------------------------------------ - -These are the ``Raw Unicode Esacpe'' codec APIs: - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s, - int size, - const char *errors} -Creates a Unicode object by decoding \var{size} bytes of the Raw-Unicode-Esacpe -encoded string \var{s}. Returns \NULL{} in case an exception was -raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s, - int size, - const char *errors} -Encodes the \ctype{Py_UNICODE} buffer of the given size using Raw-Unicode-Escape -and returns a Python string object. Returns \NULL{} in case an -exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode} -Encodes a Unicode objects using Raw-Unicode-Escape and returns the result -as Python string object. Error handling is ``strict''. Returns -\NULL{} in case an exception was raised by the codec. -\end{cfuncdesc} - -% --- Latin-1 Codecs ----------------------------------------------------- - -These are the Latin-1 codec APIs: - -Latin-1 corresponds to the first 256 Unicode ordinals and only these -are accepted by the codecs during encoding. - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s, - int size, - const char *errors} -Creates a Unicode object by decoding \var{size} bytes of the Latin-1 -encoded string \var{s}. Returns \NULL{} in case an exception was -raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s, - int size, - const char *errors} -Encodes the \ctype{Py_UNICODE} buffer of the given size using Latin-1 -and returns a Python string object. Returns \NULL{} in case an -exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode} -Encodes a Unicode objects using Latin-1 and returns the result as -Python string object. Error handling is ``strict''. Returns -\NULL{} in case an exception was raised by the codec. -\end{cfuncdesc} - -% --- ASCII Codecs ------------------------------------------------------- - -These are the \ASCII{} codec APIs. Only 7-bit \ASCII{} data is -accepted. All other codes generate errors. - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s, - int size, - const char *errors} -Creates a Unicode object by decoding \var{size} bytes of the -\ASCII{} encoded string \var{s}. Returns \NULL{} in case an exception -was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s, - int size, - const char *errors} -Encodes the \ctype{Py_UNICODE} buffer of the given size using -\ASCII{} and returns a Python string object. Returns \NULL{} in case -an exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode} -Encodes a Unicode objects using \ASCII{} and returns the result as Python -string object. Error handling is ``strict''. Returns -\NULL{} in case an exception was raised by the codec. -\end{cfuncdesc} - -% --- Character Map Codecs ----------------------------------------------- - -These are the mapping codec APIs: - -This codec is special in that it can be used to implement many -different codecs (and this is in fact what was done to obtain most of -the standard codecs included in the \module{encodings} package). The -codec uses mapping to encode and decode characters. - -Decoding mappings must map single string characters to single Unicode -characters, integers (which are then interpreted as Unicode ordinals) -or None (meaning "undefined mapping" and causing an error). - -Encoding mappings must map single Unicode characters to single string -characters, integers (which are then interpreted as Latin-1 ordinals) -or None (meaning "undefined mapping" and causing an error). - -The mapping objects provided must only support the __getitem__ mapping -interface. - -If a character lookup fails with a LookupError, the character is -copied as-is meaning that its ordinal value will be interpreted as -Unicode or Latin-1 ordinal resp. Because of this, mappings only need -to contain those mappings which map characters to different code -points. - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s, - int size, - PyObject *mapping, - const char *errors} -Creates a Unicode object by decoding \var{size} bytes of the encoded -string \var{s} using the given \var{mapping} object. Returns \NULL{} -in case an exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s, - int size, - PyObject *mapping, - const char *errors} -Encodes the \ctype{Py_UNICODE} buffer of the given size using the -given \var{mapping} object and returns a Python string object. -Returns \NULL{} in case an exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode, - PyObject *mapping} -Encodes a Unicode objects using the given \var{mapping} object and -returns the result as Python string object. Error handling is -``strict''. Returns \NULL{} in case an exception was raised by the -codec. -\end{cfuncdesc} - -The following codec API is special in that maps Unicode to Unicode. - -\begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s, - int size, - PyObject *table, - const char *errors} -Translates a \ctype{Py_UNICODE} buffer of the given length by applying -a character mapping \var{table} to it and returns the resulting -Unicode object. Returns \NULL{} when an exception was raised by the -codec. - -The \var{mapping} table must map Unicode ordinal integers to Unicode -ordinal integers or None (causing deletion of the character). - -Mapping tables must only provide the __getitem__ interface, -e.g. dictionaries or sequences. Unmapped character ordinals (ones -which cause a LookupError) are left untouched and are copied as-is. -\end{cfuncdesc} - -% --- MBCS codecs for Windows -------------------------------------------- - -These are the MBCS codec APIs. They are currently only available on -Windows and use the Win32 MBCS converters to implement the -conversions. Note that MBCS (or DBCS) is a class of encodings, not -just one. The target encoding is defined by the user settings on the -machine running the codec. - -\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s, - int size, - const char *errors} -Creates a Unicode object by decoding \var{size} bytes of the MBCS -encoded string \var{s}. Returns \NULL{} in case an exception was -raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s, - int size, - const char *errors} -Encodes the \ctype{Py_UNICODE} buffer of the given size using MBCS -and returns a Python string object. Returns \NULL{} in case an -exception was raised by the codec. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode} -Encodes a Unicode objects using MBCS and returns the result as Python -string object. Error handling is ``strict''. Returns \NULL{} in case -an exception was raised by the codec. -\end{cfuncdesc} - -% --- Methods & Slots ---------------------------------------------------- - -\subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}} - -The following APIs are capable of handling Unicode objects and strings -on input (we refer to them as strings in the descriptions) and return -Unicode objects or integers as apporpriate. - -They all return \NULL{} or -1 in case an exception occurrs. - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left, - PyObject *right} -Concat two strings giving a new Unicode string. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s, - PyObject *sep, - int maxsplit} -Split a string giving a list of Unicode strings. - -If sep is NULL, splitting will be done at all whitespace -substrings. Otherwise, splits occur at the given separator. - -At most maxsplit splits will be done. If negative, no limit is set. - -Separators are not included in the resulting list. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s, - int maxsplit} -Split a Unicode string at line breaks, returning a list of Unicode -strings. CRLF is considered to be one line break. The Line break -characters are not included in the resulting strings. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str, - PyObject *table, - const char *errors} -Translate a string by applying a character mapping table to it and -return the resulting Unicode object. - -The mapping table must map Unicode ordinal integers to Unicode ordinal -integers or None (causing deletion of the character). - -Mapping tables must only provide the __getitem__ interface, -e.g. dictionaries or sequences. Unmapped character ordinals (ones -which cause a LookupError) are left untouched and are copied as-is. - -\var{errors} has the usual meaning for codecs. It may be \NULL{} -which indicates to use the default error handling. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator, - PyObject *seq} -Join a sequence of strings using the given separator and return -the resulting Unicode string. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str, - PyObject *substr, - int start, - int end, - int direction} -Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at -the given tail end (\var{direction} == -1 means to do a prefix match, -\var{direction} == 1 a suffix match), 0 otherwise. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Find}{PyObject *str, - PyObject *substr, - int start, - int end, - int direction} -Return the first position of \var{substr} in -\var{str}[\var{start}:\var{end}] using the given \var{direction} -(\var{direction} == 1 means to do a forward search, -\var{direction} == -1 a backward search), 0 otherwise. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Count}{PyObject *str, - PyObject *substr, - int start, - int end} -Count the number of occurrences of \var{substr} in -\var{str}[\var{start}:\var{end}] -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str, - PyObject *substr, - PyObject *replstr, - int maxcount} -Replace at most \var{maxcount} occurrences of \var{substr} in -\var{str} with \var{replstr} and return the resulting Unicode object. -\var{maxcount} == -1 means: replace all occurrences. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right} -Compare two strings and return -1, 0, 1 for less than, equal, -greater than resp. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format, - PyObject *args} -Returns a new string object from \var{format} and \var{args}; this is -analogous to \code{\var{format} \%\ \var{args}}. The -\var{args} argument must be a tuple. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container, - PyObject *element} -Checks whether \var{element} is contained in \var{container} and -returns true or false accordingly. - -\var{element} has to coerce to a one element Unicode string. \code{-1} is -returned in case of an error. -\end{cfuncdesc} - - -\subsection{Buffer Objects \label{bufferObjects}} -\sectionauthor{Greg Stein}{gstein@lyra.org} - -\obindex{buffer} -Python objects implemented in C can export a group of functions called -the ``buffer\index{buffer interface} interface.'' These functions can -be used by an object to expose its data in a raw, byte-oriented -format. Clients of the object can use the buffer interface to access -the object data directly, without needing to copy it first. - -Two examples of objects that support -the buffer interface are strings and arrays. The string object exposes -the character contents in the buffer interface's byte-oriented -form. An array can also expose its contents, but it should be noted -that array elements may be multi-byte values. - -An example user of the buffer interface is the file object's -\method{write()} method. Any object that can export a series of bytes -through the buffer interface can be written to a file. There are a -number of format codes to \cfunction{PyArg_ParseTuple()} that operate -against an object's buffer interface, returning data from the target -object. - -More information on the buffer interface is provided in the section -``Buffer Object Structures'' (section \ref{buffer-structs}), under -the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}. - -A ``buffer object'' is defined in the \file{bufferobject.h} header -(included by \file{Python.h}). These objects look very similar to -string objects at the Python programming level: they support slicing, -indexing, concatenation, and some other standard string -operations. However, their data can come from one of two sources: from -a block of memory, or from another object which exports the buffer -interface. - -Buffer objects are useful as a way to expose the data from another -object's buffer interface to the Python programmer. They can also be -used as a zero-copy slicing mechanism. Using their ability to -reference a block of memory, it is possible to expose any data to the -Python programmer quite easily. The memory could be a large, constant -array in a C extension, it could be a raw block of memory for -manipulation before passing to an operating system library, or it -could be used to pass around structured data in its native, in-memory -format. - -\begin{ctypedesc}{PyBufferObject} -This subtype of \ctype{PyObject} represents a buffer object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyBuffer_Type} -The instance of \ctype{PyTypeObject} which represents the Python -buffer type; it is the same object as \code{types.BufferType} in the -Python layer.\withsubitem{(in module types)}{\ttindex{BufferType}}. -\end{cvardesc} - -\begin{cvardesc}{int}{Py_END_OF_BUFFER} -This constant may be passed as the \var{size} parameter to -\cfunction{PyBuffer_FromObject()} or -\cfunction{PyBuffer_FromReadWriteObject()}. It indicates that the new -\ctype{PyBufferObject} should refer to \var{base} object from the -specified \var{offset} to the end of its exported buffer. Using this -enables the caller to avoid querying the \var{base} object for its -length. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyBuffer_Check}{PyObject *p} -Return true if the argument has type \cdata{PyBuffer_Type}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base, - int offset, int size} -Return a new read-only buffer object. This raises -\exception{TypeError} if \var{base} doesn't support the read-only -buffer protocol or doesn't provide exactly one buffer segment, or it -raises \exception{ValueError} if \var{offset} is less than zero. The -buffer will hold a reference to the \var{base} object, and the -buffer's contents will refer to the \var{base} object's buffer -interface, starting as position \var{offset} and extending for -\var{size} bytes. If \var{size} is \constant{Py_END_OF_BUFFER}, then -the new buffer's contents extend to the length of the -\var{base} object's exported buffer data. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteObject}{PyObject *base, - int offset, - int size} -Return a new writable buffer object. Parameters and exceptions are -similar to those for \cfunction{PyBuffer_FromObject()}. -If the \var{base} object does not export the writeable buffer -protocol, then \exception{TypeError} is raised. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyBuffer_FromMemory}{void *ptr, int size} -Return a new read-only buffer object that reads from a specified -location in memory, with a specified size. -The caller is responsible for ensuring that the memory buffer, passed -in as \var{ptr}, is not deallocated while the returned buffer object -exists. Raises \exception{ValueError} if \var{size} is less than -zero. Note that \constant{Py_END_OF_BUFFER} may \emph{not} be passed -for the \var{size} parameter; \exception{ValueError} will be raised in -that case. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, int size} -Similar to \cfunction{PyBuffer_FromMemory()}, but the returned buffer -is writable. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{int size} -Returns a new writable buffer object that maintains its own memory -buffer of \var{size} bytes. \exception{ValueError} is returned if -\var{size} is not zero or positive. -\end{cfuncdesc} - - -\subsection{Tuple Objects \label{tupleObjects}} - -\obindex{tuple} -\begin{ctypedesc}{PyTupleObject} -This subtype of \ctype{PyObject} represents a Python tuple object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyTuple_Type} -This instance of \ctype{PyTypeObject} represents the Python tuple -type; it is the same object as \code{types.TupleType} in the Python -layer.\withsubitem{(in module types)}{\ttindex{TupleType}}. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p} -Return true if \var{p} is a tuple object or an instance of a subtype -of the tuple type. -\versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTuple_CheckExact}{PyObject *p} -Return true if \var{p} is a tuple object, but not an instance of -a subtype of the tuple type. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len} -Return a new tuple object of size \var{len}, or \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p} -Takes a pointer to a tuple object, and returns the size -of that tuple. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTuple_GET_SIZE}{PyObject *p} -Return the size of the tuple \var{p}, which must be non-\NULL{} and -point to a tuple; no error checking is performed. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, int pos} -Returns the object at position \var{pos} in the tuple pointed -to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and -sets an \exception{IndexError} exception. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, int pos} -Like \cfunction{PyTuple_GetItem()}, but does no checking of its -arguments. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p, - int low, int high} -Takes a slice of the tuple pointed to by \var{p} from -\var{low} to \var{high} and returns it as a new tuple. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p, - int pos, PyObject *o} -Inserts a reference to object \var{o} at position \var{pos} of -the tuple pointed to by \var{p}. It returns \code{0} on success. -\strong{Note:} This function ``steals'' a reference to \var{o}. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p, - int pos, PyObject *o} -Like \cfunction{PyTuple_SetItem()}, but does no error checking, and -should \emph{only} be used to fill in brand new tuples. -\strong{Note:} This function ``steals'' a reference to \var{o}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, int newsize} -Can be used to resize a tuple. \var{newsize} will be the new length -of the tuple. Because tuples are \emph{supposed} to be immutable, -this should only be used if there is only one reference to the object. -Do \emph{not} use this if the tuple may already be known to some other -part of the code. The tuple will always grow or shrink at the end. -Think of this as destroying the old tuple and creating a new one, only -more efficiently. Returns \code{0} on success. Client code should -never assume that the resulting value of \code{*\var{p}} will be the -same as before calling this function. If the object referenced by -\code{*\var{p}} is replaced, the original \code{*\var{p}} is -destroyed. On failure, returns \code{-1} and sets \code{*\var{p}} to -\NULL, and raises \exception{MemoryError} or \exception{SystemError}. -\versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2} -\end{cfuncdesc} - - -\subsection{List Objects \label{listObjects}} - -\obindex{list} -\begin{ctypedesc}{PyListObject} -This subtype of \ctype{PyObject} represents a Python list object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyList_Type} -This instance of \ctype{PyTypeObject} represents the Python list -type. This is the same object as \code{types.ListType}. -\withsubitem{(in module types)}{\ttindex{ListType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p} -Returns true if its argument is a \ctype{PyListObject}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyList_New}{int len} -Returns a new list of length \var{len} on success, or \NULL{} on -failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Size}{PyObject *list} -Returns the length of the list object in \var{list}; this is -equivalent to \samp{len(\var{list})} on a list object. -\bifuncindex{len} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list} -Macro form of \cfunction{PyList_Size()} without error checking. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index} -Returns the object at position \var{pos} in the list pointed -to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and -sets an \exception{IndexError} exception. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i} -Macro form of \cfunction{PyList_GetItem()} without error checking. -\end{cfuncdesc} - -\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}{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} - -\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index, - PyObject *item} -Inserts the item \var{item} into list \var{list} in front of index -\var{index}. Returns \code{0} if successful; returns \code{-1} and -raises an exception if unsuccessful. Analogous to -\code{\var{list}.insert(\var{index}, \var{item})}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item} -Appends the object \var{item} at the end of list \var{list}. Returns -\code{0} if successful; returns \code{-1} and sets an exception if -unsuccessful. Analogous to \code{\var{list}.append(\var{item})}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list, - int low, int high} -Returns a list of the objects in \var{list} containing the objects -\emph{between} \var{low} and \var{high}. Returns NULL and sets an -exception if unsuccessful. -Analogous to \code{\var{list}[\var{low}:\var{high}]}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list, - int low, int high, - PyObject *itemlist} -Sets the slice of \var{list} between \var{low} and \var{high} to the -contents of \var{itemlist}. Analogous to -\code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}. Returns -\code{0} on success, \code{-1} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list} -Sorts the items of \var{list} in place. Returns \code{0} on success, -\code{-1} on failure. This is equivalent to -\samp{\var{list}.sort()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list} -Reverses the items of \var{list} in place. Returns \code{0} on -success, \code{-1} on failure. This is the equivalent of -\samp{\var{list}.reverse()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list} -Returns a new tuple object containing the contents of \var{list}; -equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple} -\end{cfuncdesc} - - -\section{Mapping Objects \label{mapObjects}} - -\obindex{mapping} - - -\subsection{Dictionary Objects \label{dictObjects}} - -\obindex{dictionary} -\begin{ctypedesc}{PyDictObject} -This subtype of \ctype{PyObject} represents a Python dictionary object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyDict_Type} -This instance of \ctype{PyTypeObject} represents the Python dictionary -type. This is exposed to Python programs as \code{types.DictType} and -\code{types.DictionaryType}. -\withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p} -Returns true if its argument is a \ctype{PyDictObject}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDict_New}{} -Returns a new empty dictionary, or \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDictProxy_New}{PyObject *dict} -Return a proxy object for a mapping which enforces read-only -behavior. This is normally used to create a proxy to prevent -modification of the dictionary for non-dynamic class types. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p} -Empties an existing dictionary of all key-value pairs. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p} -Returns a new dictionary that contains the same key-value pairs as -\var{p}. -\versionadded{1.6} -\end{cfuncdesc} - -\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} - -\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p, - 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} - -\begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key} -Removes the entry in dictionary \var{p} with key \var{key}. -\var{key} must be hashable; if it isn't, \exception{TypeError} is -raised. -\end{cfuncdesc} - -\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} -Returns the object from dictionary \var{p} which has a key -\var{key}. Returns \NULL{} if the key \var{key} is not present, but -\emph{without} setting an exception. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, char *key} -This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is -specified as a \ctype{char*}, rather than a \ctype{PyObject*}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyObject *p} -Returns a \ctype{PyListObject} containing all the items -from the dictionary, as in the dictinoary method \method{items()} (see -the \citetitle[../lib/lib.html]{Python Library Reference}). -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p} -Returns a \ctype{PyListObject} containing all the keys -from the dictionary, as in the dictionary method \method{keys()} (see the -\citetitle[../lib/lib.html]{Python Library Reference}). -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyObject *p} -Returns a \ctype{PyListObject} containing all the values -from the dictionary \var{p}, as in the dictionary method -\method{values()} (see the \citetitle[../lib/lib.html]{Python Library -Reference}). -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_Size}{PyObject *p} -Returns the number of items in the dictionary. This is equivalent to -\samp{len(\var{p})} on a dictionary.\bifuncindex{len} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, int *ppos, - PyObject **pkey, PyObject **pvalue} -Iterate over all key-value pairs in the dictionary \var{p}. The -\ctype{int} referred to by \var{ppos} must be initialized to \code{0} -prior to the first call to this function to start the iteration; the -function returns true for each pair in the dictionary, and false once -all pairs have been reported. The parameters \var{pkey} and -\var{pvalue} should either point to \ctype{PyObject*} variables that -will be filled in with each key and value, respectively, or may be -\NULL. - -For example: - -\begin{verbatim} -PyObject *key, *value; -int pos = 0; - -while (PyDict_Next(self->dict, &pos, &key, &value)) { - /* do something interesting with the values... */ - ... -} -\end{verbatim} - -The dictionary \var{p} should not be mutated during iteration. It is -safe (since Python 2.1) to modify the values of the keys as you -iterate over the dictionary, but only so long as the set of keys does -not change. For example: - -\begin{verbatim} -PyObject *key, *value; -int pos = 0; - -while (PyDict_Next(self->dict, &pos, &key, &value)) { - int i = PyInt_AS_LONG(value) + 1; - PyObject *o = PyInt_FromLong(i); - if (o == NULL) - return -1; - if (PyDict_SetItem(self->dict, key, o) < 0) { - Py_DECREF(o); - return -1; - } - Py_DECREF(o); -} -\end{verbatim} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_Merge}{PyObject *a, PyObject *b, int override} -Iterate over dictionary \var{b} adding key-value pairs to dictionary -\var{a}. If \var{override} is true, existing pairs in \var{a} will be -replaced if a matching key is found in \var{b}, otherwise pairs will -only be added if there is not a matching key in \var{a}. Returns -\code{0} on success or \code{-1} if an exception was raised. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDict_Update}{PyObject *a, PyObject *b} -This is the same as \code{PyDict_Merge(\var{a}, \var{b}, 1)} in C, or -\code{\var{a}.update(\var{b})} in Python. Returns \code{0} on success -or \code{-1} if an exception was raised. -\versionadded{2.2} -\end{cfuncdesc} - - -\section{Other Objects \label{otherObjects}} - -\subsection{File Objects \label{fileObjects}} - -\obindex{file} -Python's built-in file objects are implemented entirely on the -\ctype{FILE*} support from the C standard library. This is an -implementation detail and may change in future releases of Python. - -\begin{ctypedesc}{PyFileObject} -This subtype of \ctype{PyObject} represents a Python file object. -\end{ctypedesc} - -\begin{cvardesc}{PyTypeObject}{PyFile_Type} -This instance of \ctype{PyTypeObject} represents the Python file -type. This is exposed to Python programs as \code{types.FileType}. -\withsubitem{(in module types)}{\ttindex{FileType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p} -Returns true if its argument is a \ctype{PyFileObject} or a subtype of -\ctype{PyFileObject}. -\versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyFile_CheckExact}{PyObject *p} -Returns true if its argument is a \ctype{PyFileObject}, but not a -subtype of \ctype{PyFileObject}. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode} -On success, returns a new file object that is opened on the -file given by \var{filename}, with a file mode given by \var{mode}, -where \var{mode} has the same semantics as the standard C routine -\cfunction{fopen()}\ttindex{fopen()}. On failure, returns \NULL. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, - char *name, char *mode, - int (*close)(FILE*)} -Creates a new \ctype{PyFileObject} from the already-open standard C -file pointer, \var{fp}. The function \var{close} will be called when -the file should be closed. Returns \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyFileObject *p} -Returns the file object associated with \var{p} as a \ctype{FILE*}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n} -Equivalent to \code{\var{p}.readline(\optional{\var{n}})}, this -function reads one line from the object \var{p}. \var{p} may be a -file object or any object with a \method{readline()} method. If -\var{n} is \code{0}, exactly one line is read, regardless of the -length of the line. If \var{n} is greater than \code{0}, no more than -\var{n} bytes will be read from the file; a partial line can be -returned. In both cases, an empty string is returned if the end of -the file is reached immediately. If \var{n} is less than \code{0}, -however, one line is read regardless of length, but -\exception{EOFError} is raised if the end of the file is reached -immediately. -\withsubitem{(built-in exception)}{\ttindex{EOFError}} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p} -Returns the name of the file specified by \var{p} as a string object. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n} -Available on systems with \cfunction{setvbuf()}\ttindex{setvbuf()} -only. This should only be called immediately after file object -creation. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag} -This function exists for internal use by the interpreter. -Sets the \member{softspace} attribute of \var{p} to \var{newflag} and -\withsubitem{(file attribute)}{\ttindex{softspace}}returns the -previous value. \var{p} does not have to be a file object -for this function to work properly; any object is supported (thought -its only interesting if the \member{softspace} attribute can be set). -This function clears any errors, and will return \code{0} as the -previous value if the attribute either does not exist or if there were -errors in retrieving it. There is no way to detect errors from this -function, but doing so should not be needed. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p, - int flags} -Writes object \var{obj} to file object \var{p}. The only supported -flag for \var{flags} is \constant{Py_PRINT_RAW}\ttindex{Py_PRINT_RAW}; -if given, the \function{str()} of the object is written instead of the -\function{repr()}. Returns \code{0} on success or \code{-1} on -failure; the appropriate exception will be set. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p} -Writes string \var{s} to file object \var{p}. Returns \code{0} on -success or \code{-1} on failure; the appropriate exception will be -set. -\end{cfuncdesc} - - -\subsection{Instance Objects \label{instanceObjects}} - -\obindex{instance} -There are very few functions specific to instance objects. - -\begin{cvardesc}{PyTypeObject}{PyInstance_Type} - Type object for class instances. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj} - Returns true if \var{obj} is an instance. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class, - PyObject *arg, - PyObject *kw} - Create a new instance of a specific class. The parameters \var{arg} - and \var{kw} are used as the positional and keyword parameters to - the object's constructor. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class, - PyObject *dict} - Create a new instance of a specific class without calling it's - constructor. \var{class} is the class of new object. The - \var{dict} parameter will be used as the object's \member{__dict__}; - if \NULL, a new dictionary will be created for the instance. -\end{cfuncdesc} - - -\subsection{Method Objects \label{method-objects}} - -\obindex{method} -There are some useful functions that are useful for working with -method objects. - -\begin{cvardesc}{PyTypeObject}{PyMethod_Type} - This instance of \ctype{PyTypeObject} represents the Python method - type. This is exposed to Python programs as \code{types.MethodType}. - \withsubitem{(in module types)}{\ttindex{MethodType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyMethod_Check}{PyObject *o} - Return true if \var{o} is a method object (has type - \cdata{PyMethod_Type}). The parameter must not be \NULL. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func. - PyObject *self, PyObject *class} - Return a new method object, with \var{func} being any callable - object; this is the function that will be called when the method is - called. If this method should be bound to an instance, \var{self} - should be the instance and \var{class} should be the class of - \var{self}, otherwise \var{self} should be \NULL{} and \var{class} - should be the class which provides the unbound method.. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_Class}{PyObject *meth} - Return the class object from which the method \var{meth} was - created; if this was created from an instance, it will be the class - of the instance. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_GET_CLASS}{PyObject *meth} - Macro version of \cfunction{PyMethod_Class()} which avoids error - checking. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_Function}{PyObject *meth} - Return the function object associated with the method \var{meth}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_GET_FUNCTION}{PyObject *meth} - Macro version of \cfunction{PyMethod_Function()} which avoids error - checking. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth} - Return the instance associated with the method \var{meth} if it is - bound, otherwise return \NULL. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyMethod_GET_SELF}{PyObject *meth} - Macro version of \cfunction{PyMethod_Self()} which avoids error - checking. -\end{cfuncdesc} - - -\subsection{Module Objects \label{moduleObjects}} - -\obindex{module} -There are only a few functions special to module objects. - -\begin{cvardesc}{PyTypeObject}{PyModule_Type} -This instance of \ctype{PyTypeObject} represents the Python module -type. This is exposed to Python programs as \code{types.ModuleType}. -\withsubitem{(in module types)}{\ttindex{ModuleType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p} -Returns true if \var{p} is a module object, or a subtype of a -module object. -\versionchanged[Allowed subtypes to be accepted]{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyModule_CheckExact}{PyObject *p} -Returns true if \var{p} is a module object, but not a subtype of -\cdata{PyModule_Type}. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyModule_New}{char *name} -Return a new module object with the \member{__name__} attribute set to -\var{name}. Only the module's \member{__doc__} and -\member{__name__} attributes are filled in; the caller is responsible -for providing a \member{__file__} attribute. -\withsubitem{(module attribute)}{ - \ttindex{__name__}\ttindex{__doc__}\ttindex{__file__}} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module} -Return the dictionary object that implements \var{module}'s namespace; -this object is the same as the \member{__dict__} attribute of the -module object. This function never fails. -\withsubitem{(module attribute)}{\ttindex{__dict__}} -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module} -Return \var{module}'s \member{__name__} value. If the module does not -provide one, or if it is not a string, \exception{SystemError} is -raised and \NULL{} is returned. -\withsubitem{(module attribute)}{\ttindex{__name__}} -\withsubitem{(built-in exception)}{\ttindex{SystemError}} -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module} -Return the name of the file from which \var{module} was loaded using -\var{module}'s \member{__file__} attribute. If this is not defined, -or if it is not a string, raise \exception{SystemError} and return -\NULL. -\withsubitem{(module attribute)}{\ttindex{__file__}} -\withsubitem{(built-in exception)}{\ttindex{SystemError}} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module, - char *name, PyObject *value} -Add an object to \var{module} as \var{name}. This is a convenience -function which can be used from the module's initialization function. -This steals a reference to \var{value}. Returns \code{-1} on error, -\code{0} on success. -\versionadded{2.0} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module, - char *name, int value} -Add an integer constant to \var{module} as \var{name}. This convenience -function can be used from the module's initialization function. -Returns \code{-1} on error, \code{0} on success. -\versionadded{2.0} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module, - char *name, char *value} -Add a string constant to \var{module} as \var{name}. This convenience -function can be used from the module's initialization function. The -string \var{value} must be null-terminated. Returns \code{-1} on -error, \code{0} on success. -\versionadded{2.0} -\end{cfuncdesc} - - -\subsection{Iterator Objects \label{iterator-objects}} - -Python provides two general-purpose iterator objects. The first, a -sequence iterator, works with an arbitrary sequence supporting the -\method{__getitem__()} method. The second works with a callable -object and a sentinel value, calling the callable for each item in the -sequence, and ending the iteration when the sentinel value is -returned. - -\begin{cvardesc}{PyTypeObject}{PySeqIter_Type} - Type object for iterator objects returned by - \cfunction{PySeqIter_New()} and the one-argument form of the - \function{iter()} built-in function for built-in sequence types. - \versionadded{2.2} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PySeqIter_Check}{op} - Return true if the type of \var{op} is \cdata{PySeqIter_Type}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySeqIter_New}{PyObject *seq} - Return an iterator that works with a general sequence object, - \var{seq}. The iteration ends when the sequence raises - \exception{IndexError} for the subscripting operation. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cvardesc}{PyTypeObject}{PyCallIter_Type} - Type object for iterator objects returned by - \cfunction{PyCallIter_New()} and the two-argument form of the - \function{iter()} built-in function. - \versionadded{2.2} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyCallIter_Check}{op} - Return true if the type of \var{op} is \cdata{PyCallIter_Type}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyCallIter_New}{PyObject *callable, - PyObject *sentinel} - Return a new iterator. The first parameter, \var{callable}, can be - any Python callable object that can be called with no parameters; - each call to it should return the next item in the iteration. When - \var{callable} returns a value equal to \var{sentinel}, the - iteration will be terminated. - \versionadded{2.2} -\end{cfuncdesc} - - -\subsection{Descriptor Objects \label{descriptor-objects}} - -\begin{cvardesc}{PyTypeObject}{PyProperty_Type} - The type object for a descriptor. - \versionadded{2.2} -\end{cvardesc} - -\begin{cfuncdesc}{PyObject*}{PyDescr_NewGetSet}{PyTypeObject *type, - PyGetSetDef *getset} - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDescr_NewMember}{PyTypeObject *type, - PyMemberDef *meth} - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDescr_NewMethod}{PyTypeObject *type, - PyMethodDef *meth} - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyDescr_NewWrapper}{PyTypeObject *type, - struct wrapperbase *wrapper, - void *wrapped} - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyDescr_IsData}{PyObject *descr} - Returns true if the descriptor objects \var{descr} describes a data - attribute, or false if it describes a method. \var{descr} must be a - descriptor object; there is no error checking. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyWrapper_New}{PyObject *, PyObject *} - \versionadded{2.2} -\end{cfuncdesc} - - -\subsection{Slice Objects \label{slice-objects}} - -\begin{cvardesc}{PyTypeObject}{PySlice_Type} - The type object for slice objects. This is the same as - \code{types.SliceType}. - \withsubitem{(in module types)}{\ttindex{SliceType}} -\end{cvardesc} - -\begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob} - Returns true if \var{ob} is a slice object; \var{ob} must not be - \NULL. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySlice_New}{PyObject *start, PyObject *stop, - PyObject *step} - Return a new slice object with the given values. The \var{start}, - \var{stop}, and \var{step} parameters are used as the values of the - slice object attributes of the same names. Any of the values may be - \NULL, in which case the \code{None} will be used for the - corresponding attribute. Returns \NULL{} if the new object could - not be allocated. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySlice_GetIndices}{PySliceObject *slice, int length, - int *start, int *stop, int *step} -\end{cfuncdesc} - - -\subsection{Weak Reference Objects \label{weakref-objects}} - -Python supports \emph{weak references} as first-class objects. There -are two specific object types which directly implement weak -references. The first is a simple reference object, and the second -acts as a proxy for the original object as much as it can. - -\begin{cfuncdesc}{int}{PyWeakref_Check}{ob} - Return true if \var{ob} is either a reference or proxy object. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyWeakref_CheckRef}{ob} - Return true if \var{ob} is a reference object. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyWeakref_CheckProxy}{ob} - Return true if \var{ob} is a proxy object. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyWeakref_NewRef}{PyObject *ob, - PyObject *callback} - Return a weak reference object for the object \var{ob}. This will - always return a new reference, but is not guaranteed to create a new - object; an existing reference object may be returned. The second - parameter, \var{callback}, can be a callable object that receives - notification when \var{ob} is garbage collected; it should accept a - single paramter, which will be the weak reference object itself. - \var{callback} may also be \code{None} or \NULL. If \var{ob} - is not a weakly-referencable object, or if \var{callback} is not - callable, \code{None}, or \NULL, this will return \NULL{} and - raise \exception{TypeError}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyWeakref_NewProxy}{PyObject *ob, - PyObject *callback} - Return a weak reference proxy object for the object \var{ob}. This - will always return a new reference, but is not guaranteed to create - a new object; an existing proxy object may be returned. The second - parameter, \var{callback}, can be a callable object that receives - notification when \var{ob} is garbage collected; it should accept a - single paramter, which will be the weak reference object itself. - \var{callback} may also be \code{None} or \NULL. If \var{ob} is not - a weakly-referencable object, or if \var{callback} is not callable, - \code{None}, or \NULL, this will return \NULL{} and raise - \exception{TypeError}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyWeakref_GetObject}{PyObject *ref} - Returns the referenced object from a weak reference, \var{ref}. If - the referent is no longer live, returns \NULL. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyWeakref_GET_OBJECT}{PyObject *ref} - Similar to \cfunction{PyWeakref_GetObject()}, but implemented as a - macro that does no error checking. - \versionadded{2.2} -\end{cfuncdesc} - - -\subsection{CObjects \label{cObjects}} - -\obindex{CObject} -Refer to \emph{Extending and Embedding the Python Interpreter}, -section 1.12 (``Providing a C API for an Extension Module), for more -information on using these objects. - - -\begin{ctypedesc}{PyCObject} -This subtype of \ctype{PyObject} represents an opaque value, useful for -C extension modules who need to pass an opaque value (as a -\ctype{void*} pointer) through Python code to other C code. It is -often used to make a C function pointer defined in one module -available to other modules, so the regular import mechanism can be -used to access C APIs defined in dynamically loaded modules. -\end{ctypedesc} - -\begin{cfuncdesc}{int}{PyCObject_Check}{PyObject *p} -Returns true if its argument is a \ctype{PyCObject}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj, - void (*destr)(void *)} -Creates a \ctype{PyCObject} from the \code{void *}\var{cobj}. The -\var{destr} function will be called when the object is reclaimed, unless -it is \NULL. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj, - void* desc, void (*destr)(void *, void *) } -Creates a \ctype{PyCObject} from the \ctype{void *}\var{cobj}. The -\var{destr} function will be called when the object is reclaimed. The -\var{desc} argument can be used to pass extra callback data for the -destructor function. -\end{cfuncdesc} - -\begin{cfuncdesc}{void*}{PyCObject_AsVoidPtr}{PyObject* self} -Returns the object \ctype{void *} that the -\ctype{PyCObject} \var{self} was created with. -\end{cfuncdesc} - -\begin{cfuncdesc}{void*}{PyCObject_GetDesc}{PyObject* self} -Returns the description \ctype{void *} that the -\ctype{PyCObject} \var{self} was created with. -\end{cfuncdesc} - - -\chapter{Initialization, Finalization, and Threads - \label{initialization}} - -\begin{cfuncdesc}{void}{Py_Initialize}{} -Initialize the Python interpreter. In an application embedding -Python, this should be called before using any other Python/C API -functions; with the exception of -\cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, -\cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()}, -\cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()}, -and \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}. -This initializes the table of loaded modules (\code{sys.modules}), and -\withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}}creates the -fundamental modules \module{__builtin__}\refbimodindex{__builtin__}, -\module{__main__}\refbimodindex{__main__} and -\module{sys}\refbimodindex{sys}. It also initializes the module -search\indexiii{module}{search}{path} path (\code{sys.path}). -It does not set \code{sys.argv}; use -\cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} for that. This -is a no-op when called for a second time (without calling -\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} first). There is no -return value; it is a fatal error if the initialization fails. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{Py_IsInitialized}{} -Return true (nonzero) when the Python interpreter has been -initialized, false (zero) if not. After \cfunction{Py_Finalize()} is -called, this returns false until \cfunction{Py_Initialize()} is called -again. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{Py_Finalize}{} -Undo all initializations made by \cfunction{Py_Initialize()} and -subsequent use of Python/C API functions, and destroy all -sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that were -created and not yet destroyed since the last call to -\cfunction{Py_Initialize()}. Ideally, this frees all memory allocated -by the Python interpreter. This is a no-op when called for a second -time (without calling \cfunction{Py_Initialize()} again first). There -is no return value; errors during finalization are ignored. - -This function is provided for a number of reasons. An embedding -application might want to restart Python without having to restart the -application itself. An application that has loaded the Python -interpreter from a dynamically loadable library (or DLL) might want to -free all memory allocated by Python before unloading the DLL. During a -hunt for memory leaks in an application a developer might want to free -all memory allocated by Python before exiting from the application. - -\strong{Bugs and caveats:} The destruction of modules and objects in -modules is done in random order; this may cause destructors -(\method{__del__()} methods) to fail when they depend on other objects -(even functions) or modules. Dynamically loaded extension modules -loaded by Python are not unloaded. Small amounts of memory allocated -by the Python interpreter may not be freed (if you find a leak, please -report it). Memory tied up in circular references between objects is -not freed. Some memory allocated by extension modules may not be -freed. Some extension may not work properly if their initialization -routine is called more than once; this can happen if an applcation -calls \cfunction{Py_Initialize()} and \cfunction{Py_Finalize()} more -than once. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{} -Create a new sub-interpreter. This is an (almost) totally separate -environment for the execution of Python code. In particular, the new -interpreter has separate, independent versions of all imported -modules, including the fundamental modules -\module{__builtin__}\refbimodindex{__builtin__}, -\module{__main__}\refbimodindex{__main__} and -\module{sys}\refbimodindex{sys}. The table of loaded modules -(\code{sys.modules}) and the module search path (\code{sys.path}) are -also separate. The new environment has no \code{sys.argv} variable. -It has new standard I/O stream file objects \code{sys.stdin}, -\code{sys.stdout} and \code{sys.stderr} (however these refer to the -same underlying \ctype{FILE} structures in the C library). -\withsubitem{(in module sys)}{ - \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}} - -The return value points to the first thread state created in the new -sub-interpreter. This thread state is made the current thread state. -Note that no actual thread is created; see the discussion of thread -states below. If creation of the new interpreter is unsuccessful, -\NULL{} is returned; no exception is set since the exception state -is stored in the current thread state and there may not be a current -thread state. (Like all other Python/C API functions, the global -interpreter lock must be held before calling this function and is -still held when it returns; however, unlike most other Python/C API -functions, there needn't be a current thread state on entry.) - -Extension modules are shared between (sub-)interpreters as follows: -the first time a particular extension is imported, it is initialized -normally, and a (shallow) copy of its module's dictionary is -squirreled away. When the same extension is imported by another -(sub-)interpreter, a new module is initialized and filled with the -contents of this copy; the extension's \code{init} function is not -called. Note that this is different from what happens when an -extension is imported after the interpreter has been completely -re-initialized by calling -\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and -\cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case, -the extension's \code{init\var{module}} function \emph{is} called -again. - -\strong{Bugs and caveats:} Because sub-interpreters (and the main -interpreter) are part of the same process, the insulation between them -isn't perfect --- for example, using low-level file operations like -\withsubitem{(in module os)}{\ttindex{close()}} -\function{os.close()} they can (accidentally or maliciously) affect each -other's open files. Because of the way extensions are shared between -(sub-)interpreters, some extensions may not work properly; this is -especially likely when the extension makes use of (static) global -variables, or when the extension manipulates its module's dictionary -after its initialization. It is possible to insert objects created in -one sub-interpreter into a namespace of another sub-interpreter; this -should be done with great care to avoid sharing user-defined -functions, methods, instances or classes between sub-interpreters, -since import operations executed by such objects may affect the -wrong (sub-)interpreter's dictionary of loaded modules. (XXX This is -a hard-to-fix bug that will be addressed in a future release.) -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate} -Destroy the (sub-)interpreter represented by the given thread state. -The given thread state must be the current thread state. See the -discussion of thread states below. When the call returns, the current -thread state is \NULL{}. All thread states associated with this -interpreted are destroyed. (The global interpreter lock must be held -before calling this function and is still held when it returns.) -\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} will destroy all -sub-interpreters that haven't been explicitly destroyed at that point. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name} -This function should be called before -\cfunction{Py_Initialize()}\ttindex{Py_Initialize()} is called -for the first time, if it is called at all. It tells the interpreter -the value of the \code{argv[0]} argument to the -\cfunction{main()}\ttindex{main()} function of the program. This is -used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some other -functions below to find the Python run-time libraries relative to the -interpreter executable. The default value is \code{'python'}. The -argument should point to a zero-terminated character string in static -storage whose contents will not change for the duration of the -program's execution. No code in the Python interpreter will change -the contents of this storage. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{Py_GetProgramName}{} -Return the program name set with -\cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, or the -default. The returned string points into static storage; the caller -should not modify its value. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{Py_GetPrefix}{} -Return the \emph{prefix} for installed platform-independent files. This -is derived through a number of complicated rules from the program name -set with \cfunction{Py_SetProgramName()} and some environment variables; -for example, if the program name is \code{'/usr/local/bin/python'}, -the prefix is \code{'/usr/local'}. The returned string points into -static storage; the caller should not modify its value. This -corresponds to the \makevar{prefix} variable in the top-level -\file{Makefile} and the \longprogramopt{prefix} argument to the -\program{configure} script at build time. The value is available to -Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See -also the next function. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{Py_GetExecPrefix}{} -Return the \emph{exec-prefix} for installed platform-\emph{de}pendent -files. This is derived through a number of complicated rules from the -program name set with \cfunction{Py_SetProgramName()} and some environment -variables; for example, if the program name is -\code{'/usr/local/bin/python'}, the exec-prefix is -\code{'/usr/local'}. The returned string points into static storage; -the caller should not modify its value. This corresponds to the -\makevar{exec_prefix} variable in the top-level \file{Makefile} and the -\longprogramopt{exec-prefix} argument to the -\program{configure} script at build time. The value is available to -Python code as \code{sys.exec_prefix}. It is only useful on \UNIX{}. - -Background: The exec-prefix differs from the prefix when platform -dependent files (such as executables and shared libraries) are -installed in a different directory tree. In a typical installation, -platform dependent files may be installed in the -\file{/usr/local/plat} subtree while platform independent may be -installed in \file{/usr/local}. - -Generally speaking, a platform is a combination of hardware and -software families, e.g. Sparc machines running the Solaris 2.x -operating system are considered the same platform, but Intel machines -running Solaris 2.x are another platform, and Intel machines running -Linux are yet another platform. Different major revisions of the same -operating system generally also form different platforms. Non-\UNIX{} -operating systems are a different story; the installation strategies -on those systems are so different that the prefix and exec-prefix are -meaningless, and set to the empty string. Note that compiled Python -bytecode files are platform independent (but not independent from the -Python version by which they were compiled!). - -System administrators will know how to configure the \program{mount} or -\program{automount} programs to share \file{/usr/local} between platforms -while having \file{/usr/local/plat} be a different filesystem for each -platform. -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{} -Return the full program name of the Python executable; this is -computed as a side-effect of deriving the default module search path -from the program name (set by -\cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()} above). -The returned string points into static storage; the caller should not -modify its value. The value is available to Python code as -\code{sys.executable}. -\withsubitem{(in module sys)}{\ttindex{executable}} -\end{cfuncdesc} - -\begin{cfuncdesc}{char*}{Py_GetPath}{} -\indexiii{module}{search}{path} -Return the default module search path; this is computed from the -program name (set by \cfunction{Py_SetProgramName()} above) and some -environment variables. The returned string consists of a series of -directory names separated by a platform dependent delimiter character. -The delimiter character is \character{:} on \UNIX{}, \character{;} on -DOS/Windows, and \character{\e n} (the \ASCII{} newline character) on -Macintosh. The returned string points into static storage; the caller -should not modify its value. The value is available to Python code -as the list \code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}}, -which may be modified to change the future search path for loaded -modules. - -% XXX should give the exact rules -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{Py_GetVersion}{} -Return the version of this Python interpreter. This is a string that -looks something like - -\begin{verbatim} -"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]" -\end{verbatim} - -The first word (up to the first space character) is the current Python -version; the first three characters are the major and minor version -separated by a period. The returned string points into static storage; -the caller should not modify its value. The value is available to -Python code as the list \code{sys.version}. -\withsubitem{(in module sys)}{\ttindex{version}} -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{Py_GetPlatform}{} -Return the platform identifier for the current platform. On \UNIX{}, -this is formed from the ``official'' name of the operating system, -converted to lower case, followed by the major revision number; e.g., -for Solaris 2.x, which is also known as SunOS 5.x, the value is -\code{'sunos5'}. On Macintosh, it is \code{'mac'}. On Windows, it -is \code{'win'}. The returned string points into static storage; -the caller should not modify its value. The value is available to -Python code as \code{sys.platform}. -\withsubitem{(in module sys)}{\ttindex{platform}} -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{Py_GetCopyright}{} -Return the official copyright string for the current Python version, -for example - -\code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'} - -The returned string points into static storage; the caller should not -modify its value. The value is available to Python code as the list -\code{sys.copyright}. -\withsubitem{(in module sys)}{\ttindex{copyright}} -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{Py_GetCompiler}{} -Return an indication of the compiler used to build the current Python -version, in square brackets, for example: - -\begin{verbatim} -"[GCC 2.7.2.2]" -\end{verbatim} - -The returned string points into static storage; the caller should not -modify its value. The value is available to Python code as part of -the variable \code{sys.version}. -\withsubitem{(in module sys)}{\ttindex{version}} -\end{cfuncdesc} - -\begin{cfuncdesc}{const char*}{Py_GetBuildInfo}{} -Return information about the sequence number and build date and time -of the current Python interpreter instance, for example - -\begin{verbatim} -"#67, Aug 1 1997, 22:34:28" -\end{verbatim} - -The returned string points into static storage; the caller should not -modify its value. The value is available to Python code as part of -the variable \code{sys.version}. -\withsubitem{(in module sys)}{\ttindex{version}} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv} -Set \code{sys.argv} based on \var{argc} and \var{argv}. These -parameters are similar to those passed to the program's -\cfunction{main()}\ttindex{main()} function with the difference that -the first entry should refer to the script file to be executed rather -than the executable hosting the Python interpreter. If there isn't a -script that will be run, the first entry in \var{argv} can be an empty -string. If this function fails to initialize \code{sys.argv}, a fatal -condition is signalled using -\cfunction{Py_FatalError()}\ttindex{Py_FatalError()}. -\withsubitem{(in module sys)}{\ttindex{argv}} -% XXX impl. doesn't seem consistent in allowing 0/NULL for the params; -% check w/ Guido. -\end{cfuncdesc} - -% XXX Other PySys thingies (doesn't really belong in this chapter) - -\section{Thread State and the Global Interpreter Lock - \label{threads}} - -\index{global interpreter lock} -\index{interpreter lock} -\index{lock, interpreter} - -The Python interpreter is not fully thread safe. In order to support -multi-threaded Python programs, there's a global lock that must be -held by the current thread before it can safely access Python objects. -Without the lock, even the simplest operations could cause problems in -a multi-threaded program: for example, when two threads simultaneously -increment the reference count of the same object, the reference count -could end up being incremented only once instead of twice. - -Therefore, the rule exists that only the thread that has acquired the -global interpreter lock may operate on Python objects or call Python/C -API functions. In order to support multi-threaded Python programs, -the interpreter regularly releases and reacquires the lock --- by -default, every ten bytecode instructions (this can be changed with -\withsubitem{(in module sys)}{\ttindex{setcheckinterval()}} -\function{sys.setcheckinterval()}). The lock is also released and -reacquired around potentially blocking I/O operations like reading or -writing a file, so that other threads can run while the thread that -requests the I/O is waiting for the I/O operation to complete. - -The Python interpreter needs to keep some bookkeeping information -separate per thread --- for this it uses a data structure called -\ctype{PyThreadState}\ttindex{PyThreadState}. This is new in Python -1.5; in earlier versions, such state was stored in global variables, -and switching threads could cause problems. In particular, exception -handling is now thread safe, when the application uses -\withsubitem{(in module sys)}{\ttindex{exc_info()}} -\function{sys.exc_info()} to access the exception last raised in the -current thread. - -There's one global variable left, however: the pointer to the current -\ctype{PyThreadState}\ttindex{PyThreadState} structure. While most -thread packages have a way to store ``per-thread global data,'' -Python's internal platform independent thread abstraction doesn't -support this yet. Therefore, the current thread state must be -manipulated explicitly. - -This is easy enough in most cases. Most code manipulating the global -interpreter lock has the following simple structure: - -\begin{verbatim} -Save the thread state in a local variable. -Release the interpreter lock. -...Do some blocking I/O operation... -Reacquire the interpreter lock. -Restore the thread state from the local variable. -\end{verbatim} - -This is so common that a pair of macros exists to simplify it: - -\begin{verbatim} -Py_BEGIN_ALLOW_THREADS -...Do some blocking I/O operation... -Py_END_ALLOW_THREADS -\end{verbatim} - -The \code{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS} macro -opens a new block and declares a hidden local variable; the -\code{Py_END_ALLOW_THREADS}\ttindex{Py_END_ALLOW_THREADS} macro closes -the block. Another advantage of using these two macros is that when -Python is compiled without thread support, they are defined empty, -thus saving the thread state and lock manipulations. - -When thread support is enabled, the block above expands to the -following code: - -\begin{verbatim} - PyThreadState *_save; - - _save = PyEval_SaveThread(); - ...Do some blocking I/O operation... - PyEval_RestoreThread(_save); -\end{verbatim} - -Using even lower level primitives, we can get roughly the same effect -as follows: - -\begin{verbatim} - PyThreadState *_save; - - _save = PyThreadState_Swap(NULL); - PyEval_ReleaseLock(); - ...Do some blocking I/O operation... - PyEval_AcquireLock(); - PyThreadState_Swap(_save); -\end{verbatim} - -There are some subtle differences; in particular, -\cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} saves -and restores the value of the global variable -\cdata{errno}\ttindex{errno}, since the lock manipulation does not -guarantee that \cdata{errno} is left alone. Also, when thread support -is disabled, -\cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and -\cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this -case, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and -\cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()} are not -available. This is done so that dynamically loaded extensions -compiled with thread support enabled can be loaded by an interpreter -that was compiled with disabled thread support. - -The global interpreter lock is used to protect the pointer to the -current thread state. When releasing the lock and saving the thread -state, the current thread state pointer must be retrieved before the -lock is released (since another thread could immediately acquire the -lock and store its own thread state in the global variable). -Conversely, when acquiring the lock and restoring the thread state, -the lock must be acquired before storing the thread state pointer. - -Why am I going on with so much detail about this? Because when -threads are created from C, they don't have the global interpreter -lock, nor is there a thread state data structure for them. Such -threads must bootstrap themselves into existence, by first creating a -thread state data structure, then acquiring the lock, and finally -storing their thread state pointer, before they can start using the -Python/C API. When they are done, they should reset the thread state -pointer, release the lock, and finally free their thread state data -structure. - -When creating a thread data structure, you need to provide an -interpreter state data structure. The interpreter state data -structure hold global data that is shared by all threads in an -interpreter, for example the module administration -(\code{sys.modules}). Depending on your needs, you can either create -a new interpreter state data structure, or share the interpreter state -data structure used by the Python main thread (to access the latter, -you must obtain the thread state and access its \member{interp} member; -this must be done by a thread that is created by Python or by the main -thread after Python is initialized). - - -\begin{ctypedesc}{PyInterpreterState} -This data structure represents the state shared by a number of -cooperating threads. Threads belonging to the same interpreter -share their module administration and a few other internal items. -There are no public members in this structure. - -Threads belonging to different interpreters initially share nothing, -except process state like available memory, open file descriptors and -such. The global interpreter lock is also shared by all threads, -regardless of to which interpreter they belong. -\end{ctypedesc} - -\begin{ctypedesc}{PyThreadState} -This data structure represents the state of a single thread. The only -public data member is \ctype{PyInterpreterState *}\member{interp}, -which points to this thread's interpreter state. -\end{ctypedesc} - -\begin{cfuncdesc}{void}{PyEval_InitThreads}{} -Initialize and acquire the global interpreter lock. It should be -called in the main thread before creating a second thread or engaging -in any other thread operations such as -\cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} or -\code{PyEval_ReleaseThread(\var{tstate})}\ttindex{PyEval_ReleaseThread()}. -It is not needed before calling -\cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} or -\cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}. - -This is a no-op when called for a second time. It is safe to call -this function before calling -\cfunction{Py_Initialize()}\ttindex{Py_Initialize()}. - -When only the main thread exists, no lock operations are needed. This -is a common situation (most Python programs do not use threads), and -the lock operations slow the interpreter down a bit. Therefore, the -lock is not created initially. This situation is equivalent to having -acquired the lock: when there is only a single thread, all object -accesses are safe. Therefore, when this function initializes the -lock, it also acquires it. Before the Python -\module{thread}\refbimodindex{thread} module creates a new thread, -knowing that either it has the lock or the lock hasn't been created -yet, it calls \cfunction{PyEval_InitThreads()}. When this call -returns, it is guaranteed that the lock has been created and that it -has acquired it. - -It is \strong{not} safe to call this function when it is unknown which -thread (if any) currently has the global interpreter lock. - -This function is not available when thread support is disabled at -compile time. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyEval_AcquireLock}{} -Acquire the global interpreter lock. The lock must have been created -earlier. If this thread already has the lock, a deadlock ensues. -This function is not available when thread support is disabled at -compile time. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{} -Release the global interpreter lock. The lock must have been created -earlier. This function is not available when thread support is -disabled at compile time. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate} -Acquire the global interpreter lock and then set the current thread -state to \var{tstate}, which should not be \NULL{}. The lock must -have been created earlier. If this thread already has the lock, -deadlock ensues. This function is not available when thread support -is disabled at compile time. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate} -Reset the current thread state to \NULL{} and release the global -interpreter lock. The lock must have been created earlier and must be -held by the current thread. The \var{tstate} argument, which must not -be \NULL{}, is only used to check that it represents the current -thread state --- if it isn't, a fatal error is reported. This -function is not available when thread support is disabled at compile -time. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{} -Release the interpreter lock (if it has been created and thread -support is enabled) and reset the thread state to \NULL{}, -returning the previous thread state (which is not \NULL{}). If -the lock has been created, the current thread must have acquired it. -(This function is available even when thread support is disabled at -compile time.) -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate} -Acquire the interpreter lock (if it has been created and thread -support is enabled) and set the thread state to \var{tstate}, which -must not be \NULL{}. If the lock has been created, the current -thread must not have acquired it, otherwise deadlock ensues. (This -function is available even when thread support is disabled at compile -time.) -\end{cfuncdesc} - -The following macros are normally used without a trailing semicolon; -look for example usage in the Python source distribution. - -\begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS} -This macro expands to -\samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}. -Note that it contains an opening brace; it must be matched with a -following \code{Py_END_ALLOW_THREADS} macro. See above for further -discussion of this macro. It is a no-op when thread support is -disabled at compile time. -\end{csimplemacrodesc} - -\begin{csimplemacrodesc}{Py_END_ALLOW_THREADS} -This macro expands to -\samp{PyEval_RestoreThread(_save); \}}. -Note that it contains a closing brace; it must be matched with an -earlier \code{Py_BEGIN_ALLOW_THREADS} macro. See above for further -discussion of this macro. It is a no-op when thread support is -disabled at compile time. -\end{csimplemacrodesc} - -\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 -time. -\end{csimplemacrodesc} - -\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 -disabled at compile time. -\end{csimplemacrodesc} - -All of the following functions are only available when thread support -is enabled at compile time, and must be called only when the -interpreter lock has been created. - -\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_New}{} -Create a new interpreter state object. The interpreter lock need not -be held, but may be held if it is necessary to serialize calls to this -function. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp} -Reset all information in an interpreter state object. The interpreter -lock must be held. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp} -Destroy an interpreter state object. The interpreter lock need not be -held. The interpreter state must have been reset with a previous -call to \cfunction{PyInterpreterState_Clear()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState*}{PyThreadState_New}{PyInterpreterState *interp} -Create a new thread state object belonging to the given interpreter -object. The interpreter lock need not be held, but may be held if it -is necessary to serialize calls to this function. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate} -Reset all information in a thread state object. The interpreter lock -must be held. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate} -Destroy a thread state object. The interpreter lock need not be -held. The thread state must have been reset with a previous -call to \cfunction{PyThreadState_Clear()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{} -Return the current thread state. The interpreter lock must be held. -When the current thread state is \NULL{}, this issues a fatal -error (so that the caller needn't check for \NULL{}). -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Swap}{PyThreadState *tstate} -Swap the current thread state with the thread state given by the -argument \var{tstate}, which may be \NULL{}. The interpreter lock -must be held. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyThreadState_GetDict}{} -Return a dictionary in which extensions can store thread-specific -state information. Each extension should use a unique key to use to -store state in the dictionary. If this function returns \NULL, an -exception has been raised and the caller should allow it to -propogate. -\end{cfuncdesc} - - -\section{Profiling and Tracing \label{profiling}} - -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -The Python interpreter provides some low-level support for attaching -profiling and execution tracing facilities. These are used for -profiling, debugging, and coverage analysis tools. - -Starting with Python 2.2, the implementation of this facility was -substantially revised, and an interface from C was added. This C -interface allows the profiling or tracing code to avoid the overhead -of calling through Python-level callable objects, making a direct C -function call instead. The essential attributes of the facility have -not changed; the interface allows trace functions to be installed -per-thread, and the basic events reported to the trace function are -the same as had been reported to the Python-level trace functions in -previous versions. - -\begin{ctypedesc}[Py_tracefunc]{int (*Py_tracefunc)(PyObject *obj, - PyFrameObject *frame, int what, - PyObject *arg)} - The type of the trace function registered using - \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}. - The first parameter is the object passed to the registration - function as \var{obj}, \var{frame} is the frame object to which the - event pertains, \var{what} is one of the constants - \constant{PyTrace_CALL}, \constant{PyTrace_EXCEPT}, - \constant{PyTrace_LINE} or \constant{PyTrace_RETURN}, and \var{arg} - depends on the value of \var{what}: - - \begin{tableii}{l|l}{constant}{Value of \var{what}}{Meaning of \var{arg}} - \lineii{PyTrace_CALL}{Always \NULL.} - \lineii{PyTrace_EXCEPT}{Exception information as returned by - \function{sys.exc_info()}.} - \lineii{PyTrace_LINE}{Always \NULL.} - \lineii{PyTrace_RETURN}{Value being returned to the caller.} - \end{tableii} -\end{ctypedesc} - -\begin{cvardesc}{int}{PyTrace_CALL} - The value of the \var{what} parameter to a \ctype{Py_tracefunc} - function when a new call to a function or method is being reported, - or a new entry into a generator. Note that the creation of the - iterator for a generator function is not reported as there is no - control transfer to the Python bytecode in the corresponding frame. -\end{cvardesc} - -\begin{cvardesc}{int}{PyTrace_EXCEPT} - The value of the \var{what} parameter to a \ctype{Py_tracefunc} - function when an exception has been raised by Python code as the - result of an operation. The operation may have explictly intended - to raise the operation (as with a \keyword{raise} statement), or may - have triggered an exception in the runtime as a result of the - specific operation. -\end{cvardesc} - -\begin{cvardesc}{int}{PyTrace_LINE} - The value passed as the \var{what} parameter to a trace function - (but not a profiling function) when a line-number event is being - reported. -\end{cvardesc} - -\begin{cvardesc}{int}{PyTrace_RETURN} - The value for the \var{what} parameter to \ctype{Py_tracefunc} - functions when a call is returning without propogating an exception. -\end{cvardesc} - -\begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj} - Set the profiler function to \var{func}. The \var{obj} parameter is - passed to the function as its first parameter, and may be any Python - object, or \NULL. If the profile function needs to maintain state, - using a different value for \var{obj} for each thread provides a - convenient and thread-safe place to store it. The profile function - is called for all monitored events except the line-number events. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj} - Set the the tracing function to \var{func}. This is similar to - \cfunction{PyEval_SetProfile()}, except the tracing function does - receive line-number events. -\end{cfuncdesc} - - -\section{Advanced Debugger Support \label{advanced-debugging}} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -These functions are only intended to be used by advanced debugging -tools. - -\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{} -Return the interpreter state object at the head of the list of all -such objects. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Next}{PyInterpreterState *interp} -Return the next interpreter state object after \var{interp} from the -list of all such objects. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState *}{PyInterpreterState_ThreadHead}{PyInterpreterState *interp} -Return the a pointer to the first \ctype{PyThreadState} object in the -list of threads associated with the interpreter \var{interp}. -\versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Next}{PyThreadState *tstate} -Return the next thread state object after \var{tstate} from the list -of all such objects belonging to the same \ctype{PyInterpreterState} -object. -\versionadded{2.2} -\end{cfuncdesc} - - -\chapter{Memory Management \label{memory}} -\sectionauthor{Vladimir Marangozov}{Vladimir.Marangozov@inrialpes.fr} - - -\section{Overview \label{memoryOverview}} - -Memory management in Python involves a private heap containing all -Python objects and data structures. The management of this private -heap is ensured internally by the \emph{Python memory manager}. The -Python memory manager has different components which deal with various -dynamic storage management aspects, like sharing, segmentation, -preallocation or caching. - -At the lowest level, a raw memory allocator ensures that there is -enough room in the private heap for storing all Python-related data -by interacting with the memory manager of the operating system. On top -of the raw memory allocator, several object-specific allocators -operate on the same heap and implement distinct memory management -policies adapted to the peculiarities of every object type. For -example, integer objects are managed differently within the heap than -strings, tuples or dictionaries because integers imply different -storage requirements and speed/space tradeoffs. The Python memory -manager thus delegates some of the work to the object-specific -allocators, but ensures that the latter operate within the bounds of -the private heap. - -It is important to understand that the management of the Python heap -is performed by the interpreter itself and that the user has no -control on it, even if she regularly manipulates object pointers to -memory blocks inside that heap. The allocation of heap space for -Python objects and other internal buffers is performed on demand by -the Python memory manager through the Python/C API functions listed in -this document. - -To avoid memory corruption, extension writers should never try to -operate on Python objects with the functions exported by the C -library: \cfunction{malloc()}\ttindex{malloc()}, -\cfunction{calloc()}\ttindex{calloc()}, -\cfunction{realloc()}\ttindex{realloc()} and -\cfunction{free()}\ttindex{free()}. This will result in -mixed calls between the C allocator and the Python memory manager -with fatal consequences, because they implement different algorithms -and operate on different heaps. However, one may safely allocate and -release memory blocks with the C library allocator for individual -purposes, as shown in the following example: - -\begin{verbatim} - PyObject *res; - char *buf = (char *) malloc(BUFSIZ); /* for I/O */ - - if (buf == NULL) - return PyErr_NoMemory(); - ...Do some I/O operation involving buf... - res = PyString_FromString(buf); - free(buf); /* malloc'ed */ - return res; -\end{verbatim} - -In this example, the memory request for the I/O buffer is handled by -the C library allocator. The Python memory manager is involved only -in the allocation of the string object returned as a result. - -In most situations, however, it is recommended to allocate memory from -the Python heap specifically because the latter is under control of -the Python memory manager. For example, this is required when the -interpreter is extended with new object types written in C. Another -reason for using the Python heap is the desire to \emph{inform} the -Python memory manager about the memory needs of the extension module. -Even when the requested memory is used exclusively for internal, -highly-specific purposes, delegating all memory requests to the Python -memory manager causes the interpreter to have a more accurate image of -its memory footprint as a whole. Consequently, under certain -circumstances, the Python memory manager may or may not trigger -appropriate actions, like garbage collection, memory compaction or -other preventive procedures. Note that by using the C library -allocator as shown in the previous example, the allocated memory for -the I/O buffer escapes completely the Python memory manager. - - -\section{Memory Interface \label{memoryInterface}} - -The following function sets, modeled after the ANSI C standard, are -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 -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()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyMem_Free}{void *p} -Frees the memory block pointed to by \var{p}, which must have been -returned by a previous call to \cfunction{PyMem_Malloc()} or -\cfunction{PyMem_Realloc()}. Otherwise, or if -\cfunction{PyMem_Free(p)} has been called before, undefined behaviour -occurs. If \var{p} is \NULL{}, no operation is performed. -\end{cfuncdesc} - -The following type-oriented macros are provided for convenience. Note -that \var{TYPE} refers to any C type. - -\begin{cfuncdesc}{\var{TYPE}*}{PyMem_New}{TYPE, size_t n} -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} -Same as \cfunction{PyMem_Realloc()}, but the memory block is resized -to \code{(\var{n} * sizeof(\var{TYPE}))} bytes. Returns a pointer -cast to \ctype{\var{TYPE}*}. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyMem_Del}{void *p} -Same as \cfunction{PyMem_Free()}. -\end{cfuncdesc} - -In addition, the following macro sets are provided for calling the -Python memory allocator directly, without involving the C API functions -listed above. However, note that their use does not preserve binary -compatibility accross Python versions and is therefore deprecated in -extension modules. - -\cfunction{PyMem_MALLOC()}, \cfunction{PyMem_REALLOC()}, \cfunction{PyMem_FREE()}. - -\cfunction{PyMem_NEW()}, \cfunction{PyMem_RESIZE()}, \cfunction{PyMem_DEL()}. - - -\section{Examples \label{memoryExamples}} - -Here is the example from section \ref{memoryOverview}, rewritten so -that the I/O buffer is allocated from the Python heap by using the -first function set: - -\begin{verbatim} - PyObject *res; - char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */ - - if (buf == NULL) - return PyErr_NoMemory(); - /* ...Do some I/O operation involving buf... */ - res = PyString_FromString(buf); - PyMem_Free(buf); /* allocated with PyMem_Malloc */ - return res; -\end{verbatim} - -The same code using the type-oriented function set: - -\begin{verbatim} - PyObject *res; - char *buf = PyMem_New(char, BUFSIZ); /* for I/O */ - - if (buf == NULL) - return PyErr_NoMemory(); - /* ...Do some I/O operation involving buf... */ - res = PyString_FromString(buf); - PyMem_Del(buf); /* allocated with PyMem_New */ - return res; -\end{verbatim} - -Note that in the two examples above, the buffer is always -manipulated via functions belonging to the same set. Indeed, it -is required to use the same memory API family for a given -memory block, so that the risk of mixing different allocators is -reduced to a minimum. The following code sequence contains two errors, -one of which is labeled as \emph{fatal} because it mixes two different -allocators operating on different heaps. - -\begin{verbatim} -char *buf1 = PyMem_New(char, BUFSIZ); -char *buf2 = (char *) malloc(BUFSIZ); -char *buf3 = (char *) PyMem_Malloc(BUFSIZ); -... -PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */ -free(buf2); /* Right -- allocated via malloc() */ -free(buf1); /* Fatal -- should be PyMem_Del() */ -\end{verbatim} - -In addition to the functions aimed at handling raw memory blocks from -the Python heap, objects in Python are allocated and released with -\cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and -\cfunction{PyObject_Del()}, or with their corresponding macros -\cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()} and -\cfunction{PyObject_DEL()}. - -These will be explained in the next chapter on defining and -implementing new object types in C. - - -\chapter{Defining New Object Types \label{newTypes}} - - -\section{Allocating Objects on the Heap - \label{allocating-objects}} - -\begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, int size} -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op} -\end{cfuncdesc} - -\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} - -\begin{cfuncdesc}{PyObject*}{Py_InitModule}{char *name, - PyMethodDef *methods} - Create a new module object based on a name and table of functions, - returning the new module object. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{Py_InitModule3}{char *name, - PyMethodDef *methods, - char *doc} - Create a new module object based on a name and table of functions, - returning the new module object. If \var{doc} is non-\NULL, it will - be used to define the docstring for the module. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{Py_InitModule4}{char *name, - PyMethodDef *methods, - char *doc, PyObject *self, - int apiver} - Create a new module object based on a name and table of functions, - returning the new module object. If \var{doc} is non-\NULL, it will - be used to define the docstring for the module. If \var{self} is - non-\NULL, it will passed to the functions of the module as their - (otherwise \NULL) first parameter. (This was added as an - experimental feature, and there are no known uses in the current - version of Python.) For \var{apiver}, the only value which should - be passed is defined by the constant \constant{PYTHON_API_VERSION}. - - \strong{Note:} Most uses of this function should probably be using - the \cfunction{Py_InitModule3()} instead; only use this if you are - sure you need it. -\end{cfuncdesc} - -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} - - -\section{Common Object Structures \label{common-structs}} - -PyObject, PyVarObject - -PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD - -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. -\end{ctypedesc} - -\begin{ctypedesc}{PyMethodDef} -Structure used to describe a method of an extension type. This -structure has four fields: - -\begin{tableiii}{l|l|l}{member}{Field}{C Type}{Meaning} - \lineiii{ml_name}{char *}{name of the method} - \lineiii{ml_meth}{PyCFunction}{pointer to the C implementation} - \lineiii{ml_flags}{int}{flag bits indicating how the call should be - constructed} - \lineiii{ml_doc}{char *}{points to the contents of the docstring} -\end{tableiii} -\end{ctypedesc} - -The \var{ml_meth} is a C function pointer. The functions may be of -different types, but they always return \ctype{PyObject*}. If the -function is not of the \ctype{PyCFunction}, the compiler will require -a cast in the method table. Even though \ctype{PyCFunction} defines -the first parameter as \ctype{PyObject*}, it is common that the method -implementation uses a the specific C type of the \var{self} object. - -The flags can have the following values. Only METH_VARARGS and -METH_KEYWORDS can be combined; the others can't. - -\begin{datadesc}{METH_VARARGS} - -This is the typical calling convention, where the methods have the -type \ctype{PyMethodDef}. The function expects two \ctype{PyObject*}. -The first one is the \var{self} object for methods; for module -functions, it has the value given to \cfunction{PyInitModule4} (or -\NULL{} if \cfunction{PyInitModule} was used). The second parameter -(often called \var{args}) is a tuple object representing all -arguments. This parameter is typically processed using -\cfunction{PyArg_ParseTuple}. - -\end{datadesc} - -\begin{datadesc}{METH_KEYWORDS} - -Methods with these flags must be of type -\ctype{PyCFunctionWithKeywords}. The function expects three -parameters: \var{self}, \var{args}, and a dictionary of all the keyword -arguments. The flag is typically combined with METH_VARARGS, and the -parameters are typically processed using -\cfunction{PyArg_ParseTupleAndKeywords}. - -\end{datadesc} - -\begin{datadesc}{METH_NOARGS} - -Methods without parameters don't need to check whether arguments are -given if they are listed with the \code{METH_NOARGS} flag. They need -to be of type \ctype{PyNoArgsFunction}, i.e. they expect a single -\var{self} parameter. - -\end{datadesc} - -\begin{datadesc}{METH_O} - -Methods with a single object argument can be listed with the -\code{METH_O} flag, instead of invoking \cfunction{PyArg_ParseTuple} -with a \code{``O''} argument. They have the type \ctype{PyCFunction}, -with the \var{self} parameter, and a \ctype{PyObject*} parameter -representing the single argument. - -\end{datadesc} - -\begin{datadesc}{METH_OLDARGS} - -This calling convention is deprecated. The method must be of type -\ctype{PyCFunction}. The second argument is \NULL{} if no arguments -are given, a single object if exactly one argument is given, and a -tuple of objects if more than one argument is given. - -\end{datadesc} - -\begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef[] table, - PyObject *ob, char *name} -Return a bound method object for an extension type implemented in C. -This function also handles the special attribute \member{__methods__}, -returning a list of all the method names defined in \var{table}. -\end{cfuncdesc} - - -\section{Mapping Object Structures \label{mapping-structs}} - -\begin{ctypedesc}{PyMappingMethods} -Structure used to hold pointers to the functions used to implement the -mapping protocol for an extension type. -\end{ctypedesc} - - -\section{Number Object Structures \label{number-structs}} - -\begin{ctypedesc}{PyNumberMethods} -Structure used to hold pointers to the functions an extension type -uses to implement the number protocol. -\end{ctypedesc} - - -\section{Sequence Object Structures \label{sequence-structs}} - -\begin{ctypedesc}{PySequenceMethods} -Structure used to hold pointers to the functions which an object uses -to implement the sequence protocol. -\end{ctypedesc} - - -\section{Buffer Object Structures \label{buffer-structs}} -\sectionauthor{Greg J. Stein}{greg@lyra.org} - -The buffer interface exports a model where an object can expose its -internal data as a set of chunks of data, where each chunk is -specified as a pointer/length pair. These chunks are called -\dfn{segments} and are presumed to be non-contiguous in memory. - -If an object does not export the buffer interface, then its -\member{tp_as_buffer} member in the \ctype{PyTypeObject} structure -should be \NULL{}. Otherwise, the \member{tp_as_buffer} will point to -a \ctype{PyBufferProcs} structure. - -\strong{Note:} It is very important that your -\ctype{PyTypeObject} structure uses \constant{Py_TPFLAGS_DEFAULT} for -the value of the \member{tp_flags} member rather than \code{0}. This -tells the Python runtime that your \ctype{PyBufferProcs} structure -contains the \member{bf_getcharbuffer} slot. Older versions of Python -did not have this member, so a new Python interpreter using an old -extension needs to be able to test for its presence before using it. - -\begin{ctypedesc}{PyBufferProcs} -Structure used to hold the function pointers which define an -implementation of the buffer protocol. - -The first slot is \member{bf_getreadbuffer}, of type -\ctype{getreadbufferproc}. If this slot is \NULL{}, then the object -does not support reading from the internal data. This is -non-sensical, so implementors should fill this in, but callers should -test that the slot contains a non-\NULL{} value. - -The next slot is \member{bf_getwritebuffer} having type -\ctype{getwritebufferproc}. This slot may be \NULL{} if the object -does not allow writing into its returned buffers. - -The third slot is \member{bf_getsegcount}, with type -\ctype{getsegcountproc}. This slot must not be \NULL{} and is used to -inform the caller how many segments the object contains. Simple -objects such as \ctype{PyString_Type} and -\ctype{PyBuffer_Type} objects contain a single segment. - -The last slot is \member{bf_getcharbuffer}, of type -\ctype{getcharbufferproc}. This slot will only be present if the -\constant{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the -\member{tp_flags} field of the object's \ctype{PyTypeObject}. Before using -this slot, the caller should test whether it is present by using the -\cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()} function. -If present, it may be \NULL, indicating that the object's contents -cannot be used as \emph{8-bit characters}. -The slot function may also raise an error if the object's contents -cannot be interpreted as 8-bit characters. For example, if the object -is an array which is configured to hold floating point values, an -exception may be raised if a caller attempts to use -\member{bf_getcharbuffer} to fetch a sequence of 8-bit characters. -This notion of exporting the internal buffers as ``text'' is used to -distinguish between objects that are binary in nature, and those which -have character-based content. - -\strong{Note:} The current policy seems to state that these characters -may be multi-byte characters. This implies that a buffer size of -\var{N} does not mean there are \var{N} characters present. -\end{ctypedesc} - -\begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER} -Flag bit set in the type structure to indicate that the -\member{bf_getcharbuffer} slot is known. This being set does not -indicate that the object supports the buffer interface or that the -\member{bf_getcharbuffer} slot is non-\NULL. -\end{datadesc} - -\begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc) - (PyObject *self, int segment, void **ptrptr)} -Return a pointer to a readable segment of the buffer. This function -is allowed to raise an exception, in which case it must return -\code{-1}. The \var{segment} which is passed must be zero or -positive, and strictly less than the number of segments returned by -the \member{bf_getsegcount} slot function. On success, it returns the -length of the buffer memory, and sets \code{*\var{ptrptr}} to a -pointer to that memory. -\end{ctypedesc} - -\begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc) - (PyObject *self, int segment, void **ptrptr)} -Return a pointer to a writable memory buffer in \code{*\var{ptrptr}}, -and the length of that segment as the function return value. -The memory buffer must correspond to buffer segment \var{segment}. -Must return \code{-1} and set an exception on error. -\exception{TypeError} should be raised if the object only supports -read-only buffers, and \exception{SystemError} should be raised when -\var{segment} specifies a segment that doesn't exist. -% Why doesn't it raise ValueError for this one? -% GJS: because you shouldn't be calling it with an invalid -% segment. That indicates a blatant programming error in the C -% code. -\end{ctypedesc} - -\begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc) - (PyObject *self, int *lenp)} -Return the number of memory segments which comprise the buffer. If -\var{lenp} is not \NULL, the implementation must report the sum of the -sizes (in bytes) of all segments in \code{*\var{lenp}}. -The function cannot fail. -\end{ctypedesc} - -\begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc) - (PyObject *self, int segment, const char **ptrptr)} -\end{ctypedesc} - - -\section{Supporting the Iterator Protocol - \label{supporting-iteration}} - - -\section{Supporting Cyclic Garbarge Collection - \label{supporting-cycle-detection}} - -Python's support for detecting and collecting garbage which involves -circular references requires support from object types which are -``containers'' for other objects which may also be containers. Types -which do not store references to other objects, or which only store -references to atomic types (such as numbers or strings), do not need -to provide any explicit support for garbage collection. - -To create a container type, the \member{tp_flags} field of the type -object must include the \constant{Py_TPFLAGS_HAVE_GC} and provide an -implementation of the \member{tp_traverse} handler. If instances of the -type are mutable, a \member{tp_clear} implementation must also be -provided. - -\begin{datadesc}{Py_TPFLAGS_HAVE_GC} - Objects with a type with this flag set must conform with the rules - documented here. For convenience these objects will be referred to - as container objects. -\end{datadesc} - -Constructors for container types must conform to two rules: - -\begin{enumerate} -\item The memory for the object must be allocated using - \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}. - -\item Once all the fields which may contain references to other - containers are initialized, it must call - \cfunction{PyObject_GC_Track()}. -\end{enumerate} - -\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_New}{TYPE, PyTypeObject *type} - Analogous to \cfunction{PyObject_New()} but for container objects with - the \constant{Py_TPFLAGS_HAVE_GC} flag set. -\end{cfuncdesc} - -\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_NewVar}{TYPE, PyTypeObject *type, - int size} - Analogous to \cfunction{PyObject_NewVar()} but for container objects - with the \constant{Py_TPFLAGS_HAVE_GC} flag set. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyVarObject *}{PyObject_GC_Resize}{PyVarObject *op, int} - Resize an object allocated by \cfunction{PyObject_NewVar()}. Returns - the resized object or \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyObject_GC_Track}{PyObject *op} - Adds the object \var{op} to the set of container objects tracked by - the collector. The collector can run at unexpected times so objects - must be valid while being tracked. This should be called once all - the fields followed by the \member{tp_traverse} handler become valid, - usually near the end of the constructor. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{_PyObject_GC_TRACK}{PyObject *op} - A macro version of \cfunction{PyObject_GC_Track()}. It should not be - used for extension modules. -\end{cfuncdesc} - -Similarly, the deallocator for the object must conform to a similar -pair of rules: - -\begin{enumerate} -\item Before fields which refer to other containers are invalidated, - \cfunction{PyObject_GC_UnTrack()} must be called. - -\item The object's memory must be deallocated using - \cfunction{PyObject_GC_Del()}. -\end{enumerate} - -\begin{cfuncdesc}{void}{PyObject_GC_Del}{PyObject *op} - Releases memory allocated to an object using - \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_NewVar()}. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{PyObject_GC_UnTrack}{PyObject *op} - Remove the object \var{op} from the set of container objects tracked - by the collector. Note that \cfunction{PyObject_GC_Track()} can be - called again on this object to add it back to the set of tracked - objects. The deallocator (\member{tp_dealloc} handler) should call - this for the object before any of the fields used by the - \member{tp_traverse} handler become invalid. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{_PyObject_GC_UNTRACK}{PyObject *op} - A macro version of \cfunction{PyObject_GC_UnTrack()}. It should not be - used for extension modules. -\end{cfuncdesc} - -The \member{tp_traverse} handler accepts a function parameter of this -type: - -\begin{ctypedesc}[visitproc]{int (*visitproc)(PyObject *object, void *arg)} - Type of the visitor function passed to the \member{tp_traverse} - handler. The function should be called with an object to traverse - as \var{object} and the third parameter to the \member{tp_traverse} - handler as \var{arg}. -\end{ctypedesc} - -The \member{tp_traverse} handler must have the following type: - -\begin{ctypedesc}[traverseproc]{int (*traverseproc)(PyObject *self, - visitproc visit, void *arg)} - Traversal function for a container object. Implementations must - call the \var{visit} function for each object directly contained by - \var{self}, with the parameters to \var{visit} being the contained - object and the \var{arg} value passed to the handler. If - \var{visit} returns a non-zero value then an error has occurred and - that value should be returned immediately. -\end{ctypedesc} - -The \member{tp_clear} handler must be of the \ctype{inquiry} type, or -\NULL{} if the object is immutable. - -\begin{ctypedesc}[inquiry]{int (*inquiry)(PyObject *self)} - 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 (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. -\end{ctypedesc} - - -\subsection{Example Cycle Collector Support - \label{example-cycle-support}} - -This example shows only enough of the implementation of an extension -type to show how the garbage collector support needs to be added. It -shows the definition of the object structure, the -\member{tp_traverse}, \member{tp_clear} and \member{tp_dealloc} -implementations, the type structure, and a constructor --- the module -initialization needed to export the constructor to Python is not shown -as there are no special considerations there for the collector. To -make this interesting, assume that the module exposes ways for the -\member{container} field of the object to be modified. Note that -since no checks are made on the type of the object used to initialize -\member{container}, we have to assume that it may be a container. - -\begin{verbatim} -#include "Python.h" - -typedef struct { - PyObject_HEAD - PyObject *container; -} MyObject; - -static int -my_traverse(MyObject *self, visitproc visit, void *arg) -{ - if (self->container != NULL) - return visit(self->container, arg); - else - return 0; -} - -static int -my_clear(MyObject *self) -{ - Py_XDECREF(self->container); - self->container = NULL; - - return 0; -} - -static void -my_dealloc(MyObject *self) -{ - PyObject_GC_UnTrack((PyObject *) self); - Py_XDECREF(self->container); - PyObject_GC_Del(self); -} -\end{verbatim} - -\begin{verbatim} -statichere PyTypeObject -MyObject_Type = { - PyObject_HEAD_INIT(NULL) - 0, - "MyObject", - sizeof(MyObject), - 0, - (destructor)my_dealloc, /* tp_dealloc */ - 0, /* tp_print */ - 0, /* tp_getattr */ - 0, /* tp_setattr */ - 0, /* tp_compare */ - 0, /* tp_repr */ - 0, /* tp_as_number */ - 0, /* tp_as_sequence */ - 0, /* tp_as_mapping */ - 0, /* tp_hash */ - 0, /* tp_call */ - 0, /* tp_str */ - 0, /* tp_getattro */ - 0, /* tp_setattro */ - 0, /* tp_as_buffer */ - Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, - 0, /* tp_doc */ - (traverseproc)my_traverse, /* tp_traverse */ - (inquiry)my_clear, /* tp_clear */ - 0, /* tp_richcompare */ - 0, /* tp_weaklistoffset */ -}; - -/* This constructor should be made accessible from Python. */ -static PyObject * -new_object(PyObject *unused, PyObject *args) -{ - PyObject *container = NULL; - MyObject *result = NULL; - - if (PyArg_ParseTuple(args, "|O:new_object", &container)) { - result = PyObject_GC_New(MyObject, &MyObject_Type); - if (result != NULL) { - result->container = container; - PyObject_GC_Track(result); - } - } - return (PyObject *) result; -} -\end{verbatim} +\input{intro} +\input{veryhigh} +\input{refcounting} +\input{exceptions} +\input{utilities} +\input{abstract} +\input{concrete} +\input{init} +\input{memory} +\input{newtypes} % \chapter{Debugging \label{debugging}} diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex new file mode 100644 index 0000000..64653a9 --- /dev/null +++ b/Doc/api/concrete.tex @@ -0,0 +1,2342 @@ +\chapter{Concrete Objects Layer \label{concrete}} + + +The functions in this chapter are specific to certain Python object +types. Passing them an object of the wrong type is not a good idea; +if you receive an object from a Python program and you are not sure +that it has the right type, you must perform a type check first; +for example, to check that an object is a dictionary, use +\cfunction{PyDict_Check()}. The chapter is structured like the +``family tree'' of Python object types. + +\warning{While the functions described in this chapter carefully check +the type of the objects which are passed in, many of them do not check +for \NULL{} being passed instead of a valid object. Allowing \NULL{} +to be passed in can cause memory access violations and immediate +termination of the interpreter.} + + +\section{Fundamental Objects \label{fundamental}} + +This section describes Python type objects and the singleton object +\code{None}. + + +\subsection{Type Objects \label{typeObjects}} + +\obindex{type} +\begin{ctypedesc}{PyTypeObject} + The C structure of the objects used to describe built-in types. +\end{ctypedesc} + +\begin{cvardesc}{PyObject*}{PyType_Type} + This is the type object for type objects; it is the same object as + \code{types.TypeType} in the Python layer. + \withsubitem{(in module types)}{\ttindex{TypeType}} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyType_Check}{PyObject *o} + Returns true is the object \var{o} is a type object. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature} + Returns true if the type object \var{o} sets the feature + \var{feature}. Type features are denoted by single bit flags. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyType_IsSubtype}{PyTypeObject *a, PyTypeObject *b} + Returns true if \var{a} is a subtype of \var{b}. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type, + int nitems} + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyType_GenericNew}{PyTypeObject *type, + PyObject *args, PyObject *kwds} + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyType_Ready}{PyTypeObject *type} + \versionadded{2.2} +\end{cfuncdesc} + + +\subsection{The None Object \label{noneObject}} + +\obindex{None@\texttt{None}} +Note that the \ctype{PyTypeObject} for \code{None} is not directly +exposed in the Python/C API. Since \code{None} is a singleton, +testing for object identity (using \samp{==} in C) is sufficient. +There is no \cfunction{PyNone_Check()} function for the same reason. + +\begin{cvardesc}{PyObject*}{Py_None} + The Python \code{None} object, denoting lack of value. This object + has no methods. +\end{cvardesc} + + +\section{Numeric Objects \label{numericObjects}} + +\obindex{numeric} + + +\subsection{Plain Integer Objects \label{intObjects}} + +\obindex{integer} +\begin{ctypedesc}{PyIntObject} + This subtype of \ctype{PyObject} represents a Python integer + object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyInt_Type} + This instance of \ctype{PyTypeObject} represents the Python plain + integer type. This is the same object as \code{types.IntType}. + \withsubitem{(in modules types)}{\ttindex{IntType}} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o} + Returns true if \var{o} is of type \cdata{PyInt_Type} or a subtype + of \cdata{PyInt_Type}. + \versionchanged[Allowed subtypes to be accepted]{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject* o} + Returns true if \var{o} is of type \cdata{PyInt_Type}, but not a + subtype of \cdata{PyInt_Type}. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival} + Creates a new integer object with a value of \var{ival}. + + The current implementation keeps an array of integer objects for all + integers between \code{-1} and \code{100}, when you create an int in + that range you actually just get back a reference to the existing + object. So it should be possible to change the value of \code{1}. I + suspect the behaviour of Python in this case is undefined. :-) +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io} + Will first attempt to cast the object to a \ctype{PyIntObject}, if + it is not already one, and then return its value. +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io} + Returns the value of the object \var{io}. No error checking is + performed. +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyInt_GetMax}{} + Returns the system's idea of the largest integer it can handle + (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system + header files). +\end{cfuncdesc} + + +\subsection{Long Integer Objects \label{longObjects}} + +\obindex{long integer} +\begin{ctypedesc}{PyLongObject} + This subtype of \ctype{PyObject} represents a Python long integer + object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyLong_Type} + This instance of \ctype{PyTypeObject} represents the Python long + integer type. This is the same object as \code{types.LongType}. + \withsubitem{(in modules types)}{\ttindex{LongType}} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p} + Returns true if its argument is a \ctype{PyLongObject} or a subtype + of \ctype{PyLongObject}. + \versionchanged[Allowed subtypes to be accepted]{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p} + Returns true if its argument is a \ctype{PyLongObject}, but not a + subtype of \ctype{PyLongObject}. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v} + Returns a new \ctype{PyLongObject} object from \var{v}, or \NULL{} + on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v} + Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned + long}, or \NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{long long v} + Returns a new \ctype{PyLongObject} object from a C \ctype{long long}, + or \NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned long long v} + Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned + long long}, or \NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v} + Returns a new \ctype{PyLongObject} object from the integer part of + \var{v}, or \NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend, + int base} + Return a new \ctype{PyLongObject} based on the string value in + \var{str}, which is interpreted according to the radix in + \var{base}. If \var{pend} is non-\NULL, \code{*\var{pend}} will + point to the first character in \var{str} which follows the + representation of the number. If \var{base} is \code{0}, the radix + will be determined base on the leading characters of \var{str}: if + \var{str} starts with \code{'0x'} or \code{'0X'}, radix 16 will be + used; if \var{str} starts with \code{'0'}, radix 8 will be used; + otherwise radix 10 will be used. If \var{base} is not \code{0}, it + must be between \code{2} and \code{36}, inclusive. Leading spaces + are ignored. If there are no digits, \exception{ValueError} will be + raised. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyLong_FromUnicode}{Py_UNICODE *u, + int length, int base} + Convert a sequence of Unicode digits to a Python long integer + value. The first parameter, \var{u}, points to the first character + of the Unicode string, \var{length} gives the number of characters, + and \var{base} is the radix for the conversion. The radix must be + in the range [2, 36]; if it is out of range, \exception{ValueError} + will be raised. + \versionadded{1.6} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyLong_FromVoidPtr}{void *p} + Create a Python integer or long integer from the pointer \var{p}. + The pointer value can be retrieved from the resulting value using + \cfunction{PyLong_AsVoidPtr()}. + \versionadded{1.5.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong} + 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)}{\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)}{\ttindex{OverflowError}} +\end{cfuncdesc} + +\begin{cfuncdesc}{long long}{PyLong_AsLongLong}{PyObject *pylong} + Return a C \ctype{long long} from a Python long integer. If + \var{pylong} cannot be represented as a \ctype{long long}, an + \exception{OverflowError} will be raised. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{unsigned long long}{PyLong_AsUnsignedLongLong}{PyObject + *pylong} + Return a C \ctype{unsigned long long} from a Python long integer. + If \var{pylong} cannot be represented as an \ctype{unsigned long + long}, an \exception{OverflowError} will be raised if the value is + positive, or a \exception{TypeError} will be raised if the value is + negative. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong} + Returns a C \ctype{double} representation of the contents of + \var{pylong}. If \var{pylong} cannot be approximately represented + as a \ctype{double}, an \exception{OverflowError} exception is + raised and \code{-1.0} will be returned. +\end{cfuncdesc} + +\begin{cfuncdesc}{void*}{PyLong_AsVoidPtr}{PyObject *pylong} + Convert a Python integer or long integer \var{pylong} to a C + \ctype{void} pointer. If \var{pylong} cannot be converted, an + \exception{OverflowError} will be raised. This is only assured to + produce a usable \ctype{void} pointer for values created with + \cfunction{PyLong_FromVoidPtr()}. + \versionadded{1.5.2} +\end{cfuncdesc} + + +\subsection{Floating Point Objects \label{floatObjects}} + +\obindex{floating point} +\begin{ctypedesc}{PyFloatObject} + This subtype of \ctype{PyObject} represents a Python floating point + object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyFloat_Type} + This instance of \ctype{PyTypeObject} represents the Python floating + point type. This is the same object as \code{types.FloatType}. + \withsubitem{(in modules types)}{\ttindex{FloatType}} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p} + Returns true if its argument is a \ctype{PyFloatObject} or a subtype + of \ctype{PyFloatObject}. + \versionchanged[Allowed subtypes to be accepted]{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p} + Returns true if its argument is a \ctype{PyFloatObject}, but not a + subtype of \ctype{PyFloatObject}. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v} + Creates a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on + failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat} + Returns a C \ctype{double} representation of the contents of + \var{pyfloat}. +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat} + Returns a C \ctype{double} representation of the contents of + \var{pyfloat}, but without error checking. +\end{cfuncdesc} + + +\subsection{Complex Number Objects \label{complexObjects}} + +\obindex{complex number} +Python's complex number objects are implemented as two distinct types +when viewed from the C API: one is the Python object exposed to +Python programs, and the other is a C structure which represents the +actual complex number value. The API provides functions for working +with both. + +\subsubsection{Complex Numbers as C Structures} + +Note that the functions which accept these structures as parameters +and return them as results do so \emph{by value} rather than +dereferencing them through pointers. This is consistent throughout +the API. + +\begin{ctypedesc}{Py_complex} + The C structure which corresponds to the value portion of a Python + complex number object. Most of the functions for dealing with + complex number objects use structures of this type as input or + output values, as appropriate. It is defined as: + +\begin{verbatim} +typedef struct { + double real; + double imag; +} Py_complex; +\end{verbatim} +\end{ctypedesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right} + Return the sum of two complex numbers, using the C + \ctype{Py_complex} representation. +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right} + Return the difference between two complex numbers, using the C + \ctype{Py_complex} representation. +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex} + Return the negation of the complex number \var{complex}, using the C + \ctype{Py_complex} representation. +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right} + Return the product of two complex numbers, using the C + \ctype{Py_complex} representation. +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend, + Py_complex divisor} + Return the quotient of two complex numbers, using the C + \ctype{Py_complex} representation. +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp} + Return the exponentiation of \var{num} by \var{exp}, using the C + \ctype{Py_complex} representation. +\end{cfuncdesc} + + +\subsubsection{Complex Numbers as Python Objects} + +\begin{ctypedesc}{PyComplexObject} + This subtype of \ctype{PyObject} represents a Python complex number + object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyComplex_Type} + This instance of \ctype{PyTypeObject} represents the Python complex + number type. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p} + Returns true if its argument is a \ctype{PyComplexObject} or a + subtype of \ctype{PyComplexObject}. + \versionchanged[Allowed subtypes to be accepted]{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p} + Returns true if its argument is a \ctype{PyComplexObject}, but not a + subtype of \ctype{PyComplexObject}. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v} + Create a new Python complex number object from a C + \ctype{Py_complex} value. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag} + Returns a new \ctype{PyComplexObject} object from \var{real} and + \var{imag}. +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op} + Returns the real part of \var{op} as a C \ctype{double}. +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op} + Returns the imaginary part of \var{op} as a C \ctype{double}. +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op} + Returns the \ctype{Py_complex} value of the complex number + \var{op}. +\end{cfuncdesc} + + + +\section{Sequence Objects \label{sequenceObjects}} + +\obindex{sequence} +Generic operations on sequence objects were discussed in the previous +chapter; this section deals with the specific kinds of sequence +objects that are intrinsic to the Python language. + + +\subsection{String Objects \label{stringObjects}} + +These functions raise \exception{TypeError} when expecting a string +parameter and are called with a non-string parameter. + +\obindex{string} +\begin{ctypedesc}{PyStringObject} + This subtype of \ctype{PyObject} represents a Python string object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyString_Type} + This instance of \ctype{PyTypeObject} represents the Python string + type; it is the same object as \code{types.TypeType} in the Python + layer. + \withsubitem{(in module types)}{\ttindex{StringType}}. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o} + Returns true if the object \var{o} is a string object or an instance + of a subtype of the string type. + \versionchanged[Allowed subtypes to be accepted]{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o} + Returns true if the object \var{o} is a string object, but not an + instance of a subtype of the string type. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v} + Returns a new string object with the value \var{v} on success, and + \NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v, + int len} + Returns a new string object with the value \var{v} and length + \var{len} on success, and \NULL{} on failure. If \var{v} is + \NULL, the contents of the string are uninitialized. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...} + Takes a C \cfunction{printf()}-style \var{format} string and a + variable number of arguments, calculates the size of the resulting + Python string and returns a string with the values formatted into + it. The variable arguments must be C types and must correspond + exactly to the format characters in the \var{format} string. The + following format characters are allowed: + + \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment} + \lineiii{\%\%}{\emph{n/a}}{The literal \% character.} + \lineiii{\%c}{int}{A single character, represented as an C int.} + \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.} + \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.} + \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.} + \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.} + \lineiii{\%s}{char*}{A null-terminated C character array.} + \lineiii{\%p}{void*}{The hex representation of a C pointer. + Mostly equivalent to \code{printf("\%p")} except that it is + guaranteed to start with the literal \code{0x} regardless of + what the platform's \code{printf} yields.} + \end{tableiii} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_FromFormatV}{const char *format, + va_list vargs} + Identical to \function{PyString_FromFormat()} except that it takes + exactly two arguments. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string} + Returns the length of the string in string object \var{string}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string} + Macro form of \cfunction{PyString_Size()} but without error + checking. +\end{cfuncdesc} + +\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string} + Returns a null-terminated representation of the contents of + \var{string}. The pointer refers to the internal buffer of + \var{string}, not a copy. The data must not be modified in any way, + unless the string was just created using + \code{PyString_FromStringAndSize(NULL, \var{size})}. + It must not be deallocated. +\end{cfuncdesc} + +\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string} + Macro form of \cfunction{PyString_AsString()} but without error + checking. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj, + char **buffer, + int *length} + Returns a null-terminated representation of the contents of the + object \var{obj} through the output variables \var{buffer} and + \var{length}. + + The function accepts both string and Unicode objects as input. For + Unicode objects it returns the default encoded version of the + object. If \var{length} is set to \NULL, the resulting buffer may + not contain null characters; if it does, the function returns -1 and + a \exception{TypeError} is raised. + + The buffer refers to an internal string buffer of \var{obj}, not a + copy. The data must not be modified in any way, unless the string + was just created using \code{PyString_FromStringAndSize(NULL, + \var{size})}. It must not be deallocated. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string, + PyObject *newpart} + Creates a new string object in \var{*string} containing the contents + of \var{newpart} appended to \var{string}; the caller will own the + new reference. The reference to the old value of \var{string} will + be stolen. If the new string cannot be created, the old reference + to \var{string} will still be discarded and the value of + \var{*string} will be set to \NULL; the appropriate exception will + be set. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string, + PyObject *newpart} + Creates a new string object in \var{*string} containing the contents + of \var{newpart} appended to \var{string}. This version decrements + the reference count of \var{newpart}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize} + A way to resize a string object even though it is ``immutable''. + Only use this to build up a brand new string object; don't use this + if the string may already be known in other parts of the code. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format, + PyObject *args} + Returns a new string object from \var{format} and \var{args}. + Analogous to \code{\var{format} \%\ \var{args}}. The \var{args} + argument must be a tuple. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string} + Intern the argument \var{*string} in place. The argument must be + the address of a pointer variable pointing to a Python string + object. If there is an existing interned string that is the same as + \var{*string}, it sets \var{*string} to it (decrementing the + reference count of the old string object and incrementing the + reference count of the interned string object), otherwise it leaves + \var{*string} alone and interns it (incrementing its reference + count). (Clarification: even though there is a lot of talk about + reference counts, think of this function as reference-count-neutral; + you own the object after the call if and only if you owned it before + the call.) +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v} + A combination of \cfunction{PyString_FromString()} and + \cfunction{PyString_InternInPlace()}, returning either a new string + object that has been interned, or a new (``owned'') reference to an + earlier interned string object with the same value. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s, + int size, + const char *encoding, + const char *errors} + Creates an object by decoding \var{size} bytes of the encoded + buffer \var{s} using the codec registered for + \var{encoding}. \var{encoding} and \var{errors} have the same + meaning as the parameters of the same name in the + \function{unicode()} built-in function. The codec to be used is + looked up using the Python codec registry. Returns \NULL{} if + an exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str, + const char *encoding, + const char *errors} + Decodes a string object by passing it to the codec registered for + \var{encoding} and returns the result as Python + object. \var{encoding} and \var{errors} have the same meaning as the + parameters of the same name in the string \method{encode()} method. + The codec to be used is looked up using the Python codec registry. + Returns \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s, + int size, + const char *encoding, + const char *errors} + Encodes the \ctype{char} buffer of the given size by passing it to + the codec registered for \var{encoding} and returns a Python object. + \var{encoding} and \var{errors} have the same meaning as the + parameters of the same name in the string \method{encode()} method. + The codec to be used is looked up using the Python codec + registry. Returns \NULL{} if an exception was raised by the + codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str, + const char *encoding, + const char *errors} + Encodes a string object using the codec registered for + \var{encoding} and returns the result as Python object. + \var{encoding} and \var{errors} have the same meaning as the + parameters of the same name in the string \method{encode()} method. + The codec to be used is looked up using the Python codec registry. + Returns \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + + +\subsection{Unicode Objects \label{unicodeObjects}} +\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com} + +%--- Unicode Type ------------------------------------------------------- + +These are the basic Unicode object types used for the Unicode +implementation in Python: + +\begin{ctypedesc}{Py_UNICODE} + This type represents a 16-bit unsigned storage type which is used by + Python internally as basis for holding Unicode ordinals. On + platforms where \ctype{wchar_t} is available and also has 16-bits, + \ctype{Py_UNICODE} is a typedef alias for \ctype{wchar_t} to enhance + native platform compatibility. On all other platforms, + \ctype{Py_UNICODE} is a typedef alias for \ctype{unsigned short}. +\end{ctypedesc} + +\begin{ctypedesc}{PyUnicodeObject} + This subtype of \ctype{PyObject} represents a Python Unicode object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyUnicode_Type} + This instance of \ctype{PyTypeObject} represents the Python Unicode + type. +\end{cvardesc} + +The following APIs are really C macros and can be used to do fast +checks and to access internal read-only data of Unicode objects: + +\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o} + Returns true if the object \var{o} is a Unicode object or an + instance of a Unicode subtype. + \versionchanged[Allowed subtypes to be accepted]{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o} + Returns true if the object \var{o} is a Unicode object, but not an + instance of a subtype. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o} + Returns the size of the object. \var{o} has to be a + \ctype{PyUnicodeObject} (not checked). +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyUnicode_GET_DATA_SIZE}{PyObject *o} + Returns the size of the object's internal buffer in bytes. \var{o} + has to be a \ctype{PyUnicodeObject} (not checked). +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o} + Returns a pointer to the internal \ctype{Py_UNICODE} buffer of the + object. \var{o} has to be a \ctype{PyUnicodeObject} (not checked). +\end{cfuncdesc} + +\begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o} + Returns a pointer to the internal buffer of the object. + \var{o} has to be a \ctype{PyUnicodeObject} (not checked). +\end{cfuncdesc} + +% --- Unicode character properties --------------------------------------- + +Unicode provides many different character properties. The most often +needed ones are available through these macros which are mapped to C +functions depending on the Python configuration. + +\begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch} + Returns 1/0 depending on whether \var{ch} is a whitespace + character. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch} + Returns 1/0 depending on whether \var{ch} is a lowercase character. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch} + Returns 1/0 depending on whether \var{ch} is an uppercase + character. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch} + Returns 1/0 depending on whether \var{ch} is a titlecase character. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch} + Returns 1/0 depending on whether \var{ch} is a linebreak character. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch} + Returns 1/0 depending on whether \var{ch} is a decimal character. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch} + Returns 1/0 depending on whether \var{ch} is a digit character. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch} + Returns 1/0 depending on whether \var{ch} is a numeric character. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch} + Returns 1/0 depending on whether \var{ch} is an alphabetic + character. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch} + Returns 1/0 depending on whether \var{ch} is an alphanumeric + character. +\end{cfuncdesc} + +These APIs can be used for fast direct character conversions: + +\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch} + Returns the character \var{ch} converted to lower case. +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch} + Returns the character \var{ch} converted to upper case. +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch} + Returns the character \var{ch} converted to title case. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch} + Returns the character \var{ch} converted to a decimal positive + integer. Returns \code{-1} if this is not possible. Does not raise + exceptions. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch} + Returns the character \var{ch} converted to a single digit integer. + Returns \code{-1} if this is not possible. Does not raise + exceptions. +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch} + Returns the character \var{ch} converted to a (positive) double. + Returns \code{-1.0} if this is not possible. Does not raise + exceptions. +\end{cfuncdesc} + +% --- Plain Py_UNICODE --------------------------------------------------- + +To create Unicode objects and access their basic sequence properties, +use these APIs: + +\begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u, + int size} + Create a Unicode Object from the Py_UNICODE buffer \var{u} of the + given size. \var{u} may be \NULL{} which causes the contents to be + undefined. It is the user's responsibility to fill in the needed + data. The buffer is copied into the new object. If the buffer is + not \NULL, the return value might be a shared object. Therefore, + modification of the resulting Unicode object is only allowed when + \var{u} is \NULL. +\end{cfuncdesc} + +\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode} + Return a read-only pointer to the Unicode object's internal + \ctype{Py_UNICODE} buffer, \NULL{} if \var{unicode} is not a Unicode + object. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode} + Return the length of the Unicode object. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj, + const char *encoding, + const char *errors} + Coerce an encoded object \var{obj} to an Unicode object and return a + reference with incremented refcount. + + Coercion is done in the following way: + +\begin{enumerate} +\item Unicode objects are passed back as-is with incremented + refcount. \note{These cannot be decoded; passing a non-\NULL{} + value for encoding will result in a \exception{TypeError}.} + +\item String and other char buffer compatible objects are decoded + according to the given encoding and using the error handling + defined by errors. Both can be \NULL{} to have the interface + use the default values (see the next section for details). + +\item All other objects cause an exception. +\end{enumerate} + + The API returns \NULL{} if there was an error. The caller is + responsible for decref'ing the returned objects. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj} + Shortcut for \code{PyUnicode_FromEncodedObject(obj, NULL, "strict")} + which is used throughout the interpreter whenever coercion to + Unicode is needed. +\end{cfuncdesc} + +% --- wchar_t support for platforms which support it --------------------- + +If the platform supports \ctype{wchar_t} and provides a header file +wchar.h, Python can interface directly to this type using the +following functions. Support is optimized if Python's own +\ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}. + +\begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w, + int size} + Create a Unicode object from the \ctype{whcar_t} buffer \var{w} of + the given size. Returns \NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode, + wchar_t *w, + int size} + Copies the Unicode object contents into the \ctype{whcar_t} buffer + \var{w}. At most \var{size} \ctype{whcar_t} characters are copied. + Returns the number of \ctype{whcar_t} characters copied or -1 in + case of an error. +\end{cfuncdesc} + + +\subsubsection{Built-in Codecs \label{builtinCodecs}} + +Python provides a set of builtin codecs which are written in C +for speed. All of these codecs are directly usable via the +following functions. + +Many of the following APIs take two arguments encoding and +errors. These parameters encoding and errors have the same semantics +as the ones of the builtin unicode() Unicode object constructor. + +Setting encoding to \NULL{} causes the default encoding to be used +which is \ASCII. The file system calls should use +\cdata{Py_FileSystemDefaultEncoding} as the encoding for file +names. This variable should be treated as read-only: On some systems, +it will be a pointer to a static string, on others, it will change at +run-time, e.g. when the application invokes setlocale. + +Error handling is set by errors which may also be set to \NULL{} +meaning to use the default handling defined for the codec. Default +error handling for all builtin codecs is ``strict'' +(\exception{ValueError} is raised). + +The codecs all use a similar interface. Only deviation from the +following generic ones are documented for simplicity. + +% --- Generic Codecs ----------------------------------------------------- + +These are the generic codec APIs: + +\begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s, + int size, + const char *encoding, + const char *errors} + Create a Unicode object by decoding \var{size} bytes of the encoded + string \var{s}. \var{encoding} and \var{errors} have the same + meaning as the parameters of the same name in the + \function{unicode()} builtin function. The codec to be used is + looked up using the Python codec registry. Returns \NULL{} if an + exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s, + int size, + const char *encoding, + const char *errors} + Encodes the \ctype{Py_UNICODE} buffer of the given size and returns + a Python string object. \var{encoding} and \var{errors} have the + same meaning as the parameters of the same name in the Unicode + \method{encode()} method. The codec to be used is looked up using + the Python codec registry. Returns \NULL{} if an exception was + raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode, + const char *encoding, + const char *errors} + Encodes a Unicode object and returns the result as Python string + object. \var{encoding} and \var{errors} have the same meaning as the + parameters of the same name in the Unicode \method{encode()} method. + The codec to be used is looked up using the Python codec registry. + Returns \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +% --- UTF-8 Codecs ------------------------------------------------------- + +These are the UTF-8 codec APIs: + +\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s, + int size, + const char *errors} + Creates a Unicode object by decoding \var{size} bytes of the UTF-8 + encoded string \var{s}. Returns \NULL{} if an exception was raised + by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s, + int size, + const char *errors} + Encodes the \ctype{Py_UNICODE} buffer of the given size using UTF-8 + and returns a Python string object. Returns \NULL{} if an exception + was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode} + Encodes a Unicode objects using UTF-8 and returns the result as + Python string object. Error handling is ``strict''. Returns + \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +% --- UTF-16 Codecs ------------------------------------------------------ */ + +These are the UTF-16 codec APIs: + +\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s, + int size, + const char *errors, + int *byteorder} + Decodes \var{length} bytes from a UTF-16 encoded buffer string and + returns the corresponding Unicode object. \var{errors} (if + non-\NULL) defines the error handling. It defaults to ``strict''. + + If \var{byteorder} is non-\NULL, the decoder starts decoding using + the given byte order: + +\begin{verbatim} + *byteorder == -1: little endian + *byteorder == 0: native order + *byteorder == 1: big endian +\end{verbatim} + + and then switches according to all byte order marks (BOM) it finds + in the input data. BOMs are not copied into the resulting Unicode + string. After completion, \var{*byteorder} is set to the current + byte order at the end of input data. + + If \var{byteorder} is \NULL, the codec starts in native order mode. + + Returns \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s, + int size, + const char *errors, + int byteorder} + Returns a Python string object holding the UTF-16 encoded value of + the Unicode data in \var{s}. If \var{byteorder} is not \code{0}, + output is written according to the following byte order: + +\begin{verbatim} + byteorder == -1: little endian + byteorder == 0: native byte order (writes a BOM mark) + byteorder == 1: big endian +\end{verbatim} + + If byteorder is \code{0}, the output string will always start with + the Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark + is prepended. + + Note that \ctype{Py_UNICODE} data is being interpreted as UTF-16 + reduced to UCS-2. This trick makes it possible to add full UTF-16 + capabilities at a later point without comprimising the APIs. + + Returns \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode} + Returns a Python string using the UTF-16 encoding in native byte + order. The string always starts with a BOM mark. Error handling is + ``strict''. Returns \NULL{} if an exception was raised by the + codec. +\end{cfuncdesc} + +% --- Unicode-Escape Codecs ---------------------------------------------- + +These are the ``Unicode Esacpe'' codec APIs: + +\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s, + int size, + const char *errors} + Creates a Unicode object by decoding \var{size} bytes of the + Unicode-Escape encoded string \var{s}. Returns \NULL{} if an + exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s, + int size, + const char *errors} + Encodes the \ctype{Py_UNICODE} buffer of the given size using + Unicode-Escape and returns a Python string object. Returns \NULL{} + if an exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode} + Encodes a Unicode objects using Unicode-Escape and returns the + result as Python string object. Error handling is ``strict''. + Returns \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +% --- Raw-Unicode-Escape Codecs ------------------------------------------ + +These are the ``Raw Unicode Esacpe'' codec APIs: + +\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s, + int size, + const char *errors} + Creates a Unicode object by decoding \var{size} bytes of the + Raw-Unicode-Esacpe encoded string \var{s}. Returns \NULL{} if an + exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s, + int size, + const char *errors} + Encodes the \ctype{Py_UNICODE} buffer of the given size using + Raw-Unicode-Escape and returns a Python string object. Returns + \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode} + Encodes a Unicode objects using Raw-Unicode-Escape and returns the + result as Python string object. Error handling is ``strict''. + Returns \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +% --- Latin-1 Codecs ----------------------------------------------------- + +These are the Latin-1 codec APIs: +Latin-1 corresponds to the first 256 Unicode ordinals and only these +are accepted by the codecs during encoding. + +\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s, + int size, + const char *errors} + Creates a Unicode object by decoding \var{size} bytes of the Latin-1 + encoded string \var{s}. Returns \NULL{} if an exception was raised + by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s, + int size, + const char *errors} + Encodes the \ctype{Py_UNICODE} buffer of the given size using + Latin-1 and returns a Python string object. Returns \NULL{} if an + exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode} + Encodes a Unicode objects using Latin-1 and returns the result as + Python string object. Error handling is ``strict''. Returns + \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +% --- ASCII Codecs ------------------------------------------------------- + +These are the \ASCII{} codec APIs. Only 7-bit \ASCII{} data is +accepted. All other codes generate errors. + +\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s, + int size, + const char *errors} + Creates a Unicode object by decoding \var{size} bytes of the + \ASCII{} encoded string \var{s}. Returns \NULL{} if an exception + was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s, + int size, + const char *errors} + Encodes the \ctype{Py_UNICODE} buffer of the given size using + \ASCII{} and returns a Python string object. Returns \NULL{} if an + exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode} + Encodes a Unicode objects using \ASCII{} and returns the result as + Python string object. Error handling is ``strict''. Returns + \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +% --- Character Map Codecs ----------------------------------------------- + +These are the mapping codec APIs: + +This codec is special in that it can be used to implement many +different codecs (and this is in fact what was done to obtain most of +the standard codecs included in the \module{encodings} package). The +codec uses mapping to encode and decode characters. + +Decoding mappings must map single string characters to single Unicode +characters, integers (which are then interpreted as Unicode ordinals) +or None (meaning "undefined mapping" and causing an error). + +Encoding mappings must map single Unicode characters to single string +characters, integers (which are then interpreted as Latin-1 ordinals) +or None (meaning "undefined mapping" and causing an error). + +The mapping objects provided must only support the __getitem__ mapping +interface. + +If a character lookup fails with a LookupError, the character is +copied as-is meaning that its ordinal value will be interpreted as +Unicode or Latin-1 ordinal resp. Because of this, mappings only need +to contain those mappings which map characters to different code +points. + +\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s, + int size, + PyObject *mapping, + const char *errors} + Creates a Unicode object by decoding \var{size} bytes of the encoded + string \var{s} using the given \var{mapping} object. Returns + \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s, + int size, + PyObject *mapping, + const char *errors} + Encodes the \ctype{Py_UNICODE} buffer of the given size using the + given \var{mapping} object and returns a Python string object. + Returns \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode, + PyObject *mapping} + Encodes a Unicode objects using the given \var{mapping} object and + returns the result as Python string object. Error handling is + ``strict''. Returns \NULL{} if an exception was raised by the + codec. +\end{cfuncdesc} + +The following codec API is special in that maps Unicode to Unicode. + +\begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s, + int size, + PyObject *table, + const char *errors} + Translates a \ctype{Py_UNICODE} buffer of the given length by + applying a character mapping \var{table} to it and returns the + resulting Unicode object. Returns \NULL{} when an exception was + raised by the codec. + + The \var{mapping} table must map Unicode ordinal integers to Unicode + ordinal integers or None (causing deletion of the character). + + Mapping tables need only provide the method{__getitem__()} + interface; dictionaries and sequences work well. Unmapped character + ordinals (ones which cause a \exception{LookupError}) are left + untouched and are copied as-is. +\end{cfuncdesc} + +% --- MBCS codecs for Windows -------------------------------------------- + +These are the MBCS codec APIs. They are currently only available on +Windows and use the Win32 MBCS converters to implement the +conversions. Note that MBCS (or DBCS) is a class of encodings, not +just one. The target encoding is defined by the user settings on the +machine running the codec. + +\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s, + int size, + const char *errors} + Creates a Unicode object by decoding \var{size} bytes of the MBCS + encoded string \var{s}. Returns \NULL{} if an exception was + raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s, + int size, + const char *errors} + Encodes the \ctype{Py_UNICODE} buffer of the given size using MBCS + and returns a Python string object. Returns \NULL{} if an exception + was raised by the codec. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode} + Encodes a Unicode objects using MBCS and returns the result as + Python string object. Error handling is ``strict''. Returns + \NULL{} if an exception was raised by the codec. +\end{cfuncdesc} + +% --- Methods & Slots ---------------------------------------------------- + +\subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}} + +The following APIs are capable of handling Unicode objects and strings +on input (we refer to them as strings in the descriptions) and return +Unicode objects or integers as apporpriate. + +They all return \NULL{} or \code{-1} if an exception occurs. + +\begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left, + PyObject *right} + Concat two strings giving a new Unicode string. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s, + PyObject *sep, + int maxsplit} + Split a string giving a list of Unicode strings. If sep is \NULL, + splitting will be done at all whitespace substrings. Otherwise, + splits occur at the given separator. At most \var{maxsplit} splits + will be done. If negative, no limit is set. Separators are not + included in the resulting list. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s, + int maxsplit} + Split a Unicode string at line breaks, returning a list of Unicode + strings. CRLF is considered to be one line break. The Line break + characters are not included in the resulting strings. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str, + PyObject *table, + const char *errors} + Translate a string by applying a character mapping table to it and + return the resulting Unicode object. + + The mapping table must map Unicode ordinal integers to Unicode + ordinal integers or None (causing deletion of the character). + + Mapping tables need only provide the \method{__getitem__()} + interface; dictionaries and sequences work well. Unmapped character + ordinals (ones which cause a \exception{LookupError}) are left + untouched and are copied as-is. + + \var{errors} has the usual meaning for codecs. It may be \NULL{} + which indicates to use the default error handling. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator, + PyObject *seq} + Join a sequence of strings using the given separator and return the + resulting Unicode string. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str, + PyObject *substr, + int start, + int end, + int direction} + Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at + the given tail end (\var{direction} == -1 means to do a prefix + match, \var{direction} == 1 a suffix match), 0 otherwise. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_Find}{PyObject *str, + PyObject *substr, + int start, + int end, + int direction} + Return the first position of \var{substr} in + \var{str}[\var{start}:\var{end}] using the given \var{direction} + (\var{direction} == 1 means to do a forward search, + \var{direction} == -1 a backward search), 0 otherwise. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_Count}{PyObject *str, + PyObject *substr, + int start, + int end} + Count the number of occurrences of \var{substr} in + \var{str}[\var{start}:\var{end}] +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str, + PyObject *substr, + PyObject *replstr, + int maxcount} + Replace at most \var{maxcount} occurrences of \var{substr} in + \var{str} with \var{replstr} and return the resulting Unicode object. + \var{maxcount} == -1 means replace all occurrences. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right} + Compare two strings and return -1, 0, 1 for less than, equal, and + greater than, respectively. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format, + PyObject *args} + Returns a new string object from \var{format} and \var{args}; this + is analogous to \code{\var{format} \%\ \var{args}}. The + \var{args} argument must be a tuple. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container, + PyObject *element} + Checks whether \var{element} is contained in \var{container} and + returns true or false accordingly. + + \var{element} has to coerce to a one element Unicode + string. \code{-1} is returned if there was an error. +\end{cfuncdesc} + + +\subsection{Buffer Objects \label{bufferObjects}} +\sectionauthor{Greg Stein}{gstein@lyra.org} + +\obindex{buffer} +Python objects implemented in C can export a group of functions called +the ``buffer\index{buffer interface} interface.'' These functions can +be used by an object to expose its data in a raw, byte-oriented +format. Clients of the object can use the buffer interface to access +the object data directly, without needing to copy it first. + +Two examples of objects that support +the buffer interface are strings and arrays. The string object exposes +the character contents in the buffer interface's byte-oriented +form. An array can also expose its contents, but it should be noted +that array elements may be multi-byte values. + +An example user of the buffer interface is the file object's +\method{write()} method. Any object that can export a series of bytes +through the buffer interface can be written to a file. There are a +number of format codes to \cfunction{PyArg_ParseTuple()} that operate +against an object's buffer interface, returning data from the target +object. + +More information on the buffer interface is provided in the section +``Buffer Object Structures'' (section \ref{buffer-structs}), under +the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}. + +A ``buffer object'' is defined in the \file{bufferobject.h} header +(included by \file{Python.h}). These objects look very similar to +string objects at the Python programming level: they support slicing, +indexing, concatenation, and some other standard string +operations. However, their data can come from one of two sources: from +a block of memory, or from another object which exports the buffer +interface. + +Buffer objects are useful as a way to expose the data from another +object's buffer interface to the Python programmer. They can also be +used as a zero-copy slicing mechanism. Using their ability to +reference a block of memory, it is possible to expose any data to the +Python programmer quite easily. The memory could be a large, constant +array in a C extension, it could be a raw block of memory for +manipulation before passing to an operating system library, or it +could be used to pass around structured data in its native, in-memory +format. + +\begin{ctypedesc}{PyBufferObject} + This subtype of \ctype{PyObject} represents a buffer object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyBuffer_Type} + The instance of \ctype{PyTypeObject} which represents the Python + buffer type; it is the same object as \code{types.BufferType} in the + Python layer.\withsubitem{(in module types)}{\ttindex{BufferType}}. +\end{cvardesc} + +\begin{cvardesc}{int}{Py_END_OF_BUFFER} + This constant may be passed as the \var{size} parameter to + \cfunction{PyBuffer_FromObject()} or + \cfunction{PyBuffer_FromReadWriteObject()}. It indicates that the + new \ctype{PyBufferObject} should refer to \var{base} object from + the specified \var{offset} to the end of its exported buffer. Using + this enables the caller to avoid querying the \var{base} object for + its length. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyBuffer_Check}{PyObject *p} + Return true if the argument has type \cdata{PyBuffer_Type}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base, + int offset, int size} + Return a new read-only buffer object. This raises + \exception{TypeError} if \var{base} doesn't support the read-only + buffer protocol or doesn't provide exactly one buffer segment, or it + raises \exception{ValueError} if \var{offset} is less than zero. The + buffer will hold a reference to the \var{base} object, and the + buffer's contents will refer to the \var{base} object's buffer + interface, starting as position \var{offset} and extending for + \var{size} bytes. If \var{size} is \constant{Py_END_OF_BUFFER}, then + the new buffer's contents extend to the length of the \var{base} + object's exported buffer data. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteObject}{PyObject *base, + int offset, + int size} + Return a new writable buffer object. Parameters and exceptions are + similar to those for \cfunction{PyBuffer_FromObject()}. If the + \var{base} object does not export the writeable buffer protocol, + then \exception{TypeError} is raised. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyBuffer_FromMemory}{void *ptr, int size} + Return a new read-only buffer object that reads from a specified + location in memory, with a specified size. The caller is + responsible for ensuring that the memory buffer, passed in as + \var{ptr}, is not deallocated while the returned buffer object + exists. Raises \exception{ValueError} if \var{size} is less than + zero. Note that \constant{Py_END_OF_BUFFER} may \emph{not} be + passed for the \var{size} parameter; \exception{ValueError} will be + raised in that case. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, int size} + Similar to \cfunction{PyBuffer_FromMemory()}, but the returned + buffer is writable. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{int size} + Returns a new writable buffer object that maintains its own memory + buffer of \var{size} bytes. \exception{ValueError} is returned if + \var{size} is not zero or positive. +\end{cfuncdesc} + + +\subsection{Tuple Objects \label{tupleObjects}} + +\obindex{tuple} +\begin{ctypedesc}{PyTupleObject} + This subtype of \ctype{PyObject} represents a Python tuple object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyTuple_Type} + This instance of \ctype{PyTypeObject} represents the Python tuple + type; it is the same object as \code{types.TupleType} in the Python + layer.\withsubitem{(in module types)}{\ttindex{TupleType}}. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p} + Return true if \var{p} is a tuple object or an instance of a subtype + of the tuple type. + \versionchanged[Allowed subtypes to be accepted]{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyTuple_CheckExact}{PyObject *p} + Return true if \var{p} is a tuple object, but not an instance of a + subtype of the tuple type. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len} + Return a new tuple object of size \var{len}, or \NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p} + Takes a pointer to a tuple object, and returns the size of that + tuple. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyTuple_GET_SIZE}{PyObject *p} + Return the size of the tuple \var{p}, which must be non-\NULL{} and + point to a tuple; no error checking is performed. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, int pos} + Returns the object at position \var{pos} in the tuple pointed to by + \var{p}. If \var{pos} is out of bounds, returns \NULL{} and sets an + \exception{IndexError} exception. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, int pos} + Like \cfunction{PyTuple_GetItem()}, but does no checking of its + arguments. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p, + int low, int high} + Takes a slice of the tuple pointed to by \var{p} from \var{low} to + \var{high} and returns it as a new tuple. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p, + int pos, PyObject *o} + Inserts a reference to object \var{o} at position \var{pos} of the + tuple pointed to by \var{p}. It returns \code{0} on success. + \note{This function ``steals'' a reference to \var{o}.} +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p, + int pos, PyObject *o} + Like \cfunction{PyTuple_SetItem()}, but does no error checking, and + should \emph{only} be used to fill in brand new tuples. \note{This + function ``steals'' a reference to \var{o}.} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, int newsize} + Can be used to resize a tuple. \var{newsize} will be the new length + of the tuple. Because tuples are \emph{supposed} to be immutable, + this should only be used if there is only one reference to the + object. Do \emph{not} use this if the tuple may already be known to + some other part of the code. The tuple will always grow or shrink + at the end. Think of this as destroying the old tuple and creating + a new one, only more efficiently. Returns \code{0} on success. + Client code should never assume that the resulting value of + \code{*\var{p}} will be the same as before calling this function. + If the object referenced by \code{*\var{p}} is replaced, the + original \code{*\var{p}} is destroyed. On failure, returns + \code{-1} and sets \code{*\var{p}} to \NULL, and raises + \exception{MemoryError} or + \exception{SystemError}. + \versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2} +\end{cfuncdesc} + + +\subsection{List Objects \label{listObjects}} + +\obindex{list} +\begin{ctypedesc}{PyListObject} + This subtype of \ctype{PyObject} represents a Python list object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyList_Type} + This instance of \ctype{PyTypeObject} represents the Python list + type. This is the same object as \code{types.ListType}. + \withsubitem{(in module types)}{\ttindex{ListType}} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p} + Returns true if its argument is a \ctype{PyListObject}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyList_New}{int len} + Returns a new list of length \var{len} on success, or \NULL{} on + failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Size}{PyObject *list} + Returns the length of the list object in \var{list}; this is + equivalent to \samp{len(\var{list})} on a list object. + \bifuncindex{len} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list} + Macro form of \cfunction{PyList_Size()} without error checking. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index} + Returns the object at position \var{pos} in the list pointed to by + \var{p}. If \var{pos} is out of bounds, returns \NULL{} and sets an + \exception{IndexError} exception. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i} + Macro form of \cfunction{PyList_GetItem()} without error checking. +\end{cfuncdesc} + +\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. \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}{void}{PyList_SET_ITEM}{PyObject *list, int i, + PyObject *o} + Macro form of \cfunction{PyList_SetItem()} without error checking. + This is normally only used to fill in new lists where there is no + previous content. + \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.} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index, + PyObject *item} + Inserts the item \var{item} into list \var{list} in front of index + \var{index}. Returns \code{0} if successful; returns \code{-1} and + raises an exception if unsuccessful. Analogous to + \code{\var{list}.insert(\var{index}, \var{item})}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item} + Appends the object \var{item} at the end of list \var{list}. + Returns \code{0} if successful; returns \code{-1} and sets an + exception if unsuccessful. Analogous to + \code{\var{list}.append(\var{item})}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list, + int low, int high} + Returns a list of the objects in \var{list} containing the objects + \emph{between} \var{low} and \var{high}. Returns \NULL{} and sets + an exception if unsuccessful. + Analogous to \code{\var{list}[\var{low}:\var{high}]}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list, + int low, int high, + PyObject *itemlist} + Sets the slice of \var{list} between \var{low} and \var{high} to the + contents of \var{itemlist}. Analogous to + \code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}. Returns + \code{0} on success, \code{-1} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list} + Sorts the items of \var{list} in place. Returns \code{0} on + success, \code{-1} on failure. This is equivalent to + \samp{\var{list}.sort()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list} + Reverses the items of \var{list} in place. Returns \code{0} on + success, \code{-1} on failure. This is the equivalent of + \samp{\var{list}.reverse()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list} + Returns a new tuple object containing the contents of \var{list}; + equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple} +\end{cfuncdesc} + + +\section{Mapping Objects \label{mapObjects}} + +\obindex{mapping} + + +\subsection{Dictionary Objects \label{dictObjects}} + +\obindex{dictionary} +\begin{ctypedesc}{PyDictObject} + This subtype of \ctype{PyObject} represents a Python dictionary + object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyDict_Type} + This instance of \ctype{PyTypeObject} represents the Python + dictionary type. This is exposed to Python programs as + \code{types.DictType} and \code{types.DictionaryType}. + \withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p} + Returns true if its argument is a \ctype{PyDictObject}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDict_New}{} + Returns a new empty dictionary, or \NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDictProxy_New}{PyObject *dict} + Return a proxy object for a mapping which enforces read-only + behavior. This is normally used to create a proxy to prevent + modification of the dictionary for non-dynamic class types. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p} + Empties an existing dictionary of all key-value pairs. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p} + Returns a new dictionary that contains the same key-value pairs as + \var{p}. + \versionadded{1.6} +\end{cfuncdesc} + +\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} + +\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p, + 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} + +\begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key} + Removes the entry in dictionary \var{p} with key \var{key}. + \var{key} must be hashable; if it isn't, \exception{TypeError} is + raised. +\end{cfuncdesc} + +\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} + Returns the object from dictionary \var{p} which has a key + \var{key}. Returns \NULL{} if the key \var{key} is not present, but + \emph{without} setting an exception. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, char *key} + This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is + specified as a \ctype{char*}, rather than a \ctype{PyObject*}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyObject *p} + Returns a \ctype{PyListObject} containing all the items from the + dictionary, as in the dictinoary method \method{items()} (see the + \citetitle[../lib/lib.html]{Python Library Reference}). +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p} + Returns a \ctype{PyListObject} containing all the keys from the + dictionary, as in the dictionary method \method{keys()} (see the + \citetitle[../lib/lib.html]{Python Library Reference}). +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyObject *p} + Returns a \ctype{PyListObject} containing all the values from the + dictionary \var{p}, as in the dictionary method \method{values()} + (see the \citetitle[../lib/lib.html]{Python Library Reference}). +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_Size}{PyObject *p} + Returns the number of items in the dictionary. This is equivalent + to \samp{len(\var{p})} on a dictionary.\bifuncindex{len} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, int *ppos, + PyObject **pkey, PyObject **pvalue} + Iterate over all key-value pairs in the dictionary \var{p}. The + \ctype{int} referred to by \var{ppos} must be initialized to + \code{0} prior to the first call to this function to start the + iteration; the function returns true for each pair in the + dictionary, and false once all pairs have been reported. The + parameters \var{pkey} and \var{pvalue} should either point to + \ctype{PyObject*} variables that will be filled in with each key and + value, respectively, or may be \NULL. + + For example: + +\begin{verbatim} +PyObject *key, *value; +int pos = 0; + +while (PyDict_Next(self->dict, &pos, &key, &value)) { + /* do something interesting with the values... */ + ... +} +\end{verbatim} + + The dictionary \var{p} should not be mutated during iteration. It + is safe (since Python 2.1) to modify the values of the keys as you + iterate over the dictionary, but only so long as the set of keys + does not change. For example: + +\begin{verbatim} +PyObject *key, *value; +int pos = 0; + +while (PyDict_Next(self->dict, &pos, &key, &value)) { + int i = PyInt_AS_LONG(value) + 1; + PyObject *o = PyInt_FromLong(i); + if (o == NULL) + return -1; + if (PyDict_SetItem(self->dict, key, o) < 0) { + Py_DECREF(o); + return -1; + } + Py_DECREF(o); +} +\end{verbatim} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_Merge}{PyObject *a, PyObject *b, int override} + Iterate over dictionary \var{b} adding key-value pairs to dictionary + \var{a}. If \var{override} is true, existing pairs in \var{a} will + be replaced if a matching key is found in \var{b}, otherwise pairs + will only be added if there is not a matching key in \var{a}. + Returns \code{0} on success or \code{-1} if an exception was + raised. +\versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDict_Update}{PyObject *a, PyObject *b} + This is the same as \code{PyDict_Merge(\var{a}, \var{b}, 1)} in C, + or \code{\var{a}.update(\var{b})} in Python. Returns \code{0} on + success or \code{-1} if an exception was raised. + \versionadded{2.2} +\end{cfuncdesc} + + +\section{Other Objects \label{otherObjects}} + +\subsection{File Objects \label{fileObjects}} + +\obindex{file} +Python's built-in file objects are implemented entirely on the +\ctype{FILE*} support from the C standard library. This is an +implementation detail and may change in future releases of Python. + +\begin{ctypedesc}{PyFileObject} + This subtype of \ctype{PyObject} represents a Python file object. +\end{ctypedesc} + +\begin{cvardesc}{PyTypeObject}{PyFile_Type} + This instance of \ctype{PyTypeObject} represents the Python file + type. This is exposed to Python programs as \code{types.FileType}. + \withsubitem{(in module types)}{\ttindex{FileType}} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p} + Returns true if its argument is a \ctype{PyFileObject} or a subtype + of \ctype{PyFileObject}. + \versionchanged[Allowed subtypes to be accepted]{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyFile_CheckExact}{PyObject *p} + Returns true if its argument is a \ctype{PyFileObject}, but not a + subtype of \ctype{PyFileObject}. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode} + On success, returns a new file object that is opened on the file + given by \var{filename}, with a file mode given by \var{mode}, where + \var{mode} has the same semantics as the standard C routine + \cfunction{fopen()}\ttindex{fopen()}. On failure, returns \NULL. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, + char *name, char *mode, + int (*close)(FILE*)} + Creates a new \ctype{PyFileObject} from the already-open standard C + file pointer, \var{fp}. The function \var{close} will be called + when the file should be closed. Returns \NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyFileObject *p} + Returns the file object associated with \var{p} as a \ctype{FILE*}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n} + Equivalent to \code{\var{p}.readline(\optional{\var{n}})}, this + function reads one line from the object \var{p}. \var{p} may be a + file object or any object with a \method{readline()} method. If + \var{n} is \code{0}, exactly one line is read, regardless of the + length of the line. If \var{n} is greater than \code{0}, no more + than \var{n} bytes will be read from the file; a partial line can be + returned. In both cases, an empty string is returned if the end of + the file is reached immediately. If \var{n} is less than \code{0}, + however, one line is read regardless of length, but + \exception{EOFError} is raised if the end of the file is reached + immediately. + \withsubitem{(built-in exception)}{\ttindex{EOFError}} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p} + Returns the name of the file specified by \var{p} as a string + object. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n} + Available on systems with \cfunction{setvbuf()}\ttindex{setvbuf()} + only. This should only be called immediately after file object + creation. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag} + This function exists for internal use by the interpreter. Sets the + \member{softspace} attribute of \var{p} to \var{newflag} and + \withsubitem{(file attribute)}{\ttindex{softspace}}returns the + previous value. \var{p} does not have to be a file object for this + function to work properly; any object is supported (thought its only + interesting if the \member{softspace} attribute can be set). This + function clears any errors, and will return \code{0} as the previous + value if the attribute either does not exist or if there were errors + in retrieving it. There is no way to detect errors from this + function, but doing so should not be needed. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p, + int flags} + Writes object \var{obj} to file object \var{p}. The only supported + flag for \var{flags} is + \constant{Py_PRINT_RAW}\ttindex{Py_PRINT_RAW}; if given, the + \function{str()} of the object is written instead of the + \function{repr()}. Returns \code{0} on success or \code{-1} on + failure; the appropriate exception will be set. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p} + Writes string \var{s} to file object \var{p}. Returns \code{0} on + success or \code{-1} on failure; the appropriate exception will be + set. +\end{cfuncdesc} + + +\subsection{Instance Objects \label{instanceObjects}} + +\obindex{instance} +There are very few functions specific to instance objects. + +\begin{cvardesc}{PyTypeObject}{PyInstance_Type} + Type object for class instances. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj} + Returns true if \var{obj} is an instance. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class, + PyObject *arg, + PyObject *kw} + Create a new instance of a specific class. The parameters \var{arg} + and \var{kw} are used as the positional and keyword parameters to + the object's constructor. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class, + PyObject *dict} + Create a new instance of a specific class without calling it's + constructor. \var{class} is the class of new object. The + \var{dict} parameter will be used as the object's \member{__dict__}; + if \NULL, a new dictionary will be created for the instance. +\end{cfuncdesc} + + +\subsection{Method Objects \label{method-objects}} + +\obindex{method} +There are some useful functions that are useful for working with +method objects. + +\begin{cvardesc}{PyTypeObject}{PyMethod_Type} + This instance of \ctype{PyTypeObject} represents the Python method + type. This is exposed to Python programs as \code{types.MethodType}. + \withsubitem{(in module types)}{\ttindex{MethodType}} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyMethod_Check}{PyObject *o} + Return true if \var{o} is a method object (has type + \cdata{PyMethod_Type}). The parameter must not be \NULL. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func. + PyObject *self, PyObject *class} + Return a new method object, with \var{func} being any callable + object; this is the function that will be called when the method is + called. If this method should be bound to an instance, \var{self} + should be the instance and \var{class} should be the class of + \var{self}, otherwise \var{self} should be \NULL{} and \var{class} + should be the class which provides the unbound method.. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyMethod_Class}{PyObject *meth} + Return the class object from which the method \var{meth} was + created; if this was created from an instance, it will be the class + of the instance. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyMethod_GET_CLASS}{PyObject *meth} + Macro version of \cfunction{PyMethod_Class()} which avoids error + checking. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyMethod_Function}{PyObject *meth} + Return the function object associated with the method \var{meth}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyMethod_GET_FUNCTION}{PyObject *meth} + Macro version of \cfunction{PyMethod_Function()} which avoids error + checking. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth} + Return the instance associated with the method \var{meth} if it is + bound, otherwise return \NULL. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyMethod_GET_SELF}{PyObject *meth} + Macro version of \cfunction{PyMethod_Self()} which avoids error + checking. +\end{cfuncdesc} + + +\subsection{Module Objects \label{moduleObjects}} + +\obindex{module} +There are only a few functions special to module objects. + +\begin{cvardesc}{PyTypeObject}{PyModule_Type} + This instance of \ctype{PyTypeObject} represents the Python module + type. This is exposed to Python programs as + \code{types.ModuleType}. + \withsubitem{(in module types)}{\ttindex{ModuleType}} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p} + Returns true if \var{p} is a module object, or a subtype of a module + object. + \versionchanged[Allowed subtypes to be accepted]{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyModule_CheckExact}{PyObject *p} + Returns true if \var{p} is a module object, but not a subtype of + \cdata{PyModule_Type}. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyModule_New}{char *name} + Return a new module object with the \member{__name__} attribute set + to \var{name}. Only the module's \member{__doc__} and + \member{__name__} attributes are filled in; the caller is + responsible for providing a \member{__file__} attribute. + \withsubitem{(module attribute)}{ + \ttindex{__name__}\ttindex{__doc__}\ttindex{__file__}} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module} + Return the dictionary object that implements \var{module}'s + namespace; this object is the same as the \member{__dict__} + attribute of the module object. This function never fails. + \withsubitem{(module attribute)}{\ttindex{__dict__}} +\end{cfuncdesc} + +\begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module} + Return \var{module}'s \member{__name__} value. If the module does + not provide one, or if it is not a string, \exception{SystemError} + is raised and \NULL{} is returned. + \withsubitem{(module attribute)}{\ttindex{__name__}} + \withsubitem{(built-in exception)}{\ttindex{SystemError}} +\end{cfuncdesc} + +\begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module} + Return the name of the file from which \var{module} was loaded using + \var{module}'s \member{__file__} attribute. If this is not defined, + or if it is not a string, raise \exception{SystemError} and return + \NULL. + \withsubitem{(module attribute)}{\ttindex{__file__}} + \withsubitem{(built-in exception)}{\ttindex{SystemError}} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module, + char *name, PyObject *value} + Add an object to \var{module} as \var{name}. This is a convenience + function which can be used from the module's initialization + function. This steals a reference to \var{value}. Returns + \code{-1} on error, \code{0} on success. + \versionadded{2.0} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module, + char *name, int value} + Add an integer constant to \var{module} as \var{name}. This + convenience function can be used from the module's initialization + function. Returns \code{-1} on error, \code{0} on success. + \versionadded{2.0} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module, + char *name, char *value} + Add a string constant to \var{module} as \var{name}. This + convenience function can be used from the module's initialization + function. The string \var{value} must be null-terminated. Returns + \code{-1} on error, \code{0} on success. + \versionadded{2.0} +\end{cfuncdesc} + + +\subsection{Iterator Objects \label{iterator-objects}} + +Python provides two general-purpose iterator objects. The first, a +sequence iterator, works with an arbitrary sequence supporting the +\method{__getitem__()} method. The second works with a callable +object and a sentinel value, calling the callable for each item in the +sequence, and ending the iteration when the sentinel value is +returned. + +\begin{cvardesc}{PyTypeObject}{PySeqIter_Type} + Type object for iterator objects returned by + \cfunction{PySeqIter_New()} and the one-argument form of the + \function{iter()} built-in function for built-in sequence types. + \versionadded{2.2} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PySeqIter_Check}{op} + Return true if the type of \var{op} is \cdata{PySeqIter_Type}. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PySeqIter_New}{PyObject *seq} + Return an iterator that works with a general sequence object, + \var{seq}. The iteration ends when the sequence raises + \exception{IndexError} for the subscripting operation. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cvardesc}{PyTypeObject}{PyCallIter_Type} + Type object for iterator objects returned by + \cfunction{PyCallIter_New()} and the two-argument form of the + \function{iter()} built-in function. + \versionadded{2.2} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyCallIter_Check}{op} + Return true if the type of \var{op} is \cdata{PyCallIter_Type}. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyCallIter_New}{PyObject *callable, + PyObject *sentinel} + Return a new iterator. The first parameter, \var{callable}, can be + any Python callable object that can be called with no parameters; + each call to it should return the next item in the iteration. When + \var{callable} returns a value equal to \var{sentinel}, the + iteration will be terminated. + \versionadded{2.2} +\end{cfuncdesc} + + +\subsection{Descriptor Objects \label{descriptor-objects}} + +\begin{cvardesc}{PyTypeObject}{PyProperty_Type} + The type object for a descriptor. + \versionadded{2.2} +\end{cvardesc} + +\begin{cfuncdesc}{PyObject*}{PyDescr_NewGetSet}{PyTypeObject *type, + PyGetSetDef *getset} + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDescr_NewMember}{PyTypeObject *type, + PyMemberDef *meth} + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDescr_NewMethod}{PyTypeObject *type, + PyMethodDef *meth} + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDescr_NewWrapper}{PyTypeObject *type, + struct wrapperbase *wrapper, + void *wrapped} + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDescr_IsData}{PyObject *descr} + Returns true if the descriptor objects \var{descr} describes a data + attribute, or false if it describes a method. \var{descr} must be a + descriptor object; there is no error checking. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyWrapper_New}{PyObject *, PyObject *} + \versionadded{2.2} +\end{cfuncdesc} + + +\subsection{Slice Objects \label{slice-objects}} + +\begin{cvardesc}{PyTypeObject}{PySlice_Type} + The type object for slice objects. This is the same as + \code{types.SliceType}. + \withsubitem{(in module types)}{\ttindex{SliceType}} +\end{cvardesc} + +\begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob} + Returns true if \var{ob} is a slice object; \var{ob} must not be + \NULL. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PySlice_New}{PyObject *start, PyObject *stop, + PyObject *step} + Return a new slice object with the given values. The \var{start}, + \var{stop}, and \var{step} parameters are used as the values of the + slice object attributes of the same names. Any of the values may be + \NULL, in which case the \code{None} will be used for the + corresponding attribute. Returns \NULL{} if the new object could + not be allocated. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySlice_GetIndices}{PySliceObject *slice, int length, + int *start, int *stop, int *step} +\end{cfuncdesc} + + +\subsection{Weak Reference Objects \label{weakref-objects}} + +Python supports \emph{weak references} as first-class objects. There +are two specific object types which directly implement weak +references. The first is a simple reference object, and the second +acts as a proxy for the original object as much as it can. + +\begin{cfuncdesc}{int}{PyWeakref_Check}{ob} + Return true if \var{ob} is either a reference or proxy object. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyWeakref_CheckRef}{ob} + Return true if \var{ob} is a reference object. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyWeakref_CheckProxy}{ob} + Return true if \var{ob} is a proxy object. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyWeakref_NewRef}{PyObject *ob, + PyObject *callback} + Return a weak reference object for the object \var{ob}. This will + always return a new reference, but is not guaranteed to create a new + object; an existing reference object may be returned. The second + parameter, \var{callback}, can be a callable object that receives + notification when \var{ob} is garbage collected; it should accept a + single paramter, which will be the weak reference object itself. + \var{callback} may also be \code{None} or \NULL. If \var{ob} + is not a weakly-referencable object, or if \var{callback} is not + callable, \code{None}, or \NULL, this will return \NULL{} and + raise \exception{TypeError}. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyWeakref_NewProxy}{PyObject *ob, + PyObject *callback} + Return a weak reference proxy object for the object \var{ob}. This + will always return a new reference, but is not guaranteed to create + a new object; an existing proxy object may be returned. The second + parameter, \var{callback}, can be a callable object that receives + notification when \var{ob} is garbage collected; it should accept a + single paramter, which will be the weak reference object itself. + \var{callback} may also be \code{None} or \NULL. If \var{ob} is not + a weakly-referencable object, or if \var{callback} is not callable, + \code{None}, or \NULL, this will return \NULL{} and raise + \exception{TypeError}. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyWeakref_GetObject}{PyObject *ref} + Returns the referenced object from a weak reference, \var{ref}. If + the referent is no longer live, returns \NULL. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyWeakref_GET_OBJECT}{PyObject *ref} + Similar to \cfunction{PyWeakref_GetObject()}, but implemented as a + macro that does no error checking. + \versionadded{2.2} +\end{cfuncdesc} + + +\subsection{CObjects \label{cObjects}} + +\obindex{CObject} +Refer to \emph{Extending and Embedding the Python Interpreter}, +section 1.12 (``Providing a C API for an Extension Module), for more +information on using these objects. + + +\begin{ctypedesc}{PyCObject} + This subtype of \ctype{PyObject} represents an opaque value, useful + for C extension modules who need to pass an opaque value (as a + \ctype{void*} pointer) through Python code to other C code. It is + often used to make a C function pointer defined in one module + available to other modules, so the regular import mechanism can be + used to access C APIs defined in dynamically loaded modules. +\end{ctypedesc} + +\begin{cfuncdesc}{int}{PyCObject_Check}{PyObject *p} + Returns true if its argument is a \ctype{PyCObject}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj, + void (*destr)(void *)} + Creates a \ctype{PyCObject} from the \code{void *}\var{cobj}. The + \var{destr} function will be called when the object is reclaimed, + unless it is \NULL. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj, + void* desc, void (*destr)(void *, void *)} + Creates a \ctype{PyCObject} from the \ctype{void *}\var{cobj}. The + \var{destr} function will be called when the object is reclaimed. + The \var{desc} argument can be used to pass extra callback data for + the destructor function. +\end{cfuncdesc} + +\begin{cfuncdesc}{void*}{PyCObject_AsVoidPtr}{PyObject* self} + Returns the object \ctype{void *} that the \ctype{PyCObject} + \var{self} was created with. +\end{cfuncdesc} + +\begin{cfuncdesc}{void*}{PyCObject_GetDesc}{PyObject* self} + Returns the description \ctype{void *} that the \ctype{PyCObject} + \var{self} was created with. +\end{cfuncdesc} diff --git a/Doc/api/exceptions.tex b/Doc/api/exceptions.tex new file mode 100644 index 0000000..355e6fb --- /dev/null +++ b/Doc/api/exceptions.tex @@ -0,0 +1,353 @@ +\chapter{Exception Handling \label{exceptionHandling}} + +The functions described in this chapter will let you handle and raise Python +exceptions. It is important to understand some of the basics of +Python exception handling. It works somewhat like the +\UNIX{} \cdata{errno} variable: there is a global indicator (per +thread) of the last error that occurred. Most functions don't clear +this on success, but will set it to indicate the cause of the error on +failure. Most functions also return an error indicator, usually +\NULL{} if they are supposed to return a pointer, or \code{-1} if they +return an integer (exception: the \cfunction{PyArg_Parse*()} functions +return \code{1} for success and \code{0} for failure). When a +function must fail because some function it called failed, it +generally doesn't set the error indicator; the function it called +already set it. + +The error indicator consists of three Python objects corresponding to +\withsubitem{(in module sys)}{ + \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} +the Python variables \code{sys.exc_type}, \code{sys.exc_value} and +\code{sys.exc_traceback}. API functions exist to interact with the +error indicator in various ways. There is a separate error indicator +for each thread. + +% XXX Order of these should be more thoughtful. +% Either alphabetical or some kind of structure. + +\begin{cfuncdesc}{void}{PyErr_Print}{} + Print a standard traceback to \code{sys.stderr} and clear the error + indicator. Call this function only when the error indicator is + set. (Otherwise it will cause a fatal error!) +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{} + Test whether the error indicator is set. If set, return the + exception \emph{type} (the first argument to the last call to one of + the \cfunction{PyErr_Set*()} functions or to + \cfunction{PyErr_Restore()}). If not set, return \NULL. You do + not own a reference to the return value, so you do not need to + \cfunction{Py_DECREF()} it. \note{Do not compare the return value + to a specific exception; use \cfunction{PyErr_ExceptionMatches()} + instead, shown below. (The comparison could easily fail since the + exception may be an instance instead of a class, in the case of a + class exception, or it may the a subclass of the expected + exception.)} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc} + Equivalent to \samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), + \var{exc})}. This should only be called when an exception is + actually set; a memory access violation will occur if no exception + has been raised. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc} + Return true if the \var{given} exception matches the exception in + \var{exc}. If \var{exc} is a class object, this also returns true + when \var{given} is an instance of a subclass. If \var{exc} is a + tuple, all exceptions in the tuple (and recursively in subtuples) + are searched for a match. If \var{given} is \NULL, a memory access + violation will occur. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb} + Under certain circumstances, the values returned by + \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning + that \code{*\var{exc}} is a class object but \code{*\var{val}} is + not an instance of the same class. This function can be used to + instantiate the class in that case. If the values are already + normalized, nothing happens. The delayed normalization is + implemented to improve performance. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_Clear}{} + Clear the error indicator. If the error indicator is not set, there + is no effect. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue, + PyObject **ptraceback} + Retrieve the error indicator into three variables whose addresses + are passed. If the error indicator is not set, set all three + variables to \NULL. If it is set, it will be cleared and you own a + reference to each object retrieved. The value and traceback object + may be \NULL{} even when the type object is not. \note{This + function is normally only used by code that needs to handle + exceptions or by code that needs to save and restore the error + indicator temporarily.} +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value, + PyObject *traceback} + Set the error indicator from the three objects. If the error + indicator is already set, it is cleared first. If the objects are + \NULL, the error indicator is cleared. Do not pass a \NULL{} type + 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: 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.) \note{This function is normally only used + by code that needs to save and restore the error indicator + temporarily.} +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message} + This is the most common way to set the error indicator. The first + argument specifies the exception type; it is normally one of the + standard exceptions, e.g. \cdata{PyExc_RuntimeError}. You need not + increment its reference count. The second argument is an error + message; it is converted to a string object. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value} + This function is similar to \cfunction{PyErr_SetString()} but lets + you specify an arbitrary Python object for the ``value'' of the + exception. You need not increment its reference count. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception, + const char *format, \moreargs} + This function sets the error indicator. \var{exception} should be a + Python exception (string or class, not an instance). \var{format} + should be a string, containing format codes, similar to + \cfunction{printf()}. The \code{width.precision} before a format + code is parsed, but the width part is ignored. + + \begin{tableii}{c|l}{character}{Character}{Meaning} + \lineii{c}{Character, as an \ctype{int} parameter} + \lineii{d}{Number in decimal, as an \ctype{int} parameter} + \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter} + \lineii{x}{A string, as a \ctype{char *} parameter} + \end{tableii} + + An unrecognized format character causes all the rest of the format + string to be copied as-is to the result string, and any extra + arguments discarded. + + A new reference is returned, which is owned by the caller. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type} + This is a shorthand for \samp{PyErr_SetObject(\var{type}, + Py_None)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_BadArgument}{} + This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError, + \var{message})}, where \var{message} indicates that a built-in + operation was invoked with an illegal argument. It is mostly for + internal use. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{} + This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it + returns \NULL{} so an object allocation function can write + \samp{return PyErr_NoMemory();} when it runs out of memory. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type} + This is a convenience function to raise an exception when a C + library function has returned an error and set the C variable + \cdata{errno}. It constructs a tuple object whose first item is the + integer \cdata{errno} value and whose second item is the + corresponding error message (gotten from + \cfunction{strerror()}\ttindex{strerror()}), and then calls + \samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX, when + the \cdata{errno} value is \constant{EINTR}, indicating an + interrupted system call, this calls + \cfunction{PyErr_CheckSignals()}, and if that set the error + indicator, leaves it set to that. The function always returns + \NULL, so a wrapper function around a system call can write + \samp{return PyErr_SetFromErrno();} when the system call returns an + error. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type, + char *filename} + Similar to \cfunction{PyErr_SetFromErrno()}, with the additional + behavior that if \var{filename} is not \NULL, it is passed to the + constructor of \var{type} as a third parameter. In the case of + exceptions such as \exception{IOError} and \exception{OSError}, this + is used to define the \member{filename} attribute of the exception + instance. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_BadInternalCall}{} + This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError, + \var{message})}, where \var{message} indicates that an internal + operation (e.g. a Python/C API function) was invoked with an illegal + argument. It is mostly for internal use. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message} + Issue a warning message. The \var{category} argument is a warning + category (see below) or \NULL; the \var{message} argument is a + message string. + + This function normally prints a warning message to \var{sys.stderr}; + however, it is also possible that the user has specified that + warnings are to be turned into errors, and in that case this will + raise an exception. It is also possible that the function raises an + exception because of a problem with the warning machinery (the + implementation imports the \module{warnings} module to do the heavy + lifting). The return value is \code{0} if no exception is raised, + or \code{-1} if an exception is raised. (It is not possible to + determine whether a warning message is actually printed, nor what + the reason is for the exception; this is intentional.) If an + exception is raised, the caller should do its normal exception + handling (for example, \cfunction{Py_DECREF()} owned references and + return an error value). + + Warning categories must be subclasses of \cdata{Warning}; the + default warning category is \cdata{RuntimeWarning}. The standard + Python warning categories are available as global variables whose + names are \samp{PyExc_} followed by the Python exception name. + These have the type \ctype{PyObject*}; they are all class objects. + Their names are \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning}, + \cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, and + \cdata{PyExc_RuntimeWarning}. \cdata{PyExc_Warning} is a subclass + of \cdata{PyExc_Exception}; the other warning categories are + subclasses of \cdata{PyExc_Warning}. + + For information about warning control, see the documentation for the + \module{warnings} module and the \programopt{-W} option in the + command line documentation. There is no C API for warning control. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message, + char *filename, int lineno, char *module, PyObject *registry} + Issue a warning message with explicit control over all warning + attributes. This is a straightforward wrapper around the Python + function \function{warnings.warn_explicit()}, see there for more + information. The \var{module} and \var{registry} arguments may be + set to \NULL{} to get the default effect described there. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyErr_CheckSignals}{} + This function interacts with Python's signal handling. It checks + whether a signal has been sent to the processes and if so, invokes + the corresponding signal handler. If the + \module{signal}\refbimodindex{signal} module is supported, this can + invoke a signal handler written in Python. In all cases, the + default effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the + \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} + \exception{KeyboardInterrupt} exception. If an exception is raised + the error indicator is set and the function returns \code{1}; + otherwise the function returns \code{0}. The error indicator may or + may not be cleared if it was previously set. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_SetInterrupt}{} + This function is obsolete. It simulates the effect of a + \constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time + \cfunction{PyErr_CheckSignals()} is called, + \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} + \exception{KeyboardInterrupt} will be raised. It may be called + without holding the interpreter lock. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name, + PyObject *base, + PyObject *dict} + This utility function creates and returns a new exception object. + The \var{name} argument must be the name of the new exception, a C + string of the form \code{module.class}. The \var{base} and + \var{dict} arguments are normally \NULL. This creates a class + object derived from the root for all exceptions, the built-in name + \exception{Exception} (accessible in C as \cdata{PyExc_Exception}). + The \member{__module__} attribute of the new class is set to the + first part (up to the last dot) of the \var{name} argument, and the + class name is set to the last part (after the last dot). The + \var{base} argument can be used to specify an alternate base class. + The \var{dict} argument can be used to specify a dictionary of class + variables and methods. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj} + This utility function prints a warning message to \code{sys.stderr} + when an exception has been set but it is impossible for the + interpreter to actually raise the exception. It is used, for + example, when an exception occurs in an \method{__del__()} method. + + The function is called with a single argument \var{obj} that + identifies where the context in which the unraisable exception + occurred. The repr of \var{obj} will be printed in the warning + message. +\end{cfuncdesc} + +\section{Standard Exceptions \label{standardExceptions}} + +All standard Python exceptions are available as global variables whose +names are \samp{PyExc_} followed by the Python exception name. These +have the type \ctype{PyObject*}; they are all class objects. For +completeness, here are all the variables: + +\begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes} + \lineiii{PyExc_Exception}{\exception{Exception}}{(1)} + \lineiii{PyExc_StandardError}{\exception{StandardError}}{(1)} + \lineiii{PyExc_ArithmeticError}{\exception{ArithmeticError}}{(1)} + \lineiii{PyExc_LookupError}{\exception{LookupError}}{(1)} + \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{} + \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{} + \lineiii{PyExc_EOFError}{\exception{EOFError}}{} + \lineiii{PyExc_EnvironmentError}{\exception{EnvironmentError}}{(1)} + \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{} + \lineiii{PyExc_IOError}{\exception{IOError}}{} + \lineiii{PyExc_ImportError}{\exception{ImportError}}{} + \lineiii{PyExc_IndexError}{\exception{IndexError}}{} + \lineiii{PyExc_KeyError}{\exception{KeyError}}{} + \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{} + \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{} + \lineiii{PyExc_NameError}{\exception{NameError}}{} + \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{} + \lineiii{PyExc_OSError}{\exception{OSError}}{} + \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{} + \lineiii{PyExc_ReferenceError}{\exception{ReferenceError}}{(2)} + \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{} + \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{} + \lineiii{PyExc_SystemError}{\exception{SystemError}}{} + \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{} + \lineiii{PyExc_TypeError}{\exception{TypeError}}{} + \lineiii{PyExc_ValueError}{\exception{ValueError}}{} + \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(3)} + \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{} +\end{tableiii} + +\noindent +Notes: +\begin{description} +\item[(1)] + This is a base class for other standard exceptions. + +\item[(2)] + This is the same as \exception{weakref.ReferenceError}. + +\item[(3)] + Only defined on Windows; protect code that uses this by testing that + the preprocessor macro \code{MS_WINDOWS} is defined. +\end{description} + + +\section{Deprecation of String Exceptions} + +All exceptions built into Python or provided in the standard library +are derived from \exception{Exception}. +\withsubitem{(built-in exception)}{\ttindex{Exception}} + +String exceptions are still supported in the interpreter to allow +existing code to run unmodified, but this will also change in a future +release. diff --git a/Doc/api/init.tex b/Doc/api/init.tex new file mode 100644 index 0000000..890ca0d --- /dev/null +++ b/Doc/api/init.tex @@ -0,0 +1,774 @@ +\chapter{Initialization, Finalization, and Threads + \label{initialization}} + +\begin{cfuncdesc}{void}{Py_Initialize}{} + Initialize the Python interpreter. In an application embedding + Python, this should be called before using any other Python/C API + functions; with the exception of + \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, + \cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()}, + \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()}, + and \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}. + This initializes the table of loaded modules (\code{sys.modules}), + and\withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}} + creates the fundamental modules + \module{__builtin__}\refbimodindex{__builtin__}, + \module{__main__}\refbimodindex{__main__} and + \module{sys}\refbimodindex{sys}. It also initializes the module + search\indexiii{module}{search}{path} path (\code{sys.path}). + It does not set \code{sys.argv}; use + \cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} for that. This + is a no-op when called for a second time (without calling + \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} first). There is + no return value; it is a fatal error if the initialization fails. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_IsInitialized}{} + Return true (nonzero) when the Python interpreter has been + initialized, false (zero) if not. After \cfunction{Py_Finalize()} + is called, this returns false until \cfunction{Py_Initialize()} is + called again. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_Finalize}{} + Undo all initializations made by \cfunction{Py_Initialize()} and + subsequent use of Python/C API functions, and destroy all + sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that + were created and not yet destroyed since the last call to + \cfunction{Py_Initialize()}. Ideally, this frees all memory + allocated by the Python interpreter. This is a no-op when called + for a second time (without calling \cfunction{Py_Initialize()} again + first). There is no return value; errors during finalization are + ignored. + + This function is provided for a number of reasons. An embedding + application might want to restart Python without having to restart + the application itself. An application that has loaded the Python + interpreter from a dynamically loadable library (or DLL) might want + to free all memory allocated by Python before unloading the + DLL. During a hunt for memory leaks in an application a developer + might want to free all memory allocated by Python before exiting + from the application. + + \strong{Bugs and caveats:} The destruction of modules and objects in + modules is done in random order; this may cause destructors + (\method{__del__()} methods) to fail when they depend on other + objects (even functions) or modules. Dynamically loaded extension + modules loaded by Python are not unloaded. Small amounts of memory + allocated by the Python interpreter may not be freed (if you find a + leak, please report it). Memory tied up in circular references + between objects is not freed. Some memory allocated by extension + modules may not be freed. Some extension may not work properly if + their initialization routine is called more than once; this can + happen if an applcation calls \cfunction{Py_Initialize()} and + \cfunction{Py_Finalize()} more than once. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{} + Create a new sub-interpreter. This is an (almost) totally separate + environment for the execution of Python code. In particular, the + new interpreter has separate, independent versions of all imported + modules, including the fundamental modules + \module{__builtin__}\refbimodindex{__builtin__}, + \module{__main__}\refbimodindex{__main__} and + \module{sys}\refbimodindex{sys}. The table of loaded modules + (\code{sys.modules}) and the module search path (\code{sys.path}) + are also separate. The new environment has no \code{sys.argv} + variable. It has new standard I/O stream file objects + \code{sys.stdin}, \code{sys.stdout} and \code{sys.stderr} (however + these refer to the same underlying \ctype{FILE} structures in the C + library). + \withsubitem{(in module sys)}{ + \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}} + + The return value points to the first thread state created in the new + sub-interpreter. This thread state is made the current thread + state. Note that no actual thread is created; see the discussion of + thread states below. If creation of the new interpreter is + unsuccessful, \NULL{} is returned; no exception is set since the + exception state is stored in the current thread state and there may + not be a current thread state. (Like all other Python/C API + functions, the global interpreter lock must be held before calling + this function and is still held when it returns; however, unlike + most other Python/C API functions, there needn't be a current thread + state on entry.) + + Extension modules are shared between (sub-)interpreters as follows: + the first time a particular extension is imported, it is initialized + normally, and a (shallow) copy of its module's dictionary is + squirreled away. When the same extension is imported by another + (sub-)interpreter, a new module is initialized and filled with the + contents of this copy; the extension's \code{init} function is not + called. Note that this is different from what happens when an + extension is imported after the interpreter has been completely + re-initialized by calling + \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and + \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case, + the extension's \code{init\var{module}} function \emph{is} called + again. + + \strong{Bugs and caveats:} Because sub-interpreters (and the main + interpreter) are part of the same process, the insulation between + them isn't perfect --- for example, using low-level file operations + like \withsubitem{(in module os)}{\ttindex{close()}} + \function{os.close()} they can (accidentally or maliciously) affect + each other's open files. Because of the way extensions are shared + between (sub-)interpreters, some extensions may not work properly; + this is especially likely when the extension makes use of (static) + global variables, or when the extension manipulates its module's + dictionary after its initialization. It is possible to insert + objects created in one sub-interpreter into a namespace of another + sub-interpreter; this should be done with great care to avoid + sharing user-defined functions, methods, instances or classes + between sub-interpreters, since import operations executed by such + objects may affect the wrong (sub-)interpreter's dictionary of + loaded modules. (XXX This is a hard-to-fix bug that will be + addressed in a future release.) +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate} + Destroy the (sub-)interpreter represented by the given thread state. + The given thread state must be the current thread state. See the + discussion of thread states below. When the call returns, the + current thread state is \NULL. All thread states associated with + this interpreted are destroyed. (The global interpreter lock must + be held before calling this function and is still held when it + returns.) \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} will + destroy all sub-interpreters that haven't been explicitly destroyed + at that point. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name} + This function should be called before + \cfunction{Py_Initialize()}\ttindex{Py_Initialize()} is called + for the first time, if it is called at all. It tells the + interpreter the value of the \code{argv[0]} argument to the + \cfunction{main()}\ttindex{main()} function of the program. This is + used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some + other functions below to find the Python run-time libraries relative + to the interpreter executable. The default value is + \code{'python'}. The argument should point to a zero-terminated + character string in static storage whose contents will not change + for the duration of the program's execution. No code in the Python + interpreter will change the contents of this storage. +\end{cfuncdesc} + +\begin{cfuncdesc}{char*}{Py_GetProgramName}{} + Return the program name set with + \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, or the + default. The returned string points into static storage; the caller + should not modify its value. +\end{cfuncdesc} + +\begin{cfuncdesc}{char*}{Py_GetPrefix}{} + Return the \emph{prefix} for installed platform-independent files. + This is derived through a number of complicated rules from the + program name set with \cfunction{Py_SetProgramName()} and some + environment variables; for example, if the program name is + \code{'/usr/local/bin/python'}, the prefix is \code{'/usr/local'}. + The returned string points into static storage; the caller should + not modify its value. This corresponds to the \makevar{prefix} + variable in the top-level \file{Makefile} and the + \longprogramopt{prefix} argument to the \program{configure} script + at build time. The value is available to Python code as + \code{sys.prefix}. It is only useful on \UNIX. See also the next + function. +\end{cfuncdesc} + +\begin{cfuncdesc}{char*}{Py_GetExecPrefix}{} + Return the \emph{exec-prefix} for installed + platform-\emph{de}pendent files. This is derived through a number + of complicated rules from the program name set with + \cfunction{Py_SetProgramName()} and some environment variables; for + example, if the program name is \code{'/usr/local/bin/python'}, the + exec-prefix is \code{'/usr/local'}. The returned string points into + static storage; the caller should not modify its value. This + corresponds to the \makevar{exec_prefix} variable in the top-level + \file{Makefile} and the \longprogramopt{exec-prefix} argument to the + \program{configure} script at build time. The value is available + to Python code as \code{sys.exec_prefix}. It is only useful on + \UNIX. + + Background: The exec-prefix differs from the prefix when platform + dependent files (such as executables and shared libraries) are + installed in a different directory tree. In a typical installation, + platform dependent files may be installed in the + \file{/usr/local/plat} subtree while platform independent may be + installed in \file{/usr/local}. + + Generally speaking, a platform is a combination of hardware and + software families, e.g. Sparc machines running the Solaris 2.x + operating system are considered the same platform, but Intel + machines running Solaris 2.x are another platform, and Intel + machines running Linux are yet another platform. Different major + revisions of the same operating system generally also form different + platforms. Non-\UNIX{} operating systems are a different story; the + installation strategies on those systems are so different that the + prefix and exec-prefix are meaningless, and set to the empty string. + Note that compiled Python bytecode files are platform independent + (but not independent from the Python version by which they were + compiled!). + + System administrators will know how to configure the \program{mount} + or \program{automount} programs to share \file{/usr/local} between + platforms while having \file{/usr/local/plat} be a different + filesystem for each platform. +\end{cfuncdesc} + +\begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{} + Return the full program name of the Python executable; this is + computed as a side-effect of deriving the default module search path + from the program name (set by + \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()} above). + The returned string points into static storage; the caller should + not modify its value. The value is available to Python code as + \code{sys.executable}. + \withsubitem{(in module sys)}{\ttindex{executable}} +\end{cfuncdesc} + +\begin{cfuncdesc}{char*}{Py_GetPath}{} + \indexiii{module}{search}{path} + Return the default module search path; this is computed from the + program name (set by \cfunction{Py_SetProgramName()} above) and some + environment variables. The returned string consists of a series of + directory names separated by a platform dependent delimiter + character. The delimiter character is \character{:} on \UNIX, + \character{;} on DOS/Windows, and \character{\e n} (the \ASCII{} + newline character) on Macintosh. The returned string points into + static storage; the caller should not modify its value. The value + is available to Python code as the list + \code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}}, which + may be modified to change the future search path for loaded + modules. + + % XXX should give the exact rules +\end{cfuncdesc} + +\begin{cfuncdesc}{const char*}{Py_GetVersion}{} + Return the version of this Python interpreter. This is a string + that looks something like + +\begin{verbatim} +"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]" +\end{verbatim} + + The first word (up to the first space character) is the current + Python version; the first three characters are the major and minor + version separated by a period. The returned string points into + static storage; the caller should not modify its value. The value + is available to Python code as the list \code{sys.version}. + \withsubitem{(in module sys)}{\ttindex{version}} +\end{cfuncdesc} + +\begin{cfuncdesc}{const char*}{Py_GetPlatform}{} + Return the platform identifier for the current platform. On \UNIX, + this is formed from the ``official'' name of the operating system, + converted to lower case, followed by the major revision number; + e.g., for Solaris 2.x, which is also known as SunOS 5.x, the value + is \code{'sunos5'}. On Macintosh, it is \code{'mac'}. On Windows, + it is \code{'win'}. The returned string points into static storage; + the caller should not modify its value. The value is available to + Python code as \code{sys.platform}. + \withsubitem{(in module sys)}{\ttindex{platform}} +\end{cfuncdesc} + +\begin{cfuncdesc}{const char*}{Py_GetCopyright}{} + Return the official copyright string for the current Python version, + for example + + \code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'} + + The returned string points into static storage; the caller should + not modify its value. The value is available to Python code as the + list \code{sys.copyright}. + \withsubitem{(in module sys)}{\ttindex{copyright}} +\end{cfuncdesc} + +\begin{cfuncdesc}{const char*}{Py_GetCompiler}{} + Return an indication of the compiler used to build the current + Python version, in square brackets, for example: + +\begin{verbatim} +"[GCC 2.7.2.2]" +\end{verbatim} + + The returned string points into static storage; the caller should + not modify its value. The value is available to Python code as part + of the variable \code{sys.version}. + \withsubitem{(in module sys)}{\ttindex{version}} +\end{cfuncdesc} + +\begin{cfuncdesc}{const char*}{Py_GetBuildInfo}{} + Return information about the sequence number and build date and time + of the current Python interpreter instance, for example + +\begin{verbatim} +"#67, Aug 1 1997, 22:34:28" +\end{verbatim} + + The returned string points into static storage; the caller should + not modify its value. The value is available to Python code as part + of the variable \code{sys.version}. + \withsubitem{(in module sys)}{\ttindex{version}} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv} + Set \code{sys.argv} based on \var{argc} and \var{argv}. These + parameters are similar to those passed to the program's + \cfunction{main()}\ttindex{main()} function with the difference that + the first entry should refer to the script file to be executed + rather than the executable hosting the Python interpreter. If there + isn't a script that will be run, the first entry in \var{argv} can + be an empty string. If this function fails to initialize + \code{sys.argv}, a fatal condition is signalled using + \cfunction{Py_FatalError()}\ttindex{Py_FatalError()}. + \withsubitem{(in module sys)}{\ttindex{argv}} + % XXX impl. doesn't seem consistent in allowing 0/NULL for the params; + % check w/ Guido. +\end{cfuncdesc} + +% XXX Other PySys thingies (doesn't really belong in this chapter) + +\section{Thread State and the Global Interpreter Lock + \label{threads}} + +\index{global interpreter lock} +\index{interpreter lock} +\index{lock, interpreter} + +The Python interpreter is not fully thread safe. In order to support +multi-threaded Python programs, there's a global lock that must be +held by the current thread before it can safely access Python objects. +Without the lock, even the simplest operations could cause problems in +a multi-threaded program: for example, when two threads simultaneously +increment the reference count of the same object, the reference count +could end up being incremented only once instead of twice. + +Therefore, the rule exists that only the thread that has acquired the +global interpreter lock may operate on Python objects or call Python/C +API functions. In order to support multi-threaded Python programs, +the interpreter regularly releases and reacquires the lock --- by +default, every ten bytecode instructions (this can be changed with +\withsubitem{(in module sys)}{\ttindex{setcheckinterval()}} +\function{sys.setcheckinterval()}). The lock is also released and +reacquired around potentially blocking I/O operations like reading or +writing a file, so that other threads can run while the thread that +requests the I/O is waiting for the I/O operation to complete. + +The Python interpreter needs to keep some bookkeeping information +separate per thread --- for this it uses a data structure called +\ctype{PyThreadState}\ttindex{PyThreadState}. This is new in Python +1.5; in earlier versions, such state was stored in global variables, +and switching threads could cause problems. In particular, exception +handling is now thread safe, when the application uses +\withsubitem{(in module sys)}{\ttindex{exc_info()}} +\function{sys.exc_info()} to access the exception last raised in the +current thread. + +There's one global variable left, however: the pointer to the current +\ctype{PyThreadState}\ttindex{PyThreadState} structure. While most +thread packages have a way to store ``per-thread global data,'' +Python's internal platform independent thread abstraction doesn't +support this yet. Therefore, the current thread state must be +manipulated explicitly. + +This is easy enough in most cases. Most code manipulating the global +interpreter lock has the following simple structure: + +\begin{verbatim} +Save the thread state in a local variable. +Release the interpreter lock. +...Do some blocking I/O operation... +Reacquire the interpreter lock. +Restore the thread state from the local variable. +\end{verbatim} + +This is so common that a pair of macros exists to simplify it: + +\begin{verbatim} +Py_BEGIN_ALLOW_THREADS +...Do some blocking I/O operation... +Py_END_ALLOW_THREADS +\end{verbatim} + +The \code{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS} macro +opens a new block and declares a hidden local variable; the +\code{Py_END_ALLOW_THREADS}\ttindex{Py_END_ALLOW_THREADS} macro closes +the block. Another advantage of using these two macros is that when +Python is compiled without thread support, they are defined empty, +thus saving the thread state and lock manipulations. + +When thread support is enabled, the block above expands to the +following code: + +\begin{verbatim} + PyThreadState *_save; + + _save = PyEval_SaveThread(); + ...Do some blocking I/O operation... + PyEval_RestoreThread(_save); +\end{verbatim} + +Using even lower level primitives, we can get roughly the same effect +as follows: + +\begin{verbatim} + PyThreadState *_save; + + _save = PyThreadState_Swap(NULL); + PyEval_ReleaseLock(); + ...Do some blocking I/O operation... + PyEval_AcquireLock(); + PyThreadState_Swap(_save); +\end{verbatim} + +There are some subtle differences; in particular, +\cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} saves +and restores the value of the global variable +\cdata{errno}\ttindex{errno}, since the lock manipulation does not +guarantee that \cdata{errno} is left alone. Also, when thread support +is disabled, +\cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and +\cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this +case, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and +\cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()} are not +available. This is done so that dynamically loaded extensions +compiled with thread support enabled can be loaded by an interpreter +that was compiled with disabled thread support. + +The global interpreter lock is used to protect the pointer to the +current thread state. When releasing the lock and saving the thread +state, the current thread state pointer must be retrieved before the +lock is released (since another thread could immediately acquire the +lock and store its own thread state in the global variable). +Conversely, when acquiring the lock and restoring the thread state, +the lock must be acquired before storing the thread state pointer. + +Why am I going on with so much detail about this? Because when +threads are created from C, they don't have the global interpreter +lock, nor is there a thread state data structure for them. Such +threads must bootstrap themselves into existence, by first creating a +thread state data structure, then acquiring the lock, and finally +storing their thread state pointer, before they can start using the +Python/C API. When they are done, they should reset the thread state +pointer, release the lock, and finally free their thread state data +structure. + +When creating a thread data structure, you need to provide an +interpreter state data structure. The interpreter state data +structure hold global data that is shared by all threads in an +interpreter, for example the module administration +(\code{sys.modules}). Depending on your needs, you can either create +a new interpreter state data structure, or share the interpreter state +data structure used by the Python main thread (to access the latter, +you must obtain the thread state and access its \member{interp} member; +this must be done by a thread that is created by Python or by the main +thread after Python is initialized). + + +\begin{ctypedesc}{PyInterpreterState} + This data structure represents the state shared by a number of + cooperating threads. Threads belonging to the same interpreter + share their module administration and a few other internal items. + There are no public members in this structure. + + Threads belonging to different interpreters initially share nothing, + except process state like available memory, open file descriptors + and such. The global interpreter lock is also shared by all + threads, regardless of to which interpreter they belong. +\end{ctypedesc} + +\begin{ctypedesc}{PyThreadState} + This data structure represents the state of a single thread. The + only public data member is \ctype{PyInterpreterState + *}\member{interp}, which points to this thread's interpreter state. +\end{ctypedesc} + +\begin{cfuncdesc}{void}{PyEval_InitThreads}{} + Initialize and acquire the global interpreter lock. It should be + called in the main thread before creating a second thread or + engaging in any other thread operations such as + \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} or + \code{PyEval_ReleaseThread(\var{tstate})}\ttindex{PyEval_ReleaseThread()}. + It is not needed before calling + \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} or + \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}. + + This is a no-op when called for a second time. It is safe to call + this function before calling + \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}. + + When only the main thread exists, no lock operations are needed. + This is a common situation (most Python programs do not use + threads), and the lock operations slow the interpreter down a bit. + Therefore, the lock is not created initially. This situation is + equivalent to having acquired the lock: when there is only a single + thread, all object accesses are safe. Therefore, when this function + initializes the lock, it also acquires it. Before the Python + \module{thread}\refbimodindex{thread} module creates a new thread, + knowing that either it has the lock or the lock hasn't been created + yet, it calls \cfunction{PyEval_InitThreads()}. When this call + returns, it is guaranteed that the lock has been created and that it + has acquired it. + + It is \strong{not} safe to call this function when it is unknown + which thread (if any) currently has the global interpreter lock. + + This function is not available when thread support is disabled at + compile time. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyEval_AcquireLock}{} + Acquire the global interpreter lock. The lock must have been + created earlier. If this thread already has the lock, a deadlock + ensues. This function is not available when thread support is + disabled at compile time. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{} + Release the global interpreter lock. The lock must have been + created earlier. This function is not available when thread support + is disabled at compile time. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate} + Acquire the global interpreter lock and then set the current thread + state to \var{tstate}, which should not be \NULL. The lock must + have been created earlier. If this thread already has the lock, + deadlock ensues. This function is not available when thread support + is disabled at compile time. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate} + Reset the current thread state to \NULL{} and release the global + interpreter lock. The lock must have been created earlier and must + be held by the current thread. The \var{tstate} argument, which + must not be \NULL, is only used to check that it represents the + current thread state --- if it isn't, a fatal error is reported. + This function is not available when thread support is disabled at + compile time. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{} + Release the interpreter lock (if it has been created and thread + support is enabled) and reset the thread state to \NULL, returning + the previous thread state (which is not \NULL). If the lock has + been created, the current thread must have acquired it. (This + function is available even when thread support is disabled at + compile time.) +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate} + Acquire the interpreter lock (if it has been created and thread + support is enabled) and set the thread state to \var{tstate}, which + must not be \NULL. If the lock has been created, the current thread + must not have acquired it, otherwise deadlock ensues. (This + function is available even when thread support is disabled at + compile time.) +\end{cfuncdesc} + +The following macros are normally used without a trailing semicolon; +look for example usage in the Python source distribution. + +\begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS} + This macro expands to + \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}. + Note that it contains an opening brace; it must be matched with a + following \code{Py_END_ALLOW_THREADS} macro. See above for further + discussion of this macro. It is a no-op when thread support is + disabled at compile time. +\end{csimplemacrodesc} + +\begin{csimplemacrodesc}{Py_END_ALLOW_THREADS} + This macro expands to \samp{PyEval_RestoreThread(_save); \}}. + Note that it contains a closing brace; it must be matched with an + earlier \code{Py_BEGIN_ALLOW_THREADS} macro. See above for further + discussion of this macro. It is a no-op when thread support is + disabled at compile time. +\end{csimplemacrodesc} + +\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 time. +\end{csimplemacrodesc} + +\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 disabled at compile time. +\end{csimplemacrodesc} + +All of the following functions are only available when thread support +is enabled at compile time, and must be called only when the +interpreter lock has been created. + +\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_New}{} + Create a new interpreter state object. The interpreter lock need + not be held, but may be held if it is necessary to serialize calls + to this function. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp} + Reset all information in an interpreter state object. The + interpreter lock must be held. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp} + Destroy an interpreter state object. The interpreter lock need not + be held. The interpreter state must have been reset with a previous + call to \cfunction{PyInterpreterState_Clear()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyThreadState*}{PyThreadState_New}{PyInterpreterState *interp} + Create a new thread state object belonging to the given interpreter + object. The interpreter lock need not be held, but may be held if + it is necessary to serialize calls to this function. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate} + Reset all information in a thread state object. The interpreter lock + must be held. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate} + Destroy a thread state object. The interpreter lock need not be + held. The thread state must have been reset with a previous call to + \cfunction{PyThreadState_Clear()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{} + Return the current thread state. The interpreter lock must be + held. When the current thread state is \NULL, this issues a fatal + error (so that the caller needn't check for \NULL). +\end{cfuncdesc} + +\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Swap}{PyThreadState *tstate} + Swap the current thread state with the thread state given by the + argument \var{tstate}, which may be \NULL. The interpreter lock + must be held. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyThreadState_GetDict}{} + Return a dictionary in which extensions can store thread-specific + state information. Each extension should use a unique key to use to + store state in the dictionary. If this function returns \NULL, an + exception has been raised and the caller should allow it to + propogate. +\end{cfuncdesc} + + +\section{Profiling and Tracing \label{profiling}} + +\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} + +The Python interpreter provides some low-level support for attaching +profiling and execution tracing facilities. These are used for +profiling, debugging, and coverage analysis tools. + +Starting with Python 2.2, the implementation of this facility was +substantially revised, and an interface from C was added. This C +interface allows the profiling or tracing code to avoid the overhead +of calling through Python-level callable objects, making a direct C +function call instead. The essential attributes of the facility have +not changed; the interface allows trace functions to be installed +per-thread, and the basic events reported to the trace function are +the same as had been reported to the Python-level trace functions in +previous versions. + +\begin{ctypedesc}[Py_tracefunc]{int (*Py_tracefunc)(PyObject *obj, + PyFrameObject *frame, int what, + PyObject *arg)} + The type of the trace function registered using + \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}. + The first parameter is the object passed to the registration + function as \var{obj}, \var{frame} is the frame object to which the + event pertains, \var{what} is one of the constants + \constant{PyTrace_CALL}, \constant{PyTrace_EXCEPT}, + \constant{PyTrace_LINE} or \constant{PyTrace_RETURN}, and \var{arg} + depends on the value of \var{what}: + + \begin{tableii}{l|l}{constant}{Value of \var{what}}{Meaning of \var{arg}} + \lineii{PyTrace_CALL}{Always \NULL.} + \lineii{PyTrace_EXCEPT}{Exception information as returned by + \function{sys.exc_info()}.} + \lineii{PyTrace_LINE}{Always \NULL.} + \lineii{PyTrace_RETURN}{Value being returned to the caller.} + \end{tableii} +\end{ctypedesc} + +\begin{cvardesc}{int}{PyTrace_CALL} + The value of the \var{what} parameter to a \ctype{Py_tracefunc} + function when a new call to a function or method is being reported, + or a new entry into a generator. Note that the creation of the + iterator for a generator function is not reported as there is no + control transfer to the Python bytecode in the corresponding frame. +\end{cvardesc} + +\begin{cvardesc}{int}{PyTrace_EXCEPT} + The value of the \var{what} parameter to a \ctype{Py_tracefunc} + function when an exception has been raised by Python code as the + result of an operation. The operation may have explictly intended + to raise the operation (as with a \keyword{raise} statement), or may + have triggered an exception in the runtime as a result of the + specific operation. +\end{cvardesc} + +\begin{cvardesc}{int}{PyTrace_LINE} + The value passed as the \var{what} parameter to a trace function + (but not a profiling function) when a line-number event is being + reported. +\end{cvardesc} + +\begin{cvardesc}{int}{PyTrace_RETURN} + The value for the \var{what} parameter to \ctype{Py_tracefunc} + functions when a call is returning without propogating an exception. +\end{cvardesc} + +\begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj} + Set the profiler function to \var{func}. The \var{obj} parameter is + passed to the function as its first parameter, and may be any Python + object, or \NULL. If the profile function needs to maintain state, + using a different value for \var{obj} for each thread provides a + convenient and thread-safe place to store it. The profile function + is called for all monitored events except the line-number events. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj} + Set the the tracing function to \var{func}. This is similar to + \cfunction{PyEval_SetProfile()}, except the tracing function does + receive line-number events. +\end{cfuncdesc} + + +\section{Advanced Debugger Support \label{advanced-debugging}} +\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} + +These functions are only intended to be used by advanced debugging +tools. + +\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{} + Return the interpreter state object at the head of the list of all + such objects. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Next}{PyInterpreterState *interp} + Return the next interpreter state object after \var{interp} from the + list of all such objects. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyThreadState *}{PyInterpreterState_ThreadHead}{PyInterpreterState *interp} + Return the a pointer to the first \ctype{PyThreadState} object in + the list of threads associated with the interpreter \var{interp}. + \versionadded{2.2} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Next}{PyThreadState *tstate} + Return the next thread state object after \var{tstate} from the list + of all such objects belonging to the same \ctype{PyInterpreterState} + object. + \versionadded{2.2} +\end{cfuncdesc} diff --git a/Doc/api/intro.tex b/Doc/api/intro.tex new file mode 100644 index 0000000..d148ba8 --- /dev/null +++ b/Doc/api/intro.tex @@ -0,0 +1,558 @@ +\chapter{Introduction \label{intro}} + + +The Application Programmer's Interface to Python gives C and +\Cpp{} programmers access to the Python interpreter at a variety of +levels. The API is equally usable from \Cpp{}, but for brevity it is +generally referred to as the Python/C API. There are two +fundamentally different reasons for using the Python/C API. The first +reason is to write \emph{extension modules} for specific purposes; +these are C modules that extend the Python interpreter. This is +probably the most common use. The second reason is to use Python as a +component in a larger application; this technique is generally +referred to as \dfn{embedding} Python in an application. + +Writing an extension module is a relatively well-understood process, +where a ``cookbook'' approach works well. There are several tools +that automate the process to some extent. While people have embedded +Python in other applications since its early existence, the process of +embedding Python is less straightforward than writing an extension. + +Many API functions are useful independent of whether you're embedding +or extending Python; moreover, most applications that embed Python +will need to provide a custom extension as well, so it's probably a +good idea to become familiar with writing an extension before +attempting to embed Python in a real application. + + +\section{Include Files \label{includes}} + +All function, type and macro definitions needed to use the Python/C +API are included in your code by the following line: + +\begin{verbatim} +#include "Python.h" +\end{verbatim} + +This implies inclusion of the following standard headers: +\code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, +\code{<limits.h>}, and \code{<stdlib.h>} (if available). +Since Python may define some pre-processor definitions which affect +the standard headers on some systems, you must include \file{Python.h} +before any standard headers are included. + +All user visible names defined by Python.h (except those defined by +the included standard headers) have one of the prefixes \samp{Py} or +\samp{_Py}. Names beginning with \samp{_Py} are for internal use by +the Python implementation and should not be used by extension writers. +Structure member names do not have a reserved prefix. + +\strong{Important:} user code should never define names that begin +with \samp{Py} or \samp{_Py}. This confuses the reader, and +jeopardizes the portability of the user code to future Python +versions, which may define additional names beginning with one of +these prefixes. + +The header files are typically installed with Python. On \UNIX, these +are located in the directories +\file{\envvar{prefix}/include/python\var{version}/} and +\file{\envvar{exec_prefix}/include/python\var{version}/}, where +\envvar{prefix} and \envvar{exec_prefix} are defined by the +corresponding parameters to Python's \program{configure} script and +\var{version} is \code{sys.version[:3]}. On Windows, the headers are +installed in \file{\envvar{prefix}/include}, where \envvar{prefix} is +the installation directory specified to the installer. + +To include the headers, place both directories (if different) on your +compiler's search path for includes. Do \emph{not} place the parent +directories on the search path and then use +\samp{\#include <python\shortversion/Python.h>}; this will break on +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}} + +Most Python/C API functions have one or more arguments as well as a +return value of type \ctype{PyObject*}. This type is a pointer +to an opaque data type representing an arbitrary Python +object. Since all Python object types are treated the same way by the +Python language in most situations (e.g., assignments, scope rules, +and argument passing), it is only fitting that they should be +represented by a single C type. Almost all Python objects live on the +heap: you never declare an automatic or static variable of type +\ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can +be declared. The sole exception are the type objects\obindex{type}; +since these must never be deallocated, they are typically static +\ctype{PyTypeObject} objects. + +All Python objects (even Python integers) have a \dfn{type} and a +\dfn{reference count}. An object's type determines what kind of object +it is (e.g., an integer, a list, or a user-defined function; there are +many more as explained in the \citetitle[../ref/ref.html]{Python +Reference Manual}). For each of the well-known types there is a macro +to check whether an object is of that type; for instance, +\samp{PyList_Check(\var{a})} is true if (and only if) the object +pointed to by \var{a} is a Python list. + + +\subsection{Reference Counts \label{refcounts}} + +The reference count is important because today's computers have a +finite (and often severely limited) memory size; it counts how many +different places there are that have a reference to an object. Such a +place could be another object, or a global (or static) C variable, or +a local variable in some C function. When an object's reference count +becomes zero, the object is deallocated. If it contains references to +other objects, their reference count is decremented. Those other +objects may be deallocated in turn, if this decrement makes their +reference count become zero, and so on. (There's an obvious problem +with objects that reference each other here; for now, the solution is +``don't do that.'') + +Reference counts are always manipulated explicitly. The normal way is +to use the macro \cfunction{Py_INCREF()}\ttindex{Py_INCREF()} to +increment an object's reference count by one, and +\cfunction{Py_DECREF()}\ttindex{Py_DECREF()} to decrement it by +one. The \cfunction{Py_DECREF()} macro is considerably more complex +than the incref one, since it must check whether the reference count +becomes zero and then cause the object's deallocator to be called. +The deallocator is a function pointer contained in the object's type +structure. The type-specific deallocator takes care of decrementing +the reference counts for other objects contained in the object if this +is a compound object type, such as a list, as well as performing any +additional finalization that's needed. There's no chance that the +reference count can overflow; at least as many bits are used to hold +the reference count as there are distinct memory locations in virtual +memory (assuming \code{sizeof(long) >= sizeof(char*)}). Thus, the +reference count increment is a simple operation. + +It is not necessary to increment an object's reference count for every +local variable that contains a pointer to an object. In theory, the +object's reference count goes up by one when the variable is made to +point to it and it goes down by one when the variable goes out of +scope. However, these two cancel each other out, so at the end the +reference count hasn't changed. The only real reason to use the +reference count is to prevent the object from being deallocated as +long as our variable is pointing to it. If we know that there is at +least one other reference to the object that lives at least as long as +our variable, there is no need to increment the reference count +temporarily. An important situation where this arises is in objects +that are passed as arguments to C functions in an extension module +that are called from Python; the call mechanism guarantees to hold a +reference to every argument for the duration of the call. + +However, a common pitfall is to extract an object from a list and +hold on to it for a while without incrementing its reference count. +Some other operation might conceivably remove the object from the +list, decrementing its reference count and possible deallocating it. +The real danger is that innocent-looking operations may invoke +arbitrary Python code which could do this; there is a code path which +allows control to flow back to the user from a \cfunction{Py_DECREF()}, +so almost any operation is potentially dangerous. + +A safe approach is to always use the generic operations (functions +whose name begins with \samp{PyObject_}, \samp{PyNumber_}, +\samp{PySequence_} or \samp{PyMapping_}). These operations always +increment the reference count of the object they return. This leaves +the caller with the responsibility to call +\cfunction{Py_DECREF()} when they are done with the result; this soon +becomes second nature. + + +\subsubsection{Reference Count Details \label{refcountDetails}} + +The reference count behavior of functions in the Python/C API is best +explained in terms of \emph{ownership of references}. Note that we +talk of owning references, never of owning objects; objects are always +shared! When a function owns a reference, it has to dispose of it +properly --- either by passing ownership on (usually to its caller) or +by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}. When +a function passes ownership of a reference on to its caller, the +caller is said to receive a \emph{new} reference. When no ownership +is transferred, the caller is said to \emph{borrow} the reference. +Nothing needs to be done for a borrowed reference. + +Conversely, when a calling function passes it a reference to an +object, there are two possibilities: the function \emph{steals} a +reference to the object, or it does not. Few functions steal +references; the two notable exceptions are +\cfunction{PyList_SetItem()}\ttindex{PyList_SetItem()} and +\cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which +steal a reference to the item (but not to the tuple or list into which +the item is put!). These functions were designed to steal a reference +because of a common idiom for populating a tuple or list with newly +created objects; for example, the code to create the tuple \code{(1, +2, "three")} could look like this (forgetting about error handling for +the moment; a better way to code this is shown below): + +\begin{verbatim} +PyObject *t; + +t = PyTuple_New(3); +PyTuple_SetItem(t, 0, PyInt_FromLong(1L)); +PyTuple_SetItem(t, 1, PyInt_FromLong(2L)); +PyTuple_SetItem(t, 2, PyString_FromString("three")); +\end{verbatim} + +Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to +set tuple items; \cfunction{PySequence_SetItem()} and +\cfunction{PyObject_SetItem()} refuse to do this since tuples are an +immutable data type. You should only use +\cfunction{PyTuple_SetItem()} for tuples that you are creating +yourself. + +Equivalent code for populating a list can be written using +\cfunction{PyList_New()} and \cfunction{PyList_SetItem()}. Such code +can also use \cfunction{PySequence_SetItem()}; this illustrates the +difference between the two (the extra \cfunction{Py_DECREF()} calls): + +\begin{verbatim} +PyObject *l, *x; + +l = PyList_New(3); +x = PyInt_FromLong(1L); +PySequence_SetItem(l, 0, x); Py_DECREF(x); +x = PyInt_FromLong(2L); +PySequence_SetItem(l, 1, x); Py_DECREF(x); +x = PyString_FromString("three"); +PySequence_SetItem(l, 2, x); Py_DECREF(x); +\end{verbatim} + +You might find it strange that the ``recommended'' approach takes more +code. However, in practice, you will rarely use these ways of +creating and populating a tuple or list. There's a generic function, +\cfunction{Py_BuildValue()}, that can create most common objects from +C values, directed by a \dfn{format string}. For example, the +above two blocks of code could be replaced by the following (which +also takes care of the error checking): + +\begin{verbatim} +PyObject *t, *l; + +t = Py_BuildValue("(iis)", 1, 2, "three"); +l = Py_BuildValue("[iis]", 1, 2, "three"); +\end{verbatim} + +It is much more common to use \cfunction{PyObject_SetItem()} and +friends with items whose references you are only borrowing, like +arguments that were passed in to the function you are writing. In +that case, their behaviour regarding reference counts is much saner, +since you don't have to increment a reference count so you can give a +reference away (``have it be stolen''). For example, this function +sets all items of a list (actually, any mutable sequence) to a given +item: + +\begin{verbatim} +int set_all(PyObject *target, PyObject *item) +{ + int i, n; + + n = PyObject_Length(target); + if (n < 0) + return -1; + for (i = 0; i < n; i++) { + if (PyObject_SetItem(target, i, item) < 0) + return -1; + } + return 0; +} +\end{verbatim} +\ttindex{set_all()} + +The situation is slightly different for function return values. +While passing a reference to most functions does not change your +ownership responsibilities for that reference, many functions that +return a referece to an object give you ownership of the reference. +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 (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 +don't own the reference --- but if you obtain the same item from the +same list using \cfunction{PySequence_GetItem()} (which happens to +take exactly the same arguments), you do own a reference to the +returned object. + +Here is an example of how you could write a function that computes the +sum of the items in a list of integers; once using +\cfunction{PyList_GetItem()}\ttindex{PyList_GetItem()}, and once using +\cfunction{PySequence_GetItem()}\ttindex{PySequence_GetItem()}. + +\begin{verbatim} +long sum_list(PyObject *list) +{ + int i, n; + long total = 0; + PyObject *item; + + n = PyList_Size(list); + if (n < 0) + return -1; /* Not a list */ + for (i = 0; i < n; i++) { + item = PyList_GetItem(list, i); /* Can't fail */ + if (!PyInt_Check(item)) continue; /* Skip non-integers */ + total += PyInt_AsLong(item); + } + return total; +} +\end{verbatim} +\ttindex{sum_list()} + +\begin{verbatim} +long sum_sequence(PyObject *sequence) +{ + int i, n; + long total = 0; + PyObject *item; + n = PySequence_Length(sequence); + if (n < 0) + return -1; /* Has no length */ + for (i = 0; i < n; i++) { + item = PySequence_GetItem(sequence, i); + if (item == NULL) + return -1; /* Not a sequence, or other failure */ + if (PyInt_Check(item)) + total += PyInt_AsLong(item); + Py_DECREF(item); /* Discard reference ownership */ + } + return total; +} +\end{verbatim} +\ttindex{sum_sequence()} + + +\subsection{Types \label{types}} + +There are few other data types that play a significant role in +the Python/C API; most are simple C types such as \ctype{int}, +\ctype{long}, \ctype{double} and \ctype{char*}. A few structure types +are used to describe static tables used to list the functions exported +by a module or the data attributes of a new object type, and another +is used to describe the value of a complex number. These will +be discussed together with the functions that use them. + + +\section{Exceptions \label{exceptions}} + +The Python programmer only needs to deal with exceptions if specific +error handling is required; unhandled exceptions are automatically +propagated to the caller, then to the caller's caller, and so on, until +they reach the top-level interpreter, where they are reported to the +user accompanied by a stack traceback. + +For C programmers, however, error checking always has to be explicit. +All functions in the Python/C API can raise exceptions, unless an +explicit claim is made otherwise in a function's documentation. In +general, when a function encounters an error, it sets an exception, +discards any object references that it owns, and returns an +error indicator --- usually \NULL{} or \code{-1}. A few functions +return a Boolean true/false result, with false indicating an error. +Very few functions return no explicit error indicator or have an +ambiguous return value, and require explicit testing for errors with +\cfunction{PyErr_Occurred()}\ttindex{PyErr_Occurred()}. + +Exception state is maintained in per-thread storage (this is +equivalent to using global storage in an unthreaded application). A +thread can be in one of two states: an exception has occurred, or not. +The function \cfunction{PyErr_Occurred()} can be used to check for +this: it returns a borrowed reference to the exception type object +when an exception has occurred, and \NULL{} otherwise. There are a +number of functions to set the exception state: +\cfunction{PyErr_SetString()}\ttindex{PyErr_SetString()} is the most +common (though not the most general) function to set the exception +state, and \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} clears the +exception state. + +The full exception state consists of three objects (all of which can +be \NULL): the exception type, the corresponding exception +value, and the traceback. These have the same meanings as the Python +\withsubitem{(in module sys)}{ + \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} +objects \code{sys.exc_type}, \code{sys.exc_value}, and +\code{sys.exc_traceback}; however, they are not the same: the Python +objects represent the last exception being handled by a Python +\keyword{try} \ldots\ \keyword{except} statement, while the C level +exception state only exists while an exception is being passed on +between C functions until it reaches the Python bytecode interpreter's +main loop, which takes care of transferring it to \code{sys.exc_type} +and friends. + +Note that starting with Python 1.5, the preferred, thread-safe way to +access the exception state from Python code is to call the function +\withsubitem{(in module sys)}{\ttindex{exc_info()}} +\function{sys.exc_info()}, which returns the per-thread exception state +for Python code. Also, the semantics of both ways to access the +exception state have changed so that a function which catches an +exception will save and restore its thread's exception state so as to +preserve the exception state of its caller. This prevents common bugs +in exception handling code caused by an innocent-looking function +overwriting the exception being handled; it also reduces the often +unwanted lifetime extension for objects that are referenced by the +stack frames in the traceback. + +As a general principle, a function that calls another function to +perform some task should check whether the called function raised an +exception, and if so, pass the exception state on to its caller. It +should discard any object references that it owns, and return an +error indicator, but it should \emph{not} set another exception --- +that would overwrite the exception that was just raised, and lose +important information about the exact cause of the error. + +A simple example of detecting exceptions and passing them on is shown +in the \cfunction{sum_sequence()}\ttindex{sum_sequence()} example +above. It so happens that that example doesn't need to clean up any +owned references when it detects an error. The following example +function shows some error cleanup. First, to remind you why you like +Python, we show the equivalent Python code: + +\begin{verbatim} +def incr_item(dict, key): + try: + item = dict[key] + except KeyError: + item = 0 + dict[key] = item + 1 +\end{verbatim} +\ttindex{incr_item()} + +Here is the corresponding C code, in all its glory: + +\begin{verbatim} +int incr_item(PyObject *dict, PyObject *key) +{ + /* Objects all initialized to NULL for Py_XDECREF */ + PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL; + int rv = -1; /* Return value initialized to -1 (failure) */ + + item = PyObject_GetItem(dict, key); + if (item == NULL) { + /* Handle KeyError only: */ + if (!PyErr_ExceptionMatches(PyExc_KeyError)) + goto error; + + /* Clear the error and use zero: */ + PyErr_Clear(); + item = PyInt_FromLong(0L); + if (item == NULL) + goto error; + } + const_one = PyInt_FromLong(1L); + if (const_one == NULL) + goto error; + + incremented_item = PyNumber_Add(item, const_one); + if (incremented_item == NULL) + goto error; + + if (PyObject_SetItem(dict, key, incremented_item) < 0) + goto error; + rv = 0; /* Success */ + /* Continue with cleanup code */ + + error: + /* Cleanup code, shared by success and failure path */ + + /* Use Py_XDECREF() to ignore NULL references */ + Py_XDECREF(item); + Py_XDECREF(const_one); + Py_XDECREF(incremented_item); + + return rv; /* -1 for error, 0 for success */ +} +\end{verbatim} +\ttindex{incr_item()} + +This example represents an endorsed use of the \keyword{goto} statement +in C! It illustrates the use of +\cfunction{PyErr_ExceptionMatches()}\ttindex{PyErr_ExceptionMatches()} and +\cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} to +handle specific exceptions, and the use of +\cfunction{Py_XDECREF()}\ttindex{Py_XDECREF()} to +dispose of owned references that may be \NULL{} (note the +\character{X} in the name; \cfunction{Py_DECREF()} would crash when +confronted with a \NULL{} reference). It is important that the +variables used to hold owned references are initialized to \NULL{} for +this to work; likewise, the proposed return value is initialized to +\code{-1} (failure) and only set to success after the final call made +is successful. + + +\section{Embedding Python \label{embedding}} + +The one important task that only embedders (as opposed to extension +writers) of the Python interpreter have to worry about is the +initialization, and possibly the finalization, of the Python +interpreter. Most functionality of the interpreter can only be used +after the interpreter has been initialized. + +The basic initialization function is +\cfunction{Py_Initialize()}\ttindex{Py_Initialize()}. +This initializes the table of loaded modules, and creates the +fundamental modules \module{__builtin__}\refbimodindex{__builtin__}, +\module{__main__}\refbimodindex{__main__}, \module{sys}\refbimodindex{sys}, +and \module{exceptions}.\refbimodindex{exceptions} It also initializes +the module search path (\code{sys.path}).% +\indexiii{module}{search}{path} +\withsubitem{(in module sys)}{\ttindex{path}} + +\cfunction{Py_Initialize()} does not set the ``script argument list'' +(\code{sys.argv}). If this variable is needed by Python code that +will be executed later, it must be set explicitly with a call to +\code{PySys_SetArgv(\var{argc}, +\var{argv})}\ttindex{PySys_SetArgv()} subsequent to the call to +\cfunction{Py_Initialize()}. + +On most systems (in particular, on \UNIX{} and Windows, although the +details are slightly different), +\cfunction{Py_Initialize()} calculates the module search path based +upon its best guess for the location of the standard Python +interpreter executable, assuming that the Python library is found in a +fixed location relative to the Python interpreter executable. In +particular, it looks for a directory named +\file{lib/python\shortversion} relative to the parent directory where +the executable named \file{python} is found on the shell command +search path (the environment variable \envvar{PATH}). + +For instance, if the Python executable is found in +\file{/usr/local/bin/python}, it will assume that the libraries are in +\file{/usr/local/lib/python\shortversion}. (In fact, this particular path +is also the ``fallback'' location, used when no executable file named +\file{python} is found along \envvar{PATH}.) The user can override +this behavior by setting the environment variable \envvar{PYTHONHOME}, +or insert additional directories in front of the standard path by +setting \envvar{PYTHONPATH}. + +The embedding application can steer the search by calling +\code{Py_SetProgramName(\var{file})}\ttindex{Py_SetProgramName()} \emph{before} calling +\cfunction{Py_Initialize()}. Note that \envvar{PYTHONHOME} still +overrides this and \envvar{PYTHONPATH} is still inserted in front of +the standard path. An application that requires total control has to +provide its own implementation of +\cfunction{Py_GetPath()}\ttindex{Py_GetPath()}, +\cfunction{Py_GetPrefix()}\ttindex{Py_GetPrefix()}, +\cfunction{Py_GetExecPrefix()}\ttindex{Py_GetExecPrefix()}, and +\cfunction{Py_GetProgramFullPath()}\ttindex{Py_GetProgramFullPath()} (all +defined in \file{Modules/getpath.c}). + +Sometimes, it is desirable to ``uninitialize'' Python. For instance, +the application may want to start over (make another call to +\cfunction{Py_Initialize()}) or the application is simply done with its +use of Python and wants to free all memory allocated by Python. This +can be accomplished by calling \cfunction{Py_Finalize()}. The function +\cfunction{Py_IsInitialized()}\ttindex{Py_IsInitialized()} returns +true if Python is currently in the initialized state. More +information about these functions is given in a later chapter. diff --git a/Doc/api/memory.tex b/Doc/api/memory.tex new file mode 100644 index 0000000..2f45259 --- /dev/null +++ b/Doc/api/memory.tex @@ -0,0 +1,201 @@ +\chapter{Memory Management \label{memory}} +\sectionauthor{Vladimir Marangozov}{Vladimir.Marangozov@inrialpes.fr} + + +\section{Overview \label{memoryOverview}} + +Memory management in Python involves a private heap containing all +Python objects and data structures. The management of this private +heap is ensured internally by the \emph{Python memory manager}. The +Python memory manager has different components which deal with various +dynamic storage management aspects, like sharing, segmentation, +preallocation or caching. + +At the lowest level, a raw memory allocator ensures that there is +enough room in the private heap for storing all Python-related data +by interacting with the memory manager of the operating system. On top +of the raw memory allocator, several object-specific allocators +operate on the same heap and implement distinct memory management +policies adapted to the peculiarities of every object type. For +example, integer objects are managed differently within the heap than +strings, tuples or dictionaries because integers imply different +storage requirements and speed/space tradeoffs. The Python memory +manager thus delegates some of the work to the object-specific +allocators, but ensures that the latter operate within the bounds of +the private heap. + +It is important to understand that the management of the Python heap +is performed by the interpreter itself and that the user has no +control on it, even if she regularly manipulates object pointers to +memory blocks inside that heap. The allocation of heap space for +Python objects and other internal buffers is performed on demand by +the Python memory manager through the Python/C API functions listed in +this document. + +To avoid memory corruption, extension writers should never try to +operate on Python objects with the functions exported by the C +library: \cfunction{malloc()}\ttindex{malloc()}, +\cfunction{calloc()}\ttindex{calloc()}, +\cfunction{realloc()}\ttindex{realloc()} and +\cfunction{free()}\ttindex{free()}. This will result in +mixed calls between the C allocator and the Python memory manager +with fatal consequences, because they implement different algorithms +and operate on different heaps. However, one may safely allocate and +release memory blocks with the C library allocator for individual +purposes, as shown in the following example: + +\begin{verbatim} + PyObject *res; + char *buf = (char *) malloc(BUFSIZ); /* for I/O */ + + if (buf == NULL) + return PyErr_NoMemory(); + ...Do some I/O operation involving buf... + res = PyString_FromString(buf); + free(buf); /* malloc'ed */ + return res; +\end{verbatim} + +In this example, the memory request for the I/O buffer is handled by +the C library allocator. The Python memory manager is involved only +in the allocation of the string object returned as a result. + +In most situations, however, it is recommended to allocate memory from +the Python heap specifically because the latter is under control of +the Python memory manager. For example, this is required when the +interpreter is extended with new object types written in C. Another +reason for using the Python heap is the desire to \emph{inform} the +Python memory manager about the memory needs of the extension module. +Even when the requested memory is used exclusively for internal, +highly-specific purposes, delegating all memory requests to the Python +memory manager causes the interpreter to have a more accurate image of +its memory footprint as a whole. Consequently, under certain +circumstances, the Python memory manager may or may not trigger +appropriate actions, like garbage collection, memory compaction or +other preventive procedures. Note that by using the C library +allocator as shown in the previous example, the allocated memory for +the I/O buffer escapes completely the Python memory manager. + + +\section{Memory Interface \label{memoryInterface}} + +The following function sets, modeled after the ANSI C standard, are +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 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()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyMem_Free}{void *p} + Frees the memory block pointed to by \var{p}, which must have been + returned by a previous call to \cfunction{PyMem_Malloc()} or + \cfunction{PyMem_Realloc()}. Otherwise, or if + \cfunction{PyMem_Free(p)} has been called before, undefined + behaviour occurs. If \var{p} is \NULL, no operation is performed. +\end{cfuncdesc} + +The following type-oriented macros are provided for convenience. Note +that \var{TYPE} refers to any C type. + +\begin{cfuncdesc}{\var{TYPE}*}{PyMem_New}{TYPE, size_t n} + 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} + Same as \cfunction{PyMem_Realloc()}, but the memory block is resized + to \code{(\var{n} * sizeof(\var{TYPE}))} bytes. Returns a pointer + cast to \ctype{\var{TYPE}*}. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyMem_Del}{void *p} + Same as \cfunction{PyMem_Free()}. +\end{cfuncdesc} + +In addition, the following macro sets are provided for calling the +Python memory allocator directly, without involving the C API functions +listed above. However, note that their use does not preserve binary +compatibility accross Python versions and is therefore deprecated in +extension modules. + +\cfunction{PyMem_MALLOC()}, \cfunction{PyMem_REALLOC()}, \cfunction{PyMem_FREE()}. + +\cfunction{PyMem_NEW()}, \cfunction{PyMem_RESIZE()}, \cfunction{PyMem_DEL()}. + + +\section{Examples \label{memoryExamples}} + +Here is the example from section \ref{memoryOverview}, rewritten so +that the I/O buffer is allocated from the Python heap by using the +first function set: + +\begin{verbatim} + PyObject *res; + char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */ + + if (buf == NULL) + return PyErr_NoMemory(); + /* ...Do some I/O operation involving buf... */ + res = PyString_FromString(buf); + PyMem_Free(buf); /* allocated with PyMem_Malloc */ + return res; +\end{verbatim} + +The same code using the type-oriented function set: + +\begin{verbatim} + PyObject *res; + char *buf = PyMem_New(char, BUFSIZ); /* for I/O */ + + if (buf == NULL) + return PyErr_NoMemory(); + /* ...Do some I/O operation involving buf... */ + res = PyString_FromString(buf); + PyMem_Del(buf); /* allocated with PyMem_New */ + return res; +\end{verbatim} + +Note that in the two examples above, the buffer is always +manipulated via functions belonging to the same set. Indeed, it +is required to use the same memory API family for a given +memory block, so that the risk of mixing different allocators is +reduced to a minimum. The following code sequence contains two errors, +one of which is labeled as \emph{fatal} because it mixes two different +allocators operating on different heaps. + +\begin{verbatim} +char *buf1 = PyMem_New(char, BUFSIZ); +char *buf2 = (char *) malloc(BUFSIZ); +char *buf3 = (char *) PyMem_Malloc(BUFSIZ); +... +PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */ +free(buf2); /* Right -- allocated via malloc() */ +free(buf1); /* Fatal -- should be PyMem_Del() */ +\end{verbatim} + +In addition to the functions aimed at handling raw memory blocks from +the Python heap, objects in Python are allocated and released with +\cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and +\cfunction{PyObject_Del()}, or with their corresponding macros +\cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()} and +\cfunction{PyObject_DEL()}. + +These will be explained in the next chapter on defining and +implementing new object types in C. diff --git a/Doc/api/newtypes.tex b/Doc/api/newtypes.tex new file mode 100644 index 0000000..870b9d6 --- /dev/null +++ b/Doc/api/newtypes.tex @@ -0,0 +1,578 @@ +\chapter{Defining New Object Types \label{newTypes}} + + +\section{Allocating Objects on the Heap + \label{allocating-objects}} + +\begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, int size} +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op} +\end{cfuncdesc} + +\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} + +\begin{cfuncdesc}{PyObject*}{Py_InitModule}{char *name, + PyMethodDef *methods} + Create a new module object based on a name and table of functions, + returning the new module object. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{Py_InitModule3}{char *name, + PyMethodDef *methods, + char *doc} + Create a new module object based on a name and table of functions, + returning the new module object. If \var{doc} is non-\NULL, it will + be used to define the docstring for the module. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{Py_InitModule4}{char *name, + PyMethodDef *methods, + char *doc, PyObject *self, + int apiver} + Create a new module object based on a name and table of functions, + returning the new module object. If \var{doc} is non-\NULL, it will + be used to define the docstring for the module. If \var{self} is + non-\NULL, it will passed to the functions of the module as their + (otherwise \NULL) first parameter. (This was added as an + experimental feature, and there are no known uses in the current + version of Python.) For \var{apiver}, the only value which should + be passed is defined by the constant \constant{PYTHON_API_VERSION}. + + \note{Most uses of this function should probably be using + the \cfunction{Py_InitModule3()} instead; only use this if you are + sure you need it.} +\end{cfuncdesc} + +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} + + +\section{Common Object Structures \label{common-structs}} + +PyObject, PyVarObject + +PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD + +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. +\end{ctypedesc} + +\begin{ctypedesc}{PyMethodDef} + Structure used to describe a method of an extension type. This + structure has four fields: + + \begin{tableiii}{l|l|l}{member}{Field}{C Type}{Meaning} + \lineiii{ml_name}{char *}{name of the method} + \lineiii{ml_meth}{PyCFunction}{pointer to the C implementation} + \lineiii{ml_flags}{int}{flag bits indicating how the call should be + constructed} + \lineiii{ml_doc}{char *}{points to the contents of the docstring} + \end{tableiii} +\end{ctypedesc} + +The \member{ml_meth} is a C function pointer. The functions may be of +different types, but they always return \ctype{PyObject*}. If the +function is not of the \ctype{PyCFunction}, the compiler will require +a cast in the method table. Even though \ctype{PyCFunction} defines +the first parameter as \ctype{PyObject*}, it is common that the method +implementation uses a the specific C type of the \var{self} object. + +The flags can have the following values. Only \constant{METH_VARARGS} +and \constant{METH_KEYWORDS} can be combined; the others can't. + +\begin{datadesc}{METH_VARARGS} + This is the typical calling convention, where the methods have the + type \ctype{PyMethodDef}. The function expects two + \ctype{PyObject*}. The first one is the \var{self} object for + methods; for module functions, it has the value given to + \cfunction{Py_InitModule4()} (or \NULL{} if + \cfunction{Py_InitModule()} was used). The second parameter + (often called \var{args}) is a tuple object representing all + arguments. This parameter is typically processed using + \cfunction{PyArg_ParseTuple()}. +\end{datadesc} + +\begin{datadesc}{METH_KEYWORDS} + Methods with these flags must be of type + \ctype{PyCFunctionWithKeywords}. The function expects three + parameters: \var{self}, \var{args}, and a dictionary of all the + keyword arguments. The flag is typically combined with + \constant{METH_VARARGS}, and the parameters are typically processed + using \cfunction{PyArg_ParseTupleAndKeywords()}. +\end{datadesc} + +\begin{datadesc}{METH_NOARGS} + Methods without parameters don't need to check whether arguments are + given if they are listed with the \constant{METH_NOARGS} flag. They + need to be of type \ctype{PyNoArgsFunction}: they expect a single + single \ctype{PyObject*} as a parameter. When used with object + methods, this parameter is typically named \code{self} and will hold + a reference to the object instance. +\end{datadesc} + +\begin{datadesc}{METH_O} + Methods with a single object argument can be listed with the + \constant{METH_O} flag, instead of invoking + \cfunction{PyArg_ParseTuple()} with a \code{"O"} argument. They have + the type \ctype{PyCFunction}, with the \var{self} parameter, and a + \ctype{PyObject*} parameter representing the single argument. +\end{datadesc} + +\begin{datadesc}{METH_OLDARGS} + This calling convention is deprecated. The method must be of type + \ctype{PyCFunction}. The second argument is \NULL{} if no arguments + are given, a single object if exactly one argument is given, and a + tuple of objects if more than one argument is given. There is no + way for a function using this convention to distinguish between a + call with multiple arguments and a call with a tuple as the only + argument. +\end{datadesc} + +\begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef table[], + PyObject *ob, char *name} + Return a bound method object for an extension type implemented in + C. This function also handles the special attribute + \member{__methods__}, returning a list of all the method names + defined in \var{table}. +\end{cfuncdesc} + + +\section{Mapping Object Structures \label{mapping-structs}} + +\begin{ctypedesc}{PyMappingMethods} + Structure used to hold pointers to the functions used to implement + the mapping protocol for an extension type. +\end{ctypedesc} + + +\section{Number Object Structures \label{number-structs}} + +\begin{ctypedesc}{PyNumberMethods} + Structure used to hold pointers to the functions an extension type + uses to implement the number protocol. +\end{ctypedesc} + + +\section{Sequence Object Structures \label{sequence-structs}} + +\begin{ctypedesc}{PySequenceMethods} + Structure used to hold pointers to the functions which an object + uses to implement the sequence protocol. +\end{ctypedesc} + + +\section{Buffer Object Structures \label{buffer-structs}} +\sectionauthor{Greg J. Stein}{greg@lyra.org} + +The buffer interface exports a model where an object can expose its +internal data as a set of chunks of data, where each chunk is +specified as a pointer/length pair. These chunks are called +\dfn{segments} and are presumed to be non-contiguous in memory. + +If an object does not export the buffer interface, then its +\member{tp_as_buffer} member in the \ctype{PyTypeObject} structure +should be \NULL. Otherwise, the \member{tp_as_buffer} will point to +a \ctype{PyBufferProcs} structure. + +\note{It is very important that your \ctype{PyTypeObject} structure +uses \constant{Py_TPFLAGS_DEFAULT} for the value of the +\member{tp_flags} member rather than \code{0}. This tells the Python +runtime that your \ctype{PyBufferProcs} structure contains the +\member{bf_getcharbuffer} slot. Older versions of Python did not have +this member, so a new Python interpreter using an old extension needs +to be able to test for its presence before using it.} + +\begin{ctypedesc}{PyBufferProcs} + Structure used to hold the function pointers which define an + implementation of the buffer protocol. + + The first slot is \member{bf_getreadbuffer}, of type + \ctype{getreadbufferproc}. If this slot is \NULL, then the object + does not support reading from the internal data. This is + non-sensical, so implementors should fill this in, but callers + should test that the slot contains a non-\NULL{} value. + + The next slot is \member{bf_getwritebuffer} having type + \ctype{getwritebufferproc}. This slot may be \NULL{} if the object + does not allow writing into its returned buffers. + + The third slot is \member{bf_getsegcount}, with type + \ctype{getsegcountproc}. This slot must not be \NULL{} and is used + to inform the caller how many segments the object contains. Simple + objects such as \ctype{PyString_Type} and \ctype{PyBuffer_Type} + objects contain a single segment. + + The last slot is \member{bf_getcharbuffer}, of type + \ctype{getcharbufferproc}. This slot will only be present if the + \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the + \member{tp_flags} field of the object's \ctype{PyTypeObject}. + Before using this slot, the caller should test whether it is present + by using the + \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()} + function. If present, it may be \NULL, indicating that the object's + contents cannot be used as \emph{8-bit characters}. + The slot function may also raise an error if the object's contents + cannot be interpreted as 8-bit characters. For example, if the + object is an array which is configured to hold floating point + values, an exception may be raised if a caller attempts to use + \member{bf_getcharbuffer} to fetch a sequence of 8-bit characters. + This notion of exporting the internal buffers as ``text'' is used to + distinguish between objects that are binary in nature, and those + which have character-based content. + + \note{The current policy seems to state that these characters + may be multi-byte characters. This implies that a buffer size of + \var{N} does not mean there are \var{N} characters present.} +\end{ctypedesc} + +\begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER} + Flag bit set in the type structure to indicate that the + \member{bf_getcharbuffer} slot is known. This being set does not + indicate that the object supports the buffer interface or that the + \member{bf_getcharbuffer} slot is non-\NULL. +\end{datadesc} + +\begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc) + (PyObject *self, int segment, void **ptrptr)} + Return a pointer to a readable segment of the buffer. This function + is allowed to raise an exception, in which case it must return + \code{-1}. The \var{segment} which is passed must be zero or + positive, and strictly less than the number of segments returned by + the \member{bf_getsegcount} slot function. On success, it returns + the length of the buffer memory, and sets \code{*\var{ptrptr}} to a + pointer to that memory. +\end{ctypedesc} + +\begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc) + (PyObject *self, int segment, void **ptrptr)} + Return a pointer to a writable memory buffer in + \code{*\var{ptrptr}}, and the length of that segment as the function + return value. The memory buffer must correspond to buffer segment + \var{segment}. Must return \code{-1} and set an exception on + error. \exception{TypeError} should be raised if the object only + supports read-only buffers, and \exception{SystemError} should be + raised when \var{segment} specifies a segment that doesn't exist. +% Why doesn't it raise ValueError for this one? +% GJS: because you shouldn't be calling it with an invalid +% segment. That indicates a blatant programming error in the C +% code. +\end{ctypedesc} + +\begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc) + (PyObject *self, int *lenp)} + Return the number of memory segments which comprise the buffer. If + \var{lenp} is not \NULL, the implementation must report the sum of + the sizes (in bytes) of all segments in \code{*\var{lenp}}. + The function cannot fail. +\end{ctypedesc} + +\begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc) + (PyObject *self, int segment, const char **ptrptr)} +\end{ctypedesc} + + +\section{Supporting the Iterator Protocol + \label{supporting-iteration}} + + +\section{Supporting Cyclic Garbarge Collection + \label{supporting-cycle-detection}} + +Python's support for detecting and collecting garbage which involves +circular references requires support from object types which are +``containers'' for other objects which may also be containers. Types +which do not store references to other objects, or which only store +references to atomic types (such as numbers or strings), do not need +to provide any explicit support for garbage collection. + +To create a container type, the \member{tp_flags} field of the type +object must include the \constant{Py_TPFLAGS_HAVE_GC} and provide an +implementation of the \member{tp_traverse} handler. If instances of the +type are mutable, a \member{tp_clear} implementation must also be +provided. + +\begin{datadesc}{Py_TPFLAGS_HAVE_GC} + Objects with a type with this flag set must conform with the rules + documented here. For convenience these objects will be referred to + as container objects. +\end{datadesc} + +Constructors for container types must conform to two rules: + +\begin{enumerate} +\item The memory for the object must be allocated using + \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}. + +\item Once all the fields which may contain references to other + containers are initialized, it must call + \cfunction{PyObject_GC_Track()}. +\end{enumerate} + +\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_New}{TYPE, PyTypeObject *type} + Analogous to \cfunction{PyObject_New()} but for container objects with + the \constant{Py_TPFLAGS_HAVE_GC} flag set. +\end{cfuncdesc} + +\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_NewVar}{TYPE, PyTypeObject *type, + int size} + Analogous to \cfunction{PyObject_NewVar()} but for container objects + with the \constant{Py_TPFLAGS_HAVE_GC} flag set. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyVarObject *}{PyObject_GC_Resize}{PyVarObject *op, int} + Resize an object allocated by \cfunction{PyObject_NewVar()}. Returns + the resized object or \NULL{} on failure. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyObject_GC_Track}{PyObject *op} + Adds the object \var{op} to the set of container objects tracked by + the collector. The collector can run at unexpected times so objects + must be valid while being tracked. This should be called once all + the fields followed by the \member{tp_traverse} handler become valid, + usually near the end of the constructor. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{_PyObject_GC_TRACK}{PyObject *op} + A macro version of \cfunction{PyObject_GC_Track()}. It should not be + used for extension modules. +\end{cfuncdesc} + +Similarly, the deallocator for the object must conform to a similar +pair of rules: + +\begin{enumerate} +\item Before fields which refer to other containers are invalidated, + \cfunction{PyObject_GC_UnTrack()} must be called. + +\item The object's memory must be deallocated using + \cfunction{PyObject_GC_Del()}. +\end{enumerate} + +\begin{cfuncdesc}{void}{PyObject_GC_Del}{PyObject *op} + Releases memory allocated to an object using + \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_NewVar()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyObject_GC_UnTrack}{PyObject *op} + Remove the object \var{op} from the set of container objects tracked + by the collector. Note that \cfunction{PyObject_GC_Track()} can be + called again on this object to add it back to the set of tracked + objects. The deallocator (\member{tp_dealloc} handler) should call + this for the object before any of the fields used by the + \member{tp_traverse} handler become invalid. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{_PyObject_GC_UNTRACK}{PyObject *op} + A macro version of \cfunction{PyObject_GC_UnTrack()}. It should not be + used for extension modules. +\end{cfuncdesc} + +The \member{tp_traverse} handler accepts a function parameter of this +type: + +\begin{ctypedesc}[visitproc]{int (*visitproc)(PyObject *object, void *arg)} + Type of the visitor function passed to the \member{tp_traverse} + handler. The function should be called with an object to traverse + as \var{object} and the third parameter to the \member{tp_traverse} + handler as \var{arg}. +\end{ctypedesc} + +The \member{tp_traverse} handler must have the following type: + +\begin{ctypedesc}[traverseproc]{int (*traverseproc)(PyObject *self, + visitproc visit, void *arg)} + Traversal function for a container object. Implementations must + call the \var{visit} function for each object directly contained by + \var{self}, with the parameters to \var{visit} being the contained + object and the \var{arg} value passed to the handler. If + \var{visit} returns a non-zero value then an error has occurred and + that value should be returned immediately. +\end{ctypedesc} + +The \member{tp_clear} handler must be of the \ctype{inquiry} type, or +\NULL{} if the object is immutable. + +\begin{ctypedesc}[inquiry]{int (*inquiry)(PyObject *self)} + 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 (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. +\end{ctypedesc} + + +\subsection{Example Cycle Collector Support + \label{example-cycle-support}} + +This example shows only enough of the implementation of an extension +type to show how the garbage collector support needs to be added. It +shows the definition of the object structure, the +\member{tp_traverse}, \member{tp_clear} and \member{tp_dealloc} +implementations, the type structure, and a constructor --- the module +initialization needed to export the constructor to Python is not shown +as there are no special considerations there for the collector. To +make this interesting, assume that the module exposes ways for the +\member{container} field of the object to be modified. Note that +since no checks are made on the type of the object used to initialize +\member{container}, we have to assume that it may be a container. + +\begin{verbatim} +#include "Python.h" + +typedef struct { + PyObject_HEAD + PyObject *container; +} MyObject; + +static int +my_traverse(MyObject *self, visitproc visit, void *arg) +{ + if (self->container != NULL) + return visit(self->container, arg); + else + return 0; +} + +static int +my_clear(MyObject *self) +{ + Py_XDECREF(self->container); + self->container = NULL; + + return 0; +} + +static void +my_dealloc(MyObject *self) +{ + PyObject_GC_UnTrack((PyObject *) self); + Py_XDECREF(self->container); + PyObject_GC_Del(self); +} +\end{verbatim} + +\begin{verbatim} +statichere PyTypeObject +MyObject_Type = { + PyObject_HEAD_INIT(NULL) + 0, + "MyObject", + sizeof(MyObject), + 0, + (destructor)my_dealloc, /* tp_dealloc */ + 0, /* tp_print */ + 0, /* tp_getattr */ + 0, /* tp_setattr */ + 0, /* tp_compare */ + 0, /* tp_repr */ + 0, /* tp_as_number */ + 0, /* tp_as_sequence */ + 0, /* tp_as_mapping */ + 0, /* tp_hash */ + 0, /* tp_call */ + 0, /* tp_str */ + 0, /* tp_getattro */ + 0, /* tp_setattro */ + 0, /* tp_as_buffer */ + Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, + 0, /* tp_doc */ + (traverseproc)my_traverse, /* tp_traverse */ + (inquiry)my_clear, /* tp_clear */ + 0, /* tp_richcompare */ + 0, /* tp_weaklistoffset */ +}; + +/* This constructor should be made accessible from Python. */ +static PyObject * +new_object(PyObject *unused, PyObject *args) +{ + PyObject *container = NULL; + MyObject *result = NULL; + + if (PyArg_ParseTuple(args, "|O:new_object", &container)) { + result = PyObject_GC_New(MyObject, &MyObject_Type); + if (result != NULL) { + result->container = container; + PyObject_GC_Track(result); + } + } + return (PyObject *) result; +} +\end{verbatim} diff --git a/Doc/api/refcounting.tex b/Doc/api/refcounting.tex new file mode 100644 index 0000000..03530f0 --- /dev/null +++ b/Doc/api/refcounting.tex @@ -0,0 +1,48 @@ +\chapter{Reference Counting \label{countingRefs}} + + +The macros in this section are used for managing reference counts +of Python objects. + + +\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o} + Increment the reference count for object \var{o}. The object must + not be \NULL; if you aren't sure that it isn't \NULL, use + \cfunction{Py_XINCREF()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o} + Increment the reference count for object \var{o}. The object may be + \NULL, in which case the macro has no effect. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o} + Decrement the reference count for object \var{o}. The object must + not be \NULL; if you aren't sure that it isn't \NULL, use + \cfunction{Py_XDECREF()}. If the reference count reaches zero, the + object's type's deallocation function (which must not be \NULL) is + invoked. + + \warning{The deallocation function can cause arbitrary Python code + to be invoked (e.g. when a class instance with a \method{__del__()} + method is deallocated). While exceptions in such code are not + propagated, the executed code has free access to all Python global + variables. This means that any object that is reachable from a + global variable should be in a consistent state before + \cfunction{Py_DECREF()} is invoked. For example, code to delete an + object from a list should copy a reference to the deleted object in + a temporary variable, update the list data structure, and then call + \cfunction{Py_DECREF()} for the temporary variable.} +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o} + Decrement the reference count for object \var{o}. The object may be + \NULL, in which case the macro has no effect; otherwise the effect + is the same as for \cfunction{Py_DECREF()}, and the same warning + applies. +\end{cfuncdesc} + +The following functions or macros are only for use within the +interpreter core: \cfunction{_Py_Dealloc()}, +\cfunction{_Py_ForgetReference()}, \cfunction{_Py_NewReference()}, as +well as the global variable \cdata{_Py_RefTotal}. diff --git a/Doc/api/utilities.tex b/Doc/api/utilities.tex new file mode 100644 index 0000000..5820524 --- /dev/null +++ b/Doc/api/utilities.tex @@ -0,0 +1,320 @@ +\chapter{Utilities \label{utilities}} + +The functions in this chapter perform various utility tasks, ranging +from helping C code be more portable across platforms, using Python +modules from C, and parsing function arguments and constructing Python +values from C values. + + +\section{Operating System Utilities \label{os}} + +\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename} + Return true (nonzero) if the standard I/O file \var{fp} with name + \var{filename} is deemed interactive. This is the case for files + for which \samp{isatty(fileno(\var{fp}))} is true. If the global + flag \cdata{Py_InteractiveFlag} is true, this function also returns + true if the \var{filename} pointer is \NULL{} or if the name is + equal to one of the strings \code{'<stdin>'} or \code{'???'}. +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename} + Return the time of last modification of the file \var{filename}. + The result is encoded in the same way as the timestamp returned by + the standard C library function \cfunction{time()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyOS_AfterFork}{} + Function to update some internal state after a process fork; this + should be called in the new process if the Python interpreter will + continue to be used. If a new executable is loaded into the new + process, this function does not need to be called. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyOS_CheckStack}{} + Return true when the interpreter runs out of stack space. This is a + reliable check, but is only available when \constant{USE_STACKCHECK} + is defined (currently on Windows using the Microsoft Visual \Cpp{} + compiler and on the Macintosh). \constant{USE_CHECKSTACK} will be + defined automatically; you should never change the definition in + your own code. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_getsig}{int i} + Return the current signal handler for signal \var{i}. This is a + thin wrapper around either \cfunction{sigaction()} or + \cfunction{signal()}. Do not call those functions directly! + \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void + (*)(int)}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_setsig}{int i, PyOS_sighandler_t h} + Set the signal handler for signal \var{i} to be \var{h}; return the + old signal handler. This is a thin wrapper around either + \cfunction{sigaction()} or \cfunction{signal()}. Do not call those + functions directly! \ctype{PyOS_sighandler_t} is a typedef alias + for \ctype{void (*)(int)}. +\end{cfuncdesc} + + +\section{Process Control \label{processControl}} + +\begin{cfuncdesc}{void}{Py_FatalError}{char *message} + Print a fatal error message and kill the process. No cleanup is + performed. This function should only be invoked when a condition is + detected that would make it dangerous to continue using the Python + interpreter; e.g., when the object administration appears to be + corrupted. On \UNIX, the standard C library function + \cfunction{abort()}\ttindex{abort()} is called which will attempt to + produce a \file{core} file. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{Py_Exit}{int status} + Exit the current process. This calls + \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and then calls the + standard C library function + \code{exit(\var{status})}\ttindex{exit()}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()} + Register a cleanup function to be called by + \cfunction{Py_Finalize()}\ttindex{Py_Finalize()}. The cleanup + function will be called with no arguments and should return no + value. At most 32 \index{cleanup functions}cleanup functions can be + registered. When the registration is successful, + \cfunction{Py_AtExit()} returns \code{0}; on failure, it returns + \code{-1}. The cleanup function registered last is called first. + Each cleanup function will be called at most once. Since Python's + internal finallization will have completed before the cleanup + function, no Python APIs should be called by \var{func}. +\end{cfuncdesc} + + +\section{Importing Modules \label{importing}} + +\begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{char *name} + 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 (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 + case. (Unfortunately, this has an additional side effect when + \var{name} in fact specifies a subpackage instead of a submodule: + the submodules specified in the package's \code{__all__} variable + are \index{package variable!\code{__all__}} + \withsubitem{(package variable)}{\ttindex{__all__}}loaded.) Return + a new reference to the imported module, or \NULL{} with an exception + set on failure (the module may still be created in this case --- + examine \code{sys.modules} to find out). + \withsubitem{(in module sys)}{\ttindex{modules}} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, + PyObject *globals, PyObject *locals, PyObject *fromlist} + Import a module. This is best described by referring to the + built-in Python function + \function{__import__()}\bifuncindex{__import__}, as the standard + \function{__import__()} function calls this function directly. + + The return value is a new reference to the imported module or + top-level package, or \NULL{} with an exception set on failure (the + module may still be created in this case). Like for + \function{__import__()}, the return value when a submodule of a + package was requested is normally the top-level package, unless a + non-empty \var{fromlist} was given. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyImport_Import}{PyObject *name} + This is a higher-level interface that calls the current ``import + hook function''. It invokes the \function{__import__()} function + from the \code{__builtins__} of the current globals. This means + that the import is done using whatever import hooks are installed in + the current environment, e.g. by \module{rexec}\refstmodindex{rexec} + or \module{ihooks}\refstmodindex{ihooks}. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyImport_ReloadModule}{PyObject *m} + Reload a module. This is best described by referring to the + built-in Python function \function{reload()}\bifuncindex{reload}, as + the standard \function{reload()} function calls this function + directly. Return a new reference to the reloaded module, or \NULL{} + with an exception set on failure (the module still exists in this + case). +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyImport_AddModule}{char *name} + Return the module object corresponding to a module name. The + \var{name} argument may be of the form \code{package.module}). + First check the modules dictionary if there's one there, and if not, + create a new one and insert in in the modules dictionary. + \note{This function does not load or import the module; if the + module wasn't already loaded, you will get an empty module object. + Use \cfunction{PyImport_ImportModule()} or one of its variants to + import a module. Return \NULL{} with an exception set on failure.} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyImport_ExecCodeModule}{char *name, PyObject *co} + Given a module name (possibly of the form \code{package.module}) and + a code object read from a Python bytecode file or obtained from the + built-in function \function{compile()}\bifuncindex{compile}, load + the module. Return a new reference to the module object, or \NULL{} + with an exception set if an error occurred (the module may still be + created in this case). (This function would reload the module if it + was already imported.) +\end{cfuncdesc} + +\begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{} + Return the magic number for Python bytecode files + (a.k.a. \file{.pyc} and \file{.pyo} files). The magic number should + be present in the first four bytes of the bytecode file, in + little-endian byte order. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyImport_GetModuleDict}{} + Return the dictionary used for the module administration + (a.k.a.\ \code{sys.modules}). Note that this is a per-interpreter + variable. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{_PyImport_Init}{} + Initialize the import mechanism. For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyImport_Cleanup}{} + Empty the module table. For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{_PyImport_Fini}{} + Finalize the import mechanism. For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *} + For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *} + For internal use only. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name} + Load a frozen module named \var{name}. Return \code{1} for success, + \code{0} if the module is not found, and \code{-1} with an exception + set if the initialization failed. To access the imported module on + a successful load, use \cfunction{PyImport_ImportModule()}. (Note + the misnomer --- this function would reload the module if it was + already imported.) +\end{cfuncdesc} + +\begin{ctypedesc}[_frozen]{struct _frozen} + This is the structure type definition for frozen module descriptors, + as generated by the \program{freeze}\index{freeze utility} utility + (see \file{Tools/freeze/} in the Python source distribution). Its + definition, found in \file{Include/import.h}, is: + +\begin{verbatim} +struct _frozen { + char *name; + unsigned char *code; + int size; +}; +\end{verbatim} +\end{ctypedesc} + +\begin{cvardesc}{struct _frozen*}{PyImport_FrozenModules} + This pointer is initialized to point to an array of \ctype{struct + _frozen} records, terminated by one whose members are all \NULL{} or + zero. When a frozen module is imported, it is searched in this + table. Third-party code could play tricks with this to provide a + dynamically created collection of frozen modules. +\end{cvardesc} + +\begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name, + void (*initfunc)(void)} + Add a single module to the existing table of built-in modules. This + is a convenience wrapper around + \cfunction{PyImport_ExtendInittab()}, returning \code{-1} if the + table could not be extended. The new module can be imported by the + name \var{name}, and uses the function \var{initfunc} as the + initialization function called on the first attempted import. This + should be called before \cfunction{Py_Initialize()}. +\end{cfuncdesc} + +\begin{ctypedesc}[_inittab]{struct _inittab} + Structure describing a single entry in the list of built-in + modules. Each of these structures gives the name and initialization + function for a module built into the interpreter. Programs which + embed Python may use an array of these structures in conjunction + with \cfunction{PyImport_ExtendInittab()} to provide additional + built-in modules. The structure is defined in + \file{Include/import.h} as: + +\begin{verbatim} +struct _inittab { + char *name; + void (*initfunc)(void); +}; +\end{verbatim} +\end{ctypedesc} + +\begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab} + Add a collection of modules to the table of built-in modules. The + \var{newtab} array must end with a sentinel entry which contains + \NULL{} for the \member{name} field; failure to provide the sentinel + value can result in a memory fault. Returns \code{0} on success or + \code{-1} if insufficient memory could be allocated to extend the + internal table. In the event of failure, no modules are added to + the internal table. This should be called before + \cfunction{Py_Initialize()}. +\end{cfuncdesc} + + +\section{Parsing arguments and building values + \label{arg-parsing}} + +These functions are useful when creating your own extensions functions +and methods. Additional information and examples are available in +\citetitle[../ext/ext.html]{Extending and Embedding the Python +Interpreter}. + +\begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format, + \moreargs} + Parse the parameters of a function that takes only positional + parameters into local variables. Returns true on success; on + failure, it returns false and raises the appropriate exception. 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. Returns true on success; + on failure, it returns false and raises the appropriate exception. + 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 use in parameter parsing in new code, and most code + in the standard interpreter has been modified to no longer use this + for that purpose. It does remain a convenient way to decompose + other tuples, however, and may continue to be used for that + purpose. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{Py_BuildValue}{char *format, + \moreargs} + Create a new value based on a format string similar to those + accepted by the \cfunction{PyArg_Parse*()} family of functions and a + sequence of values. Returns the value or \NULL{} in the case of an + error; an exception will be raised if \NULL{} is returned. For more + information on the format string and additional parameters, see + \citetitle[../ext/buildValue.html]{Extending and Embedding the + Python Interpreter}. +\end{cfuncdesc} diff --git a/Doc/api/veryhigh.tex b/Doc/api/veryhigh.tex new file mode 100644 index 0000000..e7cb094 --- /dev/null +++ b/Doc/api/veryhigh.tex @@ -0,0 +1,141 @@ +\chapter{The Very High Level Layer \label{veryhigh}} + + +The functions in this chapter will let you execute Python source code +given in a file or a buffer, but they will not let you interact in a +more detailed way with the interpreter. + +Several of these functions accept a start symbol from the grammar as a +parameter. The available start symbols are \constant{Py_eval_input}, +\constant{Py_file_input}, and \constant{Py_single_input}. These are +described following the functions which accept them as parameters. + +Note also that several of these functions take \ctype{FILE*} +parameters. On particular issue which needs to be handled carefully +is that the \ctype{FILE} structure for different C libraries can be +different and incompatible. Under Windows (at least), it is possible +for dynamically linked extensions to actually use different libraries, +so care should be taken that \ctype{FILE*} parameters are only passed +to these functions if it is certain that they were created by the same +library that the Python runtime is using. + + +\begin{cfuncdesc}{int}{Py_Main}{int argc, char **argv} + The main program for the standard interpreter. This is made + available for programs which embed Python. The \var{argc} and + \var{argv} parameters should be prepared exactly as those which are + passed to a C program's \cfunction{main()} function. It is + important to note that the argument list may be modified (but the + contents of the strings pointed to by the argument list are not). + The return value will be the integer passed to the + \function{sys.exit()} function, \code{1} if the interpreter exits + due to an exception, or \code{2} if the parameter list does not + represent a valid Python command line. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename} + If \var{fp} refers to a file associated with an interactive device + (console or terminal input or \UNIX{} pseudo-terminal), return the + value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the + result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is + \NULL, this function uses \code{"???"} as the filename. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command} + Executes the Python source code from \var{command} in the + \module{__main__} module. If \module{__main__} does not already + exist, it is created. Returns \code{0} on success or \code{-1} if + an exception was raised. If there was an error, there is no way to + get the exception information. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename} + Similar to \cfunction{PyRun_SimpleString()}, but the Python source + code is read from \var{fp} instead of an in-memory string. + \var{filename} should be the name of the file. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename} + Read and execute a single statement from a file associated with an + interactive device. If \var{filename} is \NULL, \code{"???"} is + used instead. The user will be prompted using \code{sys.ps1} and + \code{sys.ps2}. Returns \code{0} when the input was executed + successfully, \code{-1} if there was an exception, or an error code + from the \file{errcode.h} include file distributed as part of Python + if there was a parse error. (Note that \file{errcode.h} is not + included by \file{Python.h}, so must be included specifically if + needed.) +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename} + Read and execute statements from a file associated with an + interactive device until \EOF{} is reached. If \var{filename} is + \NULL, \code{"???"} is used instead. The user will be prompted + using \code{sys.ps1} and \code{sys.ps2}. Returns \code{0} at \EOF. +\end{cfuncdesc} + +\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str, + int start} + Parse Python source code from \var{str} using the start token + \var{start}. The result can be used to create a code object which + can be evaluated efficiently. This is useful if a code fragment + must be evaluated many times. +\end{cfuncdesc} + +\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp, + char *filename, int start} + Similar to \cfunction{PyParser_SimpleParseString()}, but the Python + source code is read from \var{fp} instead of an in-memory string. + \var{filename} should be the name of the file. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start, + PyObject *globals, + PyObject *locals} + Execute Python source code from \var{str} in the context specified + by the dictionaries \var{globals} and \var{locals}. The parameter + \var{start} specifies the start token that should be used to parse + the source code. + + Returns the result of executing the code as a Python object, or + \NULL{} if an exception was raised. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename, + int start, PyObject *globals, + PyObject *locals} + Similar to \cfunction{PyRun_String()}, but the Python source code is + read from \var{fp} instead of an in-memory string. + \var{filename} should be the name of the file. +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename, + int start} + Parse and compile the Python source code in \var{str}, returning the + resulting code object. The start token is given by \var{start}; + this can be used to constrain the code which can be compiled and should + be \constant{Py_eval_input}, \constant{Py_file_input}, or + \constant{Py_single_input}. The filename specified by + \var{filename} is used to construct the code object and may appear + in tracebacks or \exception{SyntaxError} exception messages. This + returns \NULL{} if the code cannot be parsed or compiled. +\end{cfuncdesc} + +\begin{cvardesc}{int}{Py_eval_input} + The start symbol from the Python grammar for isolated expressions; + for use with + \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. +\end{cvardesc} + +\begin{cvardesc}{int}{Py_file_input} + The start symbol from the Python grammar for sequences of statements + as read from a file or other source; for use with + \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. This is + the symbol to use when compiling arbitrarily long Python source code. +\end{cvardesc} + +\begin{cvardesc}{int}{Py_single_input} + The start symbol from the Python grammar for a single statement; for + use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. + This is the symbol used for the interactive interpreter loop. +\end{cvardesc} |