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