• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /* Abstract Object Interface (many thanks to Jim Fulton) */
2 
3 #ifndef Py_ABSTRACTOBJECT_H
4 #define Py_ABSTRACTOBJECT_H
5 #ifdef __cplusplus
6 extern "C" {
7 #endif
8 
9 /* === Object Protocol ================================================== */
10 
11 /* Implemented elsewhere:
12 
13    int PyObject_Print(PyObject *o, FILE *fp, int flags);
14 
15    Print an object 'o' on file 'fp'.  Returns -1 on error. The flags argument
16    is used to enable certain printing options. The only option currently
17    supported is Py_Print_RAW.
18 
19    (What should be said about Py_Print_RAW?). */
20 
21 
22 /* Implemented elsewhere:
23 
24    int PyObject_HasAttrString(PyObject *o, const char *attr_name);
25 
26    Returns 1 if object 'o' has the attribute attr_name, and 0 otherwise.
27 
28    This is equivalent to the Python expression: hasattr(o,attr_name).
29 
30    This function always succeeds. */
31 
32 
33 /* Implemented elsewhere:
34 
35    PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name);
36 
37    Retrieve an attributed named attr_name form object o.
38    Returns the attribute value on success, or NULL on failure.
39 
40    This is the equivalent of the Python expression: o.attr_name. */
41 
42 
43 /* Implemented elsewhere:
44 
45    int PyObject_HasAttr(PyObject *o, PyObject *attr_name);
46 
47    Returns 1 if o has the attribute attr_name, and 0 otherwise.
48 
49    This is equivalent to the Python expression: hasattr(o,attr_name).
50 
51    This function always succeeds. */
52 
53 /* Implemented elsewhere:
54 
55    PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name);
56 
57    Retrieve an attributed named 'attr_name' form object 'o'.
58    Returns the attribute value on success, or NULL on failure.
59 
60    This is the equivalent of the Python expression: o.attr_name. */
61 
62 
63 /* Implemented elsewhere:
64 
65    int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v);
66 
67    Set the value of the attribute named attr_name, for object 'o',
68    to the value 'v'. Raise an exception and return -1 on failure; return 0 on
69    success.
70 
71    This is the equivalent of the Python statement o.attr_name=v. */
72 
73 
74 /* Implemented elsewhere:
75 
76    int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v);
77 
78    Set the value of the attribute named attr_name, for object 'o', to the value
79    'v'. an exception and return -1 on failure; return 0 on success.
80 
81    This is the equivalent of the Python statement o.attr_name=v. */
82 
83 /* Implemented as a macro:
84 
85    int PyObject_DelAttrString(PyObject *o, const char *attr_name);
86 
87    Delete attribute named attr_name, for object o. Returns
88    -1 on failure.
89 
90    This is the equivalent of the Python statement: del o.attr_name. */
91 #define PyObject_DelAttrString(O,A) PyObject_SetAttrString((O),(A), NULL)
92 
93 
94 /* Implemented as a macro:
95 
96    int PyObject_DelAttr(PyObject *o, PyObject *attr_name);
97 
98    Delete attribute named attr_name, for object o. Returns -1
99    on failure.  This is the equivalent of the Python
100    statement: del o.attr_name. */
101 #define  PyObject_DelAttr(O,A) PyObject_SetAttr((O),(A), NULL)
102 
103 
104 /* Implemented elsewhere:
105 
106    PyObject *PyObject_Repr(PyObject *o);
107 
108    Compute the string representation of object 'o'.  Returns the
109    string representation on success, NULL on failure.
110 
111    This is the equivalent of the Python expression: repr(o).
112 
113    Called by the repr() built-in function. */
114 
115 
116 /* Implemented elsewhere:
117 
118    PyObject *PyObject_Str(PyObject *o);
119 
120    Compute the string representation of object, o.  Returns the
121    string representation on success, NULL on failure.
122 
123    This is the equivalent of the Python expression: str(o).
124 
125    Called by the str() and print() built-in functions. */
126 
127 
128 /* Declared elsewhere
129 
130    PyAPI_FUNC(int) PyCallable_Check(PyObject *o);
131 
132    Determine if the object, o, is callable.  Return 1 if the object is callable
133    and 0 otherwise.
134 
135    This function always succeeds. */
136 
137 
138 #ifdef PY_SSIZE_T_CLEAN
139 #  define PyObject_CallFunction _PyObject_CallFunction_SizeT
140 #  define PyObject_CallMethod _PyObject_CallMethod_SizeT
141 #  ifndef Py_LIMITED_API
142 #    define _PyObject_CallMethodId _PyObject_CallMethodId_SizeT
143 #  endif /* !Py_LIMITED_API */
144 #endif
145 
146 
147 /* Call a callable Python object 'callable' with arguments given by the
148    tuple 'args' and keywords arguments given by the dictionary 'kwargs'.
149 
150    'args' must not be *NULL*, use an empty tuple if no arguments are
151    needed. If no named arguments are needed, 'kwargs' can be NULL.
152 
153    This is the equivalent of the Python expression:
154    callable(*args, **kwargs). */
155 PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable,
156                                      PyObject *args, PyObject *kwargs);
157 
158 #ifndef Py_LIMITED_API
159 PyAPI_FUNC(PyObject*) _PyStack_AsTuple(
160     PyObject *const *stack,
161     Py_ssize_t nargs);
162 
163 PyAPI_FUNC(PyObject*) _PyStack_AsTupleSlice(
164     PyObject *const *stack,
165     Py_ssize_t nargs,
166     Py_ssize_t start,
167     Py_ssize_t end);
168 
169 /* Convert keyword arguments from the FASTCALL (stack: C array, kwnames: tuple)
170    format to a Python dictionary ("kwargs" dict).
171 
172    The type of kwnames keys is not checked. The final function getting
173    arguments is responsible to check if all keys are strings, for example using
174    PyArg_ParseTupleAndKeywords() or PyArg_ValidateKeywordArguments().
175 
176    Duplicate keys are merged using the last value. If duplicate keys must raise
177    an exception, the caller is responsible to implement an explicit keys on
178    kwnames. */
179 PyAPI_FUNC(PyObject *) _PyStack_AsDict(
180     PyObject *const *values,
181     PyObject *kwnames);
182 
183 /* Convert (args, nargs, kwargs: dict) into a (stack, nargs, kwnames: tuple).
184 
185    Return 0 on success, raise an exception and return -1 on error.
186 
187    Write the new stack into *p_stack. If *p_stack is differen than args, it
188    must be released by PyMem_Free().
189 
190    The stack uses borrowed references.
191 
192    The type of keyword keys is not checked, these checks should be done
193    later (ex: _PyArg_ParseStackAndKeywords). */
194 PyAPI_FUNC(int) _PyStack_UnpackDict(
195     PyObject *const *args,
196     Py_ssize_t nargs,
197     PyObject *kwargs,
198     PyObject *const **p_stack,
199     PyObject **p_kwnames);
200 
201 /* Suggested size (number of positional arguments) for arrays of PyObject*
202    allocated on a C stack to avoid allocating memory on the heap memory. Such
203    array is used to pass positional arguments to call functions of the
204    _PyObject_FastCall() family.
205 
206    The size is chosen to not abuse the C stack and so limit the risk of stack
207    overflow. The size is also chosen to allow using the small stack for most
208    function calls of the Python standard library. On 64-bit CPU, it allocates
209    40 bytes on the stack. */
210 #define _PY_FASTCALL_SMALL_STACK 5
211 
212 /* Return 1 if callable supports FASTCALL calling convention for positional
213    arguments: see _PyObject_FastCallDict() and _PyObject_FastCallKeywords() */
214 PyAPI_FUNC(int) _PyObject_HasFastCall(PyObject *callable);
215 
216 /* Call the callable object 'callable' with the "fast call" calling convention:
217    args is a C array for positional arguments (nargs is the number of
218    positional arguments), kwargs is a dictionary for keyword arguments.
219 
220    If nargs is equal to zero, args can be NULL. kwargs can be NULL.
221    nargs must be greater or equal to zero.
222 
223    Return the result on success. Raise an exception on return NULL on
224    error. */
225 PyAPI_FUNC(PyObject *) _PyObject_FastCallDict(
226     PyObject *callable,
227     PyObject *const *args,
228     Py_ssize_t nargs,
229     PyObject *kwargs);
230 
231 /* Call the callable object 'callable' with the "fast call" calling convention:
232    args is a C array for positional arguments followed by values of
233    keyword arguments. Keys of keyword arguments are stored as a tuple
234    of strings in kwnames. nargs is the number of positional parameters at
235    the beginning of stack. The size of kwnames gives the number of keyword
236    values in the stack after positional arguments.
237 
238    kwnames must only contains str strings, no subclass, and all keys must
239    be unique.
240 
241    If nargs is equal to zero and there is no keyword argument (kwnames is
242    NULL or its size is zero), args can be NULL.
243 
244    Return the result on success. Raise an exception and return NULL on
245    error. */
246 PyAPI_FUNC(PyObject *) _PyObject_FastCallKeywords(
247     PyObject *callable,
248     PyObject *const *args,
249     Py_ssize_t nargs,
250     PyObject *kwnames);
251 
252 #define _PyObject_FastCall(func, args, nargs) \
253     _PyObject_FastCallDict((func), (args), (nargs), NULL)
254 
255 #define _PyObject_CallNoArg(func) \
256     _PyObject_FastCallDict((func), NULL, 0, NULL)
257 
258 PyAPI_FUNC(PyObject *) _PyObject_Call_Prepend(
259     PyObject *callable,
260     PyObject *obj,
261     PyObject *args,
262     PyObject *kwargs);
263 
264 PyAPI_FUNC(PyObject *) _PyObject_FastCall_Prepend(
265     PyObject *callable,
266     PyObject *obj,
267     PyObject *const *args,
268     Py_ssize_t nargs);
269 
270 PyAPI_FUNC(PyObject *) _Py_CheckFunctionResult(PyObject *callable,
271                                                PyObject *result,
272                                                const char *where);
273 #endif   /* Py_LIMITED_API */
274 
275 
276 /* Call a callable Python object 'callable', with arguments given by the
277    tuple 'args'.  If no arguments are needed, then 'args' can be *NULL*.
278 
279    Returns the result of the call on success, or *NULL* on failure.
280 
281    This is the equivalent of the Python expression:
282    callable(*args). */
283 PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable,
284                                            PyObject *args);
285 
286 /* Call a callable Python object, callable, with a variable number of C
287    arguments. The C arguments are described using a mkvalue-style format
288    string.
289 
290    The format may be NULL, indicating that no arguments are provided.
291 
292    Returns the result of the call on success, or NULL on failure.
293 
294    This is the equivalent of the Python expression:
295    callable(arg1, arg2, ...). */
296 PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable,
297                                              const char *format, ...);
298 
299 /* Call the method named 'name' of object 'obj' with a variable number of
300    C arguments.  The C arguments are described by a mkvalue format string.
301 
302    The format can be NULL, indicating that no arguments are provided.
303 
304    Returns the result of the call on success, or NULL on failure.
305 
306    This is the equivalent of the Python expression:
307    obj.name(arg1, arg2, ...). */
308 PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *obj,
309                                            const char *name,
310                                            const char *format, ...);
311 
312 #ifndef Py_LIMITED_API
313 /* Like PyObject_CallMethod(), but expect a _Py_Identifier*
314    as the method name. */
315 PyAPI_FUNC(PyObject *) _PyObject_CallMethodId(PyObject *obj,
316                                               _Py_Identifier *name,
317                                               const char *format, ...);
318 #endif /* !Py_LIMITED_API */
319 
320 PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,
321                                                     const char *format,
322                                                     ...);
323 
324 PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *obj,
325                                                   const char *name,
326                                                   const char *format,
327                                                   ...);
328 
329 #ifndef Py_LIMITED_API
330 PyAPI_FUNC(PyObject *) _PyObject_CallMethodId_SizeT(PyObject *obj,
331                                                     _Py_Identifier *name,
332                                                     const char *format,
333                                                     ...);
334 #endif /* !Py_LIMITED_API */
335 
336 /* Call a callable Python object 'callable' with a variable number of C
337    arguments. The C arguments are provided as PyObject* values, terminated
338    by a NULL.
339 
340    Returns the result of the call on success, or NULL on failure.
341 
342    This is the equivalent of the Python expression:
343    callable(arg1, arg2, ...). */
344 PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,
345                                                     ...);
346 
347 /* Call the method named 'name' of object 'obj' with a variable number of
348    C arguments.  The C arguments are provided as PyObject* values, terminated
349    by NULL.
350 
351    Returns the result of the call on success, or NULL on failure.
352 
353    This is the equivalent of the Python expression: obj.name(*args). */
354 
355 PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(
356     PyObject *obj,
357     PyObject *name,
358     ...);
359 
360 #ifndef Py_LIMITED_API
361 PyAPI_FUNC(PyObject *) _PyObject_CallMethodIdObjArgs(
362     PyObject *obj,
363     struct _Py_Identifier *name,
364     ...);
365 #endif /* !Py_LIMITED_API */
366 
367 
368 /* Implemented elsewhere:
369 
370    Py_hash_t PyObject_Hash(PyObject *o);
371 
372    Compute and return the hash, hash_value, of an object, o.  On
373    failure, return -1.
374 
375    This is the equivalent of the Python expression: hash(o). */
376 
377 
378 /* Implemented elsewhere:
379 
380    int PyObject_IsTrue(PyObject *o);
381 
382    Returns 1 if the object, o, is considered to be true, 0 if o is
383    considered to be false and -1 on failure.
384 
385    This is equivalent to the Python expression: not not o. */
386 
387 
388 /* Implemented elsewhere:
389 
390    int PyObject_Not(PyObject *o);
391 
392    Returns 0 if the object, o, is considered to be true, 1 if o is
393    considered to be false and -1 on failure.
394 
395    This is equivalent to the Python expression: not o. */
396 
397 
398 /* Get the type of an object.
399 
400    On success, returns a type object corresponding to the object type of object
401    'o'. On failure, returns NULL.
402 
403    This is equivalent to the Python expression: type(o) */
404 PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o);
405 
406 
407 /* Return the size of object 'o'.  If the object 'o' provides both sequence and
408    mapping protocols, the sequence size is returned.
409 
410    On error, -1 is returned.
411 
412    This is the equivalent to the Python expression: len(o) */
413 PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
414 
415 
416 /* For DLL compatibility */
417 #undef PyObject_Length
418 PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);
419 #define PyObject_Length PyObject_Size
420 
421 
422 #ifndef Py_LIMITED_API
423 PyAPI_FUNC(int) _PyObject_HasLen(PyObject *o);
424 
425 /* Guess the size of object 'o' using len(o) or o.__length_hint__().
426    If neither of those return a non-negative value, then return the default
427    value.  If one of the calls fails, this function returns -1. */
428 PyAPI_FUNC(Py_ssize_t) PyObject_LengthHint(PyObject *o, Py_ssize_t);
429 #endif
430 
431 /* Return element of 'o' corresponding to the object 'key'. Return NULL
432   on failure.
433 
434   This is the equivalent of the Python expression: o[key] */
435 PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
436 
437 
438 /* Map the object 'key' to the value 'v' into 'o'.
439 
440    Raise an exception and return -1 on failure; return 0 on success.
441 
442    This is the equivalent of the Python statement: o[key]=v. */
443 PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
444 
445 /* Remove the mapping for the string 'key' from the object 'o'.
446    Returns -1 on failure.
447 
448    This is equivalent to the Python statement: del o[key]. */
449 PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, const char *key);
450 
451 /* Delete the mapping for the object 'key' from the object 'o'.
452    Returns -1 on failure.
453 
454    This is the equivalent of the Python statement: del o[key]. */
455 PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
456 
457 
458 /* === Old Buffer API ============================================ */
459 
460 /* FIXME:  usage of these should all be replaced in Python itself
461    but for backwards compatibility we will implement them.
462    Their usage without a corresponding "unlock" mechanism
463    may create issues (but they would already be there). */
464 
465 /* Takes an arbitrary object which must support the (character, single segment)
466    buffer interface and returns a pointer to a read-only memory location
467    useable as character based input for subsequent processing.
468 
469    Return 0 on success.  buffer and buffer_len are only set in case no error
470    occurs. Otherwise, -1 is returned and an exception set. */
471 PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,
472                                       const char **buffer,
473                                       Py_ssize_t *buffer_len)
474                                       Py_DEPRECATED(3.0);
475 
476 /* Checks whether an arbitrary object supports the (character, single segment)
477    buffer interface.
478 
479    Returns 1 on success, 0 on failure. */
480 PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj)
481                                          Py_DEPRECATED(3.0);
482 
483 /* Same as PyObject_AsCharBuffer() except that this API expects (readable,
484    single segment) buffer interface and returns a pointer to a read-only memory
485    location which can contain arbitrary data.
486 
487    0 is returned on success.  buffer and buffer_len are only set in case no
488    error occurs.  Otherwise, -1 is returned and an exception set. */
489 PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,
490                                       const void **buffer,
491                                       Py_ssize_t *buffer_len)
492                                       Py_DEPRECATED(3.0);
493 
494 /* Takes an arbitrary object which must support the (writable, single segment)
495    buffer interface and returns a pointer to a writable memory location in
496    buffer of size 'buffer_len'.
497 
498    Return 0 on success.  buffer and buffer_len are only set in case no error
499    occurs. Otherwise, -1 is returned and an exception set. */
500 PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,
501                                        void **buffer,
502                                        Py_ssize_t *buffer_len)
503                                        Py_DEPRECATED(3.0);
504 
505 
506 /* === New Buffer API ============================================ */
507 
508 #ifndef Py_LIMITED_API
509 
510 /* Return 1 if the getbuffer function is available, otherwise return 0. */
511 #define PyObject_CheckBuffer(obj) \
512     (((obj)->ob_type->tp_as_buffer != NULL) &&  \
513      ((obj)->ob_type->tp_as_buffer->bf_getbuffer != NULL))
514 
515 /* This is a C-API version of the getbuffer function call.  It checks
516    to make sure object has the required function pointer and issues the
517    call.
518 
519    Returns -1 and raises an error on failure and returns 0 on success. */
520 PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view,
521                                    int flags);
522 
523 /* Get the memory area pointed to by the indices for the buffer given.
524    Note that view->ndim is the assumed size of indices. */
525 PyAPI_FUNC(void *) PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices);
526 
527 /* Return the implied itemsize of the data-format area from a
528    struct-style description. */
529 PyAPI_FUNC(int) PyBuffer_SizeFromFormat(const char *);
530 
531 /* Implementation in memoryobject.c */
532 PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, Py_buffer *view,
533                                       Py_ssize_t len, char order);
534 
535 PyAPI_FUNC(int) PyBuffer_FromContiguous(Py_buffer *view, void *buf,
536                                         Py_ssize_t len, char order);
537 
538 /* Copy len bytes of data from the contiguous chunk of memory
539    pointed to by buf into the buffer exported by obj.  Return
540    0 on success and return -1 and raise a PyBuffer_Error on
541    error (i.e. the object does not have a buffer interface or
542    it is not working).
543 
544    If fort is 'F', then if the object is multi-dimensional,
545    then the data will be copied into the array in
546    Fortran-style (first dimension varies the fastest).  If
547    fort is 'C', then the data will be copied into the array
548    in C-style (last dimension varies the fastest).  If fort
549    is 'A', then it does not matter and the copy will be made
550    in whatever way is more efficient. */
551 PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);
552 
553 /* Copy the data from the src buffer to the buffer of destination. */
554 PyAPI_FUNC(int) PyBuffer_IsContiguous(const Py_buffer *view, char fort);
555 
556 /*Fill the strides array with byte-strides of a contiguous
557   (Fortran-style if fort is 'F' or C-style otherwise)
558   array of the given shape with the given number of bytes
559   per element. */
560 PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims,
561                                                Py_ssize_t *shape,
562                                                Py_ssize_t *strides,
563                                                int itemsize,
564                                                char fort);
565 
566 /* Fills in a buffer-info structure correctly for an exporter
567    that can only share a contiguous chunk of memory of
568    "unsigned bytes" of the given length.
569 
570    Returns 0 on success and -1 (with raising an error) on error. */
571 PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf,
572                                   Py_ssize_t len, int readonly,
573                                   int flags);
574 
575 /* Releases a Py_buffer obtained from getbuffer ParseTuple's "s*". */
576 PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);
577 
578 #endif /* Py_LIMITED_API */
579 
580 /* Takes an arbitrary object and returns the result of calling
581    obj.__format__(format_spec). */
582 PyAPI_FUNC(PyObject *) PyObject_Format(PyObject *obj,
583                                        PyObject *format_spec);
584 
585 
586 /* ==== Iterators ================================================ */
587 
588 /* Takes an object and returns an iterator for it.
589    This is typically a new iterator but if the argument is an iterator, this
590    returns itself. */
591 PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);
592 
593 #define PyIter_Check(obj) \
594     ((obj)->ob_type->tp_iternext != NULL && \
595      (obj)->ob_type->tp_iternext != &_PyObject_NextNotImplemented)
596 
597 /* Takes an iterator object and calls its tp_iternext slot,
598    returning the next value.
599 
600    If the iterator is exhausted, this returns NULL without setting an
601    exception.
602 
603    NULL with an exception means an error occurred. */
604 PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);
605 
606 
607 /* === Number Protocol ================================================== */
608 
609 /* Returns 1 if the object 'o' provides numeric protocols, and 0 otherwise.
610 
611    This function always succeeds. */
612 PyAPI_FUNC(int) PyNumber_Check(PyObject *o);
613 
614 /* Returns the result of adding o1 and o2, or NULL on failure.
615 
616    This is the equivalent of the Python expression: o1 + o2. */
617 PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);
618 
619 /* Returns the result of subtracting o2 from o1, or NULL on failure.
620 
621    This is the equivalent of the Python expression: o1 - o2. */
622 PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2);
623 
624 /* Returns the result of multiplying o1 and o2, or NULL on failure.
625 
626    This is the equivalent of the Python expression: o1 * o2. */
627 PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2);
628 
629 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
630 /* This is the equivalent of the Python expression: o1 @ o2. */
631 PyAPI_FUNC(PyObject *) PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2);
632 #endif
633 
634 /* Returns the result of dividing o1 by o2 giving an integral result,
635    or NULL on failure.
636 
637    This is the equivalent of the Python expression: o1 // o2. */
638 PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2);
639 
640 /* Returns the result of dividing o1 by o2 giving a float result, or NULL on
641    failure.
642 
643    This is the equivalent of the Python expression: o1 / o2. */
644 PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2);
645 
646 /* Returns the remainder of dividing o1 by o2, or NULL on failure.
647 
648    This is the equivalent of the Python expression: o1 % o2. */
649 PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);
650 
651 /* See the built-in function divmod.
652 
653    Returns NULL on failure.
654 
655    This is the equivalent of the Python expression: divmod(o1, o2). */
656 PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);
657 
658 /* See the built-in function pow. Returns NULL on failure.
659 
660    This is the equivalent of the Python expression: pow(o1, o2, o3),
661    where o3 is optional. */
662 PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,
663                                       PyObject *o3);
664 
665 /* Returns the negation of o on success, or NULL on failure.
666 
667  This is the equivalent of the Python expression: -o. */
668 PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o);
669 
670 /* Returns the positive of o on success, or NULL on failure.
671 
672    This is the equivalent of the Python expression: +o. */
673 PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o);
674 
675 /* Returns the absolute value of 'o', or NULL on failure.
676 
677    This is the equivalent of the Python expression: abs(o). */
678 PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o);
679 
680 /* Returns the bitwise negation of 'o' on success, or NULL on failure.
681 
682    This is the equivalent of the Python expression: ~o. */
683 PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o);
684 
685 /* Returns the result of left shifting o1 by o2 on success, or NULL on failure.
686 
687    This is the equivalent of the Python expression: o1 << o2. */
688 PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);
689 
690 /* Returns the result of right shifting o1 by o2 on success, or NULL on
691    failure.
692 
693    This is the equivalent of the Python expression: o1 >> o2. */
694 PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);
695 
696 /* Returns the result of bitwise and of o1 and o2 on success, or NULL on
697    failure.
698 
699    This is the equivalent of the Python expression: o1 & o2. */
700 PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);
701 
702 /* Returns the bitwise exclusive or of o1 by o2 on success, or NULL on failure.
703 
704    This is the equivalent of the Python expression: o1 ^ o2. */
705 PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);
706 
707 /* Returns the result of bitwise or on o1 and o2 on success, or NULL on
708    failure.
709 
710    This is the equivalent of the Python expression: o1 | o2. */
711 PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);
712 
713 #define PyIndex_Check(obj)                              \
714     ((obj)->ob_type->tp_as_number != NULL &&            \
715      (obj)->ob_type->tp_as_number->nb_index != NULL)
716 
717 /* Returns the object 'o' converted to a Python int, or NULL with an exception
718    raised on failure. */
719 PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o);
720 
721 /* Returns the object 'o' converted to Py_ssize_t by going through
722    PyNumber_Index() first.
723 
724    If an overflow error occurs while converting the int to Py_ssize_t, then the
725    second argument 'exc' is the error-type to return.  If it is NULL, then the
726    overflow error is cleared and the value is clipped. */
727 PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc);
728 
729 /* Returns the object 'o' converted to an integer object on success, or NULL
730    on failure.
731 
732    This is the equivalent of the Python expression: int(o). */
733 PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);
734 
735 /* Returns the object 'o' converted to a float object on success, or NULL
736   on failure.
737 
738   This is the equivalent of the Python expression: float(o). */
739 PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);
740 
741 
742 /* --- In-place variants of (some of) the above number protocol functions -- */
743 
744 /* Returns the result of adding o2 to o1, possibly in-place, or NULL
745    on failure.
746 
747    This is the equivalent of the Python expression: o1 += o2. */
748 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);
749 
750 /* Returns the result of subtracting o2 from o1, possibly in-place or
751    NULL on failure.
752 
753    This is the equivalent of the Python expression: o1 -= o2. */
754 PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);
755 
756 /* Returns the result of multiplying o1 by o2, possibly in-place, or NULL on
757    failure.
758 
759    This is the equivalent of the Python expression: o1 *= o2. */
760 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);
761 
762 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
763 /* This is the equivalent of the Python expression: o1 @= o2. */
764 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2);
765 #endif
766 
767 /* Returns the result of dividing o1 by o2 giving an integral result, possibly
768    in-place, or NULL on failure.
769 
770    This is the equivalent of the Python expression: o1 /= o2. */
771 PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1,
772                                                    PyObject *o2);
773 
774 /* Returns the result of dividing o1 by o2 giving a float result, possibly
775    in-place, or null on failure.
776 
777    This is the equivalent of the Python expression: o1 /= o2. */
778 PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1,
779                                                   PyObject *o2);
780 
781 /* Returns the remainder of dividing o1 by o2, possibly in-place, or NULL on
782    failure.
783 
784    This is the equivalent of the Python expression: o1 %= o2. */
785 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);
786 
787 /* Returns the result of raising o1 to the power of o2, possibly in-place,
788    or NULL on failure.
789 
790    This is the equivalent of the Python expression: o1 **= o2,
791    or o1 = pow(o1, o2, o3) if o3 is present. */
792 PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,
793                                              PyObject *o3);
794 
795 /* Returns the result of left shifting o1 by o2, possibly in-place, or NULL
796    on failure.
797 
798    This is the equivalent of the Python expression: o1 <<= o2. */
799 PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);
800 
801 /* Returns the result of right shifting o1 by o2, possibly in-place or NULL
802    on failure.
803 
804    This is the equivalent of the Python expression: o1 >>= o2. */
805 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);
806 
807 /* Returns the result of bitwise and of o1 and o2, possibly in-place, or NULL
808    on failure.
809 
810    This is the equivalent of the Python expression: o1 &= o2. */
811 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);
812 
813 /* Returns the bitwise exclusive or of o1 by o2, possibly in-place, or NULL
814    on failure.
815 
816    This is the equivalent of the Python expression: o1 ^= o2. */
817 PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);
818 
819 /* Returns the result of bitwise or of o1 and o2, possibly in-place,
820    or NULL on failure.
821 
822    This is the equivalent of the Python expression: o1 |= o2. */
823 PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);
824 
825 /* Returns the integer n converted to a string with a base, with a base
826    marker of 0b, 0o or 0x prefixed if applicable.
827 
828    If n is not an int object, it is converted with PyNumber_Index first. */
829 PyAPI_FUNC(PyObject *) PyNumber_ToBase(PyObject *n, int base);
830 
831 
832 /* === Sequence protocol ================================================ */
833 
834 /* Return 1 if the object provides sequence protocol, and zero
835    otherwise.
836 
837    This function always succeeds. */
838 PyAPI_FUNC(int) PySequence_Check(PyObject *o);
839 
840 /* Return the size of sequence object o, or -1 on failure. */
841 PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
842 
843 /* For DLL compatibility */
844 #undef PySequence_Length
845 PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);
846 #define PySequence_Length PySequence_Size
847 
848 
849 /* Return the concatenation of o1 and o2 on success, and NULL on failure.
850 
851    This is the equivalent of the Python expression: o1 + o2. */
852 PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);
853 
854 /* Return the result of repeating sequence object 'o' 'count' times,
855   or NULL on failure.
856 
857   This is the equivalent of the Python expression: o * count. */
858 PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count);
859 
860 /* Return the ith element of o, or NULL on failure.
861 
862    This is the equivalent of the Python expression: o[i]. */
863 PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i);
864 
865 /* Return the slice of sequence object o between i1 and i2, or NULL on failure.
866 
867    This is the equivalent of the Python expression: o[i1:i2]. */
868 PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
869 
870 /* Assign object 'v' to the ith element of the sequence 'o'. Raise an exception
871    and return -1 on failure; return 0 on success.
872 
873    This is the equivalent of the Python statement o[i] = v. */
874 PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);
875 
876 /* Delete the 'i'-th element of the sequence 'v'. Returns -1 on failure.
877 
878    This is the equivalent of the Python statement: del o[i]. */
879 PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
880 
881 /* Assign the sequence object 'v' to the slice in sequence object 'o',
882    from 'i1' to 'i2'. Returns -1 on failure.
883 
884    This is the equivalent of the Python statement: o[i1:i2] = v. */
885 PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2,
886                                     PyObject *v);
887 
888 /* Delete the slice in sequence object 'o' from 'i1' to 'i2'.
889    Returns -1 on failure.
890 
891    This is the equivalent of the Python statement: del o[i1:i2]. */
892 PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
893 
894 /* Returns the sequence 'o' as a tuple on success, and NULL on failure.
895 
896    This is equivalent to the Python expression: tuple(o). */
897 PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);
898 
899 /* Returns the sequence 'o' as a list on success, and NULL on failure.
900    This is equivalent to the Python expression: list(o) */
901 PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);
902 
903 /* Return the sequence 'o' as a list, unless it's already a tuple or list.
904 
905    Use PySequence_Fast_GET_ITEM to access the members of this list, and
906    PySequence_Fast_GET_SIZE to get its length.
907 
908    Returns NULL on failure.  If the object does not support iteration, raises a
909    TypeError exception with 'm' as the message text. */
910 PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
911 
912 /* Return the size of the sequence 'o', assuming that 'o' was returned by
913    PySequence_Fast and is not NULL. */
914 #define PySequence_Fast_GET_SIZE(o) \
915     (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o))
916 
917 /* Return the 'i'-th element of the sequence 'o', assuming that o was returned
918    by PySequence_Fast, and that i is within bounds. */
919 #define PySequence_Fast_GET_ITEM(o, i)\
920      (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i))
921 
922 /* Assume tp_as_sequence and sq_item exist and that 'i' does not
923    need to be corrected for a negative index. */
924 #define PySequence_ITEM(o, i)\
925     ( Py_TYPE(o)->tp_as_sequence->sq_item(o, i) )
926 
927 /* Return a pointer to the underlying item array for
928    an object retured by PySequence_Fast */
929 #define PySequence_Fast_ITEMS(sf) \
930     (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \
931                       : ((PyTupleObject *)(sf))->ob_item)
932 
933 /* Return the number of occurrences on value on 'o', that is, return
934    the number of keys for which o[key] == value.
935 
936    On failure, return -1.  This is equivalent to the Python expression:
937    o.count(value). */
938 PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value);
939 
940 /* Return 1 if 'ob' is in the sequence 'seq'; 0 if 'ob' is not in the sequence
941    'seq'; -1 on error.
942 
943    Use __contains__ if possible, else _PySequence_IterSearch(). */
944 PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob);
945 
946 #ifndef Py_LIMITED_API
947 #define PY_ITERSEARCH_COUNT    1
948 #define PY_ITERSEARCH_INDEX    2
949 #define PY_ITERSEARCH_CONTAINS 3
950 
951 /* Iterate over seq.
952 
953    Result depends on the operation:
954 
955    PY_ITERSEARCH_COUNT:  return # of times obj appears in seq; -1 if
956      error.
957    PY_ITERSEARCH_INDEX:  return 0-based index of first occurrence of
958      obj in seq; set ValueError and return -1 if none found;
959      also return -1 on error.
960    PY_ITERSEARCH_CONTAINS:  return 1 if obj in seq, else 0; -1 on
961      error. */
962 PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq,
963                                               PyObject *obj, int operation);
964 #endif
965 
966 
967 /* For DLL-level backwards compatibility */
968 #undef PySequence_In
969 /* Determine if the sequence 'o' contains 'value'. If an item in 'o' is equal
970    to 'value', return 1, otherwise return 0. On error, return -1.
971 
972    This is equivalent to the Python expression: value in o. */
973 PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value);
974 
975 /* For source-level backwards compatibility */
976 #define PySequence_In PySequence_Contains
977 
978 
979 /* Return the first index for which o[i] == value.
980    On error, return -1.
981 
982    This is equivalent to the Python expression: o.index(value). */
983 PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value);
984 
985 
986 /* --- In-place versions of some of the above Sequence functions --- */
987 
988 /* Append sequence 'o2' to sequence 'o1', in-place when possible. Return the
989    resulting object, which could be 'o1', or NULL on failure.
990 
991   This is the equivalent of the Python expression: o1 += o2. */
992 PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);
993 
994 /* Repeat sequence 'o' by 'count', in-place when possible. Return the resulting
995    object, which could be 'o', or NULL on failure.
996 
997    This is the equivalent of the Python expression: o1 *= count.  */
998 PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count);
999 
1000 
1001 /* === Mapping protocol ================================================= */
1002 
1003 /* Return 1 if the object provides mapping protocol, and 0 otherwise.
1004 
1005    This function always succeeds. */
1006 PyAPI_FUNC(int) PyMapping_Check(PyObject *o);
1007 
1008 /* Returns the number of keys in mapping object 'o' on success, and -1 on
1009   failure. This is equivalent to the Python expression: len(o). */
1010 PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
1011 
1012 /* For DLL compatibility */
1013 #undef PyMapping_Length
1014 PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
1015 #define PyMapping_Length PyMapping_Size
1016 
1017 
1018 /* Implemented as a macro:
1019 
1020    int PyMapping_DelItemString(PyObject *o, const char *key);
1021 
1022    Remove the mapping for the string 'key' from the mapping 'o'. Returns -1 on
1023    failure.
1024 
1025    This is equivalent to the Python statement: del o[key]. */
1026 #define PyMapping_DelItemString(O,K) PyObject_DelItemString((O),(K))
1027 
1028 /* Implemented as a macro:
1029 
1030    int PyMapping_DelItem(PyObject *o, PyObject *key);
1031 
1032    Remove the mapping for the object 'key' from the mapping object 'o'.
1033    Returns -1 on failure.
1034 
1035    This is equivalent to the Python statement: del o[key]. */
1036 #define PyMapping_DelItem(O,K) PyObject_DelItem((O),(K))
1037 
1038 /* On success, return 1 if the mapping object 'o' has the key 'key',
1039    and 0 otherwise.
1040 
1041    This is equivalent to the Python expression: key in o.
1042 
1043    This function always succeeds. */
1044 PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, const char *key);
1045 
1046 /* Return 1 if the mapping object has the key 'key', and 0 otherwise.
1047 
1048    This is equivalent to the Python expression: key in o.
1049 
1050    This function always succeeds. */
1051 PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key);
1052 
1053 /* On success, return a list or tuple of the keys in mapping object 'o'.
1054    On failure, return NULL. */
1055 PyAPI_FUNC(PyObject *) PyMapping_Keys(PyObject *o);
1056 
1057 /* On success, return a list or tuple of the values in mapping object 'o'.
1058    On failure, return NULL. */
1059 PyAPI_FUNC(PyObject *) PyMapping_Values(PyObject *o);
1060 
1061 /* On success, return a list or tuple of the items in mapping object 'o',
1062    where each item is a tuple containing a key-value pair. On failure, return
1063    NULL. */
1064 PyAPI_FUNC(PyObject *) PyMapping_Items(PyObject *o);
1065 
1066 /* Return element of 'o' corresponding to the string 'key' or NULL on failure.
1067 
1068    This is the equivalent of the Python expression: o[key]. */
1069 PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o,
1070                                                const char *key);
1071 
1072 /* Map the string 'key' to the value 'v' in the mapping 'o'.
1073    Returns -1 on failure.
1074 
1075    This is the equivalent of the Python statement: o[key]=v. */
1076 PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, const char *key,
1077                                         PyObject *value);
1078 
1079 /* isinstance(object, typeorclass) */
1080 PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
1081 
1082 /* issubclass(object, typeorclass) */
1083 PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass);
1084 
1085 
1086 #ifndef Py_LIMITED_API
1087 PyAPI_FUNC(int) _PyObject_RealIsInstance(PyObject *inst, PyObject *cls);
1088 
1089 PyAPI_FUNC(int) _PyObject_RealIsSubclass(PyObject *derived, PyObject *cls);
1090 
1091 PyAPI_FUNC(char *const *) _PySequence_BytesToCharpArray(PyObject* self);
1092 
1093 PyAPI_FUNC(void) _Py_FreeCharPArray(char *const array[]);
1094 
1095 /* For internal use by buffer API functions */
1096 PyAPI_FUNC(void) _Py_add_one_to_index_F(int nd, Py_ssize_t *index,
1097                                         const Py_ssize_t *shape);
1098 PyAPI_FUNC(void) _Py_add_one_to_index_C(int nd, Py_ssize_t *index,
1099                                         const Py_ssize_t *shape);
1100 
1101 /* Convert Python int to Py_ssize_t. Do nothing if the argument is None. */
1102 PyAPI_FUNC(int) _Py_convert_optional_to_ssize_t(PyObject *, void *);
1103 #endif /* !Py_LIMITED_API */
1104 
1105 
1106 #ifdef __cplusplus
1107 }
1108 #endif
1109 #endif /* Py_ABSTRACTOBJECT_H */
1110