blob: 6bb76ec95f1b2e47273c3fd50e3aa89d5c9dc037 [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
Serhiy Storchaka9fab79b2016-09-11 11:03:14 +030010#ifndef Py_LIMITED_API
Martin v. Löwisafe55bb2011-10-09 10:38:36 +020011#define _PyObject_CallMethodId _PyObject_CallMethodId_SizeT
Serhiy Storchaka9fab79b2016-09-11 11:03:14 +030012#endif /* !Py_LIMITED_API */
Thomas Wouters49fd7fa2006-04-21 10:40:58 +000013#endif
14
Guido van Rossuma8275371995-07-18 14:07:00 +000015/* Abstract Object Interface (many thanks to Jim Fulton) */
16
17/*
18 PROPOSAL: A Generic Python Object Interface for Python C Modules
19
20Problem
21
22 Python modules written in C that must access Python objects must do
23 so through routines whose interfaces are described by a set of
24 include files. Unfortunately, these routines vary according to the
25 object accessed. To use these routines, the C programmer must check
26 the type of the object being used and must call a routine based on
27 the object type. For example, to access an element of a sequence,
28 the programmer must determine whether the sequence is a list or a
29 tuple:
30
31 if(is_tupleobject(o))
32 e=gettupleitem(o,i)
33 else if(is_listitem(o))
34 e=getlistitem(o,i)
35
36 If the programmer wants to get an item from another type of object
37 that provides sequence behavior, there is no clear way to do it
Antoine Pitrouf95a1b32010-05-09 15:52:27 +000038 correctly.
Guido van Rossuma8275371995-07-18 14:07:00 +000039
40 The persistent programmer may peruse object.h and find that the
41 _typeobject structure provides a means of invoking up to (currently
42 about) 41 special operators. So, for example, a routine can get an
43 item from any object that provides sequence behavior. However, to
44 use this mechanism, the programmer must make their code dependent on
45 the current Python implementation.
46
47 Also, certain semantics, especially memory management semantics, may
48 differ by the type of object being used. Unfortunately, these
49 semantics are not clearly described in the current include files.
Antoine Pitrouf95a1b32010-05-09 15:52:27 +000050 An abstract interface providing more consistent semantics is needed.
Guido van Rossuma8275371995-07-18 14:07:00 +000051
52Proposal
53
54 I propose the creation of a standard interface (with an associated
55 library of routines and/or macros) for generically obtaining the
56 services of Python objects. This proposal can be viewed as one
57 components of a Python C interface consisting of several components.
58
Raymond Hettingera72e2f92003-02-28 05:11:03 +000059 From the viewpoint of C access to Python services, we have (as
Guido van Rossuma8275371995-07-18 14:07:00 +000060 suggested by Guido in off-line discussions):
61
62 - "Very high level layer": two or three functions that let you exec or
63 eval arbitrary Python code given as a string in a module whose name is
64 given, passing C values in and getting C values out using
65 mkvalue/getargs style format strings. This does not require the user
66 to declare any variables of type "PyObject *". This should be enough
67 to write a simple application that gets Python code from the user,
68 execs it, and returns the output or errors. (Error handling must also
69 be part of this API.)
70
71 - "Abstract objects layer": which is the subject of this proposal.
72 It has many functions operating on objects, and lest you do many
73 things from C that you can also write in Python, without going
74 through the Python parser.
75
76 - "Concrete objects layer": This is the public type-dependent
77 interface provided by the standard built-in types, such as floats,
78 strings, and lists. This interface exists and is currently
Raymond Hettingera72e2f92003-02-28 05:11:03 +000079 documented by the collection of include files provided with the
Guido van Rossuma8275371995-07-18 14:07:00 +000080 Python distributions.
81
82 From the point of view of Python accessing services provided by C
Antoine Pitrouf95a1b32010-05-09 15:52:27 +000083 modules:
Guido van Rossuma8275371995-07-18 14:07:00 +000084
85 - "Python module interface": this interface consist of the basic
86 routines used to define modules and their members. Most of the
87 current extensions-writing guide deals with this interface.
88
89 - "Built-in object interface": this is the interface that a new
90 built-in type must provide and the mechanisms and rules that a
91 developer of a new built-in type must use and follow.
92
93 This proposal is a "first-cut" that is intended to spur
94 discussion. See especially the lists of notes.
95
96 The Python C object interface will provide four protocols: object,
97 numeric, sequence, and mapping. Each protocol consists of a
98 collection of related operations. If an operation that is not
99 provided by a particular type is invoked, then a standard exception,
Martin Panter7462b6492015-11-02 03:37:02 +0000100 NotImplementedError is raised with an operation name as an argument.
Guido van Rossuma8275371995-07-18 14:07:00 +0000101 In addition, for convenience this interface defines a set of
102 constructors for building objects of built-in types. This is needed
103 so new objects can be returned from C functions that otherwise treat
104 objects generically.
105
106Memory Management
107
108 For all of the functions described in this proposal, if a function
109 retains a reference to a Python object passed as an argument, then the
110 function will increase the reference count of the object. It is
111 unnecessary for the caller to increase the reference count of an
112 argument in anticipation of the object's retention.
113
114 All Python objects returned from functions should be treated as new
115 objects. Functions that return objects assume that the caller will
116 retain a reference and the reference count of the object has already
117 been incremented to account for this fact. A caller that does not
118 retain a reference to an object that is returned from a function
119 must decrement the reference count of the object (using
120 DECREF(object)) to prevent memory leaks.
121
122 Note that the behavior mentioned here is different from the current
123 behavior for some objects (e.g. lists and tuples) when certain
124 type-specific routines are called directly (e.g. setlistitem). The
125 proposed abstraction layer will provide a consistent memory
126 management interface, correcting for inconsistent behavior for some
127 built-in types.
128
129Protocols
130
131xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
132
133/* Object Protocol: */
134
135 /* Implemented elsewhere:
136
137 int PyObject_Print(PyObject *o, FILE *fp, int flags);
138
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000139 Print an object, o, on file, fp. Returns -1 on
140 error. The flags argument is used to enable certain printing
141 options. The only option currently supported is Py_Print_RAW.
Guido van Rossuma8275371995-07-18 14:07:00 +0000142
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000143 (What should be said about Py_Print_RAW?)
Guido van Rossuma8275371995-07-18 14:07:00 +0000144
145 */
146
147 /* Implemented elsewhere:
148
Serhiy Storchakac6792272013-10-19 21:03:34 +0300149 int PyObject_HasAttrString(PyObject *o, const char *attr_name);
Guido van Rossuma8275371995-07-18 14:07:00 +0000150
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000151 Returns 1 if o has the attribute attr_name, and 0 otherwise.
152 This is equivalent to the Python expression:
153 hasattr(o,attr_name).
Guido van Rossuma8275371995-07-18 14:07:00 +0000154
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000155 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +0000156
157 */
158
159 /* Implemented elsewhere:
160
Serhiy Storchakac6792272013-10-19 21:03:34 +0300161 PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name);
Guido van Rossuma8275371995-07-18 14:07:00 +0000162
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000163 Retrieve an attributed named attr_name form object o.
164 Returns the attribute value on success, or NULL on failure.
165 This is the equivalent of the Python expression: o.attr_name.
Guido van Rossuma8275371995-07-18 14:07:00 +0000166
167 */
168
169 /* Implemented elsewhere:
170
171 int PyObject_HasAttr(PyObject *o, PyObject *attr_name);
172
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000173 Returns 1 if o has the attribute attr_name, and 0 otherwise.
174 This is equivalent to the Python expression:
175 hasattr(o,attr_name).
Guido van Rossuma8275371995-07-18 14:07:00 +0000176
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000177 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +0000178
179 */
180
181 /* Implemented elsewhere:
182
183 PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name);
184
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000185 Retrieve an attributed named attr_name form object o.
186 Returns the attribute value on success, or NULL on failure.
187 This is the equivalent of the Python expression: o.attr_name.
Guido van Rossuma8275371995-07-18 14:07:00 +0000188
189 */
190
191
192 /* Implemented elsewhere:
193
Serhiy Storchakac6792272013-10-19 21:03:34 +0300194 int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v);
Guido van Rossuma8275371995-07-18 14:07:00 +0000195
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000196 Set the value of the attribute named attr_name, for object o,
Martin Panter45be8d62015-12-08 00:03:20 +0000197 to the value v. Raise an exception and return -1 on failure; return 0 on
198 success. This is the equivalent of the Python statement o.attr_name=v.
Guido van Rossuma8275371995-07-18 14:07:00 +0000199
200 */
201
202 /* Implemented elsewhere:
203
204 int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v);
205
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000206 Set the value of the attribute named attr_name, for object o,
Martin Panter45be8d62015-12-08 00:03:20 +0000207 to the value v. Raise an exception and return -1 on failure; return 0 on
208 success. This is the equivalent of the Python statement o.attr_name=v.
Guido van Rossuma8275371995-07-18 14:07:00 +0000209
210 */
211
212 /* implemented as a macro:
213
Serhiy Storchakac6792272013-10-19 21:03:34 +0300214 int PyObject_DelAttrString(PyObject *o, const char *attr_name);
Guido van Rossuma8275371995-07-18 14:07:00 +0000215
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000216 Delete attribute named attr_name, for object o. Returns
217 -1 on failure. This is the equivalent of the Python
218 statement: del o.attr_name.
Guido van Rossuma8275371995-07-18 14:07:00 +0000219
220 */
221#define PyObject_DelAttrString(O,A) PyObject_SetAttrString((O),(A),NULL)
222
223 /* implemented as a macro:
224
225 int PyObject_DelAttr(PyObject *o, PyObject *attr_name);
226
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000227 Delete attribute named attr_name, for object o. Returns -1
228 on failure. This is the equivalent of the Python
229 statement: del o.attr_name.
Guido van Rossuma8275371995-07-18 14:07:00 +0000230
231 */
232#define PyObject_DelAttr(O,A) PyObject_SetAttr((O),(A),NULL)
233
Guido van Rossuma8275371995-07-18 14:07:00 +0000234 /* Implemented elsewhere:
235
236 PyObject *PyObject_Repr(PyObject *o);
237
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000238 Compute the string representation of object, o. Returns the
239 string representation on success, NULL on failure. This is
240 the equivalent of the Python expression: repr(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000241
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000242 Called by the repr() built-in function.
Guido van Rossuma8275371995-07-18 14:07:00 +0000243
244 */
245
246 /* Implemented elsewhere:
247
248 PyObject *PyObject_Str(PyObject *o);
249
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000250 Compute the string representation of object, o. Returns the
251 string representation on success, NULL on failure. This is
252 the equivalent of the Python expression: str(o).)
Guido van Rossuma8275371995-07-18 14:07:00 +0000253
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000254 Called by the str() and print() built-in functions.
Marc-André Lemburgad7c98e2001-01-17 17:09:53 +0000255
256 */
257
Thomas Wouters89f507f2006-12-13 04:49:30 +0000258 /* Declared elsewhere
259
Mark Hammond91a681d2002-08-12 07:21:58 +0000260 PyAPI_FUNC(int) PyCallable_Check(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000261
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000262 Determine if the object, o, is callable. Return 1 if the
263 object is callable and 0 otherwise.
Guido van Rossuma8275371995-07-18 14:07:00 +0000264
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000265 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +0000266 */
267
Mark Hammond91a681d2002-08-12 07:21:58 +0000268 PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable_object,
Victor Stinner8a31c822016-08-19 17:12:23 +0200269 PyObject *args, PyObject *kwargs);
Tim Peters6d6c1a32001-08-02 04:15:00 +0000270
271 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000272 Call a callable Python object, callable_object, with
273 arguments and keywords arguments. The 'args' argument can not be
Serhiy Storchakab0f75c52016-12-06 13:45:44 +0200274 NULL.
Tim Peters6d6c1a32001-08-02 04:15:00 +0000275 */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000276
Victor Stinner4a7cc882015-03-06 23:35:27 +0100277#ifndef Py_LIMITED_API
Victor Stinnerae8b69c2016-09-09 14:07:44 -0700278 PyAPI_FUNC(PyObject*) _PyStack_AsTuple(
279 PyObject **stack,
Victor Stinner9be7e7b2016-08-19 16:11:43 +0200280 Py_ssize_t nargs);
281
Victor Stinner57f91ac2016-09-12 13:37:07 +0200282 /* Convert keyword arguments from the (stack, kwnames) format to a Python
283 dictionary.
284
285 kwnames must only contains str strings, no subclass, and all keys must
286 be unique. kwnames is not checked, usually these checks are done before or later
287 calling _PyStack_AsDict(). For example, _PyArg_ParseStack() raises an
288 error if a key is not a string. */
Victor Stinnerae8b69c2016-09-09 14:07:44 -0700289 PyAPI_FUNC(PyObject *) _PyStack_AsDict(
290 PyObject **values,
Victor Stinnerb8d768b2016-09-12 13:30:02 +0200291 PyObject *kwnames);
Victor Stinnerae8b69c2016-09-09 14:07:44 -0700292
Victor Stinnerf0ff8492017-06-09 13:24:53 +0200293 /* Convert (args, nargs, kwargs: dict) into (stack, nargs, kwnames: tuple).
Victor Stinnera9efb2f2016-09-09 17:40:22 -0700294
Victor Stinnerf0ff8492017-06-09 13:24:53 +0200295 Return 0 on success, raise an exception and return -1 on error.
296
297 Write the new stack into *p_stack. If *p_stack is differen than args, it
298 must be released by PyMem_Free().
Victor Stinnera9efb2f2016-09-09 17:40:22 -0700299
300 The stack uses borrowed references.
301
302 The type of keyword keys is not checked, these checks should be done
Victor Stinnerf0ff8492017-06-09 13:24:53 +0200303 later (ex: _PyArg_ParseStackAndKeywords). */
304 PyAPI_FUNC(int) _PyStack_UnpackDict(
Victor Stinnera9efb2f2016-09-09 17:40:22 -0700305 PyObject **args,
306 Py_ssize_t nargs,
307 PyObject *kwargs,
Victor Stinnerf0ff8492017-06-09 13:24:53 +0200308 PyObject ***p_stack,
309 PyObject **p_kwnames);
Victor Stinnera9efb2f2016-09-09 17:40:22 -0700310
Victor Stinner57f91ac2016-09-12 13:37:07 +0200311 /* Call the callable object func with the "fast call" calling convention:
312 args is a C array for positional arguments (nargs is the number of
313 positional arguments), kwargs is a dictionary for keyword arguments.
Victor Stinner9be7e7b2016-08-19 16:11:43 +0200314
Victor Stinner57f91ac2016-09-12 13:37:07 +0200315 If nargs is equal to zero, args can be NULL. kwargs can be NULL.
316 nargs must be greater or equal to zero.
Victor Stinner9be7e7b2016-08-19 16:11:43 +0200317
Victor Stinner57f91ac2016-09-12 13:37:07 +0200318 Return the result on success. Raise an exception on return NULL on
319 error. */
320 PyAPI_FUNC(PyObject *) _PyObject_FastCallDict(PyObject *func,
321 PyObject **args, Py_ssize_t nargs,
322 PyObject *kwargs);
Victor Stinner559bb6a2016-08-22 22:48:54 +0200323
Victor Stinner57f91ac2016-09-12 13:37:07 +0200324 /* Call the callable object func with the "fast call" calling convention:
325 args is a C array for positional arguments followed by values of
326 keyword arguments. Keys of keyword arguments are stored as a tuple
327 of strings in kwnames. nargs is the number of positional parameters at
328 the beginning of stack. The size of kwnames gives the number of keyword
329 values in the stack after positional arguments.
Victor Stinnerd8735722016-09-09 12:36:44 -0700330
Victor Stinner57f91ac2016-09-12 13:37:07 +0200331 kwnames must only contains str strings, no subclass, and all keys must
332 be unique.
Victor Stinnerd8735722016-09-09 12:36:44 -0700333
Victor Stinner57f91ac2016-09-12 13:37:07 +0200334 If nargs is equal to zero and there is no keyword argument (kwnames is
335 NULL or its size is zero), args can be NULL.
336
337 Return the result on success. Raise an exception and return NULL on
338 error. */
339 PyAPI_FUNC(PyObject *) _PyObject_FastCallKeywords
340 (PyObject *func,
341 PyObject **args,
342 Py_ssize_t nargs,
343 PyObject *kwnames);
Victor Stinnerd8735722016-09-09 12:36:44 -0700344
Victor Stinner559bb6a2016-08-22 22:48:54 +0200345#define _PyObject_FastCall(func, args, nargs) \
346 _PyObject_FastCallDict((func), (args), (nargs), NULL)
347
348#define _PyObject_CallNoArg(func) \
349 _PyObject_FastCall((func), NULL, 0)
350
351#define _PyObject_CallArg1(func, arg) \
352 _PyObject_FastCall((func), &(arg), 1)
Victor Stinner9be7e7b2016-08-19 16:11:43 +0200353
Victor Stinner3f1057a2016-08-25 01:04:14 +0200354 PyAPI_FUNC(PyObject *) _PyObject_Call_Prepend(PyObject *func,
355 PyObject *obj, PyObject *args,
356 PyObject *kwargs);
357
Victor Stinnerefde1462015-03-21 15:04:43 +0100358 PyAPI_FUNC(PyObject *) _Py_CheckFunctionResult(PyObject *func,
359 PyObject *result,
360 const char *where);
Victor Stinner9be7e7b2016-08-19 16:11:43 +0200361#endif /* Py_LIMITED_API */
Victor Stinner4a7cc882015-03-06 23:35:27 +0100362
Mark Hammond91a681d2002-08-12 07:21:58 +0000363 PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable_object,
Neal Norwitzfe554642006-03-17 06:58:45 +0000364 PyObject *args);
Guido van Rossuma8275371995-07-18 14:07:00 +0000365
366 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000367 Call a callable Python object, callable_object, with
368 arguments given by the tuple, args. If no arguments are
369 needed, then args may be NULL. Returns the result of the
370 call on success, or NULL on failure. This is the equivalent
371 of the Python expression: o(*args).
Guido van Rossuma8275371995-07-18 14:07:00 +0000372 */
373
Mark Hammond91a681d2002-08-12 07:21:58 +0000374 PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable_object,
Serhiy Storchaka1cfebc72013-05-29 18:50:54 +0300375 const char *format, ...);
Guido van Rossuma8275371995-07-18 14:07:00 +0000376
377 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000378 Call a callable Python object, callable_object, with a
379 variable number of C arguments. The C arguments are described
380 using a mkvalue-style format string. The format may be NULL,
381 indicating that no arguments are provided. Returns the
382 result of the call on success, or NULL on failure. This is
383 the equivalent of the Python expression: o(*args).
Guido van Rossuma8275371995-07-18 14:07:00 +0000384 */
385
386
Serhiy Storchaka1cfebc72013-05-29 18:50:54 +0300387 PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *o,
388 const char *method,
389 const char *format, ...);
Guido van Rossuma8275371995-07-18 14:07:00 +0000390
391 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000392 Call the method named m of object o with a variable number of
393 C arguments. The C arguments are described by a mkvalue
394 format string. The format may be NULL, indicating that no
395 arguments are provided. Returns the result of the call on
396 success, or NULL on failure. This is the equivalent of the
397 Python expression: o.method(args).
Fred Drakeb421b8c2001-10-26 16:21:32 +0000398 */
Guido van Rossuma8275371995-07-18 14:07:00 +0000399
Serhiy Storchaka9fab79b2016-09-11 11:03:14 +0300400#ifndef Py_LIMITED_API
Serhiy Storchaka1cfebc72013-05-29 18:50:54 +0300401 PyAPI_FUNC(PyObject *) _PyObject_CallMethodId(PyObject *o,
402 _Py_Identifier *method,
403 const char *format, ...);
Martin v. Löwisafe55bb2011-10-09 10:38:36 +0200404
405 /*
406 Like PyObject_CallMethod, but expect a _Py_Identifier* as the
407 method name.
408 */
Serhiy Storchaka9fab79b2016-09-11 11:03:14 +0300409#endif /* !Py_LIMITED_API */
Martin v. Löwisafe55bb2011-10-09 10:38:36 +0200410
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000411 PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,
Serhiy Storchaka1cfebc72013-05-29 18:50:54 +0300412 const char *format,
413 ...);
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000414 PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *o,
Serhiy Storchaka1cfebc72013-05-29 18:50:54 +0300415 const char *name,
416 const char *format,
417 ...);
Serhiy Storchaka9fab79b2016-09-11 11:03:14 +0300418#ifndef Py_LIMITED_API
Martin v. Löwisafe55bb2011-10-09 10:38:36 +0200419 PyAPI_FUNC(PyObject *) _PyObject_CallMethodId_SizeT(PyObject *o,
420 _Py_Identifier *name,
Serhiy Storchaka1cfebc72013-05-29 18:50:54 +0300421 const char *format,
422 ...);
Serhiy Storchaka9fab79b2016-09-11 11:03:14 +0300423#endif /* !Py_LIMITED_API */
Guido van Rossuma8275371995-07-18 14:07:00 +0000424
Mark Hammond91a681d2002-08-12 07:21:58 +0000425 PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,
Neal Norwitzfe554642006-03-17 06:58:45 +0000426 ...);
Fred Drakeb421b8c2001-10-26 16:21:32 +0000427
428 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000429 Call a callable Python object, callable_object, with a
430 variable number of C arguments. The C arguments are provided
431 as PyObject * values, terminated by a NULL. Returns the
432 result of the call on success, or NULL on failure. This is
433 the equivalent of the Python expression: o(*args).
Fred Drakeb421b8c2001-10-26 16:21:32 +0000434 */
435
436
Mark Hammond91a681d2002-08-12 07:21:58 +0000437 PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(PyObject *o,
Neal Norwitzfe554642006-03-17 06:58:45 +0000438 PyObject *method, ...);
Serhiy Storchaka9fab79b2016-09-11 11:03:14 +0300439#ifndef Py_LIMITED_API
Alexandre Vassalotti865eaa12013-05-02 10:44:04 -0700440 PyAPI_FUNC(PyObject *) _PyObject_CallMethodIdObjArgs(PyObject *o,
Brett Cannonfd074152012-04-14 14:10:13 -0400441 struct _Py_Identifier *method,
442 ...);
Serhiy Storchaka9fab79b2016-09-11 11:03:14 +0300443#endif /* !Py_LIMITED_API */
Brett Cannonfd074152012-04-14 14:10:13 -0400444
Fred Drakeb421b8c2001-10-26 16:21:32 +0000445 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000446 Call the method named m of object o with a variable number of
447 C arguments. The C arguments are provided as PyObject *
448 values, terminated by NULL. Returns the result of the call
449 on success, or NULL on failure. This is the equivalent of
450 the Python expression: o.method(args).
Guido van Rossuma8275371995-07-18 14:07:00 +0000451 */
452
453
454 /* Implemented elsewhere:
455
456 long PyObject_Hash(PyObject *o);
457
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000458 Compute and return the hash, hash_value, of an object, o. On
459 failure, return -1. This is the equivalent of the Python
460 expression: hash(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000461 */
462
463
464 /* Implemented elsewhere:
465
466 int PyObject_IsTrue(PyObject *o);
467
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000468 Returns 1 if the object, o, is considered to be true, 0 if o is
469 considered to be false and -1 on failure. This is equivalent to the
470 Python expression: not not o
Guido van Rossuma8275371995-07-18 14:07:00 +0000471 */
472
Guido van Rossumc3d3f961998-04-09 17:53:59 +0000473 /* Implemented elsewhere:
474
475 int PyObject_Not(PyObject *o);
476
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000477 Returns 0 if the object, o, is considered to be true, 1 if o is
478 considered to be false and -1 on failure. This is equivalent to the
479 Python expression: not o
Guido van Rossumc3d3f961998-04-09 17:53:59 +0000480 */
481
Mark Hammond91a681d2002-08-12 07:21:58 +0000482 PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000483
484 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000485 On success, returns a type object corresponding to the object
486 type of object o. On failure, returns NULL. This is
487 equivalent to the Python expression: type(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000488 */
489
Martin v. Löwis18e16552006-02-15 17:27:45 +0000490 PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
Jeremy Hylton6253f832000-07-12 12:56:19 +0000491
Guido van Rossuma8275371995-07-18 14:07:00 +0000492 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000493 Return the size of object o. If the object, o, provides
494 both sequence and mapping protocols, the sequence size is
495 returned. On error, -1 is returned. This is the equivalent
496 to the Python expression: len(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000497 */
498
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000499 /* For DLL compatibility */
500#undef PyObject_Length
Martin v. Löwis18e16552006-02-15 17:27:45 +0000501 PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000502#define PyObject_Length PyObject_Size
503
Armin Ronacher74b38b12012-10-07 10:29:32 +0200504#ifndef Py_LIMITED_API
505 PyAPI_FUNC(int) _PyObject_HasLen(PyObject *o);
Martin v. Löwis1c0689c2014-01-03 21:36:49 +0100506 PyAPI_FUNC(Py_ssize_t) PyObject_LengthHint(PyObject *o, Py_ssize_t);
Armin Ronacher74b38b12012-10-07 10:29:32 +0200507#endif
Raymond Hettinger6b27cda2005-09-24 21:23:05 +0000508
509 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000510 Guess the size of object o using len(o) or o.__length_hint__().
511 If neither of those return a non-negative value, then return the
512 default value. If one of the calls fails, this function returns -1.
Raymond Hettinger6b27cda2005-09-24 21:23:05 +0000513 */
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +0000514
Mark Hammond91a681d2002-08-12 07:21:58 +0000515 PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
Guido van Rossuma8275371995-07-18 14:07:00 +0000516
517 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000518 Return element of o corresponding to the object, key, or NULL
519 on failure. This is the equivalent of the Python expression:
520 o[key].
Guido van Rossuma8275371995-07-18 14:07:00 +0000521 */
522
Mark Hammond91a681d2002-08-12 07:21:58 +0000523 PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
Guido van Rossuma8275371995-07-18 14:07:00 +0000524
525 /*
Martin Panter45be8d62015-12-08 00:03:20 +0000526 Map the object key to the value v. Raise an exception and return -1
527 on failure; return 0 on success. This is the equivalent of the Python
528 statement o[key]=v.
Guido van Rossuma8275371995-07-18 14:07:00 +0000529 */
530
Serhiy Storchakac6792272013-10-19 21:03:34 +0300531 PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, const char *key);
Martin v. Löwisb0d71d02002-01-05 10:50:30 +0000532
533 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000534 Remove the mapping for object, key, from the object *o.
535 Returns -1 on failure. This is equivalent to
536 the Python statement: del o[key].
Martin v. Löwisb0d71d02002-01-05 10:50:30 +0000537 */
538
Mark Hammond91a681d2002-08-12 07:21:58 +0000539 PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
Guido van Rossum6cdc6f41996-08-21 17:41:54 +0000540
541 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000542 Delete the mapping for key from *o. Returns -1 on failure.
543 This is the equivalent of the Python statement: del o[key].
Guido van Rossum6cdc6f41996-08-21 17:41:54 +0000544 */
545
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000546 /* old buffer API
547 FIXME: usage of these should all be replaced in Python itself
548 but for backwards compatibility we will implement them.
Raymond Hettinger15f44ab2016-08-30 10:47:49 -0700549 Their usage without a corresponding "unlock" mechanism
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000550 may create issues (but they would already be there). */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000551
Mark Hammond91a681d2002-08-12 07:21:58 +0000552 PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000553 const char **buffer,
554 Py_ssize_t *buffer_len);
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000555
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000556 /*
557 Takes an arbitrary object which must support the (character,
558 single segment) buffer interface and returns a pointer to a
559 read-only memory location useable as character based input
560 for subsequent processing.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000561
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000562 0 is returned on success. buffer and buffer_len are only
563 set in case no error occurs. Otherwise, -1 is returned and
564 an exception set.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000565 */
566
Mark Hammond91a681d2002-08-12 07:21:58 +0000567 PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);
Jeremy Hylton89c3a222001-11-09 21:59:42 +0000568
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000569 /*
570 Checks whether an arbitrary object supports the (character,
571 single segment) buffer interface. Returns 1 on success, 0
572 on failure.
Jeremy Hylton89c3a222001-11-09 21:59:42 +0000573 */
574
Mark Hammond91a681d2002-08-12 07:21:58 +0000575 PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000576 const void **buffer,
577 Py_ssize_t *buffer_len);
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000578
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000579 /*
580 Same as PyObject_AsCharBuffer() except that this API expects
581 (readable, single segment) buffer interface and returns a
582 pointer to a read-only memory location which can contain
583 arbitrary data.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000584
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000585 0 is returned on success. buffer and buffer_len are only
Ezio Melotti13925002011-03-16 11:05:33 +0200586 set in case no error occurs. Otherwise, -1 is returned and
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000587 an exception set.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000588 */
589
Mark Hammond91a681d2002-08-12 07:21:58 +0000590 PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000591 void **buffer,
592 Py_ssize_t *buffer_len);
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000593
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000594 /*
595 Takes an arbitrary object which must support the (writable,
596 single segment) buffer interface and returns a pointer to a
597 writable memory location in buffer of size buffer_len.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000598
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000599 0 is returned on success. buffer and buffer_len are only
Ezio Melotti13925002011-03-16 11:05:33 +0200600 set in case no error occurs. Otherwise, -1 is returned and
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000601 an exception set.
Guido van Rossumfd9eed32000-03-10 22:35:06 +0000602 */
Guido van Rossuma8275371995-07-18 14:07:00 +0000603
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000604 /* new buffer API */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000605
Martin v. Löwisc83bc3c2011-01-06 19:15:47 +0000606#ifndef Py_LIMITED_API
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000607#define PyObject_CheckBuffer(obj) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000608 (((obj)->ob_type->tp_as_buffer != NULL) && \
609 ((obj)->ob_type->tp_as_buffer->bf_getbuffer != NULL))
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000610
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000611 /* Return 1 if the getbuffer function is available, otherwise
612 return 0 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000613
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000614 PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view,
615 int flags);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000616
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000617 /* This is a C-API version of the getbuffer function call. It checks
618 to make sure object has the required function pointer and issues the
619 call. Returns -1 and raises an error on failure and returns 0 on
620 success
621 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000622
623
Travis E. Oliphant8ae62b62007-09-23 02:00:13 +0000624 PyAPI_FUNC(void *) PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices);
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000625
626 /* Get the memory area pointed to by the indices for the buffer given.
627 Note that view->ndim is the assumed size of indices
628 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000629
630 PyAPI_FUNC(int) PyBuffer_SizeFromFormat(const char *);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000631
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000632 /* Return the implied itemsize of the data-format area from a
633 struct-style description */
634
635
636
Stefan Krah7d12d9d2012-07-28 12:25:55 +0200637 /* Implementation in memoryobject.c */
Travis E. Oliphant8ae62b62007-09-23 02:00:13 +0000638 PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, Py_buffer *view,
Stefan Krah7d12d9d2012-07-28 12:25:55 +0200639 Py_ssize_t len, char order);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000640
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000641 PyAPI_FUNC(int) PyBuffer_FromContiguous(Py_buffer *view, void *buf,
Stefan Krah7d12d9d2012-07-28 12:25:55 +0200642 Py_ssize_t len, char order);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000643
644
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000645 /* Copy len bytes of data from the contiguous chunk of memory
646 pointed to by buf into the buffer exported by obj. Return
647 0 on success and return -1 and raise a PyBuffer_Error on
648 error (i.e. the object does not have a buffer interface or
649 it is not working).
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000650
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000651 If fort is 'F', then if the object is multi-dimensional,
652 then the data will be copied into the array in
653 Fortran-style (first dimension varies the fastest). If
654 fort is 'C', then the data will be copied into the array
655 in C-style (last dimension varies the fastest). If fort
656 is 'A', then it does not matter and the copy will be made
657 in whatever way is more efficient.
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000658
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000659 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000660
661 PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000662
663 /* Copy the data from the src buffer to the buffer of destination
664 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000665
Stefan Krah9a2d99e2012-02-25 12:24:21 +0100666 PyAPI_FUNC(int) PyBuffer_IsContiguous(const Py_buffer *view, char fort);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000667
668
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000669 PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims,
670 Py_ssize_t *shape,
671 Py_ssize_t *strides,
672 int itemsize,
673 char fort);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000674
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000675 /* Fill the strides array with byte-strides of a contiguous
676 (Fortran-style if fort is 'F' or C-style otherwise)
677 array of the given shape with the given number of bytes
678 per element.
679 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000680
Martin v. Löwis423be952008-08-13 15:53:07 +0000681 PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000682 Py_ssize_t len, int readonly,
683 int flags);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000684
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000685 /* Fills in a buffer-info structure correctly for an exporter
686 that can only share a contiguous chunk of memory of
687 "unsigned bytes" of the given length. Returns 0 on success
688 and -1 (with raising an error) on error.
689 */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000690
Martin v. Löwis423be952008-08-13 15:53:07 +0000691 PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);
692
693 /* Releases a Py_buffer obtained from getbuffer ParseTuple's s*.
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000694 */
Martin v. Löwisc83bc3c2011-01-06 19:15:47 +0000695#endif /* Py_LIMITED_API */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000696
Eric Smith8fd3eba2008-02-17 19:48:00 +0000697 PyAPI_FUNC(PyObject *) PyObject_Format(PyObject* obj,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000698 PyObject *format_spec);
Eric Smith8fd3eba2008-02-17 19:48:00 +0000699 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000700 Takes an arbitrary object and returns the result of
701 calling obj.__format__(format_spec).
Eric Smith8fd3eba2008-02-17 19:48:00 +0000702 */
703
Guido van Rossum213c7a62001-04-23 14:08:49 +0000704/* Iterators */
705
Mark Hammond91a681d2002-08-12 07:21:58 +0000706 PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);
Guido van Rossum59d1d2b2001-04-20 19:13:02 +0000707 /* Takes an object and returns an iterator for it.
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000708 This is typically a new iterator but if the argument
709 is an iterator, this returns itself. */
Guido van Rossum59d1d2b2001-04-20 19:13:02 +0000710
Guido van Rossum213c7a62001-04-23 14:08:49 +0000711#define PyIter_Check(obj) \
Amaury Forgeot d'Arcf343e012009-01-12 23:58:21 +0000712 ((obj)->ob_type->tp_iternext != NULL && \
713 (obj)->ob_type->tp_iternext != &_PyObject_NextNotImplemented)
Guido van Rossum213c7a62001-04-23 14:08:49 +0000714
Mark Hammond91a681d2002-08-12 07:21:58 +0000715 PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);
Guido van Rossum213c7a62001-04-23 14:08:49 +0000716 /* Takes an iterator object and calls its tp_iternext slot,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000717 returning the next value. If the iterator is exhausted,
718 this returns NULL without setting an exception.
719 NULL with an exception means an error occurred. */
Guido van Rossum213c7a62001-04-23 14:08:49 +0000720
Guido van Rossuma8275371995-07-18 14:07:00 +0000721/* Number Protocol:*/
722
Mark Hammond91a681d2002-08-12 07:21:58 +0000723 PyAPI_FUNC(int) PyNumber_Check(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000724
725 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000726 Returns 1 if the object, o, provides numeric protocols, and
727 false otherwise.
Guido van Rossuma8275371995-07-18 14:07:00 +0000728
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000729 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +0000730 */
731
Mark Hammond91a681d2002-08-12 07:21:58 +0000732 PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000733
734 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000735 Returns the result of adding o1 and o2, or null on failure.
736 This is the equivalent of the Python 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_Subtract(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 subtracting o2 from o1, or null on
743 failure. This is the equivalent of the Python expression:
744 o1-o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000745 */
746
Mark Hammond91a681d2002-08-12 07:21:58 +0000747 PyAPI_FUNC(PyObject *) PyNumber_Multiply(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 multiplying o1 and o2, or null on
751 failure. This is the equivalent of the Python expression:
752 o1*o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000753 */
754
Serhiy Storchaka34d0ac82016-12-27 14:57:39 +0200755#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
Benjamin Petersond51374e2014-04-09 23:55:56 -0400756 PyAPI_FUNC(PyObject *) PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2);
757
758 /*
759 This is the equivalent of the Python expression: o1 @ o2.
760 */
Serhiy Storchaka34d0ac82016-12-27 14:57:39 +0200761#endif
Benjamin Petersond51374e2014-04-09 23:55:56 -0400762
Mark Hammond91a681d2002-08-12 07:21:58 +0000763 PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2);
Guido van Rossum4668b002001-08-08 05:00:18 +0000764
765 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000766 Returns the result of dividing o1 by o2 giving an integral result,
767 or null on failure.
768 This is the equivalent of the Python expression: o1//o2.
Guido van Rossum4668b002001-08-08 05:00:18 +0000769 */
770
Mark Hammond91a681d2002-08-12 07:21:58 +0000771 PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2);
Guido van Rossum4668b002001-08-08 05:00:18 +0000772
773 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000774 Returns the result of dividing o1 by o2 giving a float result,
775 or null on failure.
776 This is the equivalent of the Python expression: o1/o2.
Guido van Rossum4668b002001-08-08 05:00:18 +0000777 */
778
Mark Hammond91a681d2002-08-12 07:21:58 +0000779 PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000780
781 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000782 Returns the remainder of dividing o1 by o2, or null on
783 failure. This is the equivalent of the Python expression:
784 o1%o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000785 */
786
Mark Hammond91a681d2002-08-12 07:21:58 +0000787 PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000788
789 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000790 See the built-in function divmod. Returns NULL on failure.
791 This is the equivalent of the Python expression:
792 divmod(o1,o2).
Guido van Rossuma8275371995-07-18 14:07:00 +0000793 */
794
Mark Hammond91a681d2002-08-12 07:21:58 +0000795 PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,
Neal Norwitzfe554642006-03-17 06:58:45 +0000796 PyObject *o3);
Guido van Rossuma8275371995-07-18 14:07:00 +0000797
798 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000799 See the built-in function pow. Returns NULL on failure.
800 This is the equivalent of the Python expression:
801 pow(o1,o2,o3), where o3 is optional.
Guido van Rossuma8275371995-07-18 14:07:00 +0000802 */
803
Mark Hammond91a681d2002-08-12 07:21:58 +0000804 PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000805
806 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000807 Returns the negation of o on success, or null on failure.
808 This is the equivalent of the Python expression: -o.
Guido van Rossuma8275371995-07-18 14:07:00 +0000809 */
810
Mark Hammond91a681d2002-08-12 07:21:58 +0000811 PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000812
813 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000814 Returns the (what?) of o on success, or NULL on failure.
815 This is the equivalent of the Python expression: +o.
Guido van Rossuma8275371995-07-18 14:07:00 +0000816 */
817
Mark Hammond91a681d2002-08-12 07:21:58 +0000818 PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000819
820 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000821 Returns the absolute value of o, or null on failure. This is
822 the equivalent of the Python expression: abs(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000823 */
824
Mark Hammond91a681d2002-08-12 07:21:58 +0000825 PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000826
827 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000828 Returns the bitwise negation of o on success, or NULL on
829 failure. This is the equivalent of the Python expression:
830 ~o.
Guido van Rossuma8275371995-07-18 14:07:00 +0000831 */
832
Mark Hammond91a681d2002-08-12 07:21:58 +0000833 PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000834
835 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000836 Returns the result of left shifting o1 by o2 on success, or
837 NULL on failure. This is the equivalent of the Python
838 expression: o1 << o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000839 */
840
Mark Hammond91a681d2002-08-12 07:21:58 +0000841 PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000842
843 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000844 Returns the result of right shifting o1 by o2 on success, or
845 NULL on failure. This is the equivalent of the Python
846 expression: o1 >> o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000847 */
848
Mark Hammond91a681d2002-08-12 07:21:58 +0000849 PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000850
851 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000852 Returns the result of bitwise and of o1 and o2 on success, or
853 NULL on failure. This is the equivalent of the Python
854 expression: o1&o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000855
Guido van Rossuma8275371995-07-18 14:07:00 +0000856 */
857
Mark Hammond91a681d2002-08-12 07:21:58 +0000858 PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000859
860 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000861 Returns the bitwise exclusive or of o1 by o2 on success, or
862 NULL on failure. This is the equivalent of the Python
863 expression: o1^o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000864 */
865
Mark Hammond91a681d2002-08-12 07:21:58 +0000866 PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +0000867
868 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000869 Returns the result of bitwise or on o1 and o2 on success, or
870 NULL on failure. This is the equivalent of the Python
871 expression: o1|o2.
Guido van Rossuma8275371995-07-18 14:07:00 +0000872 */
873
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000874#define PyIndex_Check(obj) \
875 ((obj)->ob_type->tp_as_number != NULL && \
876 (obj)->ob_type->tp_as_number->nb_index != NULL)
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000877
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000878 PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o);
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000879
880 /*
Serhiy Storchaka95949422013-08-27 19:40:23 +0300881 Returns the object converted to a Python int
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000882 or NULL with an error raised on failure.
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000883 */
884
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000885 PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc);
886
887 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000888 Returns the object converted to Py_ssize_t by going through
889 PyNumber_Index first. If an overflow error occurs while
Serhiy Storchaka95949422013-08-27 19:40:23 +0300890 converting the int to Py_ssize_t, then the second argument
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000891 is the error-type to return. If it is NULL, then the overflow error
892 is cleared and the value is clipped.
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000893 */
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000894
Mark Dickinsond7467682009-01-10 22:14:33 +0000895 PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);
896
Guido van Rossuma8275371995-07-18 14:07:00 +0000897 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000898 Returns the o converted to an integer object on success, or
899 NULL on failure. This is the equivalent of the Python
900 expression: int(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000901 */
902
Mark Hammond91a681d2002-08-12 07:21:58 +0000903 PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +0000904
905 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000906 Returns the o converted to a float object on success, or NULL
907 on failure. This is the equivalent of the Python expression:
908 float(o).
Guido van Rossuma8275371995-07-18 14:07:00 +0000909 */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000910
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000911/* In-place variants of (some of) the above number protocol functions */
912
Mark Hammond91a681d2002-08-12 07:21:58 +0000913 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000914
915 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000916 Returns the result of adding o2 to o1, possibly in-place, or null
917 on failure. This is the equivalent of the Python expression:
918 o1 += o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000919 */
920
Mark Hammond91a681d2002-08-12 07:21:58 +0000921 PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000922
923 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000924 Returns the result of subtracting o2 from o1, possibly in-place or
925 null on failure. This is the equivalent of the Python expression:
926 o1 -= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000927 */
928
Mark Hammond91a681d2002-08-12 07:21:58 +0000929 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000930
931 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000932 Returns the result of multiplying o1 by o2, possibly in-place, or
933 null on failure. This is the equivalent of the Python expression:
934 o1 *= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000935 */
936
Serhiy Storchaka34d0ac82016-12-27 14:57:39 +0200937#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
Benjamin Petersond51374e2014-04-09 23:55:56 -0400938 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2);
939
940 /*
941 This is the equivalent of the Python expression: o1 @= o2.
942 */
Serhiy Storchaka34d0ac82016-12-27 14:57:39 +0200943#endif
Benjamin Petersond51374e2014-04-09 23:55:56 -0400944
Mark Hammond91a681d2002-08-12 07:21:58 +0000945 PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000946 PyObject *o2);
Guido van Rossum4668b002001-08-08 05:00:18 +0000947
948 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000949 Returns the result of dividing o1 by o2 giving an integral result,
950 possibly in-place, or null on failure.
951 This is the equivalent of the Python expression:
952 o1 /= o2.
Guido van Rossum4668b002001-08-08 05:00:18 +0000953 */
954
Mark Hammond91a681d2002-08-12 07:21:58 +0000955 PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000956 PyObject *o2);
Guido van Rossum4668b002001-08-08 05:00:18 +0000957
958 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000959 Returns the result of dividing o1 by o2 giving a float result,
960 possibly in-place, or null on failure.
961 This is the equivalent of the Python expression:
962 o1 /= o2.
Guido van Rossum4668b002001-08-08 05:00:18 +0000963 */
964
Mark Hammond91a681d2002-08-12 07:21:58 +0000965 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000966
967 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000968 Returns the remainder of dividing o1 by o2, possibly in-place, or
969 null on failure. This is the equivalent of the Python expression:
970 o1 %= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000971 */
972
Mark Hammond91a681d2002-08-12 07:21:58 +0000973 PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000974 PyObject *o3);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000975
976 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000977 Returns the result of raising o1 to the power of o2, possibly
978 in-place, or null on failure. This is the equivalent of the Python
979 expression: o1 **= o2, or pow(o1, o2, o3) if o3 is present.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000980 */
981
Mark Hammond91a681d2002-08-12 07:21:58 +0000982 PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000983
984 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000985 Returns the result of left shifting o1 by o2, possibly in-place, or
986 null on failure. This is the equivalent of the Python expression:
987 o1 <<= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000988 */
989
Mark Hammond91a681d2002-08-12 07:21:58 +0000990 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000991
992 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000993 Returns the result of right shifting o1 by o2, possibly in-place or
994 null on failure. This is the equivalent of the Python expression:
995 o1 >>= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000996 */
997
Mark Hammond91a681d2002-08-12 07:21:58 +0000998 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +0000999
1000 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001001 Returns the result of bitwise and of o1 and o2, possibly in-place,
1002 or null on failure. This is the equivalent of the Python
1003 expression: o1 &= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001004 */
1005
Mark Hammond91a681d2002-08-12 07:21:58 +00001006 PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001007
1008 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001009 Returns the bitwise exclusive or of o1 by o2, possibly in-place, or
1010 null on failure. This is the equivalent of the Python expression:
1011 o1 ^= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001012 */
1013
Mark Hammond91a681d2002-08-12 07:21:58 +00001014 PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001015
1016 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001017 Returns the result of bitwise or of o1 and o2, possibly in-place,
1018 or null on failure. This is the equivalent of the Python
1019 expression: o1 |= o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001020 */
1021
Guido van Rossumcd16bf62007-06-13 18:07:49 +00001022 PyAPI_FUNC(PyObject *) PyNumber_ToBase(PyObject *n, int base);
1023
1024 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001025 Returns the integer n converted to a string with a base, with a base
1026 marker of 0b, 0o or 0x prefixed if applicable.
1027 If n is not an int object, it is converted with PyNumber_Index first.
Guido van Rossumcd16bf62007-06-13 18:07:49 +00001028 */
1029
Guido van Rossuma8275371995-07-18 14:07:00 +00001030
1031/* Sequence protocol:*/
1032
Mark Hammond91a681d2002-08-12 07:21:58 +00001033 PyAPI_FUNC(int) PySequence_Check(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001034
1035 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001036 Return 1 if the object provides sequence protocol, and zero
1037 otherwise.
Guido van Rossuma8275371995-07-18 14:07:00 +00001038
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001039 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +00001040 */
1041
Martin v. Löwis18e16552006-02-15 17:27:45 +00001042 PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
Jeremy Hylton6253f832000-07-12 12:56:19 +00001043
Guido van Rossum4f4ce681996-07-21 02:22:56 +00001044 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001045 Return the size of sequence object o, or -1 on failure.
Guido van Rossum4f4ce681996-07-21 02:22:56 +00001046 */
1047
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +00001048 /* For DLL compatibility */
1049#undef PySequence_Length
Martin v. Löwis18e16552006-02-15 17:27:45 +00001050 PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +00001051#define PySequence_Length PySequence_Size
1052
1053
Mark Hammond91a681d2002-08-12 07:21:58 +00001054 PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);
Guido van Rossuma8275371995-07-18 14:07:00 +00001055
1056 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001057 Return the concatenation of o1 and o2 on success, and NULL on
1058 failure. This is the equivalent of the Python
1059 expression: o1+o2.
Guido van Rossuma8275371995-07-18 14:07:00 +00001060 */
1061
Martin v. Löwis18e16552006-02-15 17:27:45 +00001062 PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count);
Guido van Rossuma8275371995-07-18 14:07:00 +00001063
1064 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001065 Return the result of repeating sequence object o count times,
1066 or NULL on failure. This is the equivalent of the Python
1067 expression: o1*count.
Guido van Rossuma8275371995-07-18 14:07:00 +00001068 */
1069
Martin v. Löwis18e16552006-02-15 17:27:45 +00001070 PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i);
Guido van Rossuma8275371995-07-18 14:07:00 +00001071
1072 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001073 Return the ith element of o, or NULL on failure. This is the
1074 equivalent of the Python expression: o[i].
Guido van Rossuma8275371995-07-18 14:07:00 +00001075 */
1076
Martin v. Löwis18e16552006-02-15 17:27:45 +00001077 PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
Guido van Rossuma8275371995-07-18 14:07:00 +00001078
1079 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001080 Return the slice of sequence object o between i1 and i2, or
1081 NULL on failure. This is the equivalent of the Python
1082 expression: o[i1:i2].
Guido van Rossuma8275371995-07-18 14:07:00 +00001083 */
1084
Martin v. Löwis18e16552006-02-15 17:27:45 +00001085 PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);
Guido van Rossuma8275371995-07-18 14:07:00 +00001086
1087 /*
Martin Panter45be8d62015-12-08 00:03:20 +00001088 Assign object v to the ith element of o. Raise an exception and return
1089 -1 on failure; return 0 on success. This is the equivalent of the
1090 Python statement o[i]=v.
Guido van Rossuma8275371995-07-18 14:07:00 +00001091 */
1092
Martin v. Löwis18e16552006-02-15 17:27:45 +00001093 PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
Guido van Rossum6cdc6f41996-08-21 17:41:54 +00001094
1095 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001096 Delete the ith element of object v. Returns
1097 -1 on failure. This is the equivalent of the Python
1098 statement: del o[i].
Guido van Rossum6cdc6f41996-08-21 17:41:54 +00001099 */
1100
Martin v. Löwis18e16552006-02-15 17:27:45 +00001101 PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2,
Neal Norwitzfe554642006-03-17 06:58:45 +00001102 PyObject *v);
Guido van Rossuma8275371995-07-18 14:07:00 +00001103
1104 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001105 Assign the sequence object, v, to the slice in sequence
1106 object, o, from i1 to i2. Returns -1 on failure. This is the
1107 equivalent of the Python statement: o[i1:i2]=v.
Guido van Rossuma8275371995-07-18 14:07:00 +00001108 */
1109
Martin v. Löwis18e16552006-02-15 17:27:45 +00001110 PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
Guido van Rossum6cdc6f41996-08-21 17:41:54 +00001111
1112 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001113 Delete the slice in sequence object, o, from i1 to i2.
1114 Returns -1 on failure. This is the equivalent of the Python
1115 statement: del o[i1:i2].
Guido van Rossum6cdc6f41996-08-21 17:41:54 +00001116 */
1117
Mark Hammond91a681d2002-08-12 07:21:58 +00001118 PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001119
1120 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001121 Returns the sequence, o, as a tuple on success, and NULL on failure.
1122 This is equivalent to the Python expression: tuple(o)
Guido van Rossuma8275371995-07-18 14:07:00 +00001123 */
1124
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001125
Mark Hammond91a681d2002-08-12 07:21:58 +00001126 PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);
Guido van Rossum2adf06b1996-12-05 21:48:50 +00001127 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001128 Returns the sequence, o, as a list on success, and NULL on failure.
1129 This is equivalent to the Python expression: list(o)
Guido van Rossum2adf06b1996-12-05 21:48:50 +00001130 */
Guido van Rossumf39fc431997-03-04 18:31:47 +00001131
Mark Hammond91a681d2002-08-12 07:21:58 +00001132 PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001133 /*
Benjamin Peterson7ddf3eb2014-04-08 10:51:20 -04001134 Return the sequence, o, as a list, unless it's already a
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001135 tuple or list. Use PySequence_Fast_GET_ITEM to access the
1136 members of this list, and PySequence_Fast_GET_SIZE to get its length.
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001137
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001138 Returns NULL on failure. If the object does not support iteration,
1139 raises a TypeError exception with m as the message text.
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001140 */
1141
Tim Peters1fc240e2001-10-26 05:06:50 +00001142#define PySequence_Fast_GET_SIZE(o) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001143 (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o))
Tim Peters1fc240e2001-10-26 05:06:50 +00001144 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001145 Return the size of o, assuming that o was returned by
1146 PySequence_Fast and is not NULL.
Tim Peters1fc240e2001-10-26 05:06:50 +00001147 */
1148
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001149#define PySequence_Fast_GET_ITEM(o, i)\
1150 (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i))
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001151 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001152 Return the ith element of o, assuming that o was returned by
1153 PySequence_Fast, and that i is within bounds.
Andrew M. Kuchling74042d62000-06-18 18:43:14 +00001154 */
1155
Martin v. Löwis01f94bd2002-05-08 08:44:21 +00001156#define PySequence_ITEM(o, i)\
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001157 ( Py_TYPE(o)->tp_as_sequence->sq_item(o, i) )
Martin v. Löwis01f94bd2002-05-08 08:44:21 +00001158 /* Assume tp_as_sequence and sq_item exist and that i does not
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001159 need to be corrected for a negative index
1160 */
Martin v. Löwis01f94bd2002-05-08 08:44:21 +00001161
Raymond Hettinger42bec932004-03-12 16:38:17 +00001162#define PySequence_Fast_ITEMS(sf) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001163 (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \
1164 : ((PyTupleObject *)(sf))->ob_item)
1165 /* Return a pointer to the underlying item array for
1166 an object retured by PySequence_Fast */
Raymond Hettingerc1e4f9d2004-03-12 08:04:00 +00001167
Neal Norwitz1fc4b772006-03-04 18:49:58 +00001168 PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value);
Guido van Rossuma8275371995-07-18 14:07:00 +00001169
1170 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001171 Return the number of occurrences on value on o, that is,
1172 return the number of keys for which o[key]==value. On
1173 failure, return -1. This is equivalent to the Python
1174 expression: o.count(value).
Guido van Rossuma8275371995-07-18 14:07:00 +00001175 */
1176
Mark Hammond91a681d2002-08-12 07:21:58 +00001177 PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob);
Tim Peterscb8d3682001-05-05 21:05:01 +00001178 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001179 Return -1 if error; 1 if ob in seq; 0 if ob not in seq.
1180 Use __contains__ if possible, else _PySequence_IterSearch().
Tim Peterscb8d3682001-05-05 21:05:01 +00001181 */
1182
Martin v. Löwis4d0d4712010-12-03 20:14:31 +00001183#ifndef Py_LIMITED_API
Tim Peters16a77ad2001-09-08 04:00:12 +00001184#define PY_ITERSEARCH_COUNT 1
1185#define PY_ITERSEARCH_INDEX 2
1186#define PY_ITERSEARCH_CONTAINS 3
Neal Norwitz1fc4b772006-03-04 18:49:58 +00001187 PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001188 PyObject *obj, int operation);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +00001189#endif
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001190 /*
1191 Iterate over seq. Result depends on the operation:
1192 PY_ITERSEARCH_COUNT: return # of times obj appears in seq; -1 if
1193 error.
1194 PY_ITERSEARCH_INDEX: return 0-based index of first occurrence of
1195 obj in seq; set ValueError and return -1 if none found;
1196 also return -1 on error.
1197 PY_ITERSEARCH_CONTAINS: return 1 if obj in seq, else 0; -1 on
1198 error.
1199 */
Guido van Rossum83684531999-03-17 18:44:39 +00001200
1201/* For DLL-level backwards compatibility */
1202#undef PySequence_In
Mark Hammond91a681d2002-08-12 07:21:58 +00001203 PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value);
Guido van Rossum83684531999-03-17 18:44:39 +00001204
1205/* For source-level backwards compatibility */
Guido van Rossumf1536db1998-08-23 22:06:59 +00001206#define PySequence_In PySequence_Contains
Guido van Rossuma8275371995-07-18 14:07:00 +00001207
1208 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001209 Determine if o contains value. If an item in o is equal to
1210 X, return 1, otherwise return 0. On error, return -1. This
1211 is equivalent to the Python expression: value in o.
Guido van Rossuma8275371995-07-18 14:07:00 +00001212 */
1213
Neal Norwitz1fc4b772006-03-04 18:49:58 +00001214 PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value);
Guido van Rossuma8275371995-07-18 14:07:00 +00001215
1216 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001217 Return the first index for which o[i]=value. On error,
1218 return -1. This is equivalent to the Python
1219 expression: o.index(value).
Guido van Rossuma8275371995-07-18 14:07:00 +00001220 */
1221
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001222/* In-place versions of some of the above Sequence functions. */
1223
Mark Hammond91a681d2002-08-12 07:21:58 +00001224 PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001225
1226 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001227 Append o2 to o1, in-place when possible. Return the resulting
1228 object, which could be o1, or NULL on failure. This is the
1229 equivalent of the Python expression: o1 += o2.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001230
1231 */
1232
Martin v. Löwis18e16552006-02-15 17:27:45 +00001233 PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count);
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001234
1235 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001236 Repeat o1 by count, in-place when possible. Return the resulting
1237 object, which could be o1, or NULL on failure. This is the
1238 equivalent of the Python expression: o1 *= count.
Thomas Woutersdd8dbdb2000-08-24 20:09:45 +00001239
1240 */
1241
Guido van Rossuma8275371995-07-18 14:07:00 +00001242/* Mapping protocol:*/
1243
Mark Hammond91a681d2002-08-12 07:21:58 +00001244 PyAPI_FUNC(int) PyMapping_Check(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001245
1246 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001247 Return 1 if the object provides mapping protocol, and zero
1248 otherwise.
Guido van Rossuma8275371995-07-18 14:07:00 +00001249
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001250 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +00001251 */
1252
Martin v. Löwis18e16552006-02-15 17:27:45 +00001253 PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
Jeremy Hylton6253f832000-07-12 12:56:19 +00001254
Guido van Rossuma8275371995-07-18 14:07:00 +00001255 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001256 Returns the number of keys in object o on success, and -1 on
1257 failure. For objects that do not provide sequence protocol,
1258 this is equivalent to the Python expression: len(o).
Guido van Rossuma8275371995-07-18 14:07:00 +00001259 */
1260
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +00001261 /* For DLL compatibility */
1262#undef PyMapping_Length
Martin v. Löwis18e16552006-02-15 17:27:45 +00001263 PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
Marc-André Lemburgcf5f3582000-07-17 09:22:55 +00001264#define PyMapping_Length PyMapping_Size
1265
1266
Guido van Rossuma25e5e91996-09-06 13:48:38 +00001267 /* implemented as a macro:
1268
Serhiy Storchakac6792272013-10-19 21:03:34 +03001269 int PyMapping_DelItemString(PyObject *o, const char *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001270
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001271 Remove the mapping for object, key, from the object *o.
1272 Returns -1 on failure. This is equivalent to
1273 the Python statement: del o[key].
Guido van Rossuma8275371995-07-18 14:07:00 +00001274 */
Jeremy Hylton7c7ee5f2001-11-28 16:20:07 +00001275#define PyMapping_DelItemString(O,K) PyObject_DelItemString((O),(K))
Guido van Rossuma25e5e91996-09-06 13:48:38 +00001276
1277 /* implemented as a macro:
Guido van Rossuma8275371995-07-18 14:07:00 +00001278
Fred Drakeea9cb5a2000-07-09 00:20:36 +00001279 int PyMapping_DelItem(PyObject *o, PyObject *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001280
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001281 Remove the mapping for object, key, from the object *o.
1282 Returns -1 on failure. This is equivalent to
1283 the Python statement: del o[key].
Guido van Rossuma8275371995-07-18 14:07:00 +00001284 */
Jeremy Hylton7c7ee5f2001-11-28 16:20:07 +00001285#define PyMapping_DelItem(O,K) PyObject_DelItem((O),(K))
Guido van Rossuma8275371995-07-18 14:07:00 +00001286
Serhiy Storchakac6792272013-10-19 21:03:34 +03001287 PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, const char *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001288
1289 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001290 On success, return 1 if the mapping object has the key, key,
1291 and 0 otherwise. This is equivalent to the Python expression:
1292 key in o.
Guido van Rossuma8275371995-07-18 14:07:00 +00001293
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001294 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +00001295 */
1296
Mark Hammond91a681d2002-08-12 07:21:58 +00001297 PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001298
1299 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001300 Return 1 if the mapping object has the key, key,
1301 and 0 otherwise. This is equivalent to the Python expression:
1302 key in o.
Guido van Rossuma8275371995-07-18 14:07:00 +00001303
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001304 This function always succeeds.
Guido van Rossuma8275371995-07-18 14:07:00 +00001305
1306 */
1307
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001308 PyAPI_FUNC(PyObject *) PyMapping_Keys(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001309
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001310 /*
Serhiy Storchaka1d480be2016-09-26 20:52:41 +03001311 On success, return a list or tuple of the keys in object o.
1312 On failure, return NULL.
Guido van Rossuma8275371995-07-18 14:07:00 +00001313 */
Guido van Rossuma8275371995-07-18 14:07:00 +00001314
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001315 PyAPI_FUNC(PyObject *) PyMapping_Values(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001316
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001317 /*
Serhiy Storchaka1d480be2016-09-26 20:52:41 +03001318 On success, return a list or tuple of the values in object o.
1319 On failure, return NULL.
Guido van Rossuma8275371995-07-18 14:07:00 +00001320 */
Guido van Rossuma8275371995-07-18 14:07:00 +00001321
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001322 PyAPI_FUNC(PyObject *) PyMapping_Items(PyObject *o);
Guido van Rossuma8275371995-07-18 14:07:00 +00001323
Guido van Rossumcc2b0162007-02-11 06:12:03 +00001324 /*
Serhiy Storchaka1d480be2016-09-26 20:52:41 +03001325 On success, return a list or tuple of the items in object o,
1326 where each item is a tuple containing a key-value pair.
1327 On failure, return NULL.
Guido van Rossuma8275371995-07-18 14:07:00 +00001328
1329 */
Guido van Rossuma8275371995-07-18 14:07:00 +00001330
Serhiy Storchakac6792272013-10-19 21:03:34 +03001331 PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o,
1332 const char *key);
Guido van Rossuma8275371995-07-18 14:07:00 +00001333
1334 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001335 Return element of o corresponding to the object, key, or NULL
1336 on failure. This is the equivalent of the Python expression:
1337 o[key].
Guido van Rossuma8275371995-07-18 14:07:00 +00001338 */
1339
Serhiy Storchakac6792272013-10-19 21:03:34 +03001340 PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, const char *key,
Fred Drakeea9cb5a2000-07-09 00:20:36 +00001341 PyObject *value);
Guido van Rossuma8275371995-07-18 14:07:00 +00001342
1343 /*
Antoine Pitrouf95a1b32010-05-09 15:52:27 +00001344 Map the object, key, to the value, v. Returns
1345 -1 on failure. This is the equivalent of the Python
1346 statement: o[key]=v.
Guido van Rossuma8275371995-07-18 14:07:00 +00001347 */
1348
1349
Mark Hammond91a681d2002-08-12 07:21:58 +00001350PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
Guido van Rossum823649d2001-03-21 18:40:58 +00001351 /* isinstance(object, typeorclass) */
1352
Mark Hammond91a681d2002-08-12 07:21:58 +00001353PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass);
Guido van Rossum823649d2001-03-21 18:40:58 +00001354 /* issubclass(object, typeorclass) */
1355
1356
Martin v. Löwis4d0d4712010-12-03 20:14:31 +00001357#ifndef Py_LIMITED_API
Antoine Pitrouec569b72008-08-26 22:40:48 +00001358PyAPI_FUNC(int) _PyObject_RealIsInstance(PyObject *inst, PyObject *cls);
1359
1360PyAPI_FUNC(int) _PyObject_RealIsSubclass(PyObject *derived, PyObject *cls);
1361
Gregory P. Smithfb94c5f2010-03-14 06:49:55 +00001362PyAPI_FUNC(char *const *) _PySequence_BytesToCharpArray(PyObject* self);
1363
1364PyAPI_FUNC(void) _Py_FreeCharPArray(char *const array[]);
Antoine Pitrouec569b72008-08-26 22:40:48 +00001365
Antoine Pitrouf68c2a72010-09-01 12:58:21 +00001366/* For internal use by buffer API functions */
1367PyAPI_FUNC(void) _Py_add_one_to_index_F(int nd, Py_ssize_t *index,
1368 const Py_ssize_t *shape);
1369PyAPI_FUNC(void) _Py_add_one_to_index_C(int nd, Py_ssize_t *index,
1370 const Py_ssize_t *shape);
Serhiy Storchaka9fab79b2016-09-11 11:03:14 +03001371#endif /* !Py_LIMITED_API */
Antoine Pitrouf68c2a72010-09-01 12:58:21 +00001372
1373
Guido van Rossum8ca687a1995-09-18 21:20:02 +00001374#ifdef __cplusplus
1375}
1376#endif
Guido van Rossuma8275371995-07-18 14:07:00 +00001377#endif /* Py_ABSTRACTOBJECT_H */