• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 #ifndef Py_ABSTRACTOBJECT_H
2 #define Py_ABSTRACTOBJECT_H
3 #ifdef __cplusplus
4 extern "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 
17 Problem
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 
49 Proposal
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 
103 Memory 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 
126 Protocols
127 
128 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
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 
1374 PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
1375       /* isinstance(object, typeorclass) */
1376 
1377 PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass);
1378       /* issubclass(object, typeorclass) */
1379 
1380 
1381 PyAPI_FUNC(int) _PyObject_RealIsInstance(PyObject *inst, PyObject *cls);
1382 
1383 PyAPI_FUNC(int) _PyObject_RealIsSubclass(PyObject *derived, PyObject *cls);
1384 
1385 
1386 /* For internal use by buffer API functions */
1387 PyAPI_FUNC(void) _Py_add_one_to_index_F(int nd, Py_ssize_t *index,
1388                                         const Py_ssize_t *shape);
1389 PyAPI_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