source: vendor/python/2.5/Doc/api/abstract.tex

Last change on this file was 3225, checked in by bird, 18 years ago

Python 2.5

File size: 43.8 KB
Line 
1\chapter{Abstract Objects Layer \label{abstract}}
2
3The functions in this chapter interact with Python objects regardless
4of their type, or with wide classes of object types (e.g. all
5numerical types, or all sequence types). When used on object types
6for which they do not apply, they will raise a Python exception.
7
8It is not possible to use these functions on objects that are not properly
9initialized, such as a list object that has been created by
10\cfunction{PyList_New()}, but whose items have not been set to some
11non-\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
194Subclass determination is done in a fairly straightforward way, but
195includes a wrinkle that implementors of extensions to the class system
196may want to be aware of. If \class{A} and \class{B} are class
197objects, \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
199object, a more general mechanism is used to determine the class
200relationship of the two objects. When testing if \var{B} is a
201subclass 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
204is searched in a depth-first fashion for \var{A} --- the presence of
205the \member{__bases__} attribute is considered sufficient for this
206determination.
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
972There are only a couple of functions specifically for working with
973iterators.
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
988To write a loop which iterates over an iterator, the C code should
989look something like this:
990
991\begin{verbatim}
992PyObject *iterator = PyObject_GetIter(obj);
993PyObject *item;
994
995if (iterator == NULL) {
996 /* propagate error */
997}
998
999while (item = PyIter_Next(iterator)) {
1000 /* do something with item */
1001 ...
1002 /* release reference when done */
1003 Py_DECREF(item);
1004}
1005
1006Py_DECREF(iterator);
1007
1008if (PyErr_Occurred()) {
1009 /* propagate error */
1010}
1011else {
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}
Note: See TracBrowser for help on using the repository browser.