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.
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 */
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
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) */
268 PyAPI_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) */
277 PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
278
279
280 /* For DLL compatibility */
281 #undef PyObject_Length
282 PyAPI_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] */
289 PyAPI_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. */
297 PyAPI_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]. */
303 PyAPI_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]. */
309 PyAPI_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. */
325 Py_DEPRECATED(3.0)
326 PyAPI_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. */
334 Py_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. */
342 Py_DEPRECATED(3.0)
343 PyAPI_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. */
353 Py_DEPRECATED(3.0)
354 PyAPI_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). */
363 PyAPI_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. */
372 PyAPI_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. */
377 PyAPI_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. */
382 PyAPI_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. */
387 PyAPI_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. */
396 PyAPI_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. */
408 PyAPI_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. */
417 PyAPI_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. */
422 PyAPI_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. */
427 PyAPI_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. */
432 PyAPI_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. */
436 PyAPI_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. */
443 PyAPI_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. */
449 PyAPI_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. */
454 PyAPI_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). */
461 PyAPI_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. */
467 PyAPI_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. */
473 PyAPI_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. */
478 PyAPI_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). */
483 PyAPI_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. */
488 PyAPI_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. */
493 PyAPI_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. */
499 PyAPI_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. */
505 PyAPI_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. */
510 PyAPI_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. */
516 PyAPI_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. */
520 PyAPI_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. */
524 PyAPI_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. */
532 PyAPI_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). */
538 PyAPI_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). */
544 PyAPI_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. */
553 PyAPI_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. */
559 PyAPI_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. */
565 PyAPI_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. */
569 PyAPI_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. */
576 PyAPI_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. */
583 PyAPI_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. */
590 PyAPI_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. */
597 PyAPI_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. */
604 PyAPI_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. */
610 PyAPI_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. */
616 PyAPI_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. */
622 PyAPI_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. */
628 PyAPI_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. */
634 PyAPI_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. */
643 PyAPI_FUNC(int) PySequence_Check(PyObject *o);
644
645 /* Return the size of sequence object o, or -1 on failure. */
646 PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
647
648 /* For DLL compatibility */
649 #undef PySequence_Length
650 PyAPI_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. */
657 PyAPI_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. */
663 PyAPI_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]. */
668 PyAPI_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]. */
673 PyAPI_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. */
679 PyAPI_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]. */
684 PyAPI_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. */
690 PyAPI_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]. */
697 PyAPI_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). */
702 PyAPI_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) */
706 PyAPI_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. */
715 PyAPI_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). */
738 PyAPI_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(). */
744 PyAPI_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. */
752 PyAPI_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). */
762 PyAPI_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. */
771 PyAPI_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. */
777 PyAPI_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. */
785 PyAPI_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). */
789 PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
790
791 /* For DLL compatibility */
792 #undef PyMapping_Length
793 PyAPI_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. */
823 PyAPI_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. */
830 PyAPI_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. */
834 PyAPI_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. */
838 PyAPI_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. */
843 PyAPI_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]. */
848 PyAPI_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. */
855 PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, const char *key,
856 PyObject *value);
857
858 /* isinstance(object, typeorclass) */
859 PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
860
861 /* issubclass(object, typeorclass) */
862 PyAPI_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 */