1#ifndef Py_ABSTRACTOBJECT_H
2#define Py_ABSTRACTOBJECT_H
3#ifdef __cplusplus
4extern "C" {
5#endif
6
7#ifdef PY_SSIZE_T_CLEAN
8#define PyObject_CallFunction _PyObject_CallFunction_SizeT
9#define PyObject_CallMethod _PyObject_CallMethod_SizeT
10#define _PyObject_CallMethodId _PyObject_CallMethodId_SizeT
11#endif
12
13/* Abstract Object Interface (many thanks to Jim Fulton) */
14
15/*
16 PROPOSAL: A Generic Python Object Interface for Python C Modules
17
18Problem
19
20 Python modules written in C that must access Python objects must do
21 so through routines whose interfaces are described by a set of
22 include files. Unfortunately, these routines vary according to the
23 object accessed. To use these routines, the C programmer must check
24 the type of the object being used and must call a routine based on
25 the object type. For example, to access an element of a sequence,
26 the programmer must determine whether the sequence is a list or a
27 tuple:
28
29 if(is_tupleobject(o))
30 e=gettupleitem(o,i)
31 else if(is_listitem(o))
32 e=getlistitem(o,i)
33
34 If the programmer wants to get an item from another type of object
35 that provides sequence behavior, there is no clear way to do it
36 correctly.
37
38 The persistent programmer may peruse object.h and find that the
39 _typeobject structure provides a means of invoking up to (currently
40 about) 41 special operators. So, for example, a routine can get an
41 item from any object that provides sequence behavior. However, to
42 use this mechanism, the programmer must make their code dependent on
43 the current Python implementation.
44
45 Also, certain semantics, especially memory management semantics, may
46 differ by the type of object being used. Unfortunately, these
47 semantics are not clearly described in the current include files.
48 An abstract interface providing more consistent semantics is needed.
49
50Proposal
51
52 I propose the creation of a standard interface (with an associated
53 library of routines and/or macros) for generically obtaining the
54 services of Python objects. This proposal can be viewed as one
55 components of a Python C interface consisting of several components.
56
57 From the viewpoint of C access to Python services, we have (as
58 suggested by Guido in off-line discussions):
59
60 - "Very high level layer": two or three functions that let you exec or
61 eval arbitrary Python code given as a string in a module whose name is
62 given, passing C values in and getting C values out using
63 mkvalue/getargs style format strings. This does not require the user
64 to declare any variables of type "PyObject *". This should be enough
65 to write a simple application that gets Python code from the user,
66 execs it, and returns the output or errors. (Error handling must also
67 be part of this API.)
68
69 - "Abstract objects layer": which is the subject of this proposal.
70 It has many functions operating on objects, and lest you do many
71 things from C that you can also write in Python, without going
72 through the Python parser.
73
74 - "Concrete objects layer": This is the public type-dependent
75 interface provided by the standard built-in types, such as floats,
76 strings, and lists. This interface exists and is currently
77 documented by the collection of include files provided with the
78 Python distributions.
79
80 From the point of view of Python accessing services provided by C
81 modules:
82
83 - "Python module interface": this interface consist of the basic
84 routines used to define modules and their members. Most of the
85 current extensions-writing guide deals with this interface.
86
87 - "Built-in object interface": this is the interface that a new
88 built-in type must provide and the mechanisms and rules that a
89 developer of a new built-in type must use and follow.
90
91 This proposal is a "first-cut" that is intended to spur
92 discussion. See especially the lists of notes.
93
94 The Python C object interface will provide four protocols: object,
95 numeric, sequence, and mapping. Each protocol consists of a
96 collection of related operations. If an operation that is not
97 provided by a particular type is invoked, then a standard exception,
98 NotImplementedError is raised with an operation name as an argument.
99 In addition, for convenience this interface defines a set of
100 constructors for building objects of built-in types. This is needed
101 so new objects can be returned from C functions that otherwise treat
102 objects generically.
103
104Memory Management
105
106 For all of the functions described in this proposal, if a function
107 retains a reference to a Python object passed as an argument, then the
108 function will increase the reference count of the object. It is
109 unnecessary for the caller to increase the reference count of an
110 argument in anticipation of the object's retention.
111
112 All Python objects returned from functions should be treated as new
113 objects. Functions that return objects assume that the caller will
114 retain a reference and the reference count of the object has already
115 been incremented to account for this fact. A caller that does not
116 retain a reference to an object that is returned from a function
117 must decrement the reference count of the object (using
118 DECREF(object)) to prevent memory leaks.
119
120 Note that the behavior mentioned here is different from the current
121 behavior for some objects (e.g. lists and tuples) when certain
122 type-specific routines are called directly (e.g. setlistitem). The
123 proposed abstraction layer will provide a consistent memory
124 management interface, correcting for inconsistent behavior for some
125 built-in types.
126
127Protocols
128
129xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
130
131/* Object Protocol: */
132
133 /* Implemented elsewhere:
134
135 int PyObject_Print(PyObject *o, FILE *fp, int flags);
136
137 Print an object, o, on file, fp. Returns -1 on
138 error. The flags argument is used to enable certain printing
139 options. The only option currently supported is Py_Print_RAW.
140
141 (What should be said about Py_Print_RAW?)
142
143 */
144
145 /* Implemented elsewhere:
146
147 int PyObject_HasAttrString(PyObject *o, const char *attr_name);
148
149 Returns 1 if o has the attribute attr_name, and 0 otherwise.
150 This is equivalent to the Python expression:
151 hasattr(o,attr_name).
152
153 This function always succeeds.
154
155 */
156
157 /* Implemented elsewhere:
158
159 PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name);
160
161 Retrieve an attributed named attr_name form object o.
162 Returns the attribute value on success, or NULL on failure.
163 This is the equivalent of the Python expression: o.attr_name.
164
165 */
166
167 /* Implemented elsewhere:
168
169 int PyObject_HasAttr(PyObject *o, PyObject *attr_name);
170
171 Returns 1 if o has the attribute attr_name, and 0 otherwise.
172 This is equivalent to the Python expression:
173 hasattr(o,attr_name).
174
175 This function always succeeds.
176
177 */
178
179 /* Implemented elsewhere:
180
181 PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name);
182
183 Retrieve an attributed named attr_name form object o.
184 Returns the attribute value on success, or NULL on failure.
185 This is the equivalent of the Python expression: o.attr_name.
186
187 */
188
189
190 /* Implemented elsewhere:
191
192 int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v);
193
194 Set the value of the attribute named attr_name, for object o,
195 to the value v. Raise an exception and return -1 on failure; return 0 on
196 success. This is the equivalent of the Python statement o.attr_name=v.
197
198 */
199
200 /* Implemented elsewhere:
201
202 int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v);
203
204 Set the value of the attribute named attr_name, for object o,
205 to the value v. Raise an exception and return -1 on failure; return 0 on
206 success. This is the equivalent of the Python statement o.attr_name=v.
207
208 */
209
210 /* implemented as a macro:
211
212 int PyObject_DelAttrString(PyObject *o, const char *attr_name);
213
214 Delete attribute named attr_name, for object o. Returns
215 -1 on failure. This is the equivalent of the Python
216 statement: del o.attr_name.
217
218 */
219#define PyObject_DelAttrString(O,A) PyObject_SetAttrString((O),(A),NULL)
220
221 /* implemented as a macro:
222
223 int PyObject_DelAttr(PyObject *o, PyObject *attr_name);
224
225 Delete attribute named attr_name, for object o. Returns -1
226 on failure. This is the equivalent of the Python
227 statement: del o.attr_name.
228
229 */
230#define PyObject_DelAttr(O,A) PyObject_SetAttr((O),(A),NULL)
231
232 /* Implemented elsewhere:
233
234 PyObject *PyObject_Repr(PyObject *o);
235
236 Compute the string representation of object, o. Returns the
237 string representation on success, NULL on failure. This is
238 the equivalent of the Python expression: repr(o).
239
240 Called by the repr() built-in function.
241
242 */
243
244 /* Implemented elsewhere:
245
246 PyObject *PyObject_Str(PyObject *o);
247
248 Compute the string representation of object, o. Returns the
249 string representation on success, NULL on failure. This is
250 the equivalent of the Python expression: str(o).)
251
252 Called by the str() and print() built-in functions.
253
254 */
255
256 /* Declared elsewhere
257
258 PyAPI_FUNC(int) PyCallable_Check(PyObject *o);
259
260 Determine if the object, o, is callable. Return 1 if the
261 object is callable and 0 otherwise.
262
263 This function always succeeds.
264 */
265
266 PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable_object,
267 PyObject *args, PyObject *kw);
268
269#ifndef Py_LIMITED_API
270 PyAPI_FUNC(PyObject *) _Py_CheckFunctionResult(PyObject *func,
271 PyObject *result,
272 const char *where);
273#endif
274
275 /*
276 Call a callable Python object, callable_object, with
277 arguments and keywords arguments. The 'args' argument can not be
278 NULL, but the 'kw' argument can be NULL.
279 */
280
281 PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable_object,
282 PyObject *args);
283
284 /*
285 Call a callable Python object, callable_object, with
286 arguments given by the tuple, args. If no arguments are
287 needed, then args may be NULL. Returns the result of the
288 call on success, or NULL on failure. This is the equivalent
289 of the Python expression: o(*args).
290 */
291
292 PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable_object,
293 const char *format, ...);
294
295 /*
296 Call a callable Python object, callable_object, with a
297 variable number of C arguments. The C arguments are described
298 using a mkvalue-style format string. The format may be NULL,
299 indicating that no arguments are provided. Returns the
300 result of the call on success, or NULL on failure. This is
301 the equivalent of the Python expression: o(*args).
302 */
303
304
305 PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *o,
306 const char *method,
307 const char *format, ...);
308
309 /*
310 Call the method named m of object o with a variable number of
311 C arguments. The C arguments are described by a mkvalue
312 format string. The format may be NULL, indicating that no
313 arguments are provided. Returns the result of the call on
314 success, or NULL on failure. This is the equivalent of the
315 Python expression: o.method(args).
316 */
317
318 PyAPI_FUNC(PyObject *) _PyObject_CallMethodId(PyObject *o,
319 _Py_Identifier *method,
320 const char *format, ...);
321
322 /*
323 Like PyObject_CallMethod, but expect a _Py_Identifier* as the
324 method name.
325 */
326
327 PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,
328 const char *format,
329 ...);
330 PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *o,
331 const char *name,
332 const char *format,
333 ...);
334 PyAPI_FUNC(PyObject *) _PyObject_CallMethodId_SizeT(PyObject *o,
335 _Py_Identifier *name,
336 const char *format,
337 ...);
338
339 PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,
340 ...);
341
342 /*
343 Call a callable Python object, callable_object, with a
344 variable number of C arguments. The C arguments are provided
345 as PyObject * values, terminated by a NULL. Returns the
346 result of the call on success, or NULL on failure. This is
347 the equivalent of the Python expression: o(*args).
348 */
349
350
351 PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(PyObject *o,
352 PyObject *method, ...);
353 PyAPI_FUNC(PyObject *) _PyObject_CallMethodIdObjArgs(PyObject *o,
354 struct _Py_Identifier *method,
355 ...);
356
357 /*
358 Call the method named m of object o with a variable number of
359 C arguments. The C arguments are provided as PyObject *
360 values, terminated by NULL. Returns the result of the call
361 on success, or NULL on failure. This is the equivalent of
362 the Python expression: o.method(args).
363 */
364
365
366 /* Implemented elsewhere:
367
368 long PyObject_Hash(PyObject *o);
369
370 Compute and return the hash, hash_value, of an object, o. On
371 failure, return -1. This is the equivalent of the Python
372 expression: hash(o).
373 */
374
375
376 /* Implemented elsewhere:
377
378 int PyObject_IsTrue(PyObject *o);
379
380 Returns 1 if the object, o, is considered to be true, 0 if o is
381 considered to be false and -1 on failure. This is equivalent to the
382 Python expression: not not o
383 */
384
385 /* Implemented elsewhere:
386
387 int PyObject_Not(PyObject *o);
388
389 Returns 0 if the object, o, is considered to be true, 1 if o is
390 considered to be false and -1 on failure. This is equivalent to the
391 Python expression: not o
392 */
393
394 PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o);
395
396 /*
397 On success, returns a type object corresponding to the object
398 type of object o. On failure, returns NULL. This is
399 equivalent to the Python expression: type(o).
400 */
401
402 PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
403
404 /*
405 Return the size of object o. If the object, o, provides
406 both sequence and mapping protocols, the sequence size is
407 returned. On error, -1 is returned. This is the equivalent
408 to the Python expression: len(o).
409 */
410
411 /* For DLL compatibility */
412#undef PyObject_Length
413 PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);
414#define PyObject_Length PyObject_Size
415
416#ifndef Py_LIMITED_API
417 PyAPI_FUNC(int) _PyObject_HasLen(PyObject *o);
418 PyAPI_FUNC(Py_ssize_t) PyObject_LengthHint(PyObject *o, Py_ssize_t);
419#endif
420
421 /*
422 Guess the size of object o using len(o) or o.__length_hint__().
423 If neither of those return a non-negative value, then return the
424 default value. If one of the calls fails, this function returns -1.
425 */
426
427 PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
428
429 /*
430 Return element of o corresponding to the object, key, or NULL
431 on failure. This is the equivalent of the Python expression:
432 o[key].
433 */
434
435 PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
436
437 /*
438 Map the object key to the value v. Raise an exception and return -1
439 on failure; return 0 on success. This is the equivalent of the Python
440 statement o[key]=v.
441 */
442
443 PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, const char *key);
444
445 /*
446 Remove the mapping for object, key, from the object *o.
447 Returns -1 on failure. This is equivalent to
448 the Python statement: del o[key].
449 */
450
451 PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
452
453 /*
454 Delete the mapping for key from *o. Returns -1 on failure.
455 This is the equivalent of the Python statement: del o[key].
456 */
457
458 /* old buffer API
459 FIXME: usage of these should all be replaced in Python itself
460 but for backwards compatibility we will implement them.
461 Their usage without a corresponding "unlock" mechansim
462 may create issues (but they would already be there). */
463
464 PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,
465 const char **buffer,
466 Py_ssize_t *buffer_len);
467
468 /*
469 Takes an arbitrary object which must support the (character,
470 single segment) buffer interface and returns a pointer to a
471 read-only memory location useable as character based input
472 for subsequent processing.
473
474 0 is returned on success. buffer and buffer_len are only
475 set in case no error occurs. Otherwise, -1 is returned and
476 an exception set.
477 */
478
479 PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);
480
481 /*
482 Checks whether an arbitrary object supports the (character,
483 single segment) buffer interface. Returns 1 on success, 0
484 on failure.
485 */
486
487 PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,
488 const void **buffer,
489 Py_ssize_t *buffer_len);
490
491 /*
492 Same as PyObject_AsCharBuffer() except that this API expects
493 (readable, single segment) buffer interface and returns a
494 pointer to a read-only memory location which can contain
495 arbitrary data.
496
497 0 is returned on success. buffer and buffer_len are only
498 set in case no error occurs. Otherwise, -1 is returned and
499 an exception set.
500 */
501
502 PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,
503 void **buffer,
504 Py_ssize_t *buffer_len);
505
506 /*
507 Takes an arbitrary object which must support the (writable,
508 single segment) buffer interface and returns a pointer to a
509 writable memory location in buffer of size buffer_len.
510
511 0 is returned on success. buffer and buffer_len are only
512 set in case no error occurs. Otherwise, -1 is returned and
513 an exception set.
514 */
515
516 /* new buffer API */
517
518#ifndef Py_LIMITED_API
519#define PyObject_CheckBuffer(obj) \
520 (((obj)->ob_type->tp_as_buffer != NULL) && \
521 ((obj)->ob_type->tp_as_buffer->bf_getbuffer != NULL))
522
523 /* Return 1 if the getbuffer function is available, otherwise
524 return 0 */
525
526 PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view,
527 int flags);
528
529 /* This is a C-API version of the getbuffer function call. It checks
530 to make sure object has the required function pointer and issues the
531 call. Returns -1 and raises an error on failure and returns 0 on
532 success
533 */
534
535
536 PyAPI_FUNC(void *) PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices);
537
538 /* Get the memory area pointed to by the indices for the buffer given.
539 Note that view->ndim is the assumed size of indices
540 */
541
542 PyAPI_FUNC(int) PyBuffer_SizeFromFormat(const char *);
543
544 /* Return the implied itemsize of the data-format area from a
545 struct-style description */
546
547
548
549 /* Implementation in memoryobject.c */
550 PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, Py_buffer *view,
551 Py_ssize_t len, char order);
552
553 PyAPI_FUNC(int) PyBuffer_FromContiguous(Py_buffer *view, void *buf,
554 Py_ssize_t len, char order);
555
556
557 /* Copy len bytes of data from the contiguous chunk of memory
558 pointed to by buf into the buffer exported by obj. Return
559 0 on success and return -1 and raise a PyBuffer_Error on
560 error (i.e. the object does not have a buffer interface or
561 it is not working).
562
563 If fort is 'F', then if the object is multi-dimensional,
564 then the data will be copied into the array in
565 Fortran-style (first dimension varies the fastest). If
566 fort is 'C', then the data will be copied into the array
567 in C-style (last dimension varies the fastest). If fort
568 is 'A', then it does not matter and the copy will be made
569 in whatever way is more efficient.
570
571 */
572
573 PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);
574
575 /* Copy the data from the src buffer to the buffer of destination
576 */
577
578 PyAPI_FUNC(int) PyBuffer_IsContiguous(const Py_buffer *view, char fort);
579
580
581 PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims,
582 Py_ssize_t *shape,
583 Py_ssize_t *strides,
584 int itemsize,
585 char fort);
586
587 /* Fill the strides array with byte-strides of a contiguous
588 (Fortran-style if fort is 'F' or C-style otherwise)
589 array of the given shape with the given number of bytes
590 per element.
591 */
592
593 PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf,
594 Py_ssize_t len, int readonly,
595 int flags);
596
597 /* Fills in a buffer-info structure correctly for an exporter
598 that can only share a contiguous chunk of memory of
599 "unsigned bytes" of the given length. Returns 0 on success
600 and -1 (with raising an error) on error.
601 */
602
603 PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);
604
605 /* Releases a Py_buffer obtained from getbuffer ParseTuple's s*.
606 */
607#endif /* Py_LIMITED_API */
608
609 PyAPI_FUNC(PyObject *) PyObject_Format(PyObject* obj,
610 PyObject *format_spec);
611 /*
612 Takes an arbitrary object and returns the result of
613 calling obj.__format__(format_spec).
614 */
615
616/* Iterators */
617
618 PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);
619 /* Takes an object and returns an iterator for it.
620 This is typically a new iterator but if the argument
621 is an iterator, this returns itself. */
622
623#define PyIter_Check(obj) \
624 ((obj)->ob_type->tp_iternext != NULL && \
625 (obj)->ob_type->tp_iternext != &_PyObject_NextNotImplemented)
626
627 PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);
628 /* Takes an iterator object and calls its tp_iternext slot,
629 returning the next value. If the iterator is exhausted,
630 this returns NULL without setting an exception.
631 NULL with an exception means an error occurred. */
632
633/* Number Protocol:*/
634
635 PyAPI_FUNC(int) PyNumber_Check(PyObject *o);
636
637 /*
638 Returns 1 if the object, o, provides numeric protocols, and
639 false otherwise.
640
641 This function always succeeds.
642 */
643
644 PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);
645
646 /*
647 Returns the result of adding o1 and o2, or null on failure.
648 This is the equivalent of the Python expression: o1+o2.
649 */
650
651 PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2);
652
653 /*
654 Returns the result of subtracting o2 from o1, or null on
655 failure. This is the equivalent of the Python expression:
656 o1-o2.
657 */
658
659 PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2);
660
661 /*
662 Returns the result of multiplying o1 and o2, or null on
663 failure. This is the equivalent of the Python expression:
664 o1*o2.
665 */
666
667 PyAPI_FUNC(PyObject *) PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2);
668
669 /*
670 This is the equivalent of the Python expression: o1 @ o2.
671 */
672
673 PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2);
674
675 /*
676 Returns the result of dividing o1 by o2 giving an integral result,
677 or null on failure.
678 This is the equivalent of the Python expression: o1//o2.
679 */
680
681 PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2);
682
683 /*
684 Returns the result of dividing o1 by o2 giving a float result,
685 or null on failure.
686 This is the equivalent of the Python expression: o1/o2.
687 */
688
689 PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);
690
691 /*
692 Returns the remainder of dividing o1 by o2, or null on
693 failure. This is the equivalent of the Python expression:
694 o1%o2.
695 */
696
697 PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);
698
699 /*
700 See the built-in function divmod. Returns NULL on failure.
701 This is the equivalent of the Python expression:
702 divmod(o1,o2).
703 */
704
705 PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,
706 PyObject *o3);
707
708 /*
709 See the built-in function pow. Returns NULL on failure.
710 This is the equivalent of the Python expression:
711 pow(o1,o2,o3), where o3 is optional.
712 */
713
714 PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o);
715
716 /*
717 Returns the negation of o on success, or null on failure.
718 This is the equivalent of the Python expression: -o.
719 */
720
721 PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o);
722
723 /*
724 Returns the (what?) of o on success, or NULL on failure.
725 This is the equivalent of the Python expression: +o.
726 */
727
728 PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o);
729
730 /*
731 Returns the absolute value of o, or null on failure. This is
732 the equivalent of the Python expression: abs(o).
733 */
734
735 PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o);
736
737 /*
738 Returns the bitwise negation of o on success, or NULL on
739 failure. This is the equivalent of the Python expression:
740 ~o.
741 */
742
743 PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);
744
745 /*
746 Returns the result of left shifting o1 by o2 on success, or
747 NULL on failure. This is the equivalent of the Python
748 expression: o1 << o2.
749 */
750
751 PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);
752
753 /*
754 Returns the result of right shifting o1 by o2 on success, or
755 NULL on failure. This is the equivalent of the Python
756 expression: o1 >> o2.
757 */
758
759 PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);
760
761 /*
762 Returns the result of bitwise and of o1 and o2 on success, or
763 NULL on failure. This is the equivalent of the Python
764 expression: o1&o2.
765
766 */
767
768 PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);
769
770 /*
771 Returns the bitwise exclusive or of o1 by o2 on success, or
772 NULL on failure. This is the equivalent of the Python
773 expression: o1^o2.
774 */
775
776 PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);
777
778 /*
779 Returns the result of bitwise or on o1 and o2 on success, or
780 NULL on failure. This is the equivalent of the Python
781 expression: o1|o2.
782 */
783
784#define PyIndex_Check(obj) \
785 ((obj)->ob_type->tp_as_number != NULL && \
786 (obj)->ob_type->tp_as_number->nb_index != NULL)
787
788 PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o);
789
790 /*
791 Returns the object converted to a Python int
792 or NULL with an error raised on failure.
793 */
794
795 PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc);
796
797 /*
798 Returns the object converted to Py_ssize_t by going through
799 PyNumber_Index first. If an overflow error occurs while
800 converting the int to Py_ssize_t, then the second argument
801 is the error-type to return. If it is NULL, then the overflow error
802 is cleared and the value is clipped.
803 */
804
805 PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);
806
807 /*
808 Returns the o converted to an integer object on success, or
809 NULL on failure. This is the equivalent of the Python
810 expression: int(o).
811 */
812
813 PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);
814
815 /*
816 Returns the o converted to a float object on success, or NULL
817 on failure. This is the equivalent of the Python expression:
818 float(o).
819 */
820
821/* In-place variants of (some of) the above number protocol functions */
822
823 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);
824
825 /*
826 Returns the result of adding o2 to o1, possibly in-place, or null
827 on failure. This is the equivalent of the Python expression:
828 o1 += o2.
829 */
830
831 PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);
832
833 /*
834 Returns the result of subtracting o2 from o1, possibly in-place or
835 null on failure. This is the equivalent of the Python expression:
836 o1 -= o2.
837 */
838
839 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);
840
841 /*
842 Returns the result of multiplying o1 by o2, possibly in-place, or
843 null on failure. This is the equivalent of the Python expression:
844 o1 *= o2.
845 */
846
847 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2);
848
849 /*
850 This is the equivalent of the Python expression: o1 @= o2.
851 */
852
853 PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1,
854 PyObject *o2);
855
856 /*
857 Returns the result of dividing o1 by o2 giving an integral result,
858 possibly in-place, or null on failure.
859 This is the equivalent of the Python expression:
860 o1 /= o2.
861 */
862
863 PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1,
864 PyObject *o2);
865
866 /*
867 Returns the result of dividing o1 by o2 giving a float result,
868 possibly in-place, or null on failure.
869 This is the equivalent of the Python expression:
870 o1 /= o2.
871 */
872
873 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);
874
875 /*
876 Returns the remainder of dividing o1 by o2, possibly in-place, or
877 null on failure. This is the equivalent of the Python expression:
878 o1 %= o2.
879 */
880
881 PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,
882 PyObject *o3);
883
884 /*
885 Returns the result of raising o1 to the power of o2, possibly
886 in-place, or null on failure. This is the equivalent of the Python
887 expression: o1 **= o2, or pow(o1, o2, o3) if o3 is present.
888 */
889
890 PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);
891
892 /*
893 Returns the result of left shifting o1 by o2, possibly in-place, or
894 null on failure. This is the equivalent of the Python expression:
895 o1 <<= o2.
896 */
897
898 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);
899
900 /*
901 Returns the result of right shifting o1 by o2, possibly in-place or
902 null on failure. This is the equivalent of the Python expression:
903 o1 >>= o2.
904 */
905
906 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);
907
908 /*
909 Returns the result of bitwise and of o1 and o2, possibly in-place,
910 or null on failure. This is the equivalent of the Python
911 expression: o1 &= o2.
912 */
913
914 PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);
915
916 /*
917 Returns the bitwise exclusive or of o1 by o2, possibly in-place, or
918 null on failure. This is the equivalent of the Python expression:
919 o1 ^= o2.
920 */
921
922 PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);
923
924 /*
925 Returns the result of bitwise or of o1 and o2, possibly in-place,
926 or null on failure. This is the equivalent of the Python
927 expression: o1 |= o2.
928 */
929
930 PyAPI_FUNC(PyObject *) PyNumber_ToBase(PyObject *n, int base);
931
932 /*
933 Returns the integer n converted to a string with a base, with a base
934 marker of 0b, 0o or 0x prefixed if applicable.
935 If n is not an int object, it is converted with PyNumber_Index first.
936 */
937
938
939/* Sequence protocol:*/
940
941 PyAPI_FUNC(int) PySequence_Check(PyObject *o);
942
943 /*
944 Return 1 if the object provides sequence protocol, and zero
945 otherwise.
946
947 This function always succeeds.
948 */
949
950 PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
951
952 /*
953 Return the size of sequence object o, or -1 on failure.
954 */
955
956 /* For DLL compatibility */
957#undef PySequence_Length
958 PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);
959#define PySequence_Length PySequence_Size
960
961
962 PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);
963
964 /*
965 Return the concatenation of o1 and o2 on success, and NULL on
966 failure. This is the equivalent of the Python
967 expression: o1+o2.
968 */
969
970 PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count);
971
972 /*
973 Return the result of repeating sequence object o count times,
974 or NULL on failure. This is the equivalent of the Python
975 expression: o1*count.
976 */
977
978 PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i);
979
980 /*
981 Return the ith element of o, or NULL on failure. This is the
982 equivalent of the Python expression: o[i].
983 */
984
985 PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
986
987 /*
988 Return the slice of sequence object o between i1 and i2, or
989 NULL on failure. This is the equivalent of the Python
990 expression: o[i1:i2].
991 */
992
993 PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);
994
995 /*
996 Assign object v to the ith element of o. Raise an exception and return
997 -1 on failure; return 0 on success. This is the equivalent of the
998 Python statement o[i]=v.
999 */
1000
1001 PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
1002
1003 /*
1004 Delete the ith element of object v. Returns
1005 -1 on failure. This is the equivalent of the Python
1006 statement: del o[i].
1007 */
1008
1009 PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2,
1010 PyObject *v);
1011
1012 /*
1013 Assign the sequence object, v, to the slice in sequence
1014 object, o, from i1 to i2. Returns -1 on failure. This is the
1015 equivalent of the Python statement: o[i1:i2]=v.
1016 */
1017
1018 PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
1019
1020 /*
1021 Delete the slice in sequence object, o, from i1 to i2.
1022 Returns -1 on failure. This is the equivalent of the Python
1023 statement: del o[i1:i2].
1024 */
1025
1026 PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);
1027
1028 /*
1029 Returns the sequence, o, as a tuple on success, and NULL on failure.
1030 This is equivalent to the Python expression: tuple(o)
1031 */
1032
1033
1034 PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);
1035 /*
1036 Returns the sequence, o, as a list on success, and NULL on failure.
1037 This is equivalent to the Python expression: list(o)
1038 */
1039
1040 PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
1041 /*
1042 Return the sequence, o, as a list, unless it's already a
1043 tuple or list. Use PySequence_Fast_GET_ITEM to access the
1044 members of this list, and PySequence_Fast_GET_SIZE to get its length.
1045
1046 Returns NULL on failure. If the object does not support iteration,
1047 raises a TypeError exception with m as the message text.
1048 */
1049
1050#define PySequence_Fast_GET_SIZE(o) \
1051 (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o))
1052 /*
1053 Return the size of o, assuming that o was returned by
1054 PySequence_Fast and is not NULL.
1055 */
1056
1057#define PySequence_Fast_GET_ITEM(o, i)\
1058 (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i))
1059 /*
1060 Return the ith element of o, assuming that o was returned by
1061 PySequence_Fast, and that i is within bounds.
1062 */
1063
1064#define PySequence_ITEM(o, i)\
1065 ( Py_TYPE(o)->tp_as_sequence->sq_item(o, i) )
1066 /* Assume tp_as_sequence and sq_item exist and that i does not
1067 need to be corrected for a negative index
1068 */
1069
1070#define PySequence_Fast_ITEMS(sf) \
1071 (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \
1072 : ((PyTupleObject *)(sf))->ob_item)
1073 /* Return a pointer to the underlying item array for
1074 an object retured by PySequence_Fast */
1075
1076 PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value);
1077
1078 /*
1079 Return the number of occurrences on value on o, that is,
1080 return the number of keys for which o[key]==value. On
1081 failure, return -1. This is equivalent to the Python
1082 expression: o.count(value).
1083 */
1084
1085 PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob);
1086 /*
1087 Return -1 if error; 1 if ob in seq; 0 if ob not in seq.
1088 Use __contains__ if possible, else _PySequence_IterSearch().
1089 */
1090
1091#ifndef Py_LIMITED_API
1092#define PY_ITERSEARCH_COUNT 1
1093#define PY_ITERSEARCH_INDEX 2
1094#define PY_ITERSEARCH_CONTAINS 3
1095 PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq,
1096 PyObject *obj, int operation);
1097#endif
1098 /*
1099 Iterate over seq. Result depends on the operation:
1100 PY_ITERSEARCH_COUNT: return # of times obj appears in seq; -1 if
1101 error.
1102 PY_ITERSEARCH_INDEX: return 0-based index of first occurrence of
1103 obj in seq; set ValueError and return -1 if none found;
1104 also return -1 on error.
1105 PY_ITERSEARCH_CONTAINS: return 1 if obj in seq, else 0; -1 on
1106 error.
1107 */
1108
1109/* For DLL-level backwards compatibility */
1110#undef PySequence_In
1111 PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value);
1112
1113/* For source-level backwards compatibility */
1114#define PySequence_In PySequence_Contains
1115
1116 /*
1117 Determine if o contains value. If an item in o is equal to
1118 X, return 1, otherwise return 0. On error, return -1. This
1119 is equivalent to the Python expression: value in o.
1120 */
1121
1122 PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value);
1123
1124 /*
1125 Return the first index for which o[i]=value. On error,
1126 return -1. This is equivalent to the Python
1127 expression: o.index(value).
1128 */
1129
1130/* In-place versions of some of the above Sequence functions. */
1131
1132 PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);
1133
1134 /*
1135 Append o2 to o1, in-place when possible. Return the resulting
1136 object, which could be o1, or NULL on failure. This is the
1137 equivalent of the Python expression: o1 += o2.
1138
1139 */
1140
1141 PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count);
1142
1143 /*
1144 Repeat o1 by count, in-place when possible. Return the resulting
1145 object, which could be o1, or NULL on failure. This is the
1146 equivalent of the Python expression: o1 *= count.
1147
1148 */
1149
1150/* Mapping protocol:*/
1151
1152 PyAPI_FUNC(int) PyMapping_Check(PyObject *o);
1153
1154 /*
1155 Return 1 if the object provides mapping protocol, and zero
1156 otherwise.
1157
1158 This function always succeeds.
1159 */
1160
1161 PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
1162
1163 /*
1164 Returns the number of keys in object o on success, and -1 on
1165 failure. For objects that do not provide sequence protocol,
1166 this is equivalent to the Python expression: len(o).
1167 */
1168
1169 /* For DLL compatibility */
1170#undef PyMapping_Length
1171 PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
1172#define PyMapping_Length PyMapping_Size
1173
1174
1175 /* implemented as a macro:
1176
1177 int PyMapping_DelItemString(PyObject *o, const char *key);
1178
1179 Remove the mapping for object, key, from the object *o.
1180 Returns -1 on failure. This is equivalent to
1181 the Python statement: del o[key].
1182 */
1183#define PyMapping_DelItemString(O,K) PyObject_DelItemString((O),(K))
1184
1185 /* implemented as a macro:
1186
1187 int PyMapping_DelItem(PyObject *o, PyObject *key);
1188
1189 Remove the mapping for object, key, from the object *o.
1190 Returns -1 on failure. This is equivalent to
1191 the Python statement: del o[key].
1192 */
1193#define PyMapping_DelItem(O,K) PyObject_DelItem((O),(K))
1194
1195 PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, const char *key);
1196
1197 /*
1198 On success, return 1 if the mapping object has the key, key,
1199 and 0 otherwise. This is equivalent to the Python expression:
1200 key in o.
1201
1202 This function always succeeds.
1203 */
1204
1205 PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key);
1206
1207 /*
1208 Return 1 if the mapping object has the key, key,
1209 and 0 otherwise. This is equivalent to the Python expression:
1210 key in o.
1211
1212 This function always succeeds.
1213
1214 */
1215
1216 PyAPI_FUNC(PyObject *) PyMapping_Keys(PyObject *o);
1217
1218 /*
1219 On success, return a list, a tuple or a dictionary view in case of a dict,
1220 of the keys in object o. On failure, return NULL.
1221 */
1222
1223 PyAPI_FUNC(PyObject *) PyMapping_Values(PyObject *o);
1224
1225 /*
1226 On success, return a list, a tuple or a dictionary view in case of a dict,
1227 of the values in object o. On failure, return NULL.
1228 */
1229
1230 PyAPI_FUNC(PyObject *) PyMapping_Items(PyObject *o);
1231
1232 /*
1233 On success, return a list, a tuple or a dictionary view in case of a dict,
1234 of the items in object o, where each item is a tuple containing a key-value
1235 pair. On failure, return NULL.
1236
1237 */
1238
1239 PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o,
1240 const char *key);
1241
1242 /*
1243 Return element of o corresponding to the object, key, or NULL
1244 on failure. This is the equivalent of the Python expression:
1245 o[key].
1246 */
1247
1248 PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, const char *key,
1249 PyObject *value);
1250
1251 /*
1252 Map the object, key, to the value, v. Returns
1253 -1 on failure. This is the equivalent of the Python
1254 statement: o[key]=v.
1255 */
1256
1257
1258PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
1259 /* isinstance(object, typeorclass) */
1260
1261PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass);
1262 /* issubclass(object, typeorclass) */
1263
1264
1265#ifndef Py_LIMITED_API
1266PyAPI_FUNC(int) _PyObject_RealIsInstance(PyObject *inst, PyObject *cls);
1267
1268PyAPI_FUNC(int) _PyObject_RealIsSubclass(PyObject *derived, PyObject *cls);
1269
1270PyAPI_FUNC(char *const *) _PySequence_BytesToCharpArray(PyObject* self);
1271
1272PyAPI_FUNC(void) _Py_FreeCharPArray(char *const array[]);
1273#endif
1274
1275/* For internal use by buffer API functions */
1276PyAPI_FUNC(void) _Py_add_one_to_index_F(int nd, Py_ssize_t *index,
1277 const Py_ssize_t *shape);
1278PyAPI_FUNC(void) _Py_add_one_to_index_C(int nd, Py_ssize_t *index,
1279 const Py_ssize_t *shape);
1280
1281
1282#ifdef __cplusplus
1283}
1284#endif
1285#endif /* Py_ABSTRACTOBJECT_H */
1286