diff options
Diffstat (limited to 'Doc/api/abstract.tex')
| -rw-r--r-- | Doc/api/abstract.tex | 1037 |
1 files changed, 0 insertions, 1037 deletions
diff --git a/Doc/api/abstract.tex b/Doc/api/abstract.tex deleted file mode 100644 index c5b53d7..0000000 --- a/Doc/api/abstract.tex +++ /dev/null @@ -1,1037 +0,0 @@ -\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. - -It is not possible to use these functions on objects that are not properly -initialized, such as a list object that has been created by -\cfunction{PyList_New()}, but whose items have not been set to some -non-\code{NULL} value yet. - -\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, const 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, - const 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, - const 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, const 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}{PyObject*}{PyObject_RichCompare}{PyObject *o1, - PyObject *o2, int opid} - Compare the values of \var{o1} and \var{o2} using the operation - specified by \var{opid}, which must be one of - \constant{Py_LT}, - \constant{Py_LE}, - \constant{Py_EQ}, - \constant{Py_NE}, - \constant{Py_GT}, or - \constant{Py_GE}, corresponding to - \code{<}, - \code{<=}, - \code{==}, - \code{!=}, - \code{>}, or - \code{>=} respectively. This is the equivalent of the Python expression - \samp{\var{o1} op \var{o2}}, where \code{op} is the operator - corresponding to \var{opid}. Returns the value of the comparison on - success, or \NULL{} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyObject_RichCompareBool}{PyObject *o1, - PyObject *o2, int opid} - Compare the values of \var{o1} and \var{o2} using the operation - specified by \var{opid}, which must be one of - \constant{Py_LT}, - \constant{Py_LE}, - \constant{Py_EQ}, - \constant{Py_NE}, - \constant{Py_GT}, or - \constant{Py_GE}, corresponding to - \code{<}, - \code{<=}, - \code{==}, - \code{!=}, - \code{>}, or - \code{>=} respectively. Returns \code{-1} on error, \code{0} if the - result is false, \code{1} otherwise. This is the equivalent of the - Python expression \samp{\var{o1} op \var{o2}}, where - \code{op} is the operator corresponding to \var{opid}. -\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{unicode(\var{o})}. Called by the - \function{unicode()}\bifuncindex{unicode} built-in function. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls} - Returns \code{1} if \var{inst} is an instance of the class \var{cls} - or a subclass of \var{cls}, or \code{0} if not. On error, returns - \code{-1} and sets an exception. 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{cls} - is a tuple, the check will be done against every entry in \var{cls}. - The result will be \code{1} when at least one of the checks returns - \code{1}, otherwise it will be \code{0}. If \var{inst} is not a class - instance and \var{cls} is neither a type object, nor a class object, - nor a tuple, \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} - \versionchanged[Support for a tuple as the second argument added]{2.2} -\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 \var{cls} - is a tuple, the check will be done against every entry in \var{cls}. - The result will be \code{1} when at least one of the checks returns - \code{1}, otherwise it will be \code{0}. If either \var{derived} or - \var{cls} is not an actual class object (or tuple), this function - uses the generic algorithm described above. - \versionadded{2.1} - \versionchanged[Older versions of Python did not support a tuple - as the second argument]{2.3} -\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_Call}{PyObject *callable_object, - PyObject *args, - PyObject *kw} - Call a callable Python object \var{callable_object}, with arguments - given by the tuple \var{args}, and named arguments given by the - dictionary \var{kw}. If no named arguments are needed, \var{kw} may - be \NULL{}. \var{args} must not be \NULL{}, use an empty tuple if - no arguments are needed. Returns the result of the call on success, - or \NULL{} on failure. This is the equivalent of the Python - expression \samp{\var{callable_object}(*\var{args}, **\var{kw})}. - \versionadded{2.2} -\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{\var{callable_object}(*\var{args})}. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable, - char *format, \moreargs} - Call a callable Python object \var{callable}, 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{\var{callable}(*\var{args})}. - Note that if you only pass \ctype{PyObject *} args, - \cfunction{PyObject_CallFunctionObjArgs} is a faster alternative. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, - char *method, char *format, - \moreargs} - Call the method named \var{method} of object \var{o} with a variable - number of C arguments. The C arguments are described by a - \cfunction{Py_BuildValue()} format string that should - produce a tuple. 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 if you only pass \ctype{PyObject *} args, - \cfunction{PyObject_CallMethodObjArgs} is a faster alternative. -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyObject_CallFunctionObjArgs}{PyObject *callable, - \moreargs, - \code{NULL}} - Call a callable Python object \var{callable}, with a variable - number of \ctype{PyObject*} arguments. The arguments are provided - as a variable number of parameters followed by \NULL. - Returns the result of the call on success, or \NULL{} on failure. - \versionadded{2.2} -\end{cfuncdesc} - - -\begin{cfuncdesc}{PyObject*}{PyObject_CallMethodObjArgs}{PyObject *o, - PyObject *name, - \moreargs, - \code{NULL}} - Calls a method of the object \var{o}, where the name of the method - is given as a Python string object in \var{name}. It is called with - a variable number of \ctype{PyObject*} arguments. The arguments are - provided as a variable number of parameters followed by \NULL. - Returns the result of the call on success, or \NULL{} on failure. - \versionadded{2.2} -\end{cfuncdesc} - - -\begin{cfuncdesc}{long}{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}}. On failure, return \code{-1}. -\end{cfuncdesc} - - -\begin{cfuncdesc}{int}{PyObject_Not}{PyObject *o} - Returns \code{0} if the object \var{o} is considered to be true, and - \code{1} otherwise. This is equivalent to the Python expression - \samp{not \var{o}}. On failure, return \code{-1}. -\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} - This function increments the reference count of the return value. - There's really no reason to use this function instead of the - common expression \code{\var{o}->ob_type}, which returns a pointer - of type \ctype{PyTypeObject*}, except when the incremented reference - count is needed. -\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}{Py_ssize_t}{PyObject_Length}{PyObject *o} -\cfuncline{Py_ssize_t}{PyObject_Size}{PyObject *o} - Return the length of object \var{o}. If the object \var{o} provides - either the 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} - -\begin{cfuncdesc}{PyObject*}{PyObject_GetIter}{PyObject *o} - This is equivalent to the Python expression \samp{iter(\var{o})}. - It returns a new iterator for the object argument, or the object - itself if the object is already an iterator. Raises - \exception{TypeError} and returns \NULL{} if the object cannot be - iterated. -\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{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*}{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 floor 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} >>= \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}{PyObject*}{PyNumber_Int}{PyObject *o} - Returns the \var{o} converted to an integer object on success, or - \NULL{} on failure. If the argument is outside the integer range - a long object will be returned instead. 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} - -\begin{cfuncdesc}{PyObject*}{PyNumber_Index}{PyObject *o} - Returns the \var{o} converted to a Python int or long on success or \NULL{} - with a TypeError exception raised on failure. - \versionadded{2.5} -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_ssize_t}{PyNumber_AsSsize_t}{PyObject *o, PyObject *exc} - Returns \var{o} converted to a Py_ssize_t value if \var{o} - can be interpreted as an integer. If \var{o} can be converted to a Python - int or long but the attempt to convert to a Py_ssize_t value - would raise an \exception{OverflowError}, then the \var{exc} argument - is the type of exception that will be raised (usually \exception{IndexError} - or \exception{OverflowError}). If \var{exc} is \NULL{}, then the exception - is cleared and the value is clipped to \var{PY_SSIZE_T_MIN} - for a negative integer or \var{PY_SSIZE_T_MAX} for a positive integer. - \versionadded{2.5} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyIndex_Check}{PyObject *o} - Returns True if \var{o} is an index integer (has the nb_index slot of - the tp_as_number structure filled in). - \versionadded{2.5} -\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}{Py_ssize_t}{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}{Py_ssize_t}{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, Py_ssize_t 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, Py_ssize_t 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, Py_ssize_t 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, Py_ssize_t i1, Py_ssize_t 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, Py_ssize_t 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}}. This function \emph{does not} - steal a reference to \var{v}. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, Py_ssize_t 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, Py_ssize_t i1, - Py_ssize_t 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, Py_ssize_t i1, Py_ssize_t 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}{Py_ssize_t}{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}{Py_ssize_t}{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} or \NULL{} on failure. If \var{o} is a tuple, - a new reference will be returned, otherwise a tuple will be - constructed with the appropriate contents. This is equivalent - to the Python expression \samp{tuple(\var{o})}. - \bifuncindex{tuple} -\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, Py_ssize_t i} - Return the \var{i}th element of \var{o}, assuming that \var{o} was - returned by \cfunction{PySequence_Fast()}, \var{o} is not \NULL, - and that \var{i} is within bounds. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject**}{PySequence_Fast_ITEMS}{PyObject *o} - Return the underlying array of PyObject pointers. Assumes that - \var{o} was returned by \cfunction{PySequence_Fast()} and - \var{o} is not \NULL. - \versionadded{2.4} -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PySequence_ITEM}{PyObject *o, Py_ssize_t i} - Return the \var{i}th element of \var{o} or \NULL{} on failure. - Macro form of \cfunction{PySequence_GetItem()} but without checking - that \cfunction{PySequence_Check(\var{o})} is true and without - adjustment for negative indices. - \versionadded{2.3} -\end{cfuncdesc} - -\begin{cfuncdesc}{Py_ssize_t}{PySequence_Fast_GET_SIZE}{PyObject *o} - Returns the length of \var{o}, assuming that \var{o} was - returned by \cfunction{PySequence_Fast()} and that \var{o} is - not \NULL. The size can also be gotten by calling - \cfunction{PySequence_Size()} on \var{o}, but - \cfunction{PySequence_Fast_GET_SIZE()} is faster because it can - assume \var{o} is a list or tuple. -\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}{Py_ssize_t}{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_GetIter(obj); -PyObject *item; - -if (iterator == NULL) { - /* propagate error */ -} - -while (item = PyIter_Next(iterator)) { - /* do something with item */ - ... - /* release reference when done */ - Py_DECREF(item); -} - -Py_DECREF(iterator); - -if (PyErr_Occurred()) { - /* propagate error */ -} -else { - /* continue doing useful work */ -} -\end{verbatim} - - -\section{Buffer Protocol \label{abstract-buffer}} - -\begin{cfuncdesc}{int}{PyObject_AsCharBuffer}{PyObject *obj, - const char **buffer, - Py_ssize_t *buffer_len} - Returns a pointer to a read-only memory location useable as character- - based input. The \var{obj} argument must support the single-segment - character buffer interface. On success, returns \code{0}, sets - \var{buffer} to the memory location and \var{buffer_len} to the buffer - length. Returns \code{-1} and sets a \exception{TypeError} on error. - \versionadded{1.6} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyObject_AsReadBuffer}{PyObject *obj, - const void **buffer, - Py_ssize_t *buffer_len} - Returns a pointer to a read-only memory location containing - arbitrary data. The \var{obj} argument must support the - single-segment readable buffer interface. On success, returns - \code{0}, sets \var{buffer} to the memory location and \var{buffer_len} - to the buffer length. Returns \code{-1} and sets a - \exception{TypeError} on error. - \versionadded{1.6} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyObject_CheckReadBuffer}{PyObject *o} - Returns \code{1} if \var{o} supports the single-segment readable - buffer interface. Otherwise returns \code{0}. - \versionadded{2.2} -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyObject_AsWriteBuffer}{PyObject *obj, - void **buffer, - Py_ssize_t *buffer_len} - Returns a pointer to a writeable memory location. The \var{obj} - argument must support the single-segment, character buffer - interface. On success, returns \code{0}, sets \var{buffer} to the - memory location and \var{buffer_len} to the buffer length. Returns - \code{-1} and sets a \exception{TypeError} on error. - \versionadded{1.6} -\end{cfuncdesc} |