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