| \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{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. 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_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} |