cpython-lru_cache-weakref: Doc/api/abstract.tex annotate

annotate Doc/api/abstract.tex @ 21467:4e35fa5d5708 legacy-trunk

Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.

author	Fred Drake <fdrake@acm.org>
date	Tue, 18 Dec 2001 16:31:08 +0000
parents	bc02c3b09626
children	7bde9ca90554

rev	line source
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1 \chapter{Abstract Objects Layer \label{abstract}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	2
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	3 The functions in this chapter interact with Python objects regardless
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	4 of their type, or with wide classes of object types (e.g. all
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	5 numerical types, or all sequence types). When used on object types
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	6 for which they do not apply, they will raise a Python exception.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	7
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	8
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	9 \section{Object Protocol \label{object}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	10
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	11 \begin{cfuncdesc}{int}{PyObject_Print}{PyObject o, FILE fp, int flags}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	12 Print an object \var{o}, on file \var{fp}. Returns \code{-1} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	13 error. The flags argument is used to enable certain printing
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	14 options. The only option currently supported is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	15 \constant{Py_PRINT_RAW}; if given, the \function{str()} of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	16 object is written instead of the \function{repr()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	17 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	18
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	19 \begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject o, char attr_name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	20 Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	21 \code{0} otherwise. This is equivalent to the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	22 \samp{hasattr(\var{o}, \var{attr_name})}. This function always
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	23 succeeds.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	24 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	25
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	26 \begin{cfuncdesc}{PyObject}{PyObject_GetAttrString}{PyObject o,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	27 char *attr_name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	28 Retrieve an attribute named \var{attr_name} from object \var{o}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	29 Returns the attribute value on success, or \NULL{} on failure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	30 This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	31 \samp{\var{o}.\var{attr_name}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	32 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	33
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	34
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	35 \begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject o, PyObject attr_name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	36 Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	37 \code{0} otherwise. This is equivalent to the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	38 \samp{hasattr(\var{o}, \var{attr_name})}. This function always
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	39 succeeds.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	40 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	41
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	42
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	43 \begin{cfuncdesc}{PyObject}{PyObject_GetAttr}{PyObject o,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	44 PyObject *attr_name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	45 Retrieve an attribute named \var{attr_name} from object \var{o}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	46 Returns the attribute value on success, or \NULL{} on failure. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	47 is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	48 \samp{\var{o}.\var{attr_name}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	49 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	50
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	51
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	52 \begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	53 char attr_name, PyObject v}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	54 Set the value of the attribute named \var{attr_name}, for object
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	55 \var{o}, to the value \var{v}. Returns \code{-1} on failure. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	56 is the equivalent of the Python statement
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	57 \samp{\var{o}.\var{attr_name} = \var{v}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	58 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	59
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	60
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	61 \begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	62 PyObject attr_name, PyObject v}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	63 Set the value of the attribute named \var{attr_name}, for object
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	64 \var{o}, to the value \var{v}. Returns \code{-1} on failure. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	65 is the equivalent of the Python statement
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	66 \samp{\var{o}.\var{attr_name} = \var{v}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	67 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	68
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	69
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	70 \begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject o, char attr_name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	71 Delete attribute named \var{attr_name}, for object \var{o}. Returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	72 \code{-1} on failure. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	73 statement: \samp{del \var{o}.\var{attr_name}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	74 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	75
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	76
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	77 \begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject o, PyObject attr_name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	78 Delete attribute named \var{attr_name}, for object \var{o}. Returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	79 \code{-1} on failure. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	80 statement \samp{del \var{o}.\var{attr_name}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	81 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	82
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	83
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	84 \begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject o1, PyObject o2, int *result}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	85 Compare the values of \var{o1} and \var{o2} using a routine provided
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	86 by \var{o1}, if one exists, otherwise with a routine provided by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	87 \var{o2}. The result of the comparison is returned in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	88 \var{result}. Returns \code{-1} on failure. This is the equivalent
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	89 of the Python statement\bifuncindex{cmp} \samp{\var{result} =
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	90 cmp(\var{o1}, \var{o2})}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	91 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	92
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	93
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	94 \begin{cfuncdesc}{int}{PyObject_Compare}{PyObject o1, PyObject o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	95 Compare the values of \var{o1} and \var{o2} using a routine provided
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	96 by \var{o1}, if one exists, otherwise with a routine provided by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	97 \var{o2}. Returns the result of the comparison on success. On
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	98 error, the value returned is undefined; use
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	99 \cfunction{PyErr_Occurred()} to detect an error. This is equivalent
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	100 to the Python expression\bifuncindex{cmp} \samp{cmp(\var{o1},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	101 \var{o2})}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	102 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	103
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	104
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	105 \begin{cfuncdesc}{PyObject}{PyObject_Repr}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	106 Compute a string representation of object \var{o}. Returns the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	107 string representation on success, \NULL{} on failure. This is the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	108 equivalent of the Python expression \samp{repr(\var{o})}. Called by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	109 the \function{repr()}\bifuncindex{repr} built-in function and by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	110 reverse quotes.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	111 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	112
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	113
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	114 \begin{cfuncdesc}{PyObject}{PyObject_Str}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	115 Compute a string representation of object \var{o}. Returns the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	116 string representation on success, \NULL{} on failure. This is the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	117 equivalent of the Python expression \samp{str(\var{o})}. Called by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	118 the \function{str()}\bifuncindex{str} built-in function and by the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	119 \keyword{print} statement.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	120 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	121
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	122
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	123 \begin{cfuncdesc}{PyObject}{PyObject_Unicode}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	124 Compute a Unicode string representation of object \var{o}. Returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	125 the Unicode string representation on success, \NULL{} on failure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	126 This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	127 \samp{unistr(\var{o})}. Called by the
20683 505dd34e0eeb Generalize dictionary() to accept a sequence of 2-sequences. At the Tim Peters <tim.peters@gmail.com> parents: 20390 diff changeset	128 \function{unistr()}\bifuncindex{unistr} built-in function.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	129 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	130
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	131 \begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject inst, PyObject cls}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	132 Return \code{1} if \var{inst} is an instance of the class \var{cls}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	133 or a subclass of \var{cls}. If \var{cls} is a type object rather
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	134 than a class object, \cfunction{PyObject_IsInstance()} returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	135 \code{1} if \var{inst} is of type \var{cls}. If \var{inst} is not a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	136 class instance and \var{cls} is neither a type object or class
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	137 object, \var{inst} must have a \member{__class__} attribute --- the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	138 class relationship of the value of that attribute with \var{cls}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	139 will be used to determine the result of this function.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	140 \versionadded{2.1}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	141 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	142
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	143 Subclass determination is done in a fairly straightforward way, but
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	144 includes a wrinkle that implementors of extensions to the class system
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	145 may want to be aware of. If \class{A} and \class{B} are class
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	146 objects, \class{B} is a subclass of \class{A} if it inherits from
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	147 \class{A} either directly or indirectly. If either is not a class
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	148 object, a more general mechanism is used to determine the class
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	149 relationship of the two objects. When testing if \var{B} is a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	150 subclass of \var{A}, if \var{A} is \var{B},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	151 \cfunction{PyObject_IsSubclass()} returns true. If \var{A} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	152 \var{B} are different objects, \var{B}'s \member{__bases__} attribute
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	153 is searched in a depth-first fashion for \var{A} --- the presence of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	154 the \member{__bases__} attribute is considered sufficient for this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	155 determination.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	156
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	157 \begin{cfuncdesc}{int}{PyObject_IsSubclass}{PyObject *derived,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	158 PyObject *cls}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	159 Returns \code{1} if the class \var{derived} is identical to or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	160 derived from the class \var{cls}, otherwise returns \code{0}. In
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	161 case of an error, returns \code{-1}. If either \var{derived} or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	162 \var{cls} is not an actual class object, this function uses the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	163 generic algorithm described above.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	164 \versionadded{2.1}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	165 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	166
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	167
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	168 \begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	169 Determine if the object \var{o} is callable. Return \code{1} if the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	170 object is callable and \code{0} otherwise. This function always
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	171 succeeds.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	172 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	173
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	174
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	175 \begin{cfuncdesc}{PyObject}{PyObject_CallObject}{PyObject callable_object,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	176 PyObject *args}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	177 Call a callable Python object \var{callable_object}, with arguments
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	178 given by the tuple \var{args}. If no arguments are needed, then
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	179 \var{args} may be \NULL. Returns the result of the call on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	180 success, or \NULL{} on failure. This is the equivalent of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	181 Python expression \samp{apply(\var{callable_object}, \var{args})} or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	182 \samp{\var{callable_object}(*\var{args})}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	183 \bifuncindex{apply}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	184 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	185
20696 398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	186 \begin{cfuncdesc}{PyObject}{PyObject_CallFunction}{PyObject callable,
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	187 char *format, \moreargs}
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	188 Call a callable Python object \var{callable}, with a variable
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	189 number of C arguments. The C arguments are described using a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	190 \cfunction{Py_BuildValue()} style format string. The format may be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	191 \NULL, indicating that no arguments are provided. Returns the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	192 result of the call on success, or \NULL{} on failure. This is the
20696 398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	193 equivalent of the Python expression \samp{apply(\var{callable},
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	194 \var{args})} or \samp{\var{callable}(*\var{args})}.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	195 \bifuncindex{apply}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	196 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	197
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	198
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	199 \begin{cfuncdesc}{PyObject}{PyObject_CallMethod}{PyObject o,
20696 398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	200 char method, char format,
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	201 \moreargs}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	202 Call the method named \var{m} of object \var{o} with a variable
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	203 number of C arguments. The C arguments are described by a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	204 \cfunction{Py_BuildValue()} format string. The format may be \NULL,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	205 indicating that no arguments are provided. Returns the result of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	206 call on success, or \NULL{} on failure. This is the equivalent of
20696 398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	207 the Python expression \samp{\var{o}.\var{method}(\var{args})}.
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	208 \end{cfuncdesc}
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	209
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	210
20729 cd600039a123 PyObject_CallFunctionObArgs() ---> PyObject_CallFunctionObjArgs() Fred Drake <fdrake@acm.org> parents: 20696 diff changeset	211 \begin{cfuncdesc}{PyObject}{PyObject_CallFunctionObjArgs}{PyObject callable,
cd600039a123 PyObject_CallFunctionObArgs() ---> PyObject_CallFunctionObjArgs() Fred Drake <fdrake@acm.org> parents: 20696 diff changeset	212 \moreargs,
cd600039a123 PyObject_CallFunctionObArgs() ---> PyObject_CallFunctionObjArgs() Fred Drake <fdrake@acm.org> parents: 20696 diff changeset	213 \code{NULL}}
20696 398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	214 Call a callable Python object \var{callable}, with a variable
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	215 number of \ctype{PyObject*} arguments. The arguments are provided
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	216 as a variable number of parameters followed by \NULL.
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	217 Returns the result of the call on success, or \NULL{} on failure.
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	218 \versionadded{2.2}
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	219 \end{cfuncdesc}
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	220
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	221
20729 cd600039a123 PyObject_CallFunctionObArgs() ---> PyObject_CallFunctionObjArgs() Fred Drake <fdrake@acm.org> parents: 20696 diff changeset	222 \begin{cfuncdesc}{PyObject}{PyObject_CallMethodObjArgs}{PyObject o,
cd600039a123 PyObject_CallFunctionObArgs() ---> PyObject_CallFunctionObjArgs() Fred Drake <fdrake@acm.org> parents: 20696 diff changeset	223 PyObject *name,
cd600039a123 PyObject_CallFunctionObArgs() ---> PyObject_CallFunctionObjArgs() Fred Drake <fdrake@acm.org> parents: 20696 diff changeset	224 \moreargs,
cd600039a123 PyObject_CallFunctionObArgs() ---> PyObject_CallFunctionObjArgs() Fred Drake <fdrake@acm.org> parents: 20696 diff changeset	225 \code{NULL}}
20696 398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	226 Calls a method of the object \var{o}, where the name of the method
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	227 is given as a Python string object in \var{name}. It is called with
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	228 a variable number of \ctype{PyObject*} arguments. The arguments are
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	229 provided as a variable number of parameters followed by \NULL.
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	230 Returns the result of the call on success, or \NULL{} on failure.
398135e400c7 Added docs for PyObject_CallFunctionObArgs() and PyObject_CallMethodObArgs(). Fred Drake <fdrake@acm.org> parents: 20683 diff changeset	231 \versionadded{2.2}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	232 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	233
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	234
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	235 \begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	236 Compute and return the hash value of an object \var{o}. On failure,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	237 return \code{-1}. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	238 \samp{hash(\var{o})}.\bifuncindex{hash}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	239 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	240
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	241
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	242 \begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	243 Returns \code{1} if the object \var{o} is considered to be true, and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	244 \code{0} otherwise. This is equivalent to the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	245 \samp{not not \var{o}}. This function always succeeds.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	246 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	247
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	248
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	249 \begin{cfuncdesc}{PyObject}{PyObject_Type}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	250 When \var{o} is non-\NULL, returns a type object corresponding to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	251 the object type of object \var{o}. On failure, raises
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	252 \exception{SystemError} and returns \NULL. This is equivalent to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	253 the Python expression \code{type(\var{o})}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	254 \bifuncindex{type}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	255 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	256
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	257 \begin{cfuncdesc}{int}{PyObject_TypeCheck}{PyObject o, PyTypeObject type}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	258 Return true if the object \var{o} is of type \var{type} or a subtype
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	259 of \var{type}. Both parameters must be non-\NULL.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	260 \versionadded{2.2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	261 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	262
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	263 \begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	264 Return the length of object \var{o}. If the object \var{o} provides
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	265 both sequence and mapping protocols, the sequence length is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	266 returned. On error, \code{-1} is returned. This is the equivalent
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	267 to the Python expression \samp{len(\var{o})}.\bifuncindex{len}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	268 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	269
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	270
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	271 \begin{cfuncdesc}{PyObject}{PyObject_GetItem}{PyObject o, PyObject *key}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	272 Return element of \var{o} corresponding to the object \var{key} or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	273 \NULL{} on failure. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	274 \samp{\var{o}[\var{key}]}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	275 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	276
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	277
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	278 \begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	279 PyObject key, PyObject v}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	280 Map the object \var{key} to the value \var{v}. Returns \code{-1} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	281 failure. This is the equivalent of the Python statement
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	282 \samp{\var{o}[\var{key}] = \var{v}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	283 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	284
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	285
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	286 \begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject o, PyObject key}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	287 Delete the mapping for \var{key} from \var{o}. Returns \code{-1} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	288 failure. This is the equivalent of the Python statement \samp{del
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	289 \var{o}[\var{key}]}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	290 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	291
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	292 \begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	293 Derives a file-descriptor from a Python object. If the object is an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	294 integer or long integer, its value is returned. If not, the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	295 object's \method{fileno()} method is called if it exists; the method
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	296 must return an integer or long integer, which is returned as the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	297 file descriptor value. Returns \code{-1} on failure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	298 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	299
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	300 \begin{cfuncdesc}{PyObject}{PyObject_Dir}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	301 This is equivalent to the Python expression \samp{dir(\var{o})},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	302 returning a (possibly empty) list of strings appropriate for the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	303 object argument, or \NULL{} if there was an error. If the argument
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	304 is \NULL, this is like the Python \samp{dir()}, returning the names
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	305 of the current locals; in this case, if no execution frame is active
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	306 then \NULL{} is returned but \cfunction{PyErr_Occurred()} will
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	307 return false.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	308 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	309
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	310
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	311 \section{Number Protocol \label{number}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	312
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	313 \begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	314 Returns \code{1} if the object \var{o} provides numeric protocols,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	315 and false otherwise. This function always succeeds.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	316 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	317
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	318
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	319 \begin{cfuncdesc}{PyObject}{PyNumber_Add}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	320 Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	321 failure. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	322 \samp{\var{o1} + \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	323 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	324
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	325
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	326 \begin{cfuncdesc}{PyObject}{PyNumber_Subtract}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	327 Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	328 on failure. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	329 \samp{\var{o1} - \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	330 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	331
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	332
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	333 \begin{cfuncdesc}{PyObject}{PyNumber_Multiply}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	334 Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	335 on failure. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	336 \samp{\var{o1} * \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	337 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	338
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	339
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	340 \begin{cfuncdesc}{PyObject}{PyNumber_Divide}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	341 Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	342 failure. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	343 \samp{\var{o1} / \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	344 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	345
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	346
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	347 \begin{cfuncdesc}{PyObject}{PyNumber_FloorDivide}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	348 Return the floor of \var{o1} divided by \var{o2}, or \NULL{} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	349 failure. This is equivalent to the ``classic'' division of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	350 integers.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	351 \versionadded{2.2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	352 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	353
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	354
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	355 \begin{cfuncdesc}{PyObject}{PyNumber_TrueDivide}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	356 Return a reasonable approximation for the mathematical value of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	357 \var{o1} divided by \var{o2}, or \NULL{} on failure. The return
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	358 value is ``approximate'' because binary floating point numbers are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	359 approximate; it is not possible to represent all real numbers in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	360 base two. This function can return a floating point value when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	361 passed two integers.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	362 \versionadded{2.2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	363 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	364
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	365
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	366 \begin{cfuncdesc}{PyObject}{PyNumber_Remainder}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	367 Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	368 on failure. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	369 \samp{\var{o1} \%\ \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	370 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	371
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	372
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	373 \begin{cfuncdesc}{PyObject}{PyNumber_Divmod}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	374 See the built-in function \function{divmod()}\bifuncindex{divmod}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	375 Returns \NULL{} on failure. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	376 expression \samp{divmod(\var{o1}, \var{o2})}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	377 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	378
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	379
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	380 \begin{cfuncdesc}{PyObject}{PyNumber_Power}{PyObject o1,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	381 PyObject o2, PyObject o3}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	382 See the built-in function \function{pow()}\bifuncindex{pow}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	383 Returns \NULL{} on failure. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	384 expression \samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	385 is optional. If \var{o3} is to be ignored, pass \cdata{Py_None} in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	386 its place (passing \NULL{} for \var{o3} would cause an illegal
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	387 memory access).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	388 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	389
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	390
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	391 \begin{cfuncdesc}{PyObject}{PyNumber_Negative}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	392 Returns the negation of \var{o} on success, or \NULL{} on failure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	393 This is the equivalent of the Python expression \samp{-\var{o}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	394 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	395
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	396
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	397 \begin{cfuncdesc}{PyObject}{PyNumber_Positive}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	398 Returns \var{o} on success, or \NULL{} on failure. This is the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	399 equivalent of the Python expression \samp{+\var{o}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	400 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	401
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	402
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	403 \begin{cfuncdesc}{PyObject}{PyNumber_Absolute}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	404 Returns the absolute value of \var{o}, or \NULL{} on failure. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	405 is the equivalent of the Python expression \samp{abs(\var{o})}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	406 \bifuncindex{abs}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	407 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	408
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	409
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	410 \begin{cfuncdesc}{PyObject}{PyNumber_Invert}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	411 Returns the bitwise negation of \var{o} on success, or \NULL{} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	412 failure. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	413 \samp{\~\var{o}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	414 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	415
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	416
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	417 \begin{cfuncdesc}{PyObject}{PyNumber_Lshift}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	418 Returns the result of left shifting \var{o1} by \var{o2} on success,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	419 or \NULL{} on failure. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	420 expression \samp{\var{o1} <\code{<} \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	421 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	422
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	423
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	424 \begin{cfuncdesc}{PyObject}{PyNumber_Rshift}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	425 Returns the result of right shifting \var{o1} by \var{o2} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	426 success, or \NULL{} on failure. This is the equivalent of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	427 Python expression \samp{\var{o1} >\code{>} \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	428 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	429
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	430
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	431 \begin{cfuncdesc}{PyObject}{PyNumber_And}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	432 Returns the ``bitwise and'' of \var{o2} and \var{o2} on success and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	433 \NULL{} on failure. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	434 \samp{\var{o1} \&\ \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	435 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	436
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	437
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	438 \begin{cfuncdesc}{PyObject}{PyNumber_Xor}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	439 Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	440 success, or \NULL{} on failure. This is the equivalent of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	441 Python expression \samp{\var{o1} \textasciicircum{} \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	442 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	443
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	444 \begin{cfuncdesc}{PyObject}{PyNumber_Or}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	445 Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	446 \NULL{} on failure. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	447 \samp{\var{o1} \| \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	448 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	449
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	450
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	451 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceAdd}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	452 Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	453 failure. The operation is done \emph{in-place} when \var{o1}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	454 supports it. This is the equivalent of the Python statement
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	455 \samp{\var{o1} += \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	456 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	457
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	458
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	459 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceSubtract}{PyObject o1,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	460 PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	461 Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	462 on failure. The operation is done \emph{in-place} when \var{o1}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	463 supports it. This is the equivalent of the Python statement
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	464 \samp{\var{o1} -= \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	465 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	466
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	467
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	468 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceMultiply}{PyObject o1,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	469 PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	470 Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	471 on failure. The operation is done \emph{in-place} when \var{o1}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	472 supports it. This is the equivalent of the Python statement
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	473 \samp{\var{o1} *= \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	474 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	475
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	476
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	477 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceDivide}{PyObject o1,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	478 PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	479 Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	480 failure. The operation is done \emph{in-place} when \var{o1}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	481 supports it. This is the equivalent of the Python statement
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	482 \samp{\var{o1} /= \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	483 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	484
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	485
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	486 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceFloorDivide}{PyObject o1,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	487 PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	488 Returns the mathematical of dividing \var{o1} by \var{o2}, or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	489 \NULL{} on failure. The operation is done \emph{in-place} when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	490 \var{o1} supports it. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	491 statement \samp{\var{o1} //= \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	492 \versionadded{2.2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	493 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	494
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	495
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	496 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceTrueDivide}{PyObject o1,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	497 PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	498 Return a reasonable approximation for the mathematical value of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	499 \var{o1} divided by \var{o2}, or \NULL{} on failure. The return
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	500 value is ``approximate'' because binary floating point numbers are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	501 approximate; it is not possible to represent all real numbers in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	502 base two. This function can return a floating point value when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	503 passed two integers. The operation is done \emph{in-place} when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	504 \var{o1} supports it.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	505 \versionadded{2.2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	506 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	507
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	508
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	509 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceRemainder}{PyObject o1,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	510 PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	511 Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	512 on failure. The operation is done \emph{in-place} when \var{o1}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	513 supports it. This is the equivalent of the Python statement
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	514 \samp{\var{o1} \%= \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	515 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	516
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	517
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	518 \begin{cfuncdesc}{PyObject}{PyNumber_InPlacePower}{PyObject o1,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	519 PyObject o2, PyObject o3}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	520 See the built-in function \function{pow()}.\bifuncindex{pow}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	521 Returns \NULL{} on failure. The operation is done \emph{in-place}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	522 when \var{o1} supports it. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	523 statement \samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None},
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	524 or an in-place variant of \samp{pow(\var{o1}, \var{o2}, \var{o3})}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	525 otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	526 place (passing \NULL{} for \var{o3} would cause an illegal memory
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	527 access).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	528 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	529
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	530 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceLshift}{PyObject o1,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	531 PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	532 Returns the result of left shifting \var{o1} by \var{o2} on success,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	533 or \NULL{} on failure. The operation is done \emph{in-place} when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	534 \var{o1} supports it. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	535 statement \samp{\var{o1} <\code{<=} \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	536 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	537
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	538
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	539 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceRshift}{PyObject o1,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	540 PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	541 Returns the result of right shifting \var{o1} by \var{o2} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	542 success, or \NULL{} on failure. The operation is done
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	543 \emph{in-place} when \var{o1} supports it. This is the equivalent
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	544 of the Python statement \samp{\var{o1} >\code{>=} \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	545 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	546
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	547
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	548 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceAnd}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	549 Returns the ``bitwise and'' of \var{o1} and \var{o2} on success and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	550 \NULL{} on failure. The operation is done \emph{in-place} when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	551 \var{o1} supports it. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	552 statement \samp{\var{o1} \&= \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	553 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	554
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	555
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	556 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceXor}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	557 Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	558 success, or \NULL{} on failure. The operation is done
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	559 \emph{in-place} when \var{o1} supports it. This is the equivalent
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	560 of the Python statement \samp{\var{o1} \textasciicircum= \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	561 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	562
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	563 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceOr}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	564 Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	565 \NULL{} on failure. The operation is done \emph{in-place} when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	566 \var{o1} supports it. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	567 statement \samp{\var{o1} \|= \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	568 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	569
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	570 \begin{cfuncdesc}{int}{PyNumber_Coerce}{PyObject p1, PyObject p2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	571 This function takes the addresses of two variables of type
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	572 \ctype{PyObject}. If the objects pointed to by \code{\var{p1}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	573 and \code{*\var{p2}} have the same type, increment their reference
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	574 count and return \code{0} (success). If the objects can be converted
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	575 to a common numeric type, replace \code{p1} and \code{p2} by their
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	576 converted value (with 'new' reference counts), and return \code{0}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	577 If no conversion is possible, or if some other error occurs, return
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	578 \code{-1} (failure) and don't increment the reference counts. The
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	579 call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	580 statement \samp{\var{o1}, \var{o2} = coerce(\var{o1}, \var{o2})}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	581 \bifuncindex{coerce}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	582 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	583
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	584 \begin{cfuncdesc}{PyObject}{PyNumber_Int}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	585 Returns the \var{o} converted to an integer object on success, or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	586 \NULL{} on failure. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	587 \samp{int(\var{o})}.\bifuncindex{int}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	588 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	589
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	590 \begin{cfuncdesc}{PyObject}{PyNumber_Long}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	591 Returns the \var{o} converted to a long integer object on success,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	592 or \NULL{} on failure. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	593 expression \samp{long(\var{o})}.\bifuncindex{long}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	594 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	595
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	596 \begin{cfuncdesc}{PyObject}{PyNumber_Float}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	597 Returns the \var{o} converted to a float object on success, or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	598 \NULL{} on failure. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	599 \samp{float(\var{o})}.\bifuncindex{float}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	600 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	601
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	602
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	603 \section{Sequence Protocol \label{sequence}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	604
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	605 \begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	606 Return \code{1} if the object provides sequence protocol, and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	607 \code{0} otherwise. This function always succeeds.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	608 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	609
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	610 \begin{cfuncdesc}{int}{PySequence_Size}{PyObject *o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	611 Returns the number of objects in sequence \var{o} on success, and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	612 \code{-1} on failure. For objects that do not provide sequence
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	613 protocol, this is equivalent to the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	614 \samp{len(\var{o})}.\bifuncindex{len}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	615 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	616
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	617 \begin{cfuncdesc}{int}{PySequence_Length}{PyObject *o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	618 Alternate name for \cfunction{PySequence_Size()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	619 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	620
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	621 \begin{cfuncdesc}{PyObject}{PySequence_Concat}{PyObject o1, PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	622 Return the concatenation of \var{o1} and \var{o2} on success, and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	623 \NULL{} on failure. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	624 expression \samp{\var{o1} + \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	625 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	626
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	627
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	628 \begin{cfuncdesc}{PyObject}{PySequence_Repeat}{PyObject o, int count}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	629 Return the result of repeating sequence object \var{o} \var{count}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	630 times, or \NULL{} on failure. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	631 expression \samp{\var{o} * \var{count}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	632 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	633
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	634 \begin{cfuncdesc}{PyObject}{PySequence_InPlaceConcat}{PyObject o1,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	635 PyObject *o2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	636 Return the concatenation of \var{o1} and \var{o2} on success, and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	637 \NULL{} on failure. The operation is done \emph{in-place} when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	638 \var{o1} supports it. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	639 expression \samp{\var{o1} += \var{o2}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	640 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	641
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	642
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	643 \begin{cfuncdesc}{PyObject}{PySequence_InPlaceRepeat}{PyObject o, int count}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	644 Return the result of repeating sequence object \var{o} \var{count}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	645 times, or \NULL{} on failure. The operation is done \emph{in-place}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	646 when \var{o} supports it. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	647 expression \samp{\var{o} *= \var{count}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	648 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	649
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	650
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	651 \begin{cfuncdesc}{PyObject}{PySequence_GetItem}{PyObject o, int i}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	652 Return the \var{i}th element of \var{o}, or \NULL{} on failure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	653 This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	654 \samp{\var{o}[\var{i}]}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	655 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	656
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	657
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	658 \begin{cfuncdesc}{PyObject}{PySequence_GetSlice}{PyObject o, int i1, int i2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	659 Return the slice of sequence object \var{o} between \var{i1} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	660 \var{i2}, or \NULL{} on failure. This is the equivalent of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	661 Python expression \samp{\var{o}[\var{i1}:\var{i2}]}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	662 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	663
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	664
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	665 \begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject o, int i, PyObject v}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	666 Assign object \var{v} to the \var{i}th element of \var{o}. Returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	667 \code{-1} on failure. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	668 statement \samp{\var{o}[\var{i}] = \var{v}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	669 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	670
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	671 \begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	672 Delete the \var{i}th element of object \var{o}. Returns \code{-1}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	673 on failure. This is the equivalent of the Python statement
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	674 \samp{del \var{o}[\var{i}]}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	675 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	676
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	677 \begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	678 int i2, PyObject *v}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	679 Assign the sequence object \var{v} to the slice in sequence object
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	680 \var{o} from \var{i1} to \var{i2}. This is the equivalent of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	681 Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	682 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	683
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	684 \begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	685 Delete the slice in sequence object \var{o} from \var{i1} to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	686 \var{i2}. Returns \code{-1} on failure. This is the equivalent of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	687 the Python statement \samp{del \var{o}[\var{i1}:\var{i2}]}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	688 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	689
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	690 \begin{cfuncdesc}{PyObject}{PySequence_Tuple}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	691 Returns the \var{o} as a tuple on success, and \NULL{} on failure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	692 This is equivalent to the Python expression \samp{tuple(\var{o})}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	693 \bifuncindex{tuple}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	694 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	695
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	696 \begin{cfuncdesc}{int}{PySequence_Count}{PyObject o, PyObject value}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	697 Return the number of occurrences of \var{value} in \var{o}, that is,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	698 return the number of keys for which \code{\var{o}[\var{key}] ==
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	699 \var{value}}. On failure, return \code{-1}. This is equivalent to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	700 the Python expression \samp{\var{o}.count(\var{value})}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	701 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	702
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	703 \begin{cfuncdesc}{int}{PySequence_Contains}{PyObject o, PyObject value}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	704 Determine if \var{o} contains \var{value}. If an item in \var{o} is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	705 equal to \var{value}, return \code{1}, otherwise return \code{0}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	706 On error, return \code{-1}. This is equivalent to the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	707 expression \samp{\var{value} in \var{o}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	708 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	709
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	710 \begin{cfuncdesc}{int}{PySequence_Index}{PyObject o, PyObject value}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	711 Return the first index \var{i} for which \code{\var{o}[\var{i}] ==
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	712 \var{value}}. On error, return \code{-1}. This is equivalent to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	713 the Python expression \samp{\var{o}.index(\var{value})}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	714 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	715
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	716 \begin{cfuncdesc}{PyObject}{PySequence_List}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	717 Return a list object with the same contents as the arbitrary
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	718 sequence \var{o}. The returned list is guaranteed to be new.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	719 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	720
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	721 \begin{cfuncdesc}{PyObject}{PySequence_Tuple}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	722 Return a tuple object with the same contents as the arbitrary
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	723 sequence \var{o}. If \var{o} is a tuple, a new reference will be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	724 returned, otherwise a tuple will be constructed with the appropriate
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	725 contents.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	726 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	727
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	728 \begin{cfuncdesc}{PyObject}{PySequence_Fast}{PyObject o, const char *m}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	729 Returns the sequence \var{o} as a tuple, unless it is already a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	730 tuple or list, in which case \var{o} is returned. Use
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	731 \cfunction{PySequence_Fast_GET_ITEM()} to access the members of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	732 result. Returns \NULL{} on failure. If the object is not a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	733 sequence, raises \exception{TypeError} with \var{m} as the message
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	734 text.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	735 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	736
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	737 \begin{cfuncdesc}{PyObject}{PySequence_Fast_GET_ITEM}{PyObject o, int i}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	738 Return the \var{i}th element of \var{o}, assuming that \var{o} was
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20957 diff changeset	739 returned by \cfunction{PySequence_Fast()}, \var{o} is not \NULL,
20683 505dd34e0eeb Generalize dictionary() to accept a sequence of 2-sequences. At the Tim Peters <tim.peters@gmail.com> parents: 20390 diff changeset	740 and that \var{i} is within bounds.
505dd34e0eeb Generalize dictionary() to accept a sequence of 2-sequences. At the Tim Peters <tim.peters@gmail.com> parents: 20390 diff changeset	741 \end{cfuncdesc}
505dd34e0eeb Generalize dictionary() to accept a sequence of 2-sequences. At the Tim Peters <tim.peters@gmail.com> parents: 20390 diff changeset	742
505dd34e0eeb Generalize dictionary() to accept a sequence of 2-sequences. At the Tim Peters <tim.peters@gmail.com> parents: 20390 diff changeset	743 \begin{cfuncdesc}{int}{PySequence_Fast_GET_SIZE}{PyObject *o}
505dd34e0eeb Generalize dictionary() to accept a sequence of 2-sequences. At the Tim Peters <tim.peters@gmail.com> parents: 20390 diff changeset	744 Returns the length of \var{o}, assuming that \var{o} was
505dd34e0eeb Generalize dictionary() to accept a sequence of 2-sequences. At the Tim Peters <tim.peters@gmail.com> parents: 20390 diff changeset	745 returned by \cfunction{PySequence_Fast()} and that \var{o} is
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20957 diff changeset	746 not \NULL. The size can also be gotten by calling
20683 505dd34e0eeb Generalize dictionary() to accept a sequence of 2-sequences. At the Tim Peters <tim.peters@gmail.com> parents: 20390 diff changeset	747 \cfunction{PySequence_Size()} on \var{o}, but
505dd34e0eeb Generalize dictionary() to accept a sequence of 2-sequences. At the Tim Peters <tim.peters@gmail.com> parents: 20390 diff changeset	748 \cfunction{PySequence_Fast_GET_SIZE()} is faster because it can
505dd34e0eeb Generalize dictionary() to accept a sequence of 2-sequences. At the Tim Peters <tim.peters@gmail.com> parents: 20390 diff changeset	749 assume \var{o} is a list or tuple.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	750 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	751
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	752
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	753 \section{Mapping Protocol \label{mapping}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	754
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	755 \begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	756 Return \code{1} if the object provides mapping protocol, and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	757 \code{0} otherwise. This function always succeeds.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	758 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	759
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	760
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	761 \begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	762 Returns the number of keys in object \var{o} on success, and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	763 \code{-1} on failure. For objects that do not provide mapping
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	764 protocol, this is equivalent to the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	765 \samp{len(\var{o})}.\bifuncindex{len}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	766 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	767
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	768
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	769 \begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject o, char key}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	770 Remove the mapping for object \var{key} from the object \var{o}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	771 Return \code{-1} on failure. This is equivalent to the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	772 statement \samp{del \var{o}[\var{key}]}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	773 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	774
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	775
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	776 \begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject o, PyObject key}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	777 Remove the mapping for object \var{key} from the object \var{o}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	778 Return \code{-1} on failure. This is equivalent to the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	779 statement \samp{del \var{o}[\var{key}]}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	780 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	781
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	782
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	783 \begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject o, char key}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	784 On success, return \code{1} if the mapping object has the key
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	785 \var{key} and \code{0} otherwise. This is equivalent to the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	786 expression \samp{\var{o}.has_key(\var{key})}. This function always
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	787 succeeds.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	788 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	789
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	790
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	791 \begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject o, PyObject key}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	792 Return \code{1} if the mapping object has the key \var{key} and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	793 \code{0} otherwise. This is equivalent to the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	794 \samp{\var{o}.has_key(\var{key})}. This function always succeeds.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	795 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	796
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	797
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	798 \begin{cfuncdesc}{PyObject}{PyMapping_Keys}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	799 On success, return a list of the keys in object \var{o}. On
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	800 failure, return \NULL. This is equivalent to the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	801 \samp{\var{o}.keys()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	802 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	803
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	804
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	805 \begin{cfuncdesc}{PyObject}{PyMapping_Values}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	806 On success, return a list of the values in object \var{o}. On
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	807 failure, return \NULL. This is equivalent to the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	808 \samp{\var{o}.values()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	809 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	810
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	811
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	812 \begin{cfuncdesc}{PyObject}{PyMapping_Items}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	813 On success, return a list of the items in object \var{o}, where each
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	814 item is a tuple containing a key-value pair. On failure, return
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	815 \NULL. This is equivalent to the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	816 \samp{\var{o}.items()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	817 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	818
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	819
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	820 \begin{cfuncdesc}{PyObject}{PyMapping_GetItemString}{PyObject o, char *key}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	821 Return element of \var{o} corresponding to the object \var{key} or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	822 \NULL{} on failure. This is the equivalent of the Python expression
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	823 \samp{\var{o}[\var{key}]}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	824 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	825
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	826 \begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject o, char key,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	827 PyObject *v}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	828 Map the object \var{key} to the value \var{v} in object \var{o}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	829 Returns \code{-1} on failure. This is the equivalent of the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	830 statement \samp{\var{o}[\var{key}] = \var{v}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	831 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	832
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	833
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	834 \section{Iterator Protocol \label{iterator}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	835
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	836 \versionadded{2.2}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	837
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	838 There are only a couple of functions specifically for working with
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	839 iterators.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	840
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	841 \begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	842 Return true if the object \var{o} supports the iterator protocol.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	843 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	844
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	845 \begin{cfuncdesc}{PyObject}{PyIter_Next}{PyObject o}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	846 Return the next value from the iteration \var{o}. If the object is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	847 an iterator, this retrieves the next value from the iteration, and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	848 returns \NULL{} with no exception set if there are no remaining
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	849 items. If the object is not an iterator, \exception{TypeError} is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	850 raised, or if there is an error in retrieving the item, returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	851 \NULL{} and passes along the exception.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	852 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	853
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	854 To write a loop which iterates over an iterator, the C code should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	855 look something like this:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	856
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	857 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	858 PyObject *iterator = ...;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	859 PyObject *item;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	860
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	861 while (item = PyIter_Next(iter)) {
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	862 /* do something with item */
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	863 }
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	864 if (PyErr_Occurred()) {
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	865 /* propogate error */
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	866 }
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	867 else {
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	868 /* continue doing useful work */
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	869 }
20946 ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	870
20948 9bfc31ca80f3 Added version annotations, remove hard tabs. Fred Drake <fdrake@acm.org> parents: 20946 diff changeset	871 \section{Buffer Protocol \label{abstract-buffer}}
20946 ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	872
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	873 \begin{cfuncdesc}{int}{PyObject_AsCharBuffer}{PyObject *obj,
20948 9bfc31ca80f3 Added version annotations, remove hard tabs. Fred Drake <fdrake@acm.org> parents: 20946 diff changeset	874 const char **buffer,
9bfc31ca80f3 Added version annotations, remove hard tabs. Fred Drake <fdrake@acm.org> parents: 20946 diff changeset	875 int *buffer_len}
20946 ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	876 Returns a pointer to a read-only memory location useable as character-
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	877 based input. The \var{obj} argument must support the single-segment
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	878 character buffer interface. On success, returns \code{1}, sets
20957 ca8bec4b3383 Fix obvious typos. Thomas Heller <theller@ctypes.org> parents: 20948 diff changeset	879 \var{buffer} to the memory location and \var{buffer_len} to the buffer
20946 ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	880 length. Returns \code{0} and sets a \exception{TypeError} on error.
20948 9bfc31ca80f3 Added version annotations, remove hard tabs. Fred Drake <fdrake@acm.org> parents: 20946 diff changeset	881 \versionadded{1.6}
20946 ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	882 \end{cfuncdesc}
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	883
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	884 \begin{cfuncdesc}{int}{PyObject_AsReadBuffer}{PyObject *obj,
20948 9bfc31ca80f3 Added version annotations, remove hard tabs. Fred Drake <fdrake@acm.org> parents: 20946 diff changeset	885 const char **buffer,
9bfc31ca80f3 Added version annotations, remove hard tabs. Fred Drake <fdrake@acm.org> parents: 20946 diff changeset	886 int *buffer_len}
20946 ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	887 Returns a pointer to a read-only memory location containing
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	888 arbitrary data. The \var{obj} argument must support the
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	889 single-segment readable buffer interface. On success, returns
20957 ca8bec4b3383 Fix obvious typos. Thomas Heller <theller@ctypes.org> parents: 20948 diff changeset	890 \code{1}, sets \var{buffer} to the memory location and \var{buffer_len}
20946 ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	891 to the buffer length. Returns \code{0} and sets a
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	892 \exception{TypeError} on error.
20948 9bfc31ca80f3 Added version annotations, remove hard tabs. Fred Drake <fdrake@acm.org> parents: 20946 diff changeset	893 \versionadded{1.6}
20946 ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	894 \end{cfuncdesc}
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	895
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	896 \begin{cfuncdesc}{int}{PyObject_CheckReadBuffer}{PyObject *o}
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	897 Returns \code{1} if \var{o} supports the single-segment readable
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	898 buffer interface. Otherwise returns \code{0}.
20948 9bfc31ca80f3 Added version annotations, remove hard tabs. Fred Drake <fdrake@acm.org> parents: 20946 diff changeset	899 \versionadded{2.2}
20946 ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	900 \enc{cfuncdesc}
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	901
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	902 \begin{cfuncdesc}{int}{PyObject_AsWriteBuffer}{PyObject *obj,
20948 9bfc31ca80f3 Added version annotations, remove hard tabs. Fred Drake <fdrake@acm.org> parents: 20946 diff changeset	903 const char **buffer,
9bfc31ca80f3 Added version annotations, remove hard tabs. Fred Drake <fdrake@acm.org> parents: 20946 diff changeset	904 int *buffer_len}
20946 ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	905 Returns a pointer to a writeable memory location. The \var{obj}
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	906 argument must support the single-segment, character buffer
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	907 interface. On success, returns \code{1}, sets \var{buffer} to the
20957 ca8bec4b3383 Fix obvious typos. Thomas Heller <theller@ctypes.org> parents: 20948 diff changeset	908 memory location and \var{buffer_len} to the buffer length. Returns
20946 ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	909 \code{0} and sets a \exception{TypeError} on error.
20948 9bfc31ca80f3 Added version annotations, remove hard tabs. Fred Drake <fdrake@acm.org> parents: 20946 diff changeset	910 \versionadded{1.6}
20946 ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	911 \end{cfuncdesc}
ef12c9ddefa7 Add PyObject_CheckReadBuffer(), which returns true if its argument Jeremy Hylton <jeremy@alum.mit.edu> parents: 20729 diff changeset	912
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	913 \end{verbatim}

Mercurial > cpython-lru_cache-weakref

annotate Doc/api/abstract.tex @ 21467:4e35fa5d5708 legacy-trunk