1029 lines
42 KiB
TeX
1029 lines
42 KiB
TeX
\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}{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{apply(\var{callable_object}, \var{args}, \var{kw})}
|
|
or \samp{\var{callable_object}(*\var{args}, **\var{kw})}.
|
|
\bifuncindex{apply}
|
|
\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{apply(\var{callable_object}, \var{args})} or
|
|
\samp{\var{callable_object}(*\var{args})}.
|
|
\bifuncindex{apply}
|
|
\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{apply(\var{callable},
|
|
\var{args})} or \samp{\var{callable}(*\var{args})}.
|
|
\bifuncindex{apply}
|
|
\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. 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})}.
|
|
\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}{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}}. 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}{int}{PyObject_Length}{PyObject *o}
|
|
\cfuncline{int}{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} >\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. 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}
|
|
|
|
|
|
\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}}. This function \emph{does not}
|
|
steal a reference to \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()}, \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, int 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}{int}{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}{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_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,
|
|
int *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 char **buffer,
|
|
int *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,
|
|
char **buffer,
|
|
int *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}
|