diff options
Diffstat (limited to 'Doc/api/abstract.tex')
| -rw-r--r-- | Doc/api/abstract.tex | 842 |
1 files changed, 842 insertions, 0 deletions
diff --git a/Doc/api/abstract.tex b/Doc/api/abstract.tex new file mode 100644 index 0000000000..8d271df571 --- /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} |