1/* Abstract Object Interface (many thanks to Jim Fulton) */
2
3#ifndef Py_ABSTRACTOBJECT_H
4#define Py_ABSTRACTOBJECT_H
5#ifdef __cplusplus
6extern "C" {
7#endif
8
9/* === Object Protocol ================================================== */
10
11/* Implemented elsewhere:
12
13 int PyObject_Print(PyObject *o, FILE *fp, int flags);
14
15 Print an object 'o' on file 'fp'. Returns -1 on error. The flags argument
16 is used to enable certain printing options. The only option currently
17 supported is Py_Print_RAW.
18
19 (What should be said about Py_Print_RAW?). */
20
21
22/* Implemented elsewhere:
23
24 int PyObject_HasAttrString(PyObject *o, const char *attr_name);
25
26 Returns 1 if object 'o' has the attribute attr_name, and 0 otherwise.
27
28 This is equivalent to the Python expression: hasattr(o,attr_name).
29
30 This function always succeeds. */
31
32
33/* Implemented elsewhere:
34
35 PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name);
36
37 Retrieve an attributed named attr_name form object o.
38 Returns the attribute value on success, or NULL on failure.
39
40 This is the equivalent of the Python expression: o.attr_name. */
41
42
43/* Implemented elsewhere:
44
45 int PyObject_HasAttr(PyObject *o, PyObject *attr_name);
46
47 Returns 1 if o has the attribute attr_name, and 0 otherwise.
48
49 This is equivalent to the Python expression: hasattr(o,attr_name).
50
51 This function always succeeds. */
52
53/* Implemented elsewhere:
54
55 PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name);
56
57 Retrieve an attributed named 'attr_name' form object 'o'.
58 Returns the attribute value on success, or NULL on failure.
59
60 This is the equivalent of the Python expression: o.attr_name. */
61
62
63/* Implemented elsewhere:
64
65 int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v);
66
67 Set the value of the attribute named attr_name, for object 'o',
68 to the value 'v'. Raise an exception and return -1 on failure; return 0 on
69 success.
70
71 This is the equivalent of the Python statement o.attr_name=v. */
72
73
74/* Implemented elsewhere:
75
76 int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v);
77
78 Set the value of the attribute named attr_name, for object 'o', to the value
79 'v'. an exception and return -1 on failure; return 0 on success.
80
81 This is the equivalent of the Python statement o.attr_name=v. */
82
83/* Implemented as a macro:
84
85 int PyObject_DelAttrString(PyObject *o, const char *attr_name);
86
87 Delete attribute named attr_name, for object o. Returns
88 -1 on failure.
89
90 This is the equivalent of the Python statement: del o.attr_name. */
91#define PyObject_DelAttrString(O,A) PyObject_SetAttrString((O),(A), NULL)
92
93
94/* Implemented as a macro:
95
96 int PyObject_DelAttr(PyObject *o, PyObject *attr_name);
97
98 Delete attribute named attr_name, for object o. Returns -1
99 on failure. This is the equivalent of the Python
100 statement: del o.attr_name. */
101#define PyObject_DelAttr(O,A) PyObject_SetAttr((O),(A), NULL)
102
103
104/* Implemented elsewhere:
105
106 PyObject *PyObject_Repr(PyObject *o);
107
108 Compute the string representation of object 'o'. Returns the
109 string representation on success, NULL on failure.
110
111 This is the equivalent of the Python expression: repr(o).
112
113 Called by the repr() built-in function. */
114
115
116/* Implemented elsewhere:
117
118 PyObject *PyObject_Str(PyObject *o);
119
120 Compute the string representation of object, o. Returns the
121 string representation on success, NULL on failure.
122
123 This is the equivalent of the Python expression: str(o).
124
125 Called by the str() and print() built-in functions. */
126
127
128/* Declared elsewhere
129
130 PyAPI_FUNC(int) PyCallable_Check(PyObject *o);
131
132 Determine if the object, o, is callable. Return 1 if the object is callable
133 and 0 otherwise.
134
135 This function always succeeds. */
136
137
138#ifdef PY_SSIZE_T_CLEAN
139# define PyObject_CallFunction _PyObject_CallFunction_SizeT
140# define PyObject_CallMethod _PyObject_CallMethod_SizeT
141#endif
142
143
144#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000
145/* Call a callable Python object without any arguments */
146PyAPI_FUNC(PyObject *) PyObject_CallNoArgs(PyObject *func);
147#endif
148
149
150/* Call a callable Python object 'callable' with arguments given by the
151 tuple 'args' and keywords arguments given by the dictionary 'kwargs'.
152
153 'args' must not be NULL, use an empty tuple if no arguments are
154 needed. If no named arguments are needed, 'kwargs' can be NULL.
155
156 This is the equivalent of the Python expression:
157 callable(*args, **kwargs). */
158PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable,
159 PyObject *args, PyObject *kwargs);
160
161
162/* Call a callable Python object 'callable', with arguments given by the
163 tuple 'args'. If no arguments are needed, then 'args' can be NULL.
164
165 Returns the result of the call on success, or NULL on failure.
166
167 This is the equivalent of the Python expression:
168 callable(*args). */
169PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable,
170 PyObject *args);
171
172/* Call a callable Python object, callable, with a variable number of C
173 arguments. The C arguments are described using a mkvalue-style format
174 string.
175
176 The format may be NULL, indicating that no arguments are provided.
177
178 Returns the result of the call on success, or NULL on failure.
179
180 This is the equivalent of the Python expression:
181 callable(arg1, arg2, ...). */
182PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable,
183 const char *format, ...);
184
185/* Call the method named 'name' of object 'obj' with a variable number of
186 C arguments. The C arguments are described by a mkvalue format string.
187
188 The format can be NULL, indicating that no arguments are provided.
189
190 Returns the result of the call on success, or NULL on failure.
191
192 This is the equivalent of the Python expression:
193 obj.name(arg1, arg2, ...). */
194PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *obj,
195 const char *name,
196 const char *format, ...);
197
198PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,
199 const char *format,
200 ...);
201
202PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *obj,
203 const char *name,
204 const char *format,
205 ...);
206
207/* Call a callable Python object 'callable' with a variable number of C
208 arguments. The C arguments are provided as PyObject* values, terminated
209 by a NULL.
210
211 Returns the result of the call on success, or NULL on failure.
212
213 This is the equivalent of the Python expression:
214 callable(arg1, arg2, ...). */
215PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,
216 ...);
217
218/* Call the method named 'name' of object 'obj' with a variable number of
219 C arguments. The C arguments are provided as PyObject* values, terminated
220 by NULL.
221
222 Returns the result of the call on success, or NULL on failure.
223
224 This is the equivalent of the Python expression: obj.name(*args). */
225
226PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(
227 PyObject *obj,
228 PyObject *name,
229 ...);
230
231
232/* Implemented elsewhere:
233
234 Py_hash_t PyObject_Hash(PyObject *o);
235
236 Compute and return the hash, hash_value, of an object, o. On
237 failure, return -1.
238
239 This is the equivalent of the Python expression: hash(o). */
240
241
242/* Implemented elsewhere:
243
244 int PyObject_IsTrue(PyObject *o);
245
246 Returns 1 if the object, o, is considered to be true, 0 if o is
247 considered to be false and -1 on failure.
248
249 This is equivalent to the Python expression: not not o. */
250
251
252/* Implemented elsewhere:
253
254 int PyObject_Not(PyObject *o);
255
256 Returns 0 if the object, o, is considered to be true, 1 if o is
257 considered to be false and -1 on failure.
258
259 This is equivalent to the Python expression: not o. */
260
261
262/* Get the type of an object.
263
264 On success, returns a type object corresponding to the object type of object
265 'o'. On failure, returns NULL.
266
267 This is equivalent to the Python expression: type(o) */
268PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o);
269
270
271/* Return the size of object 'o'. If the object 'o' provides both sequence and
272 mapping protocols, the sequence size is returned.
273
274 On error, -1 is returned.
275
276 This is the equivalent to the Python expression: len(o) */
277PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
278
279
280/* For DLL compatibility */
281#undef PyObject_Length
282PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);
283#define PyObject_Length PyObject_Size
284
285/* Return element of 'o' corresponding to the object 'key'. Return NULL
286 on failure.
287
288 This is the equivalent of the Python expression: o[key] */
289PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
290
291
292/* Map the object 'key' to the value 'v' into 'o'.
293
294 Raise an exception and return -1 on failure; return 0 on success.
295
296 This is the equivalent of the Python statement: o[key]=v. */
297PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
298
299/* Remove the mapping for the string 'key' from the object 'o'.
300 Returns -1 on failure.
301
302 This is equivalent to the Python statement: del o[key]. */
303PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, const char *key);
304
305/* Delete the mapping for the object 'key' from the object 'o'.
306 Returns -1 on failure.
307
308 This is the equivalent of the Python statement: del o[key]. */
309PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
310
311
312/* === Old Buffer API ============================================ */
313
314/* FIXME: usage of these should all be replaced in Python itself
315 but for backwards compatibility we will implement them.
316 Their usage without a corresponding "unlock" mechanism
317 may create issues (but they would already be there). */
318
319/* Takes an arbitrary object which must support the (character, single segment)
320 buffer interface and returns a pointer to a read-only memory location
321 usable as character based input for subsequent processing.
322
323 Return 0 on success. buffer and buffer_len are only set in case no error
324 occurs. Otherwise, -1 is returned and an exception set. */
325Py_DEPRECATED(3.0)
326PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,
327 const char **buffer,
328 Py_ssize_t *buffer_len);
329
330/* Checks whether an arbitrary object supports the (character, single segment)
331 buffer interface.
332
333 Returns 1 on success, 0 on failure. */
334Py_DEPRECATED(3.0) PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);
335
336/* Same as PyObject_AsCharBuffer() except that this API expects (readable,
337 single segment) buffer interface and returns a pointer to a read-only memory
338 location which can contain arbitrary data.
339
340 0 is returned on success. buffer and buffer_len are only set in case no
341 error occurs. Otherwise, -1 is returned and an exception set. */
342Py_DEPRECATED(3.0)
343PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,
344 const void **buffer,
345 Py_ssize_t *buffer_len);
346
347/* Takes an arbitrary object which must support the (writable, single segment)
348 buffer interface and returns a pointer to a writable memory location in
349 buffer of size 'buffer_len'.
350
351 Return 0 on success. buffer and buffer_len are only set in case no error
352 occurs. Otherwise, -1 is returned and an exception set. */
353Py_DEPRECATED(3.0)
354PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,
355 void **buffer,
356 Py_ssize_t *buffer_len);
357
358
359/* === New Buffer API ============================================ */
360
361/* Takes an arbitrary object and returns the result of calling
362 obj.__format__(format_spec). */
363PyAPI_FUNC(PyObject *) PyObject_Format(PyObject *obj,
364 PyObject *format_spec);
365
366
367/* ==== Iterators ================================================ */
368
369/* Takes an object and returns an iterator for it.
370 This is typically a new iterator but if the argument is an iterator, this
371 returns itself. */
372PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);
373
374/* Takes an AsyncIterable object and returns an AsyncIterator for it.
375 This is typically a new iterator but if the argument is an AsyncIterator,
376 this returns itself. */
377PyAPI_FUNC(PyObject *) PyObject_GetAIter(PyObject *);
378
379/* Returns non-zero if the object 'obj' provides iterator protocols, and 0 otherwise.
380
381 This function always succeeds. */
382PyAPI_FUNC(int) PyIter_Check(PyObject *);
383
384/* Returns non-zero if the object 'obj' provides AsyncIterator protocols, and 0 otherwise.
385
386 This function always succeeds. */
387PyAPI_FUNC(int) PyAIter_Check(PyObject *);
388
389/* Takes an iterator object and calls its tp_iternext slot,
390 returning the next value.
391
392 If the iterator is exhausted, this returns NULL without setting an
393 exception.
394
395 NULL with an exception means an error occurred. */
396PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);
397
398#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000
399
400/* Takes generator, coroutine or iterator object and sends the value into it.
401 Returns:
402 - PYGEN_RETURN (0) if generator has returned.
403 'result' parameter is filled with return value
404 - PYGEN_ERROR (-1) if exception was raised.
405 'result' parameter is NULL
406 - PYGEN_NEXT (1) if generator has yielded.
407 'result' parameter is filled with yielded value. */
408PyAPI_FUNC(PySendResult) PyIter_Send(PyObject *, PyObject *, PyObject **);
409#endif
410
411
412/* === Number Protocol ================================================== */
413
414/* Returns 1 if the object 'o' provides numeric protocols, and 0 otherwise.
415
416 This function always succeeds. */
417PyAPI_FUNC(int) PyNumber_Check(PyObject *o);
418
419/* Returns the result of adding o1 and o2, or NULL on failure.
420
421 This is the equivalent of the Python expression: o1 + o2. */
422PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);
423
424/* Returns the result of subtracting o2 from o1, or NULL on failure.
425
426 This is the equivalent of the Python expression: o1 - o2. */
427PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2);
428
429/* Returns the result of multiplying o1 and o2, or NULL on failure.
430
431 This is the equivalent of the Python expression: o1 * o2. */
432PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2);
433
434#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
435/* This is the equivalent of the Python expression: o1 @ o2. */
436PyAPI_FUNC(PyObject *) PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2);
437#endif
438
439/* Returns the result of dividing o1 by o2 giving an integral result,
440 or NULL on failure.
441
442 This is the equivalent of the Python expression: o1 // o2. */
443PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2);
444
445/* Returns the result of dividing o1 by o2 giving a float result, or NULL on
446 failure.
447
448 This is the equivalent of the Python expression: o1 / o2. */
449PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2);
450
451/* Returns the remainder of dividing o1 by o2, or NULL on failure.
452
453 This is the equivalent of the Python expression: o1 % o2. */
454PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);
455
456/* See the built-in function divmod.
457
458 Returns NULL on failure.
459
460 This is the equivalent of the Python expression: divmod(o1, o2). */
461PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);
462
463/* See the built-in function pow. Returns NULL on failure.
464
465 This is the equivalent of the Python expression: pow(o1, o2, o3),
466 where o3 is optional. */
467PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,
468 PyObject *o3);
469
470/* Returns the negation of o on success, or NULL on failure.
471
472 This is the equivalent of the Python expression: -o. */
473PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o);
474
475/* Returns the positive of o on success, or NULL on failure.
476
477 This is the equivalent of the Python expression: +o. */
478PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o);
479
480/* Returns the absolute value of 'o', or NULL on failure.
481
482 This is the equivalent of the Python expression: abs(o). */
483PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o);
484
485/* Returns the bitwise negation of 'o' on success, or NULL on failure.
486
487 This is the equivalent of the Python expression: ~o. */
488PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o);
489
490/* Returns the result of left shifting o1 by o2 on success, or NULL on failure.
491
492 This is the equivalent of the Python expression: o1 << o2. */
493PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);
494
495/* Returns the result of right shifting o1 by o2 on success, or NULL on
496 failure.
497
498 This is the equivalent of the Python expression: o1 >> o2. */
499PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);
500
501/* Returns the result of bitwise and of o1 and o2 on success, or NULL on
502 failure.
503
504 This is the equivalent of the Python expression: o1 & o2. */
505PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);
506
507/* Returns the bitwise exclusive or of o1 by o2 on success, or NULL on failure.
508
509 This is the equivalent of the Python expression: o1 ^ o2. */
510PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);
511
512/* Returns the result of bitwise or on o1 and o2 on success, or NULL on
513 failure.
514
515 This is the equivalent of the Python expression: o1 | o2. */
516PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);
517
518/* Returns 1 if obj is an index integer (has the nb_index slot of the
519 tp_as_number structure filled in), and 0 otherwise. */
520PyAPI_FUNC(int) PyIndex_Check(PyObject *);
521
522/* Returns the object 'o' converted to a Python int, or NULL with an exception
523 raised on failure. */
524PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o);
525
526/* Returns the object 'o' converted to Py_ssize_t by going through
527 PyNumber_Index() first.
528
529 If an overflow error occurs while converting the int to Py_ssize_t, then the
530 second argument 'exc' is the error-type to return. If it is NULL, then the
531 overflow error is cleared and the value is clipped. */
532PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc);
533
534/* Returns the object 'o' converted to an integer object on success, or NULL
535 on failure.
536
537 This is the equivalent of the Python expression: int(o). */
538PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);
539
540/* Returns the object 'o' converted to a float object on success, or NULL
541 on failure.
542
543 This is the equivalent of the Python expression: float(o). */
544PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);
545
546
547/* --- In-place variants of (some of) the above number protocol functions -- */
548
549/* Returns the result of adding o2 to o1, possibly in-place, or NULL
550 on failure.
551
552 This is the equivalent of the Python expression: o1 += o2. */
553PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);
554
555/* Returns the result of subtracting o2 from o1, possibly in-place or
556 NULL on failure.
557
558 This is the equivalent of the Python expression: o1 -= o2. */
559PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);
560
561/* Returns the result of multiplying o1 by o2, possibly in-place, or NULL on
562 failure.
563
564 This is the equivalent of the Python expression: o1 *= o2. */
565PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);
566
567#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
568/* This is the equivalent of the Python expression: o1 @= o2. */
569PyAPI_FUNC(PyObject *) PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2);
570#endif
571
572/* Returns the result of dividing o1 by o2 giving an integral result, possibly
573 in-place, or NULL on failure.
574
575 This is the equivalent of the Python expression: o1 /= o2. */
576PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1,
577 PyObject *o2);
578
579/* Returns the result of dividing o1 by o2 giving a float result, possibly
580 in-place, or null on failure.
581
582 This is the equivalent of the Python expression: o1 /= o2. */
583PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1,
584 PyObject *o2);
585
586/* Returns the remainder of dividing o1 by o2, possibly in-place, or NULL on
587 failure.
588
589 This is the equivalent of the Python expression: o1 %= o2. */
590PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);
591
592/* Returns the result of raising o1 to the power of o2, possibly in-place,
593 or NULL on failure.
594
595 This is the equivalent of the Python expression: o1 **= o2,
596 or o1 = pow(o1, o2, o3) if o3 is present. */
597PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,
598 PyObject *o3);
599
600/* Returns the result of left shifting o1 by o2, possibly in-place, or NULL
601 on failure.
602
603 This is the equivalent of the Python expression: o1 <<= o2. */
604PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);
605
606/* Returns the result of right shifting o1 by o2, possibly in-place or NULL
607 on failure.
608
609 This is the equivalent of the Python expression: o1 >>= o2. */
610PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);
611
612/* Returns the result of bitwise and of o1 and o2, possibly in-place, or NULL
613 on failure.
614
615 This is the equivalent of the Python expression: o1 &= o2. */
616PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);
617
618/* Returns the bitwise exclusive or of o1 by o2, possibly in-place, or NULL
619 on failure.
620
621 This is the equivalent of the Python expression: o1 ^= o2. */
622PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);
623
624/* Returns the result of bitwise or of o1 and o2, possibly in-place,
625 or NULL on failure.
626
627 This is the equivalent of the Python expression: o1 |= o2. */
628PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);
629
630/* Returns the integer n converted to a string with a base, with a base
631 marker of 0b, 0o or 0x prefixed if applicable.
632
633 If n is not an int object, it is converted with PyNumber_Index first. */
634PyAPI_FUNC(PyObject *) PyNumber_ToBase(PyObject *n, int base);
635
636
637/* === Sequence protocol ================================================ */
638
639/* Return 1 if the object provides sequence protocol, and zero
640 otherwise.
641
642 This function always succeeds. */
643PyAPI_FUNC(int) PySequence_Check(PyObject *o);
644
645/* Return the size of sequence object o, or -1 on failure. */
646PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
647
648/* For DLL compatibility */
649#undef PySequence_Length
650PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);
651#define PySequence_Length PySequence_Size
652
653
654/* Return the concatenation of o1 and o2 on success, and NULL on failure.
655
656 This is the equivalent of the Python expression: o1 + o2. */
657PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);
658
659/* Return the result of repeating sequence object 'o' 'count' times,
660 or NULL on failure.
661
662 This is the equivalent of the Python expression: o * count. */
663PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count);
664
665/* Return the ith element of o, or NULL on failure.
666
667 This is the equivalent of the Python expression: o[i]. */
668PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i);
669
670/* Return the slice of sequence object o between i1 and i2, or NULL on failure.
671
672 This is the equivalent of the Python expression: o[i1:i2]. */
673PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
674
675/* Assign object 'v' to the ith element of the sequence 'o'. Raise an exception
676 and return -1 on failure; return 0 on success.
677
678 This is the equivalent of the Python statement o[i] = v. */
679PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);
680
681/* Delete the 'i'-th element of the sequence 'v'. Returns -1 on failure.
682
683 This is the equivalent of the Python statement: del o[i]. */
684PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
685
686/* Assign the sequence object 'v' to the slice in sequence object 'o',
687 from 'i1' to 'i2'. Returns -1 on failure.
688
689 This is the equivalent of the Python statement: o[i1:i2] = v. */
690PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2,
691 PyObject *v);
692
693/* Delete the slice in sequence object 'o' from 'i1' to 'i2'.
694 Returns -1 on failure.
695
696 This is the equivalent of the Python statement: del o[i1:i2]. */
697PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
698
699/* Returns the sequence 'o' as a tuple on success, and NULL on failure.
700
701 This is equivalent to the Python expression: tuple(o). */
702PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);
703
704/* Returns the sequence 'o' as a list on success, and NULL on failure.
705 This is equivalent to the Python expression: list(o) */
706PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);
707
708/* Return the sequence 'o' as a list, unless it's already a tuple or list.
709
710 Use PySequence_Fast_GET_ITEM to access the members of this list, and
711 PySequence_Fast_GET_SIZE to get its length.
712
713 Returns NULL on failure. If the object does not support iteration, raises a
714 TypeError exception with 'm' as the message text. */
715PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
716
717/* Return the size of the sequence 'o', assuming that 'o' was returned by
718 PySequence_Fast and is not NULL. */
719#define PySequence_Fast_GET_SIZE(o) \
720 (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o))
721
722/* Return the 'i'-th element of the sequence 'o', assuming that o was returned
723 by PySequence_Fast, and that i is within bounds. */
724#define PySequence_Fast_GET_ITEM(o, i)\
725 (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i))
726
727/* Return a pointer to the underlying item array for
728 an object returned by PySequence_Fast */
729#define PySequence_Fast_ITEMS(sf) \
730 (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \
731 : ((PyTupleObject *)(sf))->ob_item)
732
733/* Return the number of occurrences on value on 'o', that is, return
734 the number of keys for which o[key] == value.
735
736 On failure, return -1. This is equivalent to the Python expression:
737 o.count(value). */
738PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value);
739
740/* Return 1 if 'ob' is in the sequence 'seq'; 0 if 'ob' is not in the sequence
741 'seq'; -1 on error.
742
743 Use __contains__ if possible, else _PySequence_IterSearch(). */
744PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob);
745
746/* For DLL-level backwards compatibility */
747#undef PySequence_In
748/* Determine if the sequence 'o' contains 'value'. If an item in 'o' is equal
749 to 'value', return 1, otherwise return 0. On error, return -1.
750
751 This is equivalent to the Python expression: value in o. */
752PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value);
753
754/* For source-level backwards compatibility */
755#define PySequence_In PySequence_Contains
756
757
758/* Return the first index for which o[i] == value.
759 On error, return -1.
760
761 This is equivalent to the Python expression: o.index(value). */
762PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value);
763
764
765/* --- In-place versions of some of the above Sequence functions --- */
766
767/* Append sequence 'o2' to sequence 'o1', in-place when possible. Return the
768 resulting object, which could be 'o1', or NULL on failure.
769
770 This is the equivalent of the Python expression: o1 += o2. */
771PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);
772
773/* Repeat sequence 'o' by 'count', in-place when possible. Return the resulting
774 object, which could be 'o', or NULL on failure.
775
776 This is the equivalent of the Python expression: o1 *= count. */
777PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count);
778
779
780/* === Mapping protocol ================================================= */
781
782/* Return 1 if the object provides mapping protocol, and 0 otherwise.
783
784 This function always succeeds. */
785PyAPI_FUNC(int) PyMapping_Check(PyObject *o);
786
787/* Returns the number of keys in mapping object 'o' on success, and -1 on
788 failure. This is equivalent to the Python expression: len(o). */
789PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
790
791/* For DLL compatibility */
792#undef PyMapping_Length
793PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
794#define PyMapping_Length PyMapping_Size
795
796
797/* Implemented as a macro:
798
799 int PyMapping_DelItemString(PyObject *o, const char *key);
800
801 Remove the mapping for the string 'key' from the mapping 'o'. Returns -1 on
802 failure.
803
804 This is equivalent to the Python statement: del o[key]. */
805#define PyMapping_DelItemString(O,K) PyObject_DelItemString((O),(K))
806
807/* Implemented as a macro:
808
809 int PyMapping_DelItem(PyObject *o, PyObject *key);
810
811 Remove the mapping for the object 'key' from the mapping object 'o'.
812 Returns -1 on failure.
813
814 This is equivalent to the Python statement: del o[key]. */
815#define PyMapping_DelItem(O,K) PyObject_DelItem((O),(K))
816
817/* On success, return 1 if the mapping object 'o' has the key 'key',
818 and 0 otherwise.
819
820 This is equivalent to the Python expression: key in o.
821
822 This function always succeeds. */
823PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, const char *key);
824
825/* Return 1 if the mapping object has the key 'key', and 0 otherwise.
826
827 This is equivalent to the Python expression: key in o.
828
829 This function always succeeds. */
830PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key);
831
832/* On success, return a list or tuple of the keys in mapping object 'o'.
833 On failure, return NULL. */
834PyAPI_FUNC(PyObject *) PyMapping_Keys(PyObject *o);
835
836/* On success, return a list or tuple of the values in mapping object 'o'.
837 On failure, return NULL. */
838PyAPI_FUNC(PyObject *) PyMapping_Values(PyObject *o);
839
840/* On success, return a list or tuple of the items in mapping object 'o',
841 where each item is a tuple containing a key-value pair. On failure, return
842 NULL. */
843PyAPI_FUNC(PyObject *) PyMapping_Items(PyObject *o);
844
845/* Return element of 'o' corresponding to the string 'key' or NULL on failure.
846
847 This is the equivalent of the Python expression: o[key]. */
848PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o,
849 const char *key);
850
851/* Map the string 'key' to the value 'v' in the mapping 'o'.
852 Returns -1 on failure.
853
854 This is the equivalent of the Python statement: o[key]=v. */
855PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, const char *key,
856 PyObject *value);
857
858/* isinstance(object, typeorclass) */
859PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
860
861/* issubclass(object, typeorclass) */
862PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass);
863
864#ifndef Py_LIMITED_API
865# define Py_CPYTHON_ABSTRACTOBJECT_H
866# include "cpython/abstract.h"
867# undef Py_CPYTHON_ABSTRACTOBJECT_H
868#endif
869
870#ifdef __cplusplus
871}
872#endif
873#endif /* Py_ABSTRACTOBJECT_H */
874