blob: 44b5af72c9bd8d645727e44325fd9d0ab989d46a [file] [log] [blame]
Guido van Rossuma8275371995-07-18 14:07:00 +00001#ifndef Py_ABSTRACTOBJECT_H
2#define Py_ABSTRACTOBJECT_H
3#ifdef __cplusplus
4extern "C" {
5#endif
6
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00007#ifdef PY_SSIZE_T_CLEAN
8#define PyObject_CallFunction _PyObject_CallFunction_SizeT
9#define PyObject_CallMethod _PyObject_CallMethod_SizeT
Martin v. Löwisafe55bb2011-10-09 10:38:36 +020010#define _PyObject_CallMethodId _PyObject_CallMethodId_SizeT
Thomas Wouters49fd7fa2006-04-21 10:40:58 +000011#endif
12
Guido van Rossuma8275371995-07-18 14:07:00 +000013/* Abstract Object Interface (many thanks to Jim Fulton) */
14
15/*
16 PROPOSAL: A Generic Python Object Interface for Python C Modules
17
18Problem
19
20 Python modules written in C that must access Python objects must do
21 so through routines whose interfaces are described by a set of
22 include files. Unfortunately, these routines vary according to the
23 object accessed. To use these routines, the C programmer must check
24 the type of the object being used and must call a routine based on
25 the object type. For example, to access an element of a sequence,
26 the programmer must determine whether the sequence is a list or a
27 tuple:
28
29 if(is_tupleobject(o))
30 e=gettupleitem(o,i)
31 else if(is_listitem(o))
32 e=getlistitem(o,i)
33
34 If the programmer wants to get an item from another type of object
35 that provides sequence behavior, there is no clear way to do it
Antoine Pitrouf95a1b32010-05-09 15:52:27 +000036 correctly.
Guido van Rossuma8275371995-07-18 14:07:00 +000037
38 The persistent programmer may peruse object.h and find that the
39 _typeobject structure provides a means of invoking up to (currently
40 about) 41 special operators. So, for example, a routine can get an
41 item from any object that provides sequence behavior. However, to
42 use this mechanism, the programmer must make their code dependent on
43 the current Python implementation.
44
45 Also, certain semantics, especially memory management semantics, may
46 differ by the type of object being used. Unfortunately, these
47 semantics are not clearly described in the current include files.
Antoine Pitrouf95a1b32010-05-09 15:52:27 +000048 An abstract interface providing more consistent semantics is needed.
Guido van Rossuma8275371995-07-18 14:07:00 +000049
50Proposal
51
52 I propose the creation of a standard interface (with an associated
53 library of routines and/or macros) for generically obtaining the
54 services of Python objects. This proposal can be viewed as one
55 components of a Python C interface consisting of several components.
56
Raymond Hettingera72e2f92003-02-28 05:11:03 +000057 From the viewpoint of C access to Python services, we have (as
Guido van Rossuma8275371995-07-18 14:07:00 +000058 suggested by Guido in off-line discussions):
59
60 - "Very high level layer": two or three functions that let you exec or
61 eval arbitrary Python code given as a string in a module whose name is
62 given, passing C values in and getting C values out using
63 mkvalue/getargs style format strings. This does not require the user
64 to declare any variables of type "PyObject *". This should be enough
65 to write a simple application that gets Python code from the user,
66 execs it, and returns the output or errors. (Error handling must also
67 be part of this API.)
68
69 - "Abstract objects layer": which is the subject of this proposal.
70 It has many functions operating on objects, and lest you do many
71 things from C that you can also write in Python, without going
72 through the Python parser.
73
74 - "Concrete objects layer": This is the public type-dependent
75 interface provided by the standard built-in types, such as floats,
76 strings, and lists. This interface exists and is currently
Raymond Hettingera72e2f92003-02-28 05:11:03 +000077 documented by the collection of include files provided with the
Guido van Rossuma8275371995-07-18 14:07:00 +000078 Python distributions.
79
80 From the point of view of Python accessing services provided by C
Antoine Pitrouf95a1b32010-05-09 15:52:27 +000081 modules:
Guido van Rossuma8275371995-07-18 14:07:00 +000082
83 - "Python module interface": this interface consist of the basic
84 routines used to define modules and their members. Most of the
85 current extensions-writing guide deals with this interface.
86
87 - "Built-in object interface": this is the interface that a new
88 built-in type must provide and the mechanisms and rules that a
89 developer of a new built-in type must use and follow.
90
91 This proposal is a "first-cut" that is intended to spur
92 discussion. See especially the lists of notes.
93
94 The Python C object interface will provide four protocols: object,
95 numeric, sequence, and mapping. Each protocol consists of a
96 collection of related operations. If an operation that is not
97 provided by a particular type is invoked, then a standard exception,
98 NotImplementedError is raised with a operation name as an argument.
99 In addition, for convenience this interface defines a set of
100 constructors for building objects of built-in types. This is needed
101 so new objects can be returned from C functions that otherwise treat
102 objects generically.
103
104Memory Management
105
106 For all of the functions described in this proposal, if a function
107 retains a reference to a Python object passed as an argument, then the
108 function will increase the reference count of the object. It is
109 unnecessary for the caller to increase the reference count of an
110 argument in anticipation of the object's retention.
111
112 All Python objects returned from functions should be treated as new
113 objects. Functions that return objects assume that the caller will
114 retain a reference and the reference count of the object has already
115 been incremented to account for this fact. A caller that does not
116 retain a reference to an object that is returned from a function
117 must decrement the reference count of the object (using
118 DECREF(object)) to prevent memory leaks.
119
120 Note that the behavior mentioned here is different from the current
121 behavior for some objects (e.g. lists and tuples) when certain
122 type-specific routines are called directly (e.g. setlistitem). The
123 proposed abstraction layer will provide a consistent memory
124 management interface, correcting for inconsistent behavior for some
125 built-in types.
126
127Protocols
128
129xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
130
131/* Object Protocol: */
132
133 /* Implemented elsewhere:
134
135 int PyObject_Print(PyObject *o, FILE *fp, int flags);
136
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000137 Print an object, o, on file, fp. Returns -1 on
138 error. The flags argument is used to enable certain printing
139 options. The only option currently supported is Py_Print_RAW.
Guido van Rossuma8275371995-07-18 14:07:00 +0000140
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000141 (What should be said about Py_Print_RAW?)
Guido van Rossuma8275371995-07-18 14:07:00 +0000142
143 */
144
145 /* Implemented elsewhere:
146
147 int PyObject_HasAttrString(PyObject *o, char *attr_name);
148
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000149 Returns 1 if o has the attribute attr_name, and 0 otherwise.
150 This is equivalent to the Python expression:
151 hasattr(o,attr_name).
Guido van Rossuma8275371995-07-18 14:07:00 +0000152
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000153 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +0000154
155 */
156
157 /* Implemented elsewhere:
158
159 PyObject* PyObject_GetAttrString(PyObject *o, char *attr_name);
160
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000161 Retrieve an attributed named attr_name form object o.
162 Returns the attribute value on success, or NULL on failure.
163 This is the equivalent of the Python expression: o.attr_name.
Guido van Rossuma8275371995-07-18 14:07:00 +0000164
165 */
166
167 /* Implemented elsewhere:
168
169 int PyObject_HasAttr(PyObject *o, PyObject *attr_name);
170
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000171 Returns 1 if o has the attribute attr_name, and 0 otherwise.
172 This is equivalent to the Python expression:
173 hasattr(o,attr_name).
Guido van Rossuma8275371995-07-18 14:07:00 +0000174
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000175 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +0000176
177 */
178
179 /* Implemented elsewhere:
180
181 PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name);
182
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000183 Retrieve an attributed named attr_name form object o.
184 Returns the attribute value on success, or NULL on failure.
185 This is the equivalent of the Python expression: o.attr_name.
Guido van Rossuma8275371995-07-18 14:07:00 +0000186
187 */
188
189
190 /* Implemented elsewhere:
191
192 int PyObject_SetAttrString(PyObject *o, char *attr_name, PyObject *v);
193
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000194 Set the value of the attribute named attr_name, for object o,
195 to the value, v. Returns -1 on failure. This is
196 the equivalent of the Python statement: o.attr_name=v.
Guido van Rossuma8275371995-07-18 14:07:00 +0000197
198 */
199
200 /* Implemented elsewhere:
201
202 int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v);
203
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000204 Set the value of the attribute named attr_name, for object o,
205 to the value, v. Returns -1 on failure. This is
206 the equivalent of the Python statement: o.attr_name=v.
Guido van Rossuma8275371995-07-18 14:07:00 +0000207
208 */
209
210 /* implemented as a macro:
211
212 int PyObject_DelAttrString(PyObject *o, char *attr_name);
213
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000214 Delete attribute named attr_name, for object o. Returns
215 -1 on failure. This is the equivalent of the Python
216 statement: del o.attr_name.
Guido van Rossuma8275371995-07-18 14:07:00 +0000217
218 */
219#define PyObject_DelAttrString(O,A) PyObject_SetAttrString((O),(A),NULL)
220
221 /* implemented as a macro:
222
223 int PyObject_DelAttr(PyObject *o, PyObject *attr_name);
224
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000225 Delete attribute named attr_name, for object o. Returns -1
226 on failure. This is the equivalent of the Python
227 statement: del o.attr_name.
Guido van Rossuma8275371995-07-18 14:07:00 +0000228
229 */
230#define PyObject_DelAttr(O,A) PyObject_SetAttr((O),(A),NULL)
231
Guido van Rossuma8275371995-07-18 14:07:00 +0000232 /* Implemented elsewhere:
233
234 PyObject *PyObject_Repr(PyObject *o);
235
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000236 Compute the string representation of object, o. Returns the
237 string representation on success, NULL on failure. This is
238 the equivalent of the Python expression: repr(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000239
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000240 Called by the repr() built-in function.
Guido van Rossuma8275371995-07-18 14:07:00 +0000241
242 */
243
244 /* Implemented elsewhere:
245
246 PyObject *PyObject_Str(PyObject *o);
247
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000248 Compute the string representation of object, o. Returns the
249 string representation on success, NULL on failure. This is
250 the equivalent of the Python expression: str(o).)
Guido van Rossuma8275371995-07-18 14:07:00 +0000251
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000252 Called by the str() and print() built-in functions.
Marc-André Lemburgad7c98e2001-01-17 17:09:53 +0000253
254 */
255
Thomas Wouters89f507f2006-12-13 04:49:30 +0000256 /* Declared elsewhere
257
Mark Hammond91a681d2002-08-12 07:21:58 +0000258 PyAPI_FUNC(int) PyCallable_Check(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000259
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000260 Determine if the object, o, is callable. Return 1 if the
261 object is callable and 0 otherwise.
Guido van Rossuma8275371995-07-18 14:07:00 +0000262
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000263 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +0000264 */
265
Mark Hammond91a681d2002-08-12 07:21:58 +0000266 PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable_object,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000267 PyObject *args, PyObject *kw);
Tim Peters6d6c1a32001-08-02 04:15:00 +0000268
269 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000270 Call a callable Python object, callable_object, with
271 arguments and keywords arguments. The 'args' argument can not be
272 NULL, but the 'kw' argument can be NULL.
Tim Peters6d6c1a32001-08-02 04:15:00 +0000273 */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000274
Mark Hammond91a681d2002-08-12 07:21:58 +0000275 PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable_object,
Neal Norwitzfe554642006-03-17 06:58:45 +0000276 PyObject *args);
Guido van Rossuma8275371995-07-18 14:07:00 +0000277
278 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000279 Call a callable Python object, callable_object, with
280 arguments given by the tuple, args. If no arguments are
281 needed, then args may be NULL. Returns the result of the
282 call on success, or NULL on failure. This is the equivalent
283 of the Python expression: o(*args).
Guido van Rossuma8275371995-07-18 14:07:00 +0000284 */
285
Mark Hammond91a681d2002-08-12 07:21:58 +0000286 PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable_object,
Neal Norwitzfe554642006-03-17 06:58:45 +0000287 char *format, ...);
Guido van Rossuma8275371995-07-18 14:07:00 +0000288
289 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000290 Call a callable Python object, callable_object, with a
291 variable number of C arguments. The C arguments are described
292 using a mkvalue-style format string. The format may be NULL,
293 indicating that no arguments are provided. Returns the
294 result of the call on success, or NULL on failure. This is
295 the equivalent of the Python expression: o(*args).
Guido van Rossuma8275371995-07-18 14:07:00 +0000296 */
297
298
Neal Norwitzfe554642006-03-17 06:58:45 +0000299 PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *o, char *method,
300 char *format, ...);
Guido van Rossuma8275371995-07-18 14:07:00 +0000301
302 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000303 Call the method named m of object o with a variable number of
304 C arguments. The C arguments are described by a mkvalue
305 format string. The format may be NULL, indicating that no
306 arguments are provided. Returns the result of the call on
307 success, or NULL on failure. This is the equivalent of the
308 Python expression: o.method(args).
Fred Drakeb421b8c2001-10-26 16:21:32 +0000309 */
Guido van Rossuma8275371995-07-18 14:07:00 +0000310
Martin v. Löwisafe55bb2011-10-09 10:38:36 +0200311 PyAPI_FUNC(PyObject *) _PyObject_CallMethodId(PyObject *o, _Py_Identifier *method,
312 char *format, ...);
313
314 /*
315 Like PyObject_CallMethod, but expect a _Py_Identifier* as the
316 method name.
317 */
318
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000319 PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000320 char *format, ...);
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000321 PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *o,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000322 char *name,
323 char *format, ...);
Martin v. Löwisafe55bb2011-10-09 10:38:36 +0200324 PyAPI_FUNC(PyObject *) _PyObject_CallMethodId_SizeT(PyObject *o,
325 _Py_Identifier *name,
326 char *format, ...);
Guido van Rossuma8275371995-07-18 14:07:00 +0000327
Mark Hammond91a681d2002-08-12 07:21:58 +0000328 PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,
Neal Norwitzfe554642006-03-17 06:58:45 +0000329 ...);
Fred Drakeb421b8c2001-10-26 16:21:32 +0000330
331 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000332 Call a callable Python object, callable_object, with a
333 variable number of C arguments. The C arguments are provided
334 as PyObject * values, terminated by a NULL. Returns the
335 result of the call on success, or NULL on failure. This is
336 the equivalent of the Python expression: o(*args).
Fred Drakeb421b8c2001-10-26 16:21:32 +0000337 */
338
339
Mark Hammond91a681d2002-08-12 07:21:58 +0000340 PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(PyObject *o,
Neal Norwitzfe554642006-03-17 06:58:45 +0000341 PyObject *method, ...);
Brett Cannonfd074152012-04-14 14:10:13 -0400342 PyAPI_FUNC(PyObject *) _PyObject_CallMethodObjIdArgs(PyObject *o,
343 struct _Py_Identifier *method,
344 ...);
345
Fred Drakeb421b8c2001-10-26 16:21:32 +0000346
347 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000348 Call the method named m of object o with a variable number of
349 C arguments. The C arguments are provided as PyObject *
350 values, terminated by NULL. Returns the result of the call
351 on success, or NULL on failure. This is the equivalent of
352 the Python expression: o.method(args).
Guido van Rossuma8275371995-07-18 14:07:00 +0000353 */
354
355
356 /* Implemented elsewhere:
357
358 long PyObject_Hash(PyObject *o);
359
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000360 Compute and return the hash, hash_value, of an object, o. On
361 failure, return -1. This is the equivalent of the Python
362 expression: hash(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000363 */
364
365
366 /* Implemented elsewhere:
367
368 int PyObject_IsTrue(PyObject *o);
369
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000370 Returns 1 if the object, o, is considered to be true, 0 if o is
371 considered to be false and -1 on failure. This is equivalent to the
372 Python expression: not not o
Guido van Rossuma8275371995-07-18 14:07:00 +0000373 */
374
Guido van Rossumc3d3f961998-04-09 17:53:59 +0000375 /* Implemented elsewhere:
376
377 int PyObject_Not(PyObject *o);
378
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000379 Returns 0 if the object, o, is considered to be true, 1 if o is
380 considered to be false and -1 on failure. This is equivalent to the
381 Python expression: not o
Guido van Rossumc3d3f961998-04-09 17:53:59 +0000382 */
383
Mark Hammond91a681d2002-08-12 07:21:58 +0000384 PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000385
386 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000387 On success, returns a type object corresponding to the object
388 type of object o. On failure, returns NULL. This is
389 equivalent to the Python expression: type(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000390 */
391
Martin v. Löwis18e16552006-02-15 17:27:45 +0000392 PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
Jeremy Hylton6253f832000-07-12 12:56:19 +0000393
Guido van Rossuma8275371995-07-18 14:07:00 +0000394 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000395 Return the size of object o. If the object, o, provides
396 both sequence and mapping protocols, the sequence size is
397 returned. On error, -1 is returned. This is the equivalent
398 to the Python expression: len(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000399 */
400
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000401 /* For DLL compatibility */
402#undef PyObject_Length
Martin v. Löwis18e16552006-02-15 17:27:45 +0000403 PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000404#define PyObject_Length PyObject_Size
405
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000406#ifndef Py_LIMITED_API
Christian Heimes255f53b2007-12-08 15:33:56 +0000407 PyAPI_FUNC(Py_ssize_t) _PyObject_LengthHint(PyObject *o, Py_ssize_t);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000408#endif
Raymond Hettinger6b27cda2005-09-24 21:23:05 +0000409
410 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000411 Guess the size of object o using len(o) or o.__length_hint__().
412 If neither of those return a non-negative value, then return the
413 default value. If one of the calls fails, this function returns -1.
Raymond Hettinger6b27cda2005-09-24 21:23:05 +0000414 */
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000415
Mark Hammond91a681d2002-08-12 07:21:58 +0000416 PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
Guido van Rossuma8275371995-07-18 14:07:00 +0000417
418 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000419 Return element of o corresponding to the object, key, or NULL
420 on failure. This is the equivalent of the Python expression:
421 o[key].
Guido van Rossuma8275371995-07-18 14:07:00 +0000422 */
423
Mark Hammond91a681d2002-08-12 07:21:58 +0000424 PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
Guido van Rossuma8275371995-07-18 14:07:00 +0000425
426 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000427 Map the object, key, to the value, v. Returns
428 -1 on failure. This is the equivalent of the Python
429 statement: o[key]=v.
Guido van Rossuma8275371995-07-18 14:07:00 +0000430 */
431
Mark Hammond91a681d2002-08-12 07:21:58 +0000432 PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, char *key);
Martin v. Löwisb0d71d02002-01-05 10:50:30 +0000433
434 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000435 Remove the mapping for object, key, from the object *o.
436 Returns -1 on failure. This is equivalent to
437 the Python statement: del o[key].
Martin v. Löwisb0d71d02002-01-05 10:50:30 +0000438 */
439
Mark Hammond91a681d2002-08-12 07:21:58 +0000440 PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
Guido van Rossum6cdc6f41996-08-21 17:41:54 +0000441
442 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000443 Delete the mapping for key from *o. Returns -1 on failure.
444 This is the equivalent of the Python statement: del o[key].
Guido van Rossum6cdc6f41996-08-21 17:41:54 +0000445 */
446
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000447 /* old buffer API
448 FIXME: usage of these should all be replaced in Python itself
449 but for backwards compatibility we will implement them.
450 Their usage without a corresponding "unlock" mechansim
451 may create issues (but they would already be there). */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000452
Mark Hammond91a681d2002-08-12 07:21:58 +0000453 PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000454 const char **buffer,
455 Py_ssize_t *buffer_len);
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000456
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000457 /*
458 Takes an arbitrary object which must support the (character,
459 single segment) buffer interface and returns a pointer to a
460 read-only memory location useable as character based input
461 for subsequent processing.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000462
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000463 0 is returned on success. buffer and buffer_len are only
464 set in case no error occurs. Otherwise, -1 is returned and
465 an exception set.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000466 */
467
Mark Hammond91a681d2002-08-12 07:21:58 +0000468 PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);
Jeremy Hylton89c3a222001-11-09 21:59:42 +0000469
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000470 /*
471 Checks whether an arbitrary object supports the (character,
472 single segment) buffer interface. Returns 1 on success, 0
473 on failure.
Jeremy Hylton89c3a222001-11-09 21:59:42 +0000474 */
475
Mark Hammond91a681d2002-08-12 07:21:58 +0000476 PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000477 const void **buffer,
478 Py_ssize_t *buffer_len);
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000479
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000480 /*
481 Same as PyObject_AsCharBuffer() except that this API expects
482 (readable, single segment) buffer interface and returns a
483 pointer to a read-only memory location which can contain
484 arbitrary data.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000485
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000486 0 is returned on success. buffer and buffer_len are only
Ezio Melotti13925002011-03-16 11:05:33 +0200487 set in case no error occurs. Otherwise, -1 is returned and
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000488 an exception set.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000489 */
490
Mark Hammond91a681d2002-08-12 07:21:58 +0000491 PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000492 void **buffer,
493 Py_ssize_t *buffer_len);
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000494
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000495 /*
496 Takes an arbitrary object which must support the (writable,
497 single segment) buffer interface and returns a pointer to a
498 writable memory location in buffer of size buffer_len.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000499
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000500 0 is returned on success. buffer and buffer_len are only
Ezio Melotti13925002011-03-16 11:05:33 +0200501 set in case no error occurs. Otherwise, -1 is returned and
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000502 an exception set.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000503 */
Guido van Rossuma8275371995-07-18 14:07:00 +0000504
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000505 /* new buffer API */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000506
Martin v. Löwisc83bc3c2011-01-06 19:15:47 +0000507#ifndef Py_LIMITED_API
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000508#define PyObject_CheckBuffer(obj) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000509 (((obj)->ob_type->tp_as_buffer != NULL) && \
510 ((obj)->ob_type->tp_as_buffer->bf_getbuffer != NULL))
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000511
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000512 /* Return 1 if the getbuffer function is available, otherwise
513 return 0 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000514
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000515 PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view,
516 int flags);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000517
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000518 /* This is a C-API version of the getbuffer function call. It checks
519 to make sure object has the required function pointer and issues the
520 call. Returns -1 and raises an error on failure and returns 0 on
521 success
522 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000523
524
Travis E. Oliphant8ae62b62007-09-23 02:00:13 +0000525 PyAPI_FUNC(void *) PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices);
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000526
527 /* Get the memory area pointed to by the indices for the buffer given.
528 Note that view->ndim is the assumed size of indices
529 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000530
531 PyAPI_FUNC(int) PyBuffer_SizeFromFormat(const char *);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000532
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000533 /* Return the implied itemsize of the data-format area from a
534 struct-style description */
535
536
537
Stefan Krah7d12d9d2012-07-28 12:25:55 +0200538 /* Implementation in memoryobject.c */
Travis E. Oliphant8ae62b62007-09-23 02:00:13 +0000539 PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, Py_buffer *view,
Stefan Krah7d12d9d2012-07-28 12:25:55 +0200540 Py_ssize_t len, char order);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000541
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000542 PyAPI_FUNC(int) PyBuffer_FromContiguous(Py_buffer *view, void *buf,
Stefan Krah7d12d9d2012-07-28 12:25:55 +0200543 Py_ssize_t len, char order);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000544
545
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000546 /* Copy len bytes of data from the contiguous chunk of memory
547 pointed to by buf into the buffer exported by obj. Return
548 0 on success and return -1 and raise a PyBuffer_Error on
549 error (i.e. the object does not have a buffer interface or
550 it is not working).
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000551
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000552 If fort is 'F', then if the object is multi-dimensional,
553 then the data will be copied into the array in
554 Fortran-style (first dimension varies the fastest). If
555 fort is 'C', then the data will be copied into the array
556 in C-style (last dimension varies the fastest). If fort
557 is 'A', then it does not matter and the copy will be made
558 in whatever way is more efficient.
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000559
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000560 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000561
562 PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000563
564 /* Copy the data from the src buffer to the buffer of destination
565 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000566
Stefan Krah9a2d99e2012-02-25 12:24:21 +0100567 PyAPI_FUNC(int) PyBuffer_IsContiguous(const Py_buffer *view, char fort);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000568
569
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000570 PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims,
571 Py_ssize_t *shape,
572 Py_ssize_t *strides,
573 int itemsize,
574 char fort);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000575
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000576 /* Fill the strides array with byte-strides of a contiguous
577 (Fortran-style if fort is 'F' or C-style otherwise)
578 array of the given shape with the given number of bytes
579 per element.
580 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000581
Martin v. Löwis423be952008-08-13 15:53:07 +0000582 PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000583 Py_ssize_t len, int readonly,
584 int flags);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000585
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000586 /* Fills in a buffer-info structure correctly for an exporter
587 that can only share a contiguous chunk of memory of
588 "unsigned bytes" of the given length. Returns 0 on success
589 and -1 (with raising an error) on error.
590 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000591
Martin v. Löwis423be952008-08-13 15:53:07 +0000592 PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);
593
594 /* Releases a Py_buffer obtained from getbuffer ParseTuple's s*.
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000595 */
Martin v. Löwisc83bc3c2011-01-06 19:15:47 +0000596#endif /* Py_LIMITED_API */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000597
Eric Smith8fd3eba2008-02-17 19:48:00 +0000598 PyAPI_FUNC(PyObject *) PyObject_Format(PyObject* obj,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000599 PyObject *format_spec);
Eric Smith8fd3eba2008-02-17 19:48:00 +0000600 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000601 Takes an arbitrary object and returns the result of
602 calling obj.__format__(format_spec).
Eric Smith8fd3eba2008-02-17 19:48:00 +0000603 */
604
Guido van Rossum213c7a62001-04-23 14:08:49 +0000605/* Iterators */
606
Mark Hammond91a681d2002-08-12 07:21:58 +0000607 PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);
Guido van Rossum59d1d2b2001-04-20 19:13:02 +0000608 /* Takes an object and returns an iterator for it.
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000609 This is typically a new iterator but if the argument
610 is an iterator, this returns itself. */
Guido van Rossum59d1d2b2001-04-20 19:13:02 +0000611
Guido van Rossum213c7a62001-04-23 14:08:49 +0000612#define PyIter_Check(obj) \
Amaury Forgeot d'Arcf343e012009-01-12 23:58:21 +0000613 ((obj)->ob_type->tp_iternext != NULL && \
614 (obj)->ob_type->tp_iternext != &_PyObject_NextNotImplemented)
Guido van Rossum213c7a62001-04-23 14:08:49 +0000615
Mark Hammond91a681d2002-08-12 07:21:58 +0000616 PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);
Guido van Rossum213c7a62001-04-23 14:08:49 +0000617 /* Takes an iterator object and calls its tp_iternext slot,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000618 returning the next value. If the iterator is exhausted,
619 this returns NULL without setting an exception.
620 NULL with an exception means an error occurred. */
Guido van Rossum213c7a62001-04-23 14:08:49 +0000621
Guido van Rossuma8275371995-07-18 14:07:00 +0000622/* Number Protocol:*/
623
Mark Hammond91a681d2002-08-12 07:21:58 +0000624 PyAPI_FUNC(int) PyNumber_Check(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000625
626 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000627 Returns 1 if the object, o, provides numeric protocols, and
628 false otherwise.
Guido van Rossuma8275371995-07-18 14:07:00 +0000629
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000630 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +0000631 */
632
Mark Hammond91a681d2002-08-12 07:21:58 +0000633 PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000634
635 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000636 Returns the result of adding o1 and o2, or null on failure.
637 This is the equivalent of the Python expression: o1+o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000638 */
639
Mark Hammond91a681d2002-08-12 07:21:58 +0000640 PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000641
642 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000643 Returns the result of subtracting o2 from o1, or null on
644 failure. This is the equivalent of the Python expression:
645 o1-o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000646 */
647
Mark Hammond91a681d2002-08-12 07:21:58 +0000648 PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000649
650 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000651 Returns the result of multiplying o1 and o2, or null on
652 failure. This is the equivalent of the Python expression:
653 o1*o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000654 */
655
Mark Hammond91a681d2002-08-12 07:21:58 +0000656 PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2);
Guido van Rossum4668b002001-08-08 05:00:18 +0000657
658 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000659 Returns the result of dividing o1 by o2 giving an integral result,
660 or null on failure.
661 This is the equivalent of the Python expression: o1//o2.
Guido van Rossum4668b002001-08-08 05:00:18 +0000662 */
663
Mark Hammond91a681d2002-08-12 07:21:58 +0000664 PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2);
Guido van Rossum4668b002001-08-08 05:00:18 +0000665
666 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000667 Returns the result of dividing o1 by o2 giving a float result,
668 or null on failure.
669 This is the equivalent of the Python expression: o1/o2.
Guido van Rossum4668b002001-08-08 05:00:18 +0000670 */
671
Mark Hammond91a681d2002-08-12 07:21:58 +0000672 PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000673
674 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000675 Returns the remainder of dividing o1 by o2, or null on
676 failure. This is the equivalent of the Python expression:
677 o1%o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000678 */
679
Mark Hammond91a681d2002-08-12 07:21:58 +0000680 PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000681
682 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000683 See the built-in function divmod. Returns NULL on failure.
684 This is the equivalent of the Python expression:
685 divmod(o1,o2).
Guido van Rossuma8275371995-07-18 14:07:00 +0000686 */
687
Mark Hammond91a681d2002-08-12 07:21:58 +0000688 PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,
Neal Norwitzfe554642006-03-17 06:58:45 +0000689 PyObject *o3);
Guido van Rossuma8275371995-07-18 14:07:00 +0000690
691 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000692 See the built-in function pow. Returns NULL on failure.
693 This is the equivalent of the Python expression:
694 pow(o1,o2,o3), where o3 is optional.
Guido van Rossuma8275371995-07-18 14:07:00 +0000695 */
696
Mark Hammond91a681d2002-08-12 07:21:58 +0000697 PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000698
699 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000700 Returns the negation of o on success, or null on failure.
701 This is the equivalent of the Python expression: -o.
Guido van Rossuma8275371995-07-18 14:07:00 +0000702 */
703
Mark Hammond91a681d2002-08-12 07:21:58 +0000704 PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000705
706 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000707 Returns the (what?) of o on success, or NULL on failure.
708 This is the equivalent of the Python expression: +o.
Guido van Rossuma8275371995-07-18 14:07:00 +0000709 */
710
Mark Hammond91a681d2002-08-12 07:21:58 +0000711 PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000712
713 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000714 Returns the absolute value of o, or null on failure. This is
715 the equivalent of the Python expression: abs(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000716 */
717
Mark Hammond91a681d2002-08-12 07:21:58 +0000718 PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000719
720 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000721 Returns the bitwise negation of o on success, or NULL on
722 failure. This is the equivalent of the Python expression:
723 ~o.
Guido van Rossuma8275371995-07-18 14:07:00 +0000724 */
725
Mark Hammond91a681d2002-08-12 07:21:58 +0000726 PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000727
728 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000729 Returns the result of left shifting o1 by o2 on success, or
730 NULL on failure. This is the equivalent of the Python
731 expression: o1 << o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000732 */
733
Mark Hammond91a681d2002-08-12 07:21:58 +0000734 PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000735
736 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000737 Returns the result of right shifting o1 by o2 on success, or
738 NULL on failure. This is the equivalent of the Python
739 expression: o1 >> o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000740 */
741
Mark Hammond91a681d2002-08-12 07:21:58 +0000742 PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000743
744 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000745 Returns the result of bitwise and of o1 and o2 on success, or
746 NULL on failure. This is the equivalent of the Python
747 expression: o1&o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000748
Guido van Rossuma8275371995-07-18 14:07:00 +0000749 */
750
Mark Hammond91a681d2002-08-12 07:21:58 +0000751 PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000752
753 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000754 Returns the bitwise exclusive or of o1 by o2 on success, or
755 NULL on failure. This is the equivalent of the Python
756 expression: o1^o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000757 */
758
Mark Hammond91a681d2002-08-12 07:21:58 +0000759 PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000760
761 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000762 Returns the result of bitwise or on o1 and o2 on success, or
763 NULL on failure. This is the equivalent of the Python
764 expression: o1|o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000765 */
766
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000767#define PyIndex_Check(obj) \
768 ((obj)->ob_type->tp_as_number != NULL && \
769 (obj)->ob_type->tp_as_number->nb_index != NULL)
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000770
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000771 PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o);
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000772
773 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000774 Returns the object converted to a Python long or int
775 or NULL with an error raised on failure.
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000776 */
777
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000778 PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc);
779
780 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000781 Returns the object converted to Py_ssize_t by going through
782 PyNumber_Index first. If an overflow error occurs while
783 converting the int-or-long to Py_ssize_t, then the second argument
784 is the error-type to return. If it is NULL, then the overflow error
785 is cleared and the value is clipped.
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000786 */
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000787
Mark Dickinsond7467682009-01-10 22:14:33 +0000788 PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);
789
Guido van Rossuma8275371995-07-18 14:07:00 +0000790 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000791 Returns the o converted to an integer object on success, or
792 NULL on failure. This is the equivalent of the Python
793 expression: int(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000794 */
795
Mark Hammond91a681d2002-08-12 07:21:58 +0000796 PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000797
798 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000799 Returns the o converted to a float object on success, or NULL
800 on failure. This is the equivalent of the Python expression:
801 float(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000802 */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000803
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000804/* In-place variants of (some of) the above number protocol functions */
805
Mark Hammond91a681d2002-08-12 07:21:58 +0000806 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000807
808 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000809 Returns the result of adding o2 to o1, possibly in-place, or null
810 on failure. This is the equivalent of the Python expression:
811 o1 += o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000812 */
813
Mark Hammond91a681d2002-08-12 07:21:58 +0000814 PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000815
816 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000817 Returns the result of subtracting o2 from o1, possibly in-place or
818 null on failure. This is the equivalent of the Python expression:
819 o1 -= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000820 */
821
Mark Hammond91a681d2002-08-12 07:21:58 +0000822 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000823
824 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000825 Returns the result of multiplying o1 by o2, possibly in-place, or
826 null on failure. This is the equivalent of the Python expression:
827 o1 *= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000828 */
829
Mark Hammond91a681d2002-08-12 07:21:58 +0000830 PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000831 PyObject *o2);
Guido van Rossum4668b002001-08-08 05:00:18 +0000832
833 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000834 Returns the result of dividing o1 by o2 giving an integral result,
835 possibly in-place, or null on failure.
836 This is the equivalent of the Python expression:
837 o1 /= o2.
Guido van Rossum4668b002001-08-08 05:00:18 +0000838 */
839
Mark Hammond91a681d2002-08-12 07:21:58 +0000840 PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000841 PyObject *o2);
Guido van Rossum4668b002001-08-08 05:00:18 +0000842
843 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000844 Returns the result of dividing o1 by o2 giving a float result,
845 possibly in-place, or null on failure.
846 This is the equivalent of the Python expression:
847 o1 /= o2.
Guido van Rossum4668b002001-08-08 05:00:18 +0000848 */
849
Mark Hammond91a681d2002-08-12 07:21:58 +0000850 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000851
852 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000853 Returns the remainder of dividing o1 by o2, possibly in-place, or
854 null on failure. This is the equivalent of the Python expression:
855 o1 %= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000856 */
857
Mark Hammond91a681d2002-08-12 07:21:58 +0000858 PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000859 PyObject *o3);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000860
861 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000862 Returns the result of raising o1 to the power of o2, possibly
863 in-place, or null on failure. This is the equivalent of the Python
864 expression: o1 **= o2, or pow(o1, o2, o3) if o3 is present.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000865 */
866
Mark Hammond91a681d2002-08-12 07:21:58 +0000867 PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000868
869 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000870 Returns the result of left shifting o1 by o2, possibly in-place, or
871 null on failure. This is the equivalent of the Python expression:
872 o1 <<= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000873 */
874
Mark Hammond91a681d2002-08-12 07:21:58 +0000875 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000876
877 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000878 Returns the result of right shifting o1 by o2, possibly in-place or
879 null on failure. This is the equivalent of the Python expression:
880 o1 >>= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000881 */
882
Mark Hammond91a681d2002-08-12 07:21:58 +0000883 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000884
885 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000886 Returns the result of bitwise and of o1 and o2, possibly in-place,
887 or null on failure. This is the equivalent of the Python
888 expression: o1 &= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000889 */
890
Mark Hammond91a681d2002-08-12 07:21:58 +0000891 PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000892
893 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000894 Returns the bitwise exclusive or of o1 by o2, possibly in-place, or
895 null on failure. This is the equivalent of the Python expression:
896 o1 ^= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000897 */
898
Mark Hammond91a681d2002-08-12 07:21:58 +0000899 PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000900
901 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000902 Returns the result of bitwise or of o1 and o2, possibly in-place,
903 or null on failure. This is the equivalent of the Python
904 expression: o1 |= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000905 */
906
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000907 PyAPI_FUNC(PyObject *) PyNumber_ToBase(PyObject *n, int base);
908
909 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000910 Returns the integer n converted to a string with a base, with a base
911 marker of 0b, 0o or 0x prefixed if applicable.
912 If n is not an int object, it is converted with PyNumber_Index first.
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000913 */
914
Guido van Rossuma8275371995-07-18 14:07:00 +0000915
916/* Sequence protocol:*/
917
Mark Hammond91a681d2002-08-12 07:21:58 +0000918 PyAPI_FUNC(int) PySequence_Check(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000919
920 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000921 Return 1 if the object provides sequence protocol, and zero
922 otherwise.
Guido van Rossuma8275371995-07-18 14:07:00 +0000923
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000924 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +0000925 */
926
Martin v. Löwis18e16552006-02-15 17:27:45 +0000927 PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
Jeremy Hylton6253f832000-07-12 12:56:19 +0000928
Guido van Rossum4f4ce681996-07-21 02:22:56 +0000929 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000930 Return the size of sequence object o, or -1 on failure.
Guido van Rossum4f4ce681996-07-21 02:22:56 +0000931 */
932
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000933 /* For DLL compatibility */
934#undef PySequence_Length
Martin v. Löwis18e16552006-02-15 17:27:45 +0000935 PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000936#define PySequence_Length PySequence_Size
937
938
Mark Hammond91a681d2002-08-12 07:21:58 +0000939 PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000940
941 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000942 Return the concatenation of o1 and o2 on success, and NULL on
943 failure. This is the equivalent of the Python
944 expression: o1+o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000945 */
946
Martin v. Löwis18e16552006-02-15 17:27:45 +0000947 PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count);
Guido van Rossuma8275371995-07-18 14:07:00 +0000948
949 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000950 Return the result of repeating sequence object o count times,
951 or NULL on failure. This is the equivalent of the Python
952 expression: o1*count.
Guido van Rossuma8275371995-07-18 14:07:00 +0000953 */
954
Martin v. Löwis18e16552006-02-15 17:27:45 +0000955 PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i);
Guido van Rossuma8275371995-07-18 14:07:00 +0000956
957 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000958 Return the ith element of o, or NULL on failure. This is the
959 equivalent of the Python expression: o[i].
Guido van Rossuma8275371995-07-18 14:07:00 +0000960 */
961
Martin v. Löwis18e16552006-02-15 17:27:45 +0000962 PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000963
964 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000965 Return the slice of sequence object o between i1 and i2, or
966 NULL on failure. This is the equivalent of the Python
967 expression: o[i1:i2].
Guido van Rossuma8275371995-07-18 14:07:00 +0000968 */
969
Martin v. Löwis18e16552006-02-15 17:27:45 +0000970 PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);
Guido van Rossuma8275371995-07-18 14:07:00 +0000971
972 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000973 Assign object v to the ith element of o. Returns
974 -1 on failure. This is the equivalent of the Python
975 statement: o[i]=v.
Guido van Rossuma8275371995-07-18 14:07:00 +0000976 */
977
Martin v. Löwis18e16552006-02-15 17:27:45 +0000978 PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
Guido van Rossum6cdc6f41996-08-21 17:41:54 +0000979
980 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000981 Delete the ith element of object v. Returns
982 -1 on failure. This is the equivalent of the Python
983 statement: del o[i].
Guido van Rossum6cdc6f41996-08-21 17:41:54 +0000984 */
985
Martin v. Löwis18e16552006-02-15 17:27:45 +0000986 PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2,
Neal Norwitzfe554642006-03-17 06:58:45 +0000987 PyObject *v);
Guido van Rossuma8275371995-07-18 14:07:00 +0000988
989 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000990 Assign the sequence object, v, to the slice in sequence
991 object, o, from i1 to i2. Returns -1 on failure. This is the
992 equivalent of the Python statement: o[i1:i2]=v.
Guido van Rossuma8275371995-07-18 14:07:00 +0000993 */
994
Martin v. Löwis18e16552006-02-15 17:27:45 +0000995 PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
Guido van Rossum6cdc6f41996-08-21 17:41:54 +0000996
997 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000998 Delete the slice in sequence object, o, from i1 to i2.
999 Returns -1 on failure. This is the equivalent of the Python
1000 statement: del o[i1:i2].
Guido van Rossum6cdc6f41996-08-21 17:41:54 +00001001 */
1002
Mark Hammond91a681d2002-08-12 07:21:58 +00001003 PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001004
1005 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001006 Returns the sequence, o, as a tuple on success, and NULL on failure.
1007 This is equivalent to the Python expression: tuple(o)
Guido van Rossuma8275371995-07-18 14:07:00 +00001008 */
1009
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001010
Mark Hammond91a681d2002-08-12 07:21:58 +00001011 PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);
Guido van Rossum2adf06b1996-12-05 21:48:50 +00001012 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001013 Returns the sequence, o, as a list on success, and NULL on failure.
1014 This is equivalent to the Python expression: list(o)
Guido van Rossum2adf06b1996-12-05 21:48:50 +00001015 */
Guido van Rossumf39fc431997-03-04 18:31:47 +00001016
Mark Hammond91a681d2002-08-12 07:21:58 +00001017 PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001018 /*
Larry Hastings06447412012-03-05 22:59:13 -08001019 Returns the sequence, o, as a list, unless it's already a
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001020 tuple or list. Use PySequence_Fast_GET_ITEM to access the
1021 members of this list, and PySequence_Fast_GET_SIZE to get its length.
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001022
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001023 Returns NULL on failure. If the object does not support iteration,
1024 raises a TypeError exception with m as the message text.
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001025 */
1026
Tim Peters1fc240e2001-10-26 05:06:50 +00001027#define PySequence_Fast_GET_SIZE(o) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001028 (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o))
Tim Peters1fc240e2001-10-26 05:06:50 +00001029 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001030 Return the size of o, assuming that o was returned by
1031 PySequence_Fast and is not NULL.
Tim Peters1fc240e2001-10-26 05:06:50 +00001032 */
1033
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001034#define PySequence_Fast_GET_ITEM(o, i)\
1035 (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i))
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001036 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001037 Return the ith element of o, assuming that o was returned by
1038 PySequence_Fast, and that i is within bounds.
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001039 */
1040
Martin v. Löwis01f94bd2002-05-08 08:44:21 +00001041#define PySequence_ITEM(o, i)\
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001042 ( Py_TYPE(o)->tp_as_sequence->sq_item(o, i) )
Martin v. Löwis01f94bd2002-05-08 08:44:21 +00001043 /* Assume tp_as_sequence and sq_item exist and that i does not
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001044 need to be corrected for a negative index
1045 */
Martin v. Löwis01f94bd2002-05-08 08:44:21 +00001046
Raymond Hettinger42bec932004-03-12 16:38:17 +00001047#define PySequence_Fast_ITEMS(sf) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001048 (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \
1049 : ((PyTupleObject *)(sf))->ob_item)
1050 /* Return a pointer to the underlying item array for
1051 an object retured by PySequence_Fast */
Raymond Hettingerc1e4f9d2004-03-12 08:04:00 +00001052
Neal Norwitz1fc4b772006-03-04 18:49:58 +00001053 PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value);
Guido van Rossuma8275371995-07-18 14:07:00 +00001054
1055 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001056 Return the number of occurrences on value on o, that is,
1057 return the number of keys for which o[key]==value. On
1058 failure, return -1. This is equivalent to the Python
1059 expression: o.count(value).
Guido van Rossuma8275371995-07-18 14:07:00 +00001060 */
1061
Mark Hammond91a681d2002-08-12 07:21:58 +00001062 PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob);
Tim Peterscb8d3682001-05-05 21:05:01 +00001063 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001064 Return -1 if error; 1 if ob in seq; 0 if ob not in seq.
1065 Use __contains__ if possible, else _PySequence_IterSearch().
Tim Peterscb8d3682001-05-05 21:05:01 +00001066 */
1067
Martin v. Löwis4d0d4712010-12-03 20:14:31 +00001068#ifndef Py_LIMITED_API
Tim Peters16a77ad2001-09-08 04:00:12 +00001069#define PY_ITERSEARCH_COUNT 1
1070#define PY_ITERSEARCH_INDEX 2
1071#define PY_ITERSEARCH_CONTAINS 3
Neal Norwitz1fc4b772006-03-04 18:49:58 +00001072 PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001073 PyObject *obj, int operation);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +00001074#endif
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001075 /*
1076 Iterate over seq. Result depends on the operation:
1077 PY_ITERSEARCH_COUNT: return # of times obj appears in seq; -1 if
1078 error.
1079 PY_ITERSEARCH_INDEX: return 0-based index of first occurrence of
1080 obj in seq; set ValueError and return -1 if none found;
1081 also return -1 on error.
1082 PY_ITERSEARCH_CONTAINS: return 1 if obj in seq, else 0; -1 on
1083 error.
1084 */
Guido van Rossum83684531999-03-17 18:44:39 +00001085
1086/* For DLL-level backwards compatibility */
1087#undef PySequence_In
Mark Hammond91a681d2002-08-12 07:21:58 +00001088 PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value);
Guido van Rossum83684531999-03-17 18:44:39 +00001089
1090/* For source-level backwards compatibility */
Guido van Rossumf1536db1998-08-23 22:06:59 +00001091#define PySequence_In PySequence_Contains
Guido van Rossuma8275371995-07-18 14:07:00 +00001092
1093 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001094 Determine if o contains value. If an item in o is equal to
1095 X, return 1, otherwise return 0. On error, return -1. This
1096 is equivalent to the Python expression: value in o.
Guido van Rossuma8275371995-07-18 14:07:00 +00001097 */
1098
Neal Norwitz1fc4b772006-03-04 18:49:58 +00001099 PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value);
Guido van Rossuma8275371995-07-18 14:07:00 +00001100
1101 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001102 Return the first index for which o[i]=value. On error,
1103 return -1. This is equivalent to the Python
1104 expression: o.index(value).
Guido van Rossuma8275371995-07-18 14:07:00 +00001105 */
1106
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001107/* In-place versions of some of the above Sequence functions. */
1108
Mark Hammond91a681d2002-08-12 07:21:58 +00001109 PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001110
1111 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001112 Append o2 to o1, in-place when possible. Return the resulting
1113 object, which could be o1, or NULL on failure. This is the
1114 equivalent of the Python expression: o1 += o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001115
1116 */
1117
Martin v. Löwis18e16552006-02-15 17:27:45 +00001118 PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001119
1120 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001121 Repeat o1 by count, in-place when possible. Return the resulting
1122 object, which could be o1, or NULL on failure. This is the
1123 equivalent of the Python expression: o1 *= count.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001124
1125 */
1126
Guido van Rossuma8275371995-07-18 14:07:00 +00001127/* Mapping protocol:*/
1128
Mark Hammond91a681d2002-08-12 07:21:58 +00001129 PyAPI_FUNC(int) PyMapping_Check(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001130
1131 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001132 Return 1 if the object provides mapping protocol, and zero
1133 otherwise.
Guido van Rossuma8275371995-07-18 14:07:00 +00001134
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001135 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +00001136 */
1137
Martin v. Löwis18e16552006-02-15 17:27:45 +00001138 PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
Jeremy Hylton6253f832000-07-12 12:56:19 +00001139
Guido van Rossuma8275371995-07-18 14:07:00 +00001140 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001141 Returns the number of keys in object o on success, and -1 on
1142 failure. For objects that do not provide sequence protocol,
1143 this is equivalent to the Python expression: len(o).
Guido van Rossuma8275371995-07-18 14:07:00 +00001144 */
1145
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +00001146 /* For DLL compatibility */
1147#undef PyMapping_Length
Martin v. Löwis18e16552006-02-15 17:27:45 +00001148 PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +00001149#define PyMapping_Length PyMapping_Size
1150
1151
Guido van Rossuma25e5e91996-09-06 13:48:38 +00001152 /* implemented as a macro:
1153
Fred Drakeea9cb5a2000-07-09 00:20:36 +00001154 int PyMapping_DelItemString(PyObject *o, char *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001155
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001156 Remove the mapping for object, key, from the object *o.
1157 Returns -1 on failure. This is equivalent to
1158 the Python statement: del o[key].
Guido van Rossuma8275371995-07-18 14:07:00 +00001159 */
Jeremy Hylton7c7ee5f2001-11-28 16:20:07 +00001160#define PyMapping_DelItemString(O,K) PyObject_DelItemString((O),(K))
Guido van Rossuma25e5e91996-09-06 13:48:38 +00001161
1162 /* implemented as a macro:
Guido van Rossuma8275371995-07-18 14:07:00 +00001163
Fred Drakeea9cb5a2000-07-09 00:20:36 +00001164 int PyMapping_DelItem(PyObject *o, PyObject *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001165
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001166 Remove the mapping for object, key, from the object *o.
1167 Returns -1 on failure. This is equivalent to
1168 the Python statement: del o[key].
Guido van Rossuma8275371995-07-18 14:07:00 +00001169 */
Jeremy Hylton7c7ee5f2001-11-28 16:20:07 +00001170#define PyMapping_DelItem(O,K) PyObject_DelItem((O),(K))
Guido van Rossuma8275371995-07-18 14:07:00 +00001171
Mark Hammond91a681d2002-08-12 07:21:58 +00001172 PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, char *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001173
1174 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001175 On success, return 1 if the mapping object has the key, key,
1176 and 0 otherwise. This is equivalent to the Python expression:
1177 key in o.
Guido van Rossuma8275371995-07-18 14:07:00 +00001178
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001179 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +00001180 */
1181
Mark Hammond91a681d2002-08-12 07:21:58 +00001182 PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001183
1184 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001185 Return 1 if the mapping object has the key, key,
1186 and 0 otherwise. This is equivalent to the Python expression:
1187 key in o.
Guido van Rossuma8275371995-07-18 14:07:00 +00001188
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001189 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +00001190
1191 */
1192
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001193 PyAPI_FUNC(PyObject *) PyMapping_Keys(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001194
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001195 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001196 On success, return a list or tuple of the keys in object o.
1197 On failure, return NULL.
Guido van Rossuma8275371995-07-18 14:07:00 +00001198 */
Guido van Rossuma8275371995-07-18 14:07:00 +00001199
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001200 PyAPI_FUNC(PyObject *) PyMapping_Values(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001201
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001202 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001203 On success, return a list or tuple of the values in object o.
1204 On failure, return NULL.
Guido van Rossuma8275371995-07-18 14:07:00 +00001205 */
Guido van Rossuma8275371995-07-18 14:07:00 +00001206
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001207 PyAPI_FUNC(PyObject *) PyMapping_Items(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001208
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001209 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001210 On success, return a list or tuple of the items in object o,
1211 where each item is a tuple containing a key-value pair.
1212 On failure, return NULL.
Guido van Rossuma8275371995-07-18 14:07:00 +00001213
1214 */
Guido van Rossuma8275371995-07-18 14:07:00 +00001215
Mark Hammond91a681d2002-08-12 07:21:58 +00001216 PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o, char *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001217
1218 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001219 Return element of o corresponding to the object, key, or NULL
1220 on failure. This is the equivalent of the Python expression:
1221 o[key].
Guido van Rossuma8275371995-07-18 14:07:00 +00001222 */
1223
Mark Hammond91a681d2002-08-12 07:21:58 +00001224 PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, char *key,
Fred Drakeea9cb5a2000-07-09 00:20:36 +00001225 PyObject *value);
Guido van Rossuma8275371995-07-18 14:07:00 +00001226
1227 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001228 Map the object, key, to the value, v. Returns
1229 -1 on failure. This is the equivalent of the Python
1230 statement: o[key]=v.
Guido van Rossuma8275371995-07-18 14:07:00 +00001231 */
1232
1233
Mark Hammond91a681d2002-08-12 07:21:58 +00001234PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
Guido van Rossum823649d2001-03-21 18:40:58 +00001235 /* isinstance(object, typeorclass) */
1236
Mark Hammond91a681d2002-08-12 07:21:58 +00001237PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass);
Guido van Rossum823649d2001-03-21 18:40:58 +00001238 /* issubclass(object, typeorclass) */
1239
1240
Martin v. Löwis4d0d4712010-12-03 20:14:31 +00001241#ifndef Py_LIMITED_API
Antoine Pitrouec569b72008-08-26 22:40:48 +00001242PyAPI_FUNC(int) _PyObject_RealIsInstance(PyObject *inst, PyObject *cls);
1243
1244PyAPI_FUNC(int) _PyObject_RealIsSubclass(PyObject *derived, PyObject *cls);
1245
Gregory P. Smithfb94c5f2010-03-14 06:49:55 +00001246PyAPI_FUNC(char *const *) _PySequence_BytesToCharpArray(PyObject* self);
1247
1248PyAPI_FUNC(void) _Py_FreeCharPArray(char *const array[]);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +00001249#endif
Antoine Pitrouec569b72008-08-26 22:40:48 +00001250
Antoine Pitrouf68c2a72010-09-01 12:58:21 +00001251/* For internal use by buffer API functions */
1252PyAPI_FUNC(void) _Py_add_one_to_index_F(int nd, Py_ssize_t *index,
1253 const Py_ssize_t *shape);
1254PyAPI_FUNC(void) _Py_add_one_to_index_C(int nd, Py_ssize_t *index,
1255 const Py_ssize_t *shape);
1256
1257
Guido van Rossum8ca687a1995-09-18 21:20:02 +00001258#ifdef __cplusplus
1259}
1260#endif
Guido van Rossuma8275371995-07-18 14:07:00 +00001261#endif /* Py_ABSTRACTOBJECT_H */