1 /* Abstract Object Interface (many thanks to Jim Fulton) */
2
3 #ifndef Py_ABSTRACTOBJECT_H
4 #define Py_ABSTRACTOBJECT_H
5 #ifdef __cplusplus
6 extern "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. By default (flags=0), PyObject_Print() formats
18 the object by calling PyObject_Repr(). If flags equals to Py_PRINT_RAW, it
19 formats the object by calling PyObject_Str(). */
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 */
146 PyAPI_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). */
158 PyAPI_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). */
169 PyAPI_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, ...). */
182 PyAPI_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, ...). */
194 PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *obj,
195 const char *name,
196 const char *format, ...);
197
198 PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,
199 const char *format,
200 ...);
201
202 PyAPI_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, ...). */
215 PyAPI_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
226 PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(
227 PyObject *obj,
228 PyObject *name,
229 ...);
230
231 /* Given a vectorcall nargsf argument, return the actual number of arguments.
232 * (For use outside the limited API, this is re-defined as a static inline
233 * function in cpython/abstract.h)
234 */
235 PyAPI_FUNC(Py_ssize_t) PyVectorcall_NARGS(size_t nargsf);
236
237 /* Call "callable" (which must support vectorcall) with positional arguments
238 "tuple" and keyword arguments "dict". "dict" may also be NULL */
239 PyAPI_FUNC(PyObject *) PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict);
240
241 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030C0000
242 #define PY_VECTORCALL_ARGUMENTS_OFFSET \
243 (_Py_STATIC_CAST(size_t, 1) << (8 * sizeof(size_t) - 1))
244
245 /* Perform a PEP 590-style vector call on 'callable' */
246 PyAPI_FUNC(PyObject *) PyObject_Vectorcall(
247 PyObject *callable,
248 PyObject *const *args,
249 size_t nargsf,
250 PyObject *kwnames);
251
252 /* Call the method 'name' on args[0] with arguments in args[1..nargsf-1]. */
253 PyAPI_FUNC(PyObject *) PyObject_VectorcallMethod(
254 PyObject *name, PyObject *const *args,
255 size_t nargsf, PyObject *kwnames);
256 #endif
257
258 /* Implemented elsewhere:
259
260 Py_hash_t PyObject_Hash(PyObject *o);
261
262 Compute and return the hash, hash_value, of an object, o. On
263 failure, return -1.
264
265 This is the equivalent of the Python expression: hash(o). */
266
267
268 /* Implemented elsewhere:
269
270 int PyObject_IsTrue(PyObject *o);
271
272 Returns 1 if the object, o, is considered to be true, 0 if o is
273 considered to be false and -1 on failure.
274
275 This is equivalent to the Python expression: not not o. */
276
277
278 /* Implemented elsewhere:
279
280 int PyObject_Not(PyObject *o);
281
282 Returns 0 if the object, o, is considered to be true, 1 if o is
283 considered to be false and -1 on failure.
284
285 This is equivalent to the Python expression: not o. */
286
287
288 /* Get the type of an object.
289
290 On success, returns a type object corresponding to the object type of object
291 'o'. On failure, returns NULL.
292
293 This is equivalent to the Python expression: type(o) */
294 PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o);
295
296
297 /* Return the size of object 'o'. If the object 'o' provides both sequence and
298 mapping protocols, the sequence size is returned.
299
300 On error, -1 is returned.
301
302 This is the equivalent to the Python expression: len(o) */
303 PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
304
305
306 /* For DLL compatibility */
307 #undef PyObject_Length
308 PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);
309 #define PyObject_Length PyObject_Size
310
311 /* Return element of 'o' corresponding to the object 'key'. Return NULL
312 on failure.
313
314 This is the equivalent of the Python expression: o[key] */
315 PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
316
317
318 /* Map the object 'key' to the value 'v' into 'o'.
319
320 Raise an exception and return -1 on failure; return 0 on success.
321
322 This is the equivalent of the Python statement: o[key]=v. */
323 PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
324
325 /* Remove the mapping for the string 'key' from the object 'o'.
326 Returns -1 on failure.
327
328 This is equivalent to the Python statement: del o[key]. */
329 PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, const char *key);
330
331 /* Delete the mapping for the object 'key' from the object 'o'.
332 Returns -1 on failure.
333
334 This is the equivalent of the Python statement: del o[key]. */
335 PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
336
337
338 /* === Old Buffer API ============================================ */
339
340 /* FIXME: usage of these should all be replaced in Python itself
341 but for backwards compatibility we will implement them.
342 Their usage without a corresponding "unlock" mechanism
343 may create issues (but they would already be there). */
344
345 /* Takes an arbitrary object which must support the (character, single segment)
346 buffer interface and returns a pointer to a read-only memory location
347 usable as character based input for subsequent processing.
348
349 Return 0 on success. buffer and buffer_len are only set in case no error
350 occurs. Otherwise, -1 is returned and an exception set. */
351 Py_DEPRECATED(3.0)
352 PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,
353 const char **buffer,
354 Py_ssize_t *buffer_len);
355
356 /* Checks whether an arbitrary object supports the (character, single segment)
357 buffer interface.
358
359 Returns 1 on success, 0 on failure. */
360 Py_DEPRECATED(3.0) PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);
361
362 /* Same as PyObject_AsCharBuffer() except that this API expects (readable,
363 single segment) buffer interface and returns a pointer to a read-only memory
364 location which can contain arbitrary data.
365
366 0 is returned on success. buffer and buffer_len are only set in case no
367 error occurs. Otherwise, -1 is returned and an exception set. */
368 Py_DEPRECATED(3.0)
369 PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,
370 const void **buffer,
371 Py_ssize_t *buffer_len);
372
373 /* Takes an arbitrary object which must support the (writable, single segment)
374 buffer interface and returns a pointer to a writable memory location in
375 buffer of size 'buffer_len'.
376
377 Return 0 on success. buffer and buffer_len are only set in case no error
378 occurs. Otherwise, -1 is returned and an exception set. */
379 Py_DEPRECATED(3.0)
380 PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,
381 void **buffer,
382 Py_ssize_t *buffer_len);
383
384
385 /* === New Buffer API ============================================ */
386
387 /* Takes an arbitrary object and returns the result of calling
388 obj.__format__(format_spec). */
389 PyAPI_FUNC(PyObject *) PyObject_Format(PyObject *obj,
390 PyObject *format_spec);
391
392
393 /* ==== Iterators ================================================ */
394
395 /* Takes an object and returns an iterator for it.
396 This is typically a new iterator but if the argument is an iterator, this
397 returns itself. */
398 PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);
399
400 /* Takes an AsyncIterable object and returns an AsyncIterator for it.
401 This is typically a new iterator but if the argument is an AsyncIterator,
402 this returns itself. */
403 PyAPI_FUNC(PyObject *) PyObject_GetAIter(PyObject *);
404
405 /* Returns non-zero if the object 'obj' provides iterator protocols, and 0 otherwise.
406
407 This function always succeeds. */
408 PyAPI_FUNC(int) PyIter_Check(PyObject *);
409
410 /* Returns non-zero if the object 'obj' provides AsyncIterator protocols, and 0 otherwise.
411
412 This function always succeeds. */
413 PyAPI_FUNC(int) PyAIter_Check(PyObject *);
414
415 /* Takes an iterator object and calls its tp_iternext slot,
416 returning the next value.
417
418 If the iterator is exhausted, this returns NULL without setting an
419 exception.
420
421 NULL with an exception means an error occurred. */
422 PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);
423
424 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000
425
426 /* Takes generator, coroutine or iterator object and sends the value into it.
427 Returns:
428 - PYGEN_RETURN (0) if generator has returned.
429 'result' parameter is filled with return value
430 - PYGEN_ERROR (-1) if exception was raised.
431 'result' parameter is NULL
432 - PYGEN_NEXT (1) if generator has yielded.
433 'result' parameter is filled with yielded value. */
434 PyAPI_FUNC(PySendResult) PyIter_Send(PyObject *, PyObject *, PyObject **);
435 #endif
436
437
438 /* === Number Protocol ================================================== */
439
440 /* Returns 1 if the object 'o' provides numeric protocols, and 0 otherwise.
441
442 This function always succeeds. */
443 PyAPI_FUNC(int) PyNumber_Check(PyObject *o);
444
445 /* Returns the result of adding o1 and o2, or NULL on failure.
446
447 This is the equivalent of the Python expression: o1 + o2. */
448 PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);
449
450 /* Returns the result of subtracting o2 from o1, or NULL on failure.
451
452 This is the equivalent of the Python expression: o1 - o2. */
453 PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2);
454
455 /* Returns the result of multiplying o1 and o2, or NULL on failure.
456
457 This is the equivalent of the Python expression: o1 * o2. */
458 PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2);
459
460 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
461 /* This is the equivalent of the Python expression: o1 @ o2. */
462 PyAPI_FUNC(PyObject *) PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2);
463 #endif
464
465 /* Returns the result of dividing o1 by o2 giving an integral result,
466 or NULL on failure.
467
468 This is the equivalent of the Python expression: o1 // o2. */
469 PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2);
470
471 /* Returns the result of dividing o1 by o2 giving a float result, or NULL on
472 failure.
473
474 This is the equivalent of the Python expression: o1 / o2. */
475 PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2);
476
477 /* Returns the remainder of dividing o1 by o2, or NULL on failure.
478
479 This is the equivalent of the Python expression: o1 % o2. */
480 PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);
481
482 /* See the built-in function divmod.
483
484 Returns NULL on failure.
485
486 This is the equivalent of the Python expression: divmod(o1, o2). */
487 PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);
488
489 /* See the built-in function pow. Returns NULL on failure.
490
491 This is the equivalent of the Python expression: pow(o1, o2, o3),
492 where o3 is optional. */
493 PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,
494 PyObject *o3);
495
496 /* Returns the negation of o on success, or NULL on failure.
497
498 This is the equivalent of the Python expression: -o. */
499 PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o);
500
501 /* Returns the positive of o on success, or NULL on failure.
502
503 This is the equivalent of the Python expression: +o. */
504 PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o);
505
506 /* Returns the absolute value of 'o', or NULL on failure.
507
508 This is the equivalent of the Python expression: abs(o). */
509 PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o);
510
511 /* Returns the bitwise negation of 'o' on success, or NULL on failure.
512
513 This is the equivalent of the Python expression: ~o. */
514 PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o);
515
516 /* Returns the result of left shifting o1 by o2 on success, or NULL on failure.
517
518 This is the equivalent of the Python expression: o1 << o2. */
519 PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);
520
521 /* Returns the result of right shifting o1 by o2 on success, or NULL on
522 failure.
523
524 This is the equivalent of the Python expression: o1 >> o2. */
525 PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);
526
527 /* Returns the result of bitwise and of o1 and o2 on success, or NULL on
528 failure.
529
530 This is the equivalent of the Python expression: o1 & o2. */
531 PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);
532
533 /* Returns the bitwise exclusive or of o1 by o2 on success, or NULL on failure.
534
535 This is the equivalent of the Python expression: o1 ^ o2. */
536 PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);
537
538 /* Returns the result of bitwise or on o1 and o2 on success, or NULL on
539 failure.
540
541 This is the equivalent of the Python expression: o1 | o2. */
542 PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);
543
544 /* Returns 1 if obj is an index integer (has the nb_index slot of the
545 tp_as_number structure filled in), and 0 otherwise. */
546 PyAPI_FUNC(int) PyIndex_Check(PyObject *);
547
548 /* Returns the object 'o' converted to a Python int, or NULL with an exception
549 raised on failure. */
550 PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o);
551
552 /* Returns the object 'o' converted to Py_ssize_t by going through
553 PyNumber_Index() first.
554
555 If an overflow error occurs while converting the int to Py_ssize_t, then the
556 second argument 'exc' is the error-type to return. If it is NULL, then the
557 overflow error is cleared and the value is clipped. */
558 PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc);
559
560 /* Returns the object 'o' converted to an integer object on success, or NULL
561 on failure.
562
563 This is the equivalent of the Python expression: int(o). */
564 PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);
565
566 /* Returns the object 'o' converted to a float object on success, or NULL
567 on failure.
568
569 This is the equivalent of the Python expression: float(o). */
570 PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);
571
572
573 /* --- In-place variants of (some of) the above number protocol functions -- */
574
575 /* Returns the result of adding o2 to o1, possibly in-place, or NULL
576 on failure.
577
578 This is the equivalent of the Python expression: o1 += o2. */
579 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);
580
581 /* Returns the result of subtracting o2 from o1, possibly in-place or
582 NULL on failure.
583
584 This is the equivalent of the Python expression: o1 -= o2. */
585 PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);
586
587 /* Returns the result of multiplying o1 by o2, possibly in-place, or NULL on
588 failure.
589
590 This is the equivalent of the Python expression: o1 *= o2. */
591 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);
592
593 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
594 /* This is the equivalent of the Python expression: o1 @= o2. */
595 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2);
596 #endif
597
598 /* Returns the result of dividing o1 by o2 giving an integral result, possibly
599 in-place, or NULL on failure.
600
601 This is the equivalent of the Python expression: o1 /= o2. */
602 PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1,
603 PyObject *o2);
604
605 /* Returns the result of dividing o1 by o2 giving a float result, possibly
606 in-place, or null on failure.
607
608 This is the equivalent of the Python expression: o1 /= o2. */
609 PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1,
610 PyObject *o2);
611
612 /* Returns the remainder of dividing o1 by o2, possibly in-place, or NULL on
613 failure.
614
615 This is the equivalent of the Python expression: o1 %= o2. */
616 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);
617
618 /* Returns the result of raising o1 to the power of o2, possibly in-place,
619 or NULL on failure.
620
621 This is the equivalent of the Python expression: o1 **= o2,
622 or o1 = pow(o1, o2, o3) if o3 is present. */
623 PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,
624 PyObject *o3);
625
626 /* Returns the result of left shifting o1 by o2, possibly in-place, or NULL
627 on failure.
628
629 This is the equivalent of the Python expression: o1 <<= o2. */
630 PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);
631
632 /* Returns the result of right shifting o1 by o2, possibly in-place or NULL
633 on failure.
634
635 This is the equivalent of the Python expression: o1 >>= o2. */
636 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);
637
638 /* Returns the result of bitwise and of o1 and o2, possibly in-place, or NULL
639 on failure.
640
641 This is the equivalent of the Python expression: o1 &= o2. */
642 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);
643
644 /* Returns the bitwise exclusive or of o1 by o2, possibly in-place, or NULL
645 on failure.
646
647 This is the equivalent of the Python expression: o1 ^= o2. */
648 PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);
649
650 /* Returns the result of bitwise or of o1 and o2, possibly in-place,
651 or NULL on failure.
652
653 This is the equivalent of the Python expression: o1 |= o2. */
654 PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);
655
656 /* Returns the integer n converted to a string with a base, with a base
657 marker of 0b, 0o or 0x prefixed if applicable.
658
659 If n is not an int object, it is converted with PyNumber_Index first. */
660 PyAPI_FUNC(PyObject *) PyNumber_ToBase(PyObject *n, int base);
661
662
663 /* === Sequence protocol ================================================ */
664
665 /* Return 1 if the object provides sequence protocol, and zero
666 otherwise.
667
668 This function always succeeds. */
669 PyAPI_FUNC(int) PySequence_Check(PyObject *o);
670
671 /* Return the size of sequence object o, or -1 on failure. */
672 PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
673
674 /* For DLL compatibility */
675 #undef PySequence_Length
676 PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);
677 #define PySequence_Length PySequence_Size
678
679
680 /* Return the concatenation of o1 and o2 on success, and NULL on failure.
681
682 This is the equivalent of the Python expression: o1 + o2. */
683 PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);
684
685 /* Return the result of repeating sequence object 'o' 'count' times,
686 or NULL on failure.
687
688 This is the equivalent of the Python expression: o * count. */
689 PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count);
690
691 /* Return the ith element of o, or NULL on failure.
692
693 This is the equivalent of the Python expression: o[i]. */
694 PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i);
695
696 /* Return the slice of sequence object o between i1 and i2, or NULL on failure.
697
698 This is the equivalent of the Python expression: o[i1:i2]. */
699 PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
700
701 /* Assign object 'v' to the ith element of the sequence 'o'. Raise an exception
702 and return -1 on failure; return 0 on success.
703
704 This is the equivalent of the Python statement o[i] = v. */
705 PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);
706
707 /* Delete the 'i'-th element of the sequence 'v'. Returns -1 on failure.
708
709 This is the equivalent of the Python statement: del o[i]. */
710 PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
711
712 /* Assign the sequence object 'v' to the slice in sequence object 'o',
713 from 'i1' to 'i2'. Returns -1 on failure.
714
715 This is the equivalent of the Python statement: o[i1:i2] = v. */
716 PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2,
717 PyObject *v);
718
719 /* Delete the slice in sequence object 'o' from 'i1' to 'i2'.
720 Returns -1 on failure.
721
722 This is the equivalent of the Python statement: del o[i1:i2]. */
723 PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
724
725 /* Returns the sequence 'o' as a tuple on success, and NULL on failure.
726
727 This is equivalent to the Python expression: tuple(o). */
728 PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);
729
730 /* Returns the sequence 'o' as a list on success, and NULL on failure.
731 This is equivalent to the Python expression: list(o) */
732 PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);
733
734 /* Return the sequence 'o' as a list, unless it's already a tuple or list.
735
736 Use PySequence_Fast_GET_ITEM to access the members of this list, and
737 PySequence_Fast_GET_SIZE to get its length.
738
739 Returns NULL on failure. If the object does not support iteration, raises a
740 TypeError exception with 'm' as the message text. */
741 PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
742
743 /* Return the size of the sequence 'o', assuming that 'o' was returned by
744 PySequence_Fast and is not NULL. */
745 #define PySequence_Fast_GET_SIZE(o) \
746 (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o))
747
748 /* Return the 'i'-th element of the sequence 'o', assuming that o was returned
749 by PySequence_Fast, and that i is within bounds. */
750 #define PySequence_Fast_GET_ITEM(o, i)\
751 (PyList_Check(o) ? PyList_GET_ITEM((o), (i)) : PyTuple_GET_ITEM((o), (i)))
752
753 /* Return a pointer to the underlying item array for
754 an object returned by PySequence_Fast */
755 #define PySequence_Fast_ITEMS(sf) \
756 (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \
757 : ((PyTupleObject *)(sf))->ob_item)
758
759 /* Return the number of occurrences on value on 'o', that is, return
760 the number of keys for which o[key] == value.
761
762 On failure, return -1. This is equivalent to the Python expression:
763 o.count(value). */
764 PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value);
765
766 /* Return 1 if 'ob' is in the sequence 'seq'; 0 if 'ob' is not in the sequence
767 'seq'; -1 on error.
768
769 Use __contains__ if possible, else _PySequence_IterSearch(). */
770 PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob);
771
772 /* For DLL-level backwards compatibility */
773 #undef PySequence_In
774 /* Determine if the sequence 'o' contains 'value'. If an item in 'o' is equal
775 to 'value', return 1, otherwise return 0. On error, return -1.
776
777 This is equivalent to the Python expression: value in o. */
778 PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value);
779
780 /* For source-level backwards compatibility */
781 #define PySequence_In PySequence_Contains
782
783
784 /* Return the first index for which o[i] == value.
785 On error, return -1.
786
787 This is equivalent to the Python expression: o.index(value). */
788 PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value);
789
790
791 /* --- In-place versions of some of the above Sequence functions --- */
792
793 /* Append sequence 'o2' to sequence 'o1', in-place when possible. Return the
794 resulting object, which could be 'o1', or NULL on failure.
795
796 This is the equivalent of the Python expression: o1 += o2. */
797 PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);
798
799 /* Repeat sequence 'o' by 'count', in-place when possible. Return the resulting
800 object, which could be 'o', or NULL on failure.
801
802 This is the equivalent of the Python expression: o1 *= count. */
803 PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count);
804
805
806 /* === Mapping protocol ================================================= */
807
808 /* Return 1 if the object provides mapping protocol, and 0 otherwise.
809
810 This function always succeeds. */
811 PyAPI_FUNC(int) PyMapping_Check(PyObject *o);
812
813 /* Returns the number of keys in mapping object 'o' on success, and -1 on
814 failure. This is equivalent to the Python expression: len(o). */
815 PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
816
817 /* For DLL compatibility */
818 #undef PyMapping_Length
819 PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
820 #define PyMapping_Length PyMapping_Size
821
822
823 /* Implemented as a macro:
824
825 int PyMapping_DelItemString(PyObject *o, const char *key);
826
827 Remove the mapping for the string 'key' from the mapping 'o'. Returns -1 on
828 failure.
829
830 This is equivalent to the Python statement: del o[key]. */
831 #define PyMapping_DelItemString(O, K) PyObject_DelItemString((O), (K))
832
833 /* Implemented as a macro:
834
835 int PyMapping_DelItem(PyObject *o, PyObject *key);
836
837 Remove the mapping for the object 'key' from the mapping object 'o'.
838 Returns -1 on failure.
839
840 This is equivalent to the Python statement: del o[key]. */
841 #define PyMapping_DelItem(O, K) PyObject_DelItem((O), (K))
842
843 /* On success, return 1 if the mapping object 'o' has the key 'key',
844 and 0 otherwise.
845
846 This is equivalent to the Python expression: key in o.
847
848 This function always succeeds. */
849 PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, const char *key);
850
851 /* Return 1 if the mapping object has the key 'key', and 0 otherwise.
852
853 This is equivalent to the Python expression: key in o.
854
855 This function always succeeds. */
856 PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key);
857
858 /* On success, return a list or tuple of the keys in mapping object 'o'.
859 On failure, return NULL. */
860 PyAPI_FUNC(PyObject *) PyMapping_Keys(PyObject *o);
861
862 /* On success, return a list or tuple of the values in mapping object 'o'.
863 On failure, return NULL. */
864 PyAPI_FUNC(PyObject *) PyMapping_Values(PyObject *o);
865
866 /* On success, return a list or tuple of the items in mapping object 'o',
867 where each item is a tuple containing a key-value pair. On failure, return
868 NULL. */
869 PyAPI_FUNC(PyObject *) PyMapping_Items(PyObject *o);
870
871 /* Return element of 'o' corresponding to the string 'key' or NULL on failure.
872
873 This is the equivalent of the Python expression: o[key]. */
874 PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o,
875 const char *key);
876
877 /* Map the string 'key' to the value 'v' in the mapping 'o'.
878 Returns -1 on failure.
879
880 This is the equivalent of the Python statement: o[key]=v. */
881 PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, const char *key,
882 PyObject *value);
883
884 /* isinstance(object, typeorclass) */
885 PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
886
887 /* issubclass(object, typeorclass) */
888 PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass);
889
890 #ifndef Py_LIMITED_API
891 # define Py_CPYTHON_ABSTRACTOBJECT_H
892 # include "cpython/abstract.h"
893 # undef Py_CPYTHON_ABSTRACTOBJECT_H
894 #endif
895
896 #ifdef __cplusplus
897 }
898 #endif
899 #endif /* Py_ABSTRACTOBJECT_H */