blob: 6e850b82e8f384e1b10bda5cdbe79be7b45525b6 [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
Serhiy Storchakac6792272013-10-19 21:03:34 +0300147 int PyObject_HasAttrString(PyObject *o, const char *attr_name);
Guido van Rossuma8275371995-07-18 14:07:00 +0000148
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
Serhiy Storchakac6792272013-10-19 21:03:34 +0300159 PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name);
Guido van Rossuma8275371995-07-18 14:07:00 +0000160
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
Serhiy Storchakac6792272013-10-19 21:03:34 +0300192 int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v);
Guido van Rossuma8275371995-07-18 14:07:00 +0000193
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
Serhiy Storchakac6792272013-10-19 21:03:34 +0300212 int PyObject_DelAttrString(PyObject *o, const char *attr_name);
Guido van Rossuma8275371995-07-18 14:07:00 +0000213
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,
Serhiy Storchaka1cfebc72013-05-29 18:50:54 +0300287 const 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
Serhiy Storchaka1cfebc72013-05-29 18:50:54 +0300299 PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *o,
300 const char *method,
301 const char *format, ...);
Guido van Rossuma8275371995-07-18 14:07:00 +0000302
303 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000304 Call the method named m of object o with a variable number of
305 C arguments. The C arguments are described by a mkvalue
306 format string. The format may be NULL, indicating that no
307 arguments are provided. Returns the result of the call on
308 success, or NULL on failure. This is the equivalent of the
309 Python expression: o.method(args).
Fred Drakeb421b8c2001-10-26 16:21:32 +0000310 */
Guido van Rossuma8275371995-07-18 14:07:00 +0000311
Serhiy Storchaka1cfebc72013-05-29 18:50:54 +0300312 PyAPI_FUNC(PyObject *) _PyObject_CallMethodId(PyObject *o,
313 _Py_Identifier *method,
314 const char *format, ...);
Martin v. Löwisafe55bb2011-10-09 10:38:36 +0200315
316 /*
317 Like PyObject_CallMethod, but expect a _Py_Identifier* as the
318 method name.
319 */
320
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000321 PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,
Serhiy Storchaka1cfebc72013-05-29 18:50:54 +0300322 const char *format,
323 ...);
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000324 PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *o,
Serhiy Storchaka1cfebc72013-05-29 18:50:54 +0300325 const char *name,
326 const char *format,
327 ...);
Martin v. Löwisafe55bb2011-10-09 10:38:36 +0200328 PyAPI_FUNC(PyObject *) _PyObject_CallMethodId_SizeT(PyObject *o,
329 _Py_Identifier *name,
Serhiy Storchaka1cfebc72013-05-29 18:50:54 +0300330 const char *format,
331 ...);
Guido van Rossuma8275371995-07-18 14:07:00 +0000332
Mark Hammond91a681d2002-08-12 07:21:58 +0000333 PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,
Neal Norwitzfe554642006-03-17 06:58:45 +0000334 ...);
Fred Drakeb421b8c2001-10-26 16:21:32 +0000335
336 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000337 Call a callable Python object, callable_object, with a
338 variable number of C arguments. The C arguments are provided
339 as PyObject * values, terminated by a NULL. Returns the
340 result of the call on success, or NULL on failure. This is
341 the equivalent of the Python expression: o(*args).
Fred Drakeb421b8c2001-10-26 16:21:32 +0000342 */
343
344
Mark Hammond91a681d2002-08-12 07:21:58 +0000345 PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(PyObject *o,
Neal Norwitzfe554642006-03-17 06:58:45 +0000346 PyObject *method, ...);
Alexandre Vassalotti865eaa12013-05-02 10:44:04 -0700347 PyAPI_FUNC(PyObject *) _PyObject_CallMethodIdObjArgs(PyObject *o,
Brett Cannonfd074152012-04-14 14:10:13 -0400348 struct _Py_Identifier *method,
349 ...);
350
Fred Drakeb421b8c2001-10-26 16:21:32 +0000351 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000352 Call the method named m of object o with a variable number of
353 C arguments. The C arguments are provided as PyObject *
354 values, terminated by NULL. Returns the result of the call
355 on success, or NULL on failure. This is the equivalent of
356 the Python expression: o.method(args).
Guido van Rossuma8275371995-07-18 14:07:00 +0000357 */
358
359
360 /* Implemented elsewhere:
361
362 long PyObject_Hash(PyObject *o);
363
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000364 Compute and return the hash, hash_value, of an object, o. On
365 failure, return -1. This is the equivalent of the Python
366 expression: hash(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000367 */
368
369
370 /* Implemented elsewhere:
371
372 int PyObject_IsTrue(PyObject *o);
373
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000374 Returns 1 if the object, o, is considered to be true, 0 if o is
375 considered to be false and -1 on failure. This is equivalent to the
376 Python expression: not not o
Guido van Rossuma8275371995-07-18 14:07:00 +0000377 */
378
Guido van Rossumc3d3f961998-04-09 17:53:59 +0000379 /* Implemented elsewhere:
380
381 int PyObject_Not(PyObject *o);
382
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000383 Returns 0 if the object, o, is considered to be true, 1 if o is
384 considered to be false and -1 on failure. This is equivalent to the
385 Python expression: not o
Guido van Rossumc3d3f961998-04-09 17:53:59 +0000386 */
387
Mark Hammond91a681d2002-08-12 07:21:58 +0000388 PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000389
390 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000391 On success, returns a type object corresponding to the object
392 type of object o. On failure, returns NULL. This is
393 equivalent to the Python expression: type(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000394 */
395
Martin v. Löwis18e16552006-02-15 17:27:45 +0000396 PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
Jeremy Hylton6253f832000-07-12 12:56:19 +0000397
Guido van Rossuma8275371995-07-18 14:07:00 +0000398 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000399 Return the size of object o. If the object, o, provides
400 both sequence and mapping protocols, the sequence size is
401 returned. On error, -1 is returned. This is the equivalent
402 to the Python expression: len(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000403 */
404
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000405 /* For DLL compatibility */
406#undef PyObject_Length
Martin v. Löwis18e16552006-02-15 17:27:45 +0000407 PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000408#define PyObject_Length PyObject_Size
409
Armin Ronacher74b38b12012-10-07 10:29:32 +0200410#ifndef Py_LIMITED_API
411 PyAPI_FUNC(int) _PyObject_HasLen(PyObject *o);
Martin v. Löwis1c0689c2014-01-03 21:36:49 +0100412 PyAPI_FUNC(Py_ssize_t) PyObject_LengthHint(PyObject *o, Py_ssize_t);
Armin Ronacher74b38b12012-10-07 10:29:32 +0200413#endif
Raymond Hettinger6b27cda2005-09-24 21:23:05 +0000414
415 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000416 Guess the size of object o using len(o) or o.__length_hint__().
417 If neither of those return a non-negative value, then return the
418 default value. If one of the calls fails, this function returns -1.
Raymond Hettinger6b27cda2005-09-24 21:23:05 +0000419 */
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000420
Mark Hammond91a681d2002-08-12 07:21:58 +0000421 PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
Guido van Rossuma8275371995-07-18 14:07:00 +0000422
423 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000424 Return element of o corresponding to the object, key, or NULL
425 on failure. This is the equivalent of the Python expression:
426 o[key].
Guido van Rossuma8275371995-07-18 14:07:00 +0000427 */
428
Mark Hammond91a681d2002-08-12 07:21:58 +0000429 PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
Guido van Rossuma8275371995-07-18 14:07:00 +0000430
431 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000432 Map the object, key, to the value, v. Returns
433 -1 on failure. This is the equivalent of the Python
434 statement: o[key]=v.
Guido van Rossuma8275371995-07-18 14:07:00 +0000435 */
436
Serhiy Storchakac6792272013-10-19 21:03:34 +0300437 PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, const char *key);
Martin v. Löwisb0d71d02002-01-05 10:50:30 +0000438
439 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000440 Remove the mapping for object, key, from the object *o.
441 Returns -1 on failure. This is equivalent to
442 the Python statement: del o[key].
Martin v. Löwisb0d71d02002-01-05 10:50:30 +0000443 */
444
Mark Hammond91a681d2002-08-12 07:21:58 +0000445 PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
Guido van Rossum6cdc6f41996-08-21 17:41:54 +0000446
447 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000448 Delete the mapping for key from *o. Returns -1 on failure.
449 This is the equivalent of the Python statement: del o[key].
Guido van Rossum6cdc6f41996-08-21 17:41:54 +0000450 */
451
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000452 /* old buffer API
453 FIXME: usage of these should all be replaced in Python itself
454 but for backwards compatibility we will implement them.
455 Their usage without a corresponding "unlock" mechansim
456 may create issues (but they would already be there). */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000457
Mark Hammond91a681d2002-08-12 07:21:58 +0000458 PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000459 const char **buffer,
460 Py_ssize_t *buffer_len);
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000461
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000462 /*
463 Takes an arbitrary object which must support the (character,
464 single segment) buffer interface and returns a pointer to a
465 read-only memory location useable as character based input
466 for subsequent processing.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000467
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000468 0 is returned on success. buffer and buffer_len are only
469 set in case no error occurs. Otherwise, -1 is returned and
470 an exception set.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000471 */
472
Mark Hammond91a681d2002-08-12 07:21:58 +0000473 PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);
Jeremy Hylton89c3a222001-11-09 21:59:42 +0000474
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000475 /*
476 Checks whether an arbitrary object supports the (character,
477 single segment) buffer interface. Returns 1 on success, 0
478 on failure.
Jeremy Hylton89c3a222001-11-09 21:59:42 +0000479 */
480
Mark Hammond91a681d2002-08-12 07:21:58 +0000481 PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000482 const void **buffer,
483 Py_ssize_t *buffer_len);
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000484
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000485 /*
486 Same as PyObject_AsCharBuffer() except that this API expects
487 (readable, single segment) buffer interface and returns a
488 pointer to a read-only memory location which can contain
489 arbitrary data.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000490
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000491 0 is returned on success. buffer and buffer_len are only
Ezio Melotti13925002011-03-16 11:05:33 +0200492 set in case no error occurs. Otherwise, -1 is returned and
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000493 an exception set.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000494 */
495
Mark Hammond91a681d2002-08-12 07:21:58 +0000496 PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000497 void **buffer,
498 Py_ssize_t *buffer_len);
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000499
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000500 /*
501 Takes an arbitrary object which must support the (writable,
502 single segment) buffer interface and returns a pointer to a
503 writable memory location in buffer of size buffer_len.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000504
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000505 0 is returned on success. buffer and buffer_len are only
Ezio Melotti13925002011-03-16 11:05:33 +0200506 set in case no error occurs. Otherwise, -1 is returned and
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000507 an exception set.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000508 */
Guido van Rossuma8275371995-07-18 14:07:00 +0000509
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000510 /* new buffer API */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000511
Martin v. Löwisc83bc3c2011-01-06 19:15:47 +0000512#ifndef Py_LIMITED_API
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000513#define PyObject_CheckBuffer(obj) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000514 (((obj)->ob_type->tp_as_buffer != NULL) && \
515 ((obj)->ob_type->tp_as_buffer->bf_getbuffer != NULL))
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000516
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000517 /* Return 1 if the getbuffer function is available, otherwise
518 return 0 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000519
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000520 PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view,
521 int flags);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000522
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000523 /* This is a C-API version of the getbuffer function call. It checks
524 to make sure object has the required function pointer and issues the
525 call. Returns -1 and raises an error on failure and returns 0 on
526 success
527 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000528
529
Travis E. Oliphant8ae62b62007-09-23 02:00:13 +0000530 PyAPI_FUNC(void *) PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices);
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000531
532 /* Get the memory area pointed to by the indices for the buffer given.
533 Note that view->ndim is the assumed size of indices
534 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000535
536 PyAPI_FUNC(int) PyBuffer_SizeFromFormat(const char *);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000537
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000538 /* Return the implied itemsize of the data-format area from a
539 struct-style description */
540
541
542
Stefan Krah7d12d9d2012-07-28 12:25:55 +0200543 /* Implementation in memoryobject.c */
Travis E. Oliphant8ae62b62007-09-23 02:00:13 +0000544 PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, Py_buffer *view,
Stefan Krah7d12d9d2012-07-28 12:25:55 +0200545 Py_ssize_t len, char order);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000546
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000547 PyAPI_FUNC(int) PyBuffer_FromContiguous(Py_buffer *view, void *buf,
Stefan Krah7d12d9d2012-07-28 12:25:55 +0200548 Py_ssize_t len, char order);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000549
550
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000551 /* Copy len bytes of data from the contiguous chunk of memory
552 pointed to by buf into the buffer exported by obj. Return
553 0 on success and return -1 and raise a PyBuffer_Error on
554 error (i.e. the object does not have a buffer interface or
555 it is not working).
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000556
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000557 If fort is 'F', then if the object is multi-dimensional,
558 then the data will be copied into the array in
559 Fortran-style (first dimension varies the fastest). If
560 fort is 'C', then the data will be copied into the array
561 in C-style (last dimension varies the fastest). If fort
562 is 'A', then it does not matter and the copy will be made
563 in whatever way is more efficient.
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000564
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000565 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000566
567 PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000568
569 /* Copy the data from the src buffer to the buffer of destination
570 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000571
Stefan Krah9a2d99e2012-02-25 12:24:21 +0100572 PyAPI_FUNC(int) PyBuffer_IsContiguous(const Py_buffer *view, char fort);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000573
574
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000575 PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims,
576 Py_ssize_t *shape,
577 Py_ssize_t *strides,
578 int itemsize,
579 char fort);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000580
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000581 /* Fill the strides array with byte-strides of a contiguous
582 (Fortran-style if fort is 'F' or C-style otherwise)
583 array of the given shape with the given number of bytes
584 per element.
585 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000586
Martin v. Löwis423be952008-08-13 15:53:07 +0000587 PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000588 Py_ssize_t len, int readonly,
589 int flags);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000590
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000591 /* Fills in a buffer-info structure correctly for an exporter
592 that can only share a contiguous chunk of memory of
593 "unsigned bytes" of the given length. Returns 0 on success
594 and -1 (with raising an error) on error.
595 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000596
Martin v. Löwis423be952008-08-13 15:53:07 +0000597 PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);
598
599 /* Releases a Py_buffer obtained from getbuffer ParseTuple's s*.
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000600 */
Martin v. Löwisc83bc3c2011-01-06 19:15:47 +0000601#endif /* Py_LIMITED_API */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000602
Eric Smith8fd3eba2008-02-17 19:48:00 +0000603 PyAPI_FUNC(PyObject *) PyObject_Format(PyObject* obj,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000604 PyObject *format_spec);
Eric Smith8fd3eba2008-02-17 19:48:00 +0000605 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000606 Takes an arbitrary object and returns the result of
607 calling obj.__format__(format_spec).
Eric Smith8fd3eba2008-02-17 19:48:00 +0000608 */
609
Guido van Rossum213c7a62001-04-23 14:08:49 +0000610/* Iterators */
611
Mark Hammond91a681d2002-08-12 07:21:58 +0000612 PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);
Guido van Rossum59d1d2b2001-04-20 19:13:02 +0000613 /* Takes an object and returns an iterator for it.
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000614 This is typically a new iterator but if the argument
615 is an iterator, this returns itself. */
Guido van Rossum59d1d2b2001-04-20 19:13:02 +0000616
Guido van Rossum213c7a62001-04-23 14:08:49 +0000617#define PyIter_Check(obj) \
Amaury Forgeot d'Arcf343e012009-01-12 23:58:21 +0000618 ((obj)->ob_type->tp_iternext != NULL && \
619 (obj)->ob_type->tp_iternext != &_PyObject_NextNotImplemented)
Guido van Rossum213c7a62001-04-23 14:08:49 +0000620
Mark Hammond91a681d2002-08-12 07:21:58 +0000621 PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);
Guido van Rossum213c7a62001-04-23 14:08:49 +0000622 /* Takes an iterator object and calls its tp_iternext slot,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000623 returning the next value. If the iterator is exhausted,
624 this returns NULL without setting an exception.
625 NULL with an exception means an error occurred. */
Guido van Rossum213c7a62001-04-23 14:08:49 +0000626
Guido van Rossuma8275371995-07-18 14:07:00 +0000627/* Number Protocol:*/
628
Mark Hammond91a681d2002-08-12 07:21:58 +0000629 PyAPI_FUNC(int) PyNumber_Check(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000630
631 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000632 Returns 1 if the object, o, provides numeric protocols, and
633 false otherwise.
Guido van Rossuma8275371995-07-18 14:07:00 +0000634
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000635 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +0000636 */
637
Mark Hammond91a681d2002-08-12 07:21:58 +0000638 PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000639
640 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000641 Returns the result of adding o1 and o2, or null on failure.
642 This is the equivalent of the Python expression: o1+o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000643 */
644
Mark Hammond91a681d2002-08-12 07:21:58 +0000645 PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000646
647 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000648 Returns the result of subtracting o2 from o1, or null on
649 failure. This is the equivalent of the Python expression:
650 o1-o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000651 */
652
Mark Hammond91a681d2002-08-12 07:21:58 +0000653 PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000654
655 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000656 Returns the result of multiplying o1 and o2, or null on
657 failure. This is the equivalent of the Python expression:
658 o1*o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000659 */
660
Mark Hammond91a681d2002-08-12 07:21:58 +0000661 PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2);
Guido van Rossum4668b002001-08-08 05:00:18 +0000662
663 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000664 Returns the result of dividing o1 by o2 giving an integral result,
665 or null on failure.
666 This is the equivalent of the Python expression: o1//o2.
Guido van Rossum4668b002001-08-08 05:00:18 +0000667 */
668
Mark Hammond91a681d2002-08-12 07:21:58 +0000669 PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2);
Guido van Rossum4668b002001-08-08 05:00:18 +0000670
671 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000672 Returns the result of dividing o1 by o2 giving a float result,
673 or null on failure.
674 This is the equivalent of the Python expression: o1/o2.
Guido van Rossum4668b002001-08-08 05:00:18 +0000675 */
676
Mark Hammond91a681d2002-08-12 07:21:58 +0000677 PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000678
679 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000680 Returns the remainder of dividing o1 by o2, or null on
681 failure. This is the equivalent of the Python expression:
682 o1%o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000683 */
684
Mark Hammond91a681d2002-08-12 07:21:58 +0000685 PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000686
687 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000688 See the built-in function divmod. Returns NULL on failure.
689 This is the equivalent of the Python expression:
690 divmod(o1,o2).
Guido van Rossuma8275371995-07-18 14:07:00 +0000691 */
692
Mark Hammond91a681d2002-08-12 07:21:58 +0000693 PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,
Neal Norwitzfe554642006-03-17 06:58:45 +0000694 PyObject *o3);
Guido van Rossuma8275371995-07-18 14:07:00 +0000695
696 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000697 See the built-in function pow. Returns NULL on failure.
698 This is the equivalent of the Python expression:
699 pow(o1,o2,o3), where o3 is optional.
Guido van Rossuma8275371995-07-18 14:07:00 +0000700 */
701
Mark Hammond91a681d2002-08-12 07:21:58 +0000702 PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000703
704 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000705 Returns the negation of o on success, or null on failure.
706 This is the equivalent of the Python expression: -o.
Guido van Rossuma8275371995-07-18 14:07:00 +0000707 */
708
Mark Hammond91a681d2002-08-12 07:21:58 +0000709 PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000710
711 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000712 Returns the (what?) of o on success, or NULL on failure.
713 This is the equivalent of the Python expression: +o.
Guido van Rossuma8275371995-07-18 14:07:00 +0000714 */
715
Mark Hammond91a681d2002-08-12 07:21:58 +0000716 PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000717
718 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000719 Returns the absolute value of o, or null on failure. This is
720 the equivalent of the Python expression: abs(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000721 */
722
Mark Hammond91a681d2002-08-12 07:21:58 +0000723 PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000724
725 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000726 Returns the bitwise negation of o on success, or NULL on
727 failure. This is the equivalent of the Python expression:
728 ~o.
Guido van Rossuma8275371995-07-18 14:07:00 +0000729 */
730
Mark Hammond91a681d2002-08-12 07:21:58 +0000731 PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000732
733 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000734 Returns the result of left shifting o1 by o2 on success, or
735 NULL on failure. This is the equivalent of the Python
736 expression: o1 << o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000737 */
738
Mark Hammond91a681d2002-08-12 07:21:58 +0000739 PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000740
741 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000742 Returns the result of right shifting o1 by o2 on success, or
743 NULL on failure. This is the equivalent of the Python
744 expression: o1 >> o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000745 */
746
Mark Hammond91a681d2002-08-12 07:21:58 +0000747 PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000748
749 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000750 Returns the result of bitwise and of o1 and o2 on success, or
751 NULL on failure. This is the equivalent of the Python
752 expression: o1&o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000753
Guido van Rossuma8275371995-07-18 14:07:00 +0000754 */
755
Mark Hammond91a681d2002-08-12 07:21:58 +0000756 PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000757
758 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000759 Returns the bitwise exclusive or of o1 by o2 on success, or
760 NULL on failure. This is the equivalent of the Python
761 expression: o1^o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000762 */
763
Mark Hammond91a681d2002-08-12 07:21:58 +0000764 PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000765
766 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000767 Returns the result of bitwise or on o1 and o2 on success, or
768 NULL on failure. This is the equivalent of the Python
769 expression: o1|o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000770 */
771
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000772#define PyIndex_Check(obj) \
773 ((obj)->ob_type->tp_as_number != NULL && \
774 (obj)->ob_type->tp_as_number->nb_index != NULL)
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000775
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000776 PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o);
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000777
778 /*
Serhiy Storchaka95949422013-08-27 19:40:23 +0300779 Returns the object converted to a Python int
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000780 or NULL with an error raised on failure.
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000781 */
782
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000783 PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc);
784
785 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000786 Returns the object converted to Py_ssize_t by going through
787 PyNumber_Index first. If an overflow error occurs while
Serhiy Storchaka95949422013-08-27 19:40:23 +0300788 converting the int to Py_ssize_t, then the second argument
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000789 is the error-type to return. If it is NULL, then the overflow error
790 is cleared and the value is clipped.
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000791 */
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000792
Mark Dickinsond7467682009-01-10 22:14:33 +0000793 PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);
794
Guido van Rossuma8275371995-07-18 14:07:00 +0000795 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000796 Returns the o converted to an integer object on success, or
797 NULL on failure. This is the equivalent of the Python
798 expression: int(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000799 */
800
Mark Hammond91a681d2002-08-12 07:21:58 +0000801 PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000802
803 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000804 Returns the o converted to a float object on success, or NULL
805 on failure. This is the equivalent of the Python expression:
806 float(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000807 */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000808
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000809/* In-place variants of (some of) the above number protocol functions */
810
Mark Hammond91a681d2002-08-12 07:21:58 +0000811 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000812
813 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000814 Returns the result of adding o2 to o1, possibly in-place, or null
815 on failure. This is the equivalent of the Python expression:
816 o1 += o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000817 */
818
Mark Hammond91a681d2002-08-12 07:21:58 +0000819 PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000820
821 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000822 Returns the result of subtracting o2 from o1, possibly in-place or
823 null on failure. This is the equivalent of the Python expression:
824 o1 -= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000825 */
826
Mark Hammond91a681d2002-08-12 07:21:58 +0000827 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000828
829 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000830 Returns the result of multiplying o1 by o2, possibly in-place, or
831 null on failure. This is the equivalent of the Python expression:
832 o1 *= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000833 */
834
Mark Hammond91a681d2002-08-12 07:21:58 +0000835 PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000836 PyObject *o2);
Guido van Rossum4668b002001-08-08 05:00:18 +0000837
838 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000839 Returns the result of dividing o1 by o2 giving an integral result,
840 possibly in-place, or null on failure.
841 This is the equivalent of the Python expression:
842 o1 /= o2.
Guido van Rossum4668b002001-08-08 05:00:18 +0000843 */
844
Mark Hammond91a681d2002-08-12 07:21:58 +0000845 PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000846 PyObject *o2);
Guido van Rossum4668b002001-08-08 05:00:18 +0000847
848 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000849 Returns the result of dividing o1 by o2 giving a float result,
850 possibly in-place, or null on failure.
851 This is the equivalent of the Python expression:
852 o1 /= o2.
Guido van Rossum4668b002001-08-08 05:00:18 +0000853 */
854
Mark Hammond91a681d2002-08-12 07:21:58 +0000855 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000856
857 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000858 Returns the remainder of dividing o1 by o2, possibly in-place, or
859 null on failure. This is the equivalent of the Python expression:
860 o1 %= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000861 */
862
Mark Hammond91a681d2002-08-12 07:21:58 +0000863 PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000864 PyObject *o3);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000865
866 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000867 Returns the result of raising o1 to the power of o2, possibly
868 in-place, or null on failure. This is the equivalent of the Python
869 expression: o1 **= o2, or pow(o1, o2, o3) if o3 is present.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000870 */
871
Mark Hammond91a681d2002-08-12 07:21:58 +0000872 PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000873
874 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000875 Returns the result of left shifting o1 by o2, possibly in-place, or
876 null on failure. This is the equivalent of the Python expression:
877 o1 <<= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000878 */
879
Mark Hammond91a681d2002-08-12 07:21:58 +0000880 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000881
882 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000883 Returns the result of right shifting o1 by o2, possibly in-place or
884 null on failure. This is the equivalent of the Python expression:
885 o1 >>= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000886 */
887
Mark Hammond91a681d2002-08-12 07:21:58 +0000888 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000889
890 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000891 Returns the result of bitwise and of o1 and o2, possibly in-place,
892 or null on failure. This is the equivalent of the Python
893 expression: o1 &= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000894 */
895
Mark Hammond91a681d2002-08-12 07:21:58 +0000896 PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000897
898 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000899 Returns the bitwise exclusive or of o1 by o2, possibly in-place, or
900 null on failure. This is the equivalent of the Python expression:
901 o1 ^= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000902 */
903
Mark Hammond91a681d2002-08-12 07:21:58 +0000904 PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000905
906 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000907 Returns the result of bitwise or of o1 and o2, possibly in-place,
908 or null on failure. This is the equivalent of the Python
909 expression: o1 |= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000910 */
911
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000912 PyAPI_FUNC(PyObject *) PyNumber_ToBase(PyObject *n, int base);
913
914 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000915 Returns the integer n converted to a string with a base, with a base
916 marker of 0b, 0o or 0x prefixed if applicable.
917 If n is not an int object, it is converted with PyNumber_Index first.
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000918 */
919
Guido van Rossuma8275371995-07-18 14:07:00 +0000920
921/* Sequence protocol:*/
922
Mark Hammond91a681d2002-08-12 07:21:58 +0000923 PyAPI_FUNC(int) PySequence_Check(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000924
925 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000926 Return 1 if the object provides sequence protocol, and zero
927 otherwise.
Guido van Rossuma8275371995-07-18 14:07:00 +0000928
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000929 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +0000930 */
931
Martin v. Löwis18e16552006-02-15 17:27:45 +0000932 PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
Jeremy Hylton6253f832000-07-12 12:56:19 +0000933
Guido van Rossum4f4ce681996-07-21 02:22:56 +0000934 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000935 Return the size of sequence object o, or -1 on failure.
Guido van Rossum4f4ce681996-07-21 02:22:56 +0000936 */
937
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000938 /* For DLL compatibility */
939#undef PySequence_Length
Martin v. Löwis18e16552006-02-15 17:27:45 +0000940 PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000941#define PySequence_Length PySequence_Size
942
943
Mark Hammond91a681d2002-08-12 07:21:58 +0000944 PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000945
946 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000947 Return the concatenation of o1 and o2 on success, and NULL on
948 failure. This is the equivalent of the Python
949 expression: o1+o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000950 */
951
Martin v. Löwis18e16552006-02-15 17:27:45 +0000952 PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count);
Guido van Rossuma8275371995-07-18 14:07:00 +0000953
954 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000955 Return the result of repeating sequence object o count times,
956 or NULL on failure. This is the equivalent of the Python
957 expression: o1*count.
Guido van Rossuma8275371995-07-18 14:07:00 +0000958 */
959
Martin v. Löwis18e16552006-02-15 17:27:45 +0000960 PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i);
Guido van Rossuma8275371995-07-18 14:07:00 +0000961
962 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000963 Return the ith element of o, or NULL on failure. This is the
964 equivalent of the Python expression: o[i].
Guido van Rossuma8275371995-07-18 14:07:00 +0000965 */
966
Martin v. Löwis18e16552006-02-15 17:27:45 +0000967 PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000968
969 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000970 Return the slice of sequence object o between i1 and i2, or
971 NULL on failure. This is the equivalent of the Python
972 expression: o[i1:i2].
Guido van Rossuma8275371995-07-18 14:07:00 +0000973 */
974
Martin v. Löwis18e16552006-02-15 17:27:45 +0000975 PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);
Guido van Rossuma8275371995-07-18 14:07:00 +0000976
977 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000978 Assign object v to the ith element of o. Returns
979 -1 on failure. This is the equivalent of the Python
980 statement: o[i]=v.
Guido van Rossuma8275371995-07-18 14:07:00 +0000981 */
982
Martin v. Löwis18e16552006-02-15 17:27:45 +0000983 PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
Guido van Rossum6cdc6f41996-08-21 17:41:54 +0000984
985 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000986 Delete the ith element of object v. Returns
987 -1 on failure. This is the equivalent of the Python
988 statement: del o[i].
Guido van Rossum6cdc6f41996-08-21 17:41:54 +0000989 */
990
Martin v. Löwis18e16552006-02-15 17:27:45 +0000991 PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2,
Neal Norwitzfe554642006-03-17 06:58:45 +0000992 PyObject *v);
Guido van Rossuma8275371995-07-18 14:07:00 +0000993
994 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000995 Assign the sequence object, v, to the slice in sequence
996 object, o, from i1 to i2. Returns -1 on failure. This is the
997 equivalent of the Python statement: o[i1:i2]=v.
Guido van Rossuma8275371995-07-18 14:07:00 +0000998 */
999
Martin v. Löwis18e16552006-02-15 17:27:45 +00001000 PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
Guido van Rossum6cdc6f41996-08-21 17:41:54 +00001001
1002 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001003 Delete the slice in sequence object, o, from i1 to i2.
1004 Returns -1 on failure. This is the equivalent of the Python
1005 statement: del o[i1:i2].
Guido van Rossum6cdc6f41996-08-21 17:41:54 +00001006 */
1007
Mark Hammond91a681d2002-08-12 07:21:58 +00001008 PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001009
1010 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001011 Returns the sequence, o, as a tuple on success, and NULL on failure.
1012 This is equivalent to the Python expression: tuple(o)
Guido van Rossuma8275371995-07-18 14:07:00 +00001013 */
1014
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001015
Mark Hammond91a681d2002-08-12 07:21:58 +00001016 PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);
Guido van Rossum2adf06b1996-12-05 21:48:50 +00001017 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001018 Returns the sequence, o, as a list on success, and NULL on failure.
1019 This is equivalent to the Python expression: list(o)
Guido van Rossum2adf06b1996-12-05 21:48:50 +00001020 */
Guido van Rossumf39fc431997-03-04 18:31:47 +00001021
Mark Hammond91a681d2002-08-12 07:21:58 +00001022 PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001023 /*
Benjamin Peterson7ddf3eb2014-04-08 10:51:20 -04001024 Return the sequence, o, as a list, unless it's already a
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001025 tuple or list. Use PySequence_Fast_GET_ITEM to access the
1026 members of this list, and PySequence_Fast_GET_SIZE to get its length.
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001027
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001028 Returns NULL on failure. If the object does not support iteration,
1029 raises a TypeError exception with m as the message text.
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001030 */
1031
Tim Peters1fc240e2001-10-26 05:06:50 +00001032#define PySequence_Fast_GET_SIZE(o) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001033 (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o))
Tim Peters1fc240e2001-10-26 05:06:50 +00001034 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001035 Return the size of o, assuming that o was returned by
1036 PySequence_Fast and is not NULL.
Tim Peters1fc240e2001-10-26 05:06:50 +00001037 */
1038
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001039#define PySequence_Fast_GET_ITEM(o, i)\
1040 (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i))
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001041 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001042 Return the ith element of o, assuming that o was returned by
1043 PySequence_Fast, and that i is within bounds.
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001044 */
1045
Martin v. Löwis01f94bd2002-05-08 08:44:21 +00001046#define PySequence_ITEM(o, i)\
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001047 ( Py_TYPE(o)->tp_as_sequence->sq_item(o, i) )
Martin v. Löwis01f94bd2002-05-08 08:44:21 +00001048 /* Assume tp_as_sequence and sq_item exist and that i does not
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001049 need to be corrected for a negative index
1050 */
Martin v. Löwis01f94bd2002-05-08 08:44:21 +00001051
Raymond Hettinger42bec932004-03-12 16:38:17 +00001052#define PySequence_Fast_ITEMS(sf) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001053 (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \
1054 : ((PyTupleObject *)(sf))->ob_item)
1055 /* Return a pointer to the underlying item array for
1056 an object retured by PySequence_Fast */
Raymond Hettingerc1e4f9d2004-03-12 08:04:00 +00001057
Neal Norwitz1fc4b772006-03-04 18:49:58 +00001058 PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value);
Guido van Rossuma8275371995-07-18 14:07:00 +00001059
1060 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001061 Return the number of occurrences on value on o, that is,
1062 return the number of keys for which o[key]==value. On
1063 failure, return -1. This is equivalent to the Python
1064 expression: o.count(value).
Guido van Rossuma8275371995-07-18 14:07:00 +00001065 */
1066
Mark Hammond91a681d2002-08-12 07:21:58 +00001067 PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob);
Tim Peterscb8d3682001-05-05 21:05:01 +00001068 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001069 Return -1 if error; 1 if ob in seq; 0 if ob not in seq.
1070 Use __contains__ if possible, else _PySequence_IterSearch().
Tim Peterscb8d3682001-05-05 21:05:01 +00001071 */
1072
Martin v. Löwis4d0d4712010-12-03 20:14:31 +00001073#ifndef Py_LIMITED_API
Tim Peters16a77ad2001-09-08 04:00:12 +00001074#define PY_ITERSEARCH_COUNT 1
1075#define PY_ITERSEARCH_INDEX 2
1076#define PY_ITERSEARCH_CONTAINS 3
Neal Norwitz1fc4b772006-03-04 18:49:58 +00001077 PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001078 PyObject *obj, int operation);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +00001079#endif
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001080 /*
1081 Iterate over seq. Result depends on the operation:
1082 PY_ITERSEARCH_COUNT: return # of times obj appears in seq; -1 if
1083 error.
1084 PY_ITERSEARCH_INDEX: return 0-based index of first occurrence of
1085 obj in seq; set ValueError and return -1 if none found;
1086 also return -1 on error.
1087 PY_ITERSEARCH_CONTAINS: return 1 if obj in seq, else 0; -1 on
1088 error.
1089 */
Guido van Rossum83684531999-03-17 18:44:39 +00001090
1091/* For DLL-level backwards compatibility */
1092#undef PySequence_In
Mark Hammond91a681d2002-08-12 07:21:58 +00001093 PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value);
Guido van Rossum83684531999-03-17 18:44:39 +00001094
1095/* For source-level backwards compatibility */
Guido van Rossumf1536db1998-08-23 22:06:59 +00001096#define PySequence_In PySequence_Contains
Guido van Rossuma8275371995-07-18 14:07:00 +00001097
1098 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001099 Determine if o contains value. If an item in o is equal to
1100 X, return 1, otherwise return 0. On error, return -1. This
1101 is equivalent to the Python expression: value in o.
Guido van Rossuma8275371995-07-18 14:07:00 +00001102 */
1103
Neal Norwitz1fc4b772006-03-04 18:49:58 +00001104 PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value);
Guido van Rossuma8275371995-07-18 14:07:00 +00001105
1106 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001107 Return the first index for which o[i]=value. On error,
1108 return -1. This is equivalent to the Python
1109 expression: o.index(value).
Guido van Rossuma8275371995-07-18 14:07:00 +00001110 */
1111
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001112/* In-place versions of some of the above Sequence functions. */
1113
Mark Hammond91a681d2002-08-12 07:21:58 +00001114 PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001115
1116 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001117 Append o2 to o1, in-place when possible. Return the resulting
1118 object, which could be o1, or NULL on failure. This is the
1119 equivalent of the Python expression: o1 += o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001120
1121 */
1122
Martin v. Löwis18e16552006-02-15 17:27:45 +00001123 PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001124
1125 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001126 Repeat o1 by count, in-place when possible. Return the resulting
1127 object, which could be o1, or NULL on failure. This is the
1128 equivalent of the Python expression: o1 *= count.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001129
1130 */
1131
Guido van Rossuma8275371995-07-18 14:07:00 +00001132/* Mapping protocol:*/
1133
Mark Hammond91a681d2002-08-12 07:21:58 +00001134 PyAPI_FUNC(int) PyMapping_Check(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001135
1136 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001137 Return 1 if the object provides mapping protocol, and zero
1138 otherwise.
Guido van Rossuma8275371995-07-18 14:07:00 +00001139
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001140 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +00001141 */
1142
Martin v. Löwis18e16552006-02-15 17:27:45 +00001143 PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
Jeremy Hylton6253f832000-07-12 12:56:19 +00001144
Guido van Rossuma8275371995-07-18 14:07:00 +00001145 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001146 Returns the number of keys in object o on success, and -1 on
1147 failure. For objects that do not provide sequence protocol,
1148 this is equivalent to the Python expression: len(o).
Guido van Rossuma8275371995-07-18 14:07:00 +00001149 */
1150
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +00001151 /* For DLL compatibility */
1152#undef PyMapping_Length
Martin v. Löwis18e16552006-02-15 17:27:45 +00001153 PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +00001154#define PyMapping_Length PyMapping_Size
1155
1156
Guido van Rossuma25e5e91996-09-06 13:48:38 +00001157 /* implemented as a macro:
1158
Serhiy Storchakac6792272013-10-19 21:03:34 +03001159 int PyMapping_DelItemString(PyObject *o, const char *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001160
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001161 Remove the mapping for object, key, from the object *o.
1162 Returns -1 on failure. This is equivalent to
1163 the Python statement: del o[key].
Guido van Rossuma8275371995-07-18 14:07:00 +00001164 */
Jeremy Hylton7c7ee5f2001-11-28 16:20:07 +00001165#define PyMapping_DelItemString(O,K) PyObject_DelItemString((O),(K))
Guido van Rossuma25e5e91996-09-06 13:48:38 +00001166
1167 /* implemented as a macro:
Guido van Rossuma8275371995-07-18 14:07:00 +00001168
Fred Drakeea9cb5a2000-07-09 00:20:36 +00001169 int PyMapping_DelItem(PyObject *o, PyObject *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001170
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001171 Remove the mapping for object, key, from the object *o.
1172 Returns -1 on failure. This is equivalent to
1173 the Python statement: del o[key].
Guido van Rossuma8275371995-07-18 14:07:00 +00001174 */
Jeremy Hylton7c7ee5f2001-11-28 16:20:07 +00001175#define PyMapping_DelItem(O,K) PyObject_DelItem((O),(K))
Guido van Rossuma8275371995-07-18 14:07:00 +00001176
Serhiy Storchakac6792272013-10-19 21:03:34 +03001177 PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, const char *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001178
1179 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001180 On success, return 1 if the mapping object has the key, key,
1181 and 0 otherwise. This is equivalent to the Python expression:
1182 key in o.
Guido van Rossuma8275371995-07-18 14:07:00 +00001183
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001184 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +00001185 */
1186
Mark Hammond91a681d2002-08-12 07:21:58 +00001187 PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001188
1189 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001190 Return 1 if the mapping object has the key, key,
1191 and 0 otherwise. This is equivalent to the Python expression:
1192 key in o.
Guido van Rossuma8275371995-07-18 14:07:00 +00001193
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001194 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +00001195
1196 */
1197
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001198 PyAPI_FUNC(PyObject *) PyMapping_Keys(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001199
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001200 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001201 On success, return a list or tuple of the keys in object o.
1202 On failure, return NULL.
Guido van Rossuma8275371995-07-18 14:07:00 +00001203 */
Guido van Rossuma8275371995-07-18 14:07:00 +00001204
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001205 PyAPI_FUNC(PyObject *) PyMapping_Values(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001206
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001207 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001208 On success, return a list or tuple of the values in object o.
1209 On failure, return NULL.
Guido van Rossuma8275371995-07-18 14:07:00 +00001210 */
Guido van Rossuma8275371995-07-18 14:07:00 +00001211
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001212 PyAPI_FUNC(PyObject *) PyMapping_Items(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001213
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001214 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001215 On success, return a list or tuple of the items in object o,
1216 where each item is a tuple containing a key-value pair.
1217 On failure, return NULL.
Guido van Rossuma8275371995-07-18 14:07:00 +00001218
1219 */
Guido van Rossuma8275371995-07-18 14:07:00 +00001220
Serhiy Storchakac6792272013-10-19 21:03:34 +03001221 PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o,
1222 const char *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001223
1224 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001225 Return element of o corresponding to the object, key, or NULL
1226 on failure. This is the equivalent of the Python expression:
1227 o[key].
Guido van Rossuma8275371995-07-18 14:07:00 +00001228 */
1229
Serhiy Storchakac6792272013-10-19 21:03:34 +03001230 PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, const char *key,
Fred Drakeea9cb5a2000-07-09 00:20:36 +00001231 PyObject *value);
Guido van Rossuma8275371995-07-18 14:07:00 +00001232
1233 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001234 Map the object, key, to the value, v. Returns
1235 -1 on failure. This is the equivalent of the Python
1236 statement: o[key]=v.
Guido van Rossuma8275371995-07-18 14:07:00 +00001237 */
1238
1239
Mark Hammond91a681d2002-08-12 07:21:58 +00001240PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
Guido van Rossum823649d2001-03-21 18:40:58 +00001241 /* isinstance(object, typeorclass) */
1242
Mark Hammond91a681d2002-08-12 07:21:58 +00001243PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass);
Guido van Rossum823649d2001-03-21 18:40:58 +00001244 /* issubclass(object, typeorclass) */
1245
1246
Martin v. Löwis4d0d4712010-12-03 20:14:31 +00001247#ifndef Py_LIMITED_API
Antoine Pitrouec569b72008-08-26 22:40:48 +00001248PyAPI_FUNC(int) _PyObject_RealIsInstance(PyObject *inst, PyObject *cls);
1249
1250PyAPI_FUNC(int) _PyObject_RealIsSubclass(PyObject *derived, PyObject *cls);
1251
Gregory P. Smithfb94c5f2010-03-14 06:49:55 +00001252PyAPI_FUNC(char *const *) _PySequence_BytesToCharpArray(PyObject* self);
1253
1254PyAPI_FUNC(void) _Py_FreeCharPArray(char *const array[]);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +00001255#endif
Antoine Pitrouec569b72008-08-26 22:40:48 +00001256
Antoine Pitrouf68c2a72010-09-01 12:58:21 +00001257/* For internal use by buffer API functions */
1258PyAPI_FUNC(void) _Py_add_one_to_index_F(int nd, Py_ssize_t *index,
1259 const Py_ssize_t *shape);
1260PyAPI_FUNC(void) _Py_add_one_to_index_C(int nd, Py_ssize_t *index,
1261 const Py_ssize_t *shape);
1262
1263
Guido van Rossum8ca687a1995-09-18 21:20:02 +00001264#ifdef __cplusplus
1265}
1266#endif
Guido van Rossuma8275371995-07-18 14:07:00 +00001267#endif /* Py_ABSTRACTOBJECT_H */