abstract.h 41.6 KB
Newer Older
1 2 3 4 5 6
#ifndef Py_ABSTRACTOBJECT_H
#define Py_ABSTRACTOBJECT_H
#ifdef __cplusplus
extern "C" {
#endif

7 8 9
#ifdef PY_SSIZE_T_CLEAN
#define PyObject_CallFunction _PyObject_CallFunction_SizeT
#define PyObject_CallMethod _PyObject_CallMethod_SizeT
10
#define _PyObject_CallMethodId _PyObject_CallMethodId_SizeT
11 12
#endif

13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
/* Abstract Object Interface (many thanks to Jim Fulton) */

/*
   PROPOSAL: A Generic Python Object Interface for Python C Modules

Problem

  Python modules written in C that must access Python objects must do
  so through routines whose interfaces are described by a set of
  include files.  Unfortunately, these routines vary according to the
  object accessed.  To use these routines, the C programmer must check
  the type of the object being used and must call a routine based on
  the object type.  For example, to access an element of a sequence,
  the programmer must determine whether the sequence is a list or a
  tuple:

    if(is_tupleobject(o))
      e=gettupleitem(o,i)
    else if(is_listitem(o))
      e=getlistitem(o,i)

  If the programmer wants to get an item from another type of object
  that provides sequence behavior, there is no clear way to do it
36
  correctly.
37 38 39 40 41 42 43 44 45 46 47

  The persistent programmer may peruse object.h and find that the
  _typeobject structure provides a means of invoking up to (currently
  about) 41 special operators.  So, for example, a routine can get an
  item from any object that provides sequence behavior. However, to
  use this mechanism, the programmer must make their code dependent on
  the current Python implementation.

  Also, certain semantics, especially memory management semantics, may
  differ by the type of object being used.  Unfortunately, these
  semantics are not clearly described in the current include files.
48
  An abstract interface providing more consistent semantics is needed.
49 50 51 52 53 54 55 56

Proposal

  I propose the creation of a standard interface (with an associated
  library of routines and/or macros) for generically obtaining the
  services of Python objects.  This proposal can be viewed as one
  components of a Python C interface consisting of several components.

57
  From the viewpoint of C access to Python services, we have (as
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
  suggested by Guido in off-line discussions):

  - "Very high level layer": two or three functions that let you exec or
    eval arbitrary Python code given as a string in a module whose name is
    given, passing C values in and getting C values out using
    mkvalue/getargs style format strings.  This does not require the user
    to declare any variables of type "PyObject *".  This should be enough
    to write a simple application that gets Python code from the user,
    execs it, and returns the output or errors.  (Error handling must also
    be part of this API.)

  - "Abstract objects layer": which is the subject of this proposal.
    It has many functions operating on objects, and lest you do many
    things from C that you can also write in Python, without going
    through the Python parser.

  - "Concrete objects layer": This is the public type-dependent
    interface provided by the standard built-in types, such as floats,
    strings, and lists.  This interface exists and is currently
77
    documented by the collection of include files provided with the
78 79 80
    Python distributions.

  From the point of view of Python accessing services provided by C
81
  modules:
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136

  - "Python module interface": this interface consist of the basic
    routines used to define modules and their members.  Most of the
    current extensions-writing guide deals with this interface.

  - "Built-in object interface": this is the interface that a new
    built-in type must provide and the mechanisms and rules that a
    developer of a new built-in type must use and follow.

  This proposal is a "first-cut" that is intended to spur
  discussion. See especially the lists of notes.

  The Python C object interface will provide four protocols: object,
  numeric, sequence, and mapping.  Each protocol consists of a
  collection of related operations.  If an operation that is not
  provided by a particular type is invoked, then a standard exception,
  NotImplementedError is raised with a operation name as an argument.
  In addition, for convenience this interface defines a set of
  constructors for building objects of built-in types.  This is needed
  so new objects can be returned from C functions that otherwise treat
  objects generically.

Memory Management

  For all of the functions described in this proposal, if a function
  retains a reference to a Python object passed as an argument, then the
  function will increase the reference count of the object.  It is
  unnecessary for the caller to increase the reference count of an
  argument in anticipation of the object's retention.

  All Python objects returned from functions should be treated as new
  objects.  Functions that return objects assume that the caller will
  retain a reference and the reference count of the object has already
  been incremented to account for this fact.  A caller that does not
  retain a reference to an object that is returned from a function
  must decrement the reference count of the object (using
  DECREF(object)) to prevent memory leaks.

  Note that the behavior mentioned here is different from the current
  behavior for some objects (e.g. lists and tuples) when certain
  type-specific routines are called directly (e.g. setlistitem).  The
  proposed abstraction layer will provide a consistent memory
  management interface, correcting for inconsistent behavior for some
  built-in types.

Protocols

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/

/*  Object Protocol: */

     /* Implemented elsewhere:

     int PyObject_Print(PyObject *o, FILE *fp, int flags);

137 138 139
     Print an object, o, on file, fp.  Returns -1 on
     error.  The flags argument is used to enable certain printing
     options. The only option currently supported is Py_Print_RAW.
140

141
     (What should be said about Py_Print_RAW?)
142 143 144 145 146 147 148

       */

     /* Implemented elsewhere:

     int PyObject_HasAttrString(PyObject *o, char *attr_name);

149 150 151
     Returns 1 if o has the attribute attr_name, and 0 otherwise.
     This is equivalent to the Python expression:
     hasattr(o,attr_name).
152

153
     This function always succeeds.
154 155 156 157 158 159 160

       */

     /* Implemented elsewhere:

     PyObject* PyObject_GetAttrString(PyObject *o, char *attr_name);

161 162 163
     Retrieve an attributed named attr_name form object o.
     Returns the attribute value on success, or NULL on failure.
     This is the equivalent of the Python expression: o.attr_name.
164 165 166 167 168 169 170

       */

     /* Implemented elsewhere:

     int PyObject_HasAttr(PyObject *o, PyObject *attr_name);

171 172 173
     Returns 1 if o has the attribute attr_name, and 0 otherwise.
     This is equivalent to the Python expression:
     hasattr(o,attr_name).
174

175
     This function always succeeds.
176 177 178 179 180 181 182

       */

     /* Implemented elsewhere:

     PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name);

183 184 185
     Retrieve an attributed named attr_name form object o.
     Returns the attribute value on success, or NULL on failure.
     This is the equivalent of the Python expression: o.attr_name.
186 187 188 189 190 191 192 193

       */


     /* Implemented elsewhere:

     int PyObject_SetAttrString(PyObject *o, char *attr_name, PyObject *v);

194 195 196
     Set the value of the attribute named attr_name, for object o,
     to the value, v. Returns -1 on failure.  This is
     the equivalent of the Python statement: o.attr_name=v.
197 198 199 200 201 202 203

       */

     /* Implemented elsewhere:

     int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v);

204 205 206
     Set the value of the attribute named attr_name, for object o,
     to the value, v. Returns -1 on failure.  This is
     the equivalent of the Python statement: o.attr_name=v.
207 208 209 210 211 212 213

       */

     /* implemented as a macro:

     int PyObject_DelAttrString(PyObject *o, char *attr_name);

214 215 216
     Delete attribute named attr_name, for object o. Returns
     -1 on failure.  This is the equivalent of the Python
     statement: del o.attr_name.
217 218 219 220 221 222 223 224

       */
#define  PyObject_DelAttrString(O,A) PyObject_SetAttrString((O),(A),NULL)

     /* implemented as a macro:

     int PyObject_DelAttr(PyObject *o, PyObject *attr_name);

225 226 227
     Delete attribute named attr_name, for object o. Returns -1
     on failure.  This is the equivalent of the Python
     statement: del o.attr_name.
228 229 230 231 232 233 234 235

       */
#define  PyObject_DelAttr(O,A) PyObject_SetAttr((O),(A),NULL)

     /* Implemented elsewhere:

     PyObject *PyObject_Repr(PyObject *o);

236 237 238
     Compute the string representation of object, o.  Returns the
     string representation on success, NULL on failure.  This is
     the equivalent of the Python expression: repr(o).
239

240
     Called by the repr() built-in function.
241 242 243 244 245 246 247

       */

     /* Implemented elsewhere:

     PyObject *PyObject_Str(PyObject *o);

248 249 250
     Compute the string representation of object, o.  Returns the
     string representation on success, NULL on failure.  This is
     the equivalent of the Python expression: str(o).)
251

252
     Called by the str() and print() built-in functions.
253 254 255

       */

256 257
       /* Declared elsewhere

258
     PyAPI_FUNC(int) PyCallable_Check(PyObject *o);
259

260 261
     Determine if the object, o, is callable.  Return 1 if the
     object is callable and 0 otherwise.
262

263
     This function always succeeds.
264 265
       */

266
     PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable_object,
267
                                          PyObject *args, PyObject *kw);
268 269

       /*
270 271 272
     Call a callable Python object, callable_object, with
     arguments and keywords arguments.  The 'args' argument can not be
     NULL, but the 'kw' argument can be NULL.
273
       */
274

275
     PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable_object,
276
                                                PyObject *args);
277 278

       /*
279 280 281 282 283
     Call a callable Python object, callable_object, with
     arguments given by the tuple, args.  If no arguments are
     needed, then args may be NULL.  Returns the result of the
     call on success, or NULL on failure.  This is the equivalent
     of the Python expression: o(*args).
284 285
       */

286
     PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable_object,
287
                                                  char *format, ...);
288 289

       /*
290 291 292 293 294 295
     Call a callable Python object, callable_object, with a
     variable number of C arguments. The C arguments are described
     using a mkvalue-style format string. The format may be NULL,
     indicating that no arguments are provided.  Returns the
     result of the call on success, or NULL on failure.  This is
     the equivalent of the Python expression: o(*args).
296 297 298
       */


299 300
     PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *o, char *method,
                                                char *format, ...);
301 302

       /*
303 304 305 306 307 308
     Call the method named m of object o with a variable number of
     C arguments.  The C arguments are described by a mkvalue
     format string.  The format may be NULL, indicating that no
     arguments are provided. Returns the result of the call on
     success, or NULL on failure.  This is the equivalent of the
     Python expression: o.method(args).
309 310
       */

311 312 313 314 315 316 317 318
     PyAPI_FUNC(PyObject *) _PyObject_CallMethodId(PyObject *o, _Py_Identifier *method,
                                                  char *format, ...);

       /*
         Like PyObject_CallMethod, but expect a _Py_Identifier* as the
         method name.
       */

319
     PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,
320
                                                         char *format, ...);
321
     PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *o,
322 323
                                                       char *name,
                                                       char *format, ...);
324 325 326
     PyAPI_FUNC(PyObject *) _PyObject_CallMethodId_SizeT(PyObject *o,
                                                       _Py_Identifier *name,
                                                       char *format, ...);
327

328
     PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,
329
                                                         ...);
330 331

       /*
332 333 334 335 336
     Call a callable Python object, callable_object, with a
     variable number of C arguments.  The C arguments are provided
     as PyObject * values, terminated by a NULL.  Returns the
     result of the call on success, or NULL on failure.  This is
     the equivalent of the Python expression: o(*args).
337
       */
338 339


340
     PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(PyObject *o,
341
                                                       PyObject *method, ...);
342 343 344 345
     PyAPI_FUNC(PyObject *) _PyObject_CallMethodObjIdArgs(PyObject *o,
                                               struct _Py_Identifier *method,
                                               ...);

346 347

       /*
348 349 350 351 352
     Call the method named m of object o with a variable number of
     C arguments.  The C arguments are provided as PyObject *
     values, terminated by NULL.  Returns the result of the call
     on success, or NULL on failure.  This is the equivalent of
     the Python expression: o.method(args).
353 354 355 356 357 358 359
       */


     /* Implemented elsewhere:

     long PyObject_Hash(PyObject *o);

360 361 362
     Compute and return the hash, hash_value, of an object, o.  On
     failure, return -1.  This is the equivalent of the Python
     expression: hash(o).
363 364 365 366 367 368 369
       */


     /* Implemented elsewhere:

     int PyObject_IsTrue(PyObject *o);

370 371 372
     Returns 1 if the object, o, is considered to be true, 0 if o is
     considered to be false and -1 on failure. This is equivalent to the
     Python expression: not not o
373 374
       */

Guido van Rossum's avatar
Guido van Rossum committed
375 376 377 378
     /* Implemented elsewhere:

     int PyObject_Not(PyObject *o);

379 380 381
     Returns 0 if the object, o, is considered to be true, 1 if o is
     considered to be false and -1 on failure. This is equivalent to the
     Python expression: not o
Guido van Rossum's avatar
Guido van Rossum committed
382 383
       */

384
     PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o);
385 386

       /*
387 388 389
     On success, returns a type object corresponding to the object
     type of object o. On failure, returns NULL.  This is
     equivalent to the Python expression: type(o).
390 391
       */

Martin v. Löwis's avatar
Martin v. Löwis committed
392
     PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
393

394
       /*
395 396 397 398
     Return the size of object o.  If the object, o, provides
     both sequence and mapping protocols, the sequence size is
     returned. On error, -1 is returned.  This is the equivalent
     to the Python expression: len(o).
399 400
       */

401 402
       /* For DLL compatibility */
#undef PyObject_Length
Martin v. Löwis's avatar
Martin v. Löwis committed
403
     PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);
404 405
#define PyObject_Length PyObject_Size

406 407
PyAPI_FUNC(int) _PyObject_HasLen(PyObject *o);
PyAPI_FUNC(Py_ssize_t) PyObject_LengthHint(PyObject *o, Py_ssize_t);
408 409

       /*
410 411 412
     Guess the size of object o using len(o) or o.__length_hint__().
     If neither of those return a non-negative value, then return the
     default value.  If one of the calls fails, this function returns -1.
413
       */
414

415
     PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
416 417

       /*
418 419 420
     Return element of o corresponding to the object, key, or NULL
     on failure. This is the equivalent of the Python expression:
     o[key].
421 422
       */

423
     PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
424 425

       /*
426 427 428
     Map the object, key, to the value, v.  Returns
     -1 on failure.  This is the equivalent of the Python
     statement: o[key]=v.
429 430
       */

431
     PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, char *key);
432 433

       /*
434 435 436
     Remove the mapping for object, key, from the object *o.
     Returns -1 on failure.  This is equivalent to
     the Python statement: del o[key].
437 438
       */

439
     PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
440 441

       /*
442 443
     Delete the mapping for key from *o.  Returns -1 on failure.
     This is the equivalent of the Python statement: del o[key].
444 445
       */

446 447 448 449 450
    /* old buffer API
       FIXME:  usage of these should all be replaced in Python itself
       but for backwards compatibility we will implement them.
       Their usage without a corresponding "unlock" mechansim
       may create issues (but they would already be there). */
451

452
     PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,
453 454
                                           const char **buffer,
                                           Py_ssize_t *buffer_len);
455

456 457 458 459 460
       /*
      Takes an arbitrary object which must support the (character,
      single segment) buffer interface and returns a pointer to a
      read-only memory location useable as character based input
      for subsequent processing.
461

462 463 464
      0 is returned on success.  buffer and buffer_len are only
      set in case no error occurs. Otherwise, -1 is returned and
      an exception set.
465 466
       */

467
     PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);
468

469 470 471 472
      /*
      Checks whether an arbitrary object supports the (character,
      single segment) buffer interface.  Returns 1 on success, 0
      on failure.
473 474
      */

475
     PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,
476 477
                                           const void **buffer,
                                           Py_ssize_t *buffer_len);
478

479 480 481 482 483
       /*
      Same as PyObject_AsCharBuffer() except that this API expects
      (readable, single segment) buffer interface and returns a
      pointer to a read-only memory location which can contain
      arbitrary data.
484

485
      0 is returned on success.  buffer and buffer_len are only
486
      set in case no error occurs.  Otherwise, -1 is returned and
487
      an exception set.
488 489
       */

490
     PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,
491 492
                                            void **buffer,
                                            Py_ssize_t *buffer_len);
493

494 495 496 497
       /*
      Takes an arbitrary object which must support the (writable,
      single segment) buffer interface and returns a pointer to a
      writable memory location in buffer of size buffer_len.
498

499
      0 is returned on success.  buffer and buffer_len are only
500
      set in case no error occurs. Otherwise, -1 is returned and
501
      an exception set.
502
       */
503

504
    /* new buffer API */
505

506
#ifndef Py_LIMITED_API
507
#define PyObject_CheckBuffer(obj) \
508 509
    (((obj)->ob_type->tp_as_buffer != NULL) &&  \
     ((obj)->ob_type->tp_as_buffer->bf_getbuffer != NULL))
510

511 512
    /* Return 1 if the getbuffer function is available, otherwise
       return 0 */
513

514 515
     PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view,
                                        int flags);
516

517 518 519 520 521
    /* This is a C-API version of the getbuffer function call.  It checks
       to make sure object has the required function pointer and issues the
       call.  Returns -1 and raises an error on failure and returns 0 on
       success
    */
522 523


524
     PyAPI_FUNC(void *) PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices);
525 526 527 528

    /* Get the memory area pointed to by the indices for the buffer given.
       Note that view->ndim is the assumed size of indices
    */
529 530 531

     PyAPI_FUNC(int) PyBuffer_SizeFromFormat(const char *);

532 533 534 535 536
    /* Return the implied itemsize of the data-format area from a
       struct-style description */



537
     /* Implementation in memoryobject.c */
538
     PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, Py_buffer *view,
539
                                           Py_ssize_t len, char order);
540

541
     PyAPI_FUNC(int) PyBuffer_FromContiguous(Py_buffer *view, void *buf,
542
                                             Py_ssize_t len, char order);
543 544


545 546 547 548 549
    /* Copy len bytes of data from the contiguous chunk of memory
       pointed to by buf into the buffer exported by obj.  Return
       0 on success and return -1 and raise a PyBuffer_Error on
       error (i.e. the object does not have a buffer interface or
       it is not working).
550

551 552 553 554 555 556 557
       If fort is 'F', then if the object is multi-dimensional,
       then the data will be copied into the array in
       Fortran-style (first dimension varies the fastest).  If
       fort is 'C', then the data will be copied into the array
       in C-style (last dimension varies the fastest).  If fort
       is 'A', then it does not matter and the copy will be made
       in whatever way is more efficient.
558

559
    */
560 561

     PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);
562 563 564

    /* Copy the data from the src buffer to the buffer of destination
     */
565

566
     PyAPI_FUNC(int) PyBuffer_IsContiguous(const Py_buffer *view, char fort);
567 568


569 570 571 572 573
     PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims,
                                                    Py_ssize_t *shape,
                                                    Py_ssize_t *strides,
                                                    int itemsize,
                                                    char fort);
574

575 576 577 578 579
    /*  Fill the strides array with byte-strides of a contiguous
        (Fortran-style if fort is 'F' or C-style otherwise)
        array of the given shape with the given number of bytes
        per element.
    */
580

581
     PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf,
582 583
                                       Py_ssize_t len, int readonly,
                                       int flags);
584

585 586 587 588 589
    /* Fills in a buffer-info structure correctly for an exporter
       that can only share a contiguous chunk of memory of
       "unsigned bytes" of the given length. Returns 0 on success
       and -1 (with raising an error) on error.
     */
590

591 592 593
     PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);

       /* Releases a Py_buffer obtained from getbuffer ParseTuple's s*.
594
    */
595
#endif /* Py_LIMITED_API */
596

597
     PyAPI_FUNC(PyObject *) PyObject_Format(PyObject* obj,
598
                                            PyObject *format_spec);
599
       /*
600 601
     Takes an arbitrary object and returns the result of
     calling obj.__format__(format_spec).
602 603
       */

604 605
/* Iterators */

606
     PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);
607
     /* Takes an object and returns an iterator for it.
608 609
    This is typically a new iterator but if the argument
    is an iterator, this returns itself. */
610

611
#define PyIter_Check(obj) \
612 613
    ((obj)->ob_type->tp_iternext != NULL && \
     (obj)->ob_type->tp_iternext != &_PyObject_NextNotImplemented)
614

615
     PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);
616
     /* Takes an iterator object and calls its tp_iternext slot,
617 618 619
    returning the next value.  If the iterator is exhausted,
    this returns NULL without setting an exception.
    NULL with an exception means an error occurred. */
620

621 622
/*  Number Protocol:*/

623
     PyAPI_FUNC(int) PyNumber_Check(PyObject *o);
624 625

       /*
626 627
     Returns 1 if the object, o, provides numeric protocols, and
     false otherwise.
628

629
     This function always succeeds.
630 631
       */

632
     PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);
633 634

       /*
635 636
     Returns the result of adding o1 and o2, or null on failure.
     This is the equivalent of the Python expression: o1+o2.
637 638
       */

639
     PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2);
640 641

       /*
642 643 644
     Returns the result of subtracting o2 from o1, or null on
     failure.  This is the equivalent of the Python expression:
     o1-o2.
645 646
       */

647
     PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2);
648 649

       /*
650 651 652
     Returns the result of multiplying o1 and o2, or null on
     failure.  This is the equivalent of the Python expression:
     o1*o2.
653 654
       */

655
     PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2);
656 657

       /*
658 659 660
     Returns the result of dividing o1 by o2 giving an integral result,
     or null on failure.
     This is the equivalent of the Python expression: o1//o2.
661 662
       */

663
     PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2);
664 665

       /*
666 667 668
     Returns the result of dividing o1 by o2 giving a float result,
     or null on failure.
     This is the equivalent of the Python expression: o1/o2.
669 670
       */

671
     PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);
672 673

       /*
674 675 676
     Returns the remainder of dividing o1 by o2, or null on
     failure.  This is the equivalent of the Python expression:
     o1%o2.
677 678
       */

679
     PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);
680 681

       /*
682 683 684
     See the built-in function divmod.  Returns NULL on failure.
     This is the equivalent of the Python expression:
     divmod(o1,o2).
685 686
       */

687
     PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,
688
                                           PyObject *o3);
689 690

       /*
691 692 693
     See the built-in function pow.  Returns NULL on failure.
     This is the equivalent of the Python expression:
     pow(o1,o2,o3), where o3 is optional.
694 695
       */

696
     PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o);
697 698

       /*
699 700
     Returns the negation of o on success, or null on failure.
     This is the equivalent of the Python expression: -o.
701 702
       */

703
     PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o);
704 705

       /*
706 707
     Returns the (what?) of o on success, or NULL on failure.
     This is the equivalent of the Python expression: +o.
708 709
       */

710
     PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o);
711 712

       /*
713 714
     Returns the absolute value of o, or null on failure.  This is
     the equivalent of the Python expression: abs(o).
715 716
       */

717
     PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o);
718 719

       /*
720 721 722
     Returns the bitwise negation of o on success, or NULL on
     failure.  This is the equivalent of the Python expression:
     ~o.
723 724
       */

725
     PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);
726 727

       /*
728 729 730
     Returns the result of left shifting o1 by o2 on success, or
     NULL on failure.  This is the equivalent of the Python
     expression: o1 << o2.
731 732
       */

733
     PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);
734 735

       /*
736 737 738
     Returns the result of right shifting o1 by o2 on success, or
     NULL on failure.  This is the equivalent of the Python
     expression: o1 >> o2.
739 740
       */

741
     PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);
742 743

       /*
744 745 746
     Returns the result of bitwise and of o1 and o2 on success, or
     NULL on failure. This is the equivalent of the Python
     expression: o1&o2.
747 748 749

       */

750
     PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);
751 752

       /*
753 754 755
     Returns the bitwise exclusive or of o1 by o2 on success, or
     NULL on failure.  This is the equivalent of the Python
     expression: o1^o2.
756 757
       */

758
     PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);
759 760

       /*
761 762 763
     Returns the result of bitwise or on o1 and o2 on success, or
     NULL on failure.  This is the equivalent of the Python
     expression: o1|o2.
764 765
       */

766 767 768
#define PyIndex_Check(obj) \
   ((obj)->ob_type->tp_as_number != NULL && \
    (obj)->ob_type->tp_as_number->nb_index != NULL)
769

770
     PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o);
771 772

       /*
773 774
     Returns the object converted to a Python long or int
     or NULL with an error raised on failure.
775 776
       */

777 778 779
     PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc);

       /*
780 781 782 783 784
    Returns the object converted to Py_ssize_t by going through
    PyNumber_Index first.  If an overflow error occurs while
    converting the int-or-long to Py_ssize_t, then the second argument
    is the error-type to return.  If it is NULL, then the overflow error
    is cleared and the value is clipped.
785
       */
786

787 788
     PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);

789
       /*
790 791 792
     Returns the o converted to an integer object on success, or
     NULL on failure.  This is the equivalent of the Python
     expression: int(o).
793 794
       */

795
     PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);
796 797

       /*
798 799 800
     Returns the o converted to a float object on success, or NULL
     on failure.  This is the equivalent of the Python expression:
     float(o).
801
       */
802

803 804
/*  In-place variants of (some of) the above number protocol functions */

805
     PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);
806 807

       /*
808 809 810
     Returns the result of adding o2 to o1, possibly in-place, or null
     on failure.  This is the equivalent of the Python expression:
     o1 += o2.
811 812
       */

813
     PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);
814 815

       /*
816 817 818
     Returns the result of subtracting o2 from o1, possibly in-place or
     null on failure.  This is the equivalent of the Python expression:
     o1 -= o2.
819 820
       */

821
     PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);
822 823

       /*
824 825 826
     Returns the result of multiplying o1 by o2, possibly in-place, or
     null on failure.  This is the equivalent of the Python expression:
     o1 *= o2.
827 828
       */

829
     PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1,
830
                                                        PyObject *o2);
831 832

       /*
833 834 835 836
     Returns the result of dividing o1 by o2 giving an integral result,
     possibly in-place, or null on failure.
     This is the equivalent of the Python expression:
     o1 /= o2.
837 838
       */

839
     PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1,
840
                                                       PyObject *o2);
841 842

       /*
843 844 845 846
     Returns the result of dividing o1 by o2 giving a float result,
     possibly in-place, or null on failure.
     This is the equivalent of the Python expression:
     o1 /= o2.
847 848
       */

849
     PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);
850 851

       /*
852 853 854
     Returns the remainder of dividing o1 by o2, possibly in-place, or
     null on failure.  This is the equivalent of the Python expression:
     o1 %= o2.
855 856
       */

857
     PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,
858
                                                  PyObject *o3);
859 860

       /*
861 862 863
     Returns the result of raising o1 to the power of o2, possibly
     in-place, or null on failure.  This is the equivalent of the Python
     expression: o1 **= o2, or pow(o1, o2, o3) if o3 is present.
864 865
       */

866
     PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);
867 868

       /*
869 870 871
     Returns the result of left shifting o1 by o2, possibly in-place, or
     null on failure.  This is the equivalent of the Python expression:
     o1 <<= o2.
872 873
       */

874
     PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);
875 876

       /*
877 878 879
     Returns the result of right shifting o1 by o2, possibly in-place or
     null on failure.  This is the equivalent of the Python expression:
     o1 >>= o2.
880 881
       */

882
     PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);
883 884

       /*
885 886 887
     Returns the result of bitwise and of o1 and o2, possibly in-place,
     or null on failure. This is the equivalent of the Python
     expression: o1 &= o2.
888 889
       */

890
     PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);
891 892

       /*
893 894 895
     Returns the bitwise exclusive or of o1 by o2, possibly in-place, or
     null on failure.  This is the equivalent of the Python expression:
     o1 ^= o2.
896 897
       */

898
     PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);
899 900

       /*
901 902 903
     Returns the result of bitwise or of o1 and o2, possibly in-place,
     or null on failure.  This is the equivalent of the Python
     expression: o1 |= o2.
904 905
       */

906 907 908
     PyAPI_FUNC(PyObject *) PyNumber_ToBase(PyObject *n, int base);

       /*
909 910 911
     Returns the integer n converted to a string with a base, with a base
     marker of 0b, 0o or 0x prefixed if applicable.
     If n is not an int object, it is converted with PyNumber_Index first.
912 913
       */

914 915 916

/*  Sequence protocol:*/

917
     PyAPI_FUNC(int) PySequence_Check(PyObject *o);
918 919

       /*
920 921
     Return 1 if the object provides sequence protocol, and zero
     otherwise.
922

923
     This function always succeeds.
924 925
       */

Martin v. Löwis's avatar
Martin v. Löwis committed
926
     PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
927

928
       /*
929
     Return the size of sequence object o, or -1 on failure.
930 931
       */

932 933
       /* For DLL compatibility */
#undef PySequence_Length
Martin v. Löwis's avatar
Martin v. Löwis committed
934
     PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);
935 936 937
#define PySequence_Length PySequence_Size


938
     PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);
939 940

       /*
941 942 943
     Return the concatenation of o1 and o2 on success, and NULL on
     failure.   This is the equivalent of the Python
     expression: o1+o2.
944 945
       */

Martin v. Löwis's avatar
Martin v. Löwis committed
946
     PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count);
947 948

       /*
949 950 951
     Return the result of repeating sequence object o count times,
     or NULL on failure.  This is the equivalent of the Python
     expression: o1*count.
952 953
       */

Martin v. Löwis's avatar
Martin v. Löwis committed
954
     PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i);
955 956

       /*
957 958
     Return the ith element of o, or NULL on failure. This is the
     equivalent of the Python expression: o[i].
959 960
       */

Martin v. Löwis's avatar
Martin v. Löwis committed
961
     PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
962 963

       /*
964 965 966
     Return the slice of sequence object o between i1 and i2, or
     NULL on failure. This is the equivalent of the Python
     expression: o[i1:i2].
967 968
       */

Martin v. Löwis's avatar
Martin v. Löwis committed
969
     PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);
970 971

       /*
972 973 974
     Assign object v to the ith element of o.  Returns
     -1 on failure.  This is the equivalent of the Python
     statement: o[i]=v.
975 976
       */

Martin v. Löwis's avatar
Martin v. Löwis committed
977
     PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
978 979

       /*
980 981 982
     Delete the ith element of object v.  Returns
     -1 on failure.  This is the equivalent of the Python
     statement: del o[i].
983 984
       */

Martin v. Löwis's avatar
Martin v. Löwis committed
985
     PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2,
986
                                         PyObject *v);
987 988

       /*
989 990 991
     Assign the sequence object, v, to the slice in sequence
     object, o, from i1 to i2.  Returns -1 on failure. This is the
     equivalent of the Python statement: o[i1:i2]=v.
992 993
       */

Martin v. Löwis's avatar
Martin v. Löwis committed
994
     PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
995 996

       /*
997 998 999
     Delete the slice in sequence object, o, from i1 to i2.
     Returns -1 on failure. This is the equivalent of the Python
     statement: del o[i1:i2].
1000 1001
       */

1002
     PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);
1003 1004

       /*
1005 1006
     Returns the sequence, o, as a tuple on success, and NULL on failure.
     This is equivalent to the Python expression: tuple(o)
1007 1008
       */

Andrew M. Kuchling's avatar
Andrew M. Kuchling committed
1009

1010
     PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);
1011
       /*
1012 1013
     Returns the sequence, o, as a list on success, and NULL on failure.
     This is equivalent to the Python expression: list(o)
1014
       */
1015

1016
     PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
Andrew M. Kuchling's avatar
Andrew M. Kuchling committed
1017
       /*
1018
     Returns the sequence, o, as a list, unless it's already a
1019 1020
     tuple or list.  Use PySequence_Fast_GET_ITEM to access the
     members of this list, and PySequence_Fast_GET_SIZE to get its length.
Andrew M. Kuchling's avatar
Andrew M. Kuchling committed
1021

1022 1023
     Returns NULL on failure.  If the object does not support iteration,
     raises a TypeError exception with m as the message text.
Andrew M. Kuchling's avatar
Andrew M. Kuchling committed
1024 1025
       */

1026
#define PySequence_Fast_GET_SIZE(o) \
1027
    (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o))
1028
       /*
1029 1030
     Return the size of o, assuming that o was returned by
     PySequence_Fast and is not NULL.
1031 1032
       */

Andrew M. Kuchling's avatar
Andrew M. Kuchling committed
1033 1034 1035
#define PySequence_Fast_GET_ITEM(o, i)\
     (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i))
       /*
1036 1037
     Return the ith element of o, assuming that o was returned by
     PySequence_Fast, and that i is within bounds.
Andrew M. Kuchling's avatar
Andrew M. Kuchling committed
1038 1039
       */

1040
#define PySequence_ITEM(o, i)\
1041
    ( Py_TYPE(o)->tp_as_sequence->sq_item(o, i) )
1042
       /* Assume tp_as_sequence and sq_item exist and that i does not
1043 1044
      need to be corrected for a negative index
       */
1045

1046
#define PySequence_Fast_ITEMS(sf) \
1047 1048 1049 1050
    (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \
                      : ((PyTupleObject *)(sf))->ob_item)
    /* Return a pointer to the underlying item array for
       an object retured by PySequence_Fast */
1051

1052
     PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value);
1053 1054

       /*
1055 1056 1057 1058
     Return the number of occurrences on value on o, that is,
     return the number of keys for which o[key]==value.  On
     failure, return -1.  This is equivalent to the Python
     expression: o.count(value).
1059 1060
       */

1061
     PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob);
1062
       /*
1063 1064
     Return -1 if error; 1 if ob in seq; 0 if ob not in seq.
     Use __contains__ if possible, else _PySequence_IterSearch().
1065 1066
       */

1067
#ifndef Py_LIMITED_API
1068 1069 1070
#define PY_ITERSEARCH_COUNT    1
#define PY_ITERSEARCH_INDEX    2
#define PY_ITERSEARCH_CONTAINS 3
1071
     PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq,
1072
                                        PyObject *obj, int operation);
1073
#endif
1074 1075 1076 1077 1078 1079 1080 1081 1082 1083
    /*
      Iterate over seq.  Result depends on the operation:
      PY_ITERSEARCH_COUNT:  return # of times obj appears in seq; -1 if
        error.
      PY_ITERSEARCH_INDEX:  return 0-based index of first occurrence of
        obj in seq; set ValueError and return -1 if none found;
        also return -1 on error.
      PY_ITERSEARCH_CONTAINS:  return 1 if obj in seq, else 0; -1 on
        error.
    */
1084 1085 1086

/* For DLL-level backwards compatibility */
#undef PySequence_In
1087
     PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value);
1088 1089

/* For source-level backwards compatibility */
1090
#define PySequence_In PySequence_Contains
1091 1092

       /*
1093 1094 1095
     Determine if o contains value.  If an item in o is equal to
     X, return 1, otherwise return 0.  On error, return -1.  This
     is equivalent to the Python expression: value in o.
1096 1097
       */

1098
     PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value);
1099 1100

       /*
1101 1102 1103
     Return the first index for which o[i]=value.  On error,
     return -1.    This is equivalent to the Python
     expression: o.index(value).
1104 1105
       */

1106 1107
/* In-place versions of some of the above Sequence functions. */

1108
     PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);
1109 1110

       /*
1111 1112 1113
     Append o2 to o1, in-place when possible. Return the resulting
     object, which could be o1, or NULL on failure.  This is the
     equivalent of the Python expression: o1 += o2.
1114 1115 1116

       */

Martin v. Löwis's avatar
Martin v. Löwis committed
1117
     PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count);
1118 1119

       /*
1120 1121 1122
     Repeat o1 by count, in-place when possible. Return the resulting
     object, which could be o1, or NULL on failure.  This is the
     equivalent of the Python expression: o1 *= count.
1123 1124 1125

       */

1126 1127
/*  Mapping protocol:*/

1128
     PyAPI_FUNC(int) PyMapping_Check(PyObject *o);
1129 1130

       /*
1131 1132
     Return 1 if the object provides mapping protocol, and zero
     otherwise.
1133

1134
     This function always succeeds.
1135 1136
       */

Martin v. Löwis's avatar
Martin v. Löwis committed
1137
     PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
1138

1139
       /*
1140 1141 1142
     Returns the number of keys in object o on success, and -1 on
     failure.  For objects that do not provide sequence protocol,
     this is equivalent to the Python expression: len(o).
1143 1144
       */

1145 1146
       /* For DLL compatibility */
#undef PyMapping_Length
Martin v. Löwis's avatar
Martin v. Löwis committed
1147
     PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
1148 1149 1150
#define PyMapping_Length PyMapping_Size


1151 1152
     /* implemented as a macro:

1153
     int PyMapping_DelItemString(PyObject *o, char *key);
1154

1155 1156 1157
     Remove the mapping for object, key, from the object *o.
     Returns -1 on failure.  This is equivalent to
     the Python statement: del o[key].
1158
       */
1159
#define PyMapping_DelItemString(O,K) PyObject_DelItemString((O),(K))
1160 1161

     /* implemented as a macro:
1162

1163
     int PyMapping_DelItem(PyObject *o, PyObject *key);
1164

1165 1166 1167
     Remove the mapping for object, key, from the object *o.
     Returns -1 on failure.  This is equivalent to
     the Python statement: del o[key].
1168
       */
1169
#define PyMapping_DelItem(O,K) PyObject_DelItem((O),(K))
1170

1171
     PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, char *key);
1172 1173

       /*
1174 1175 1176
     On success, return 1 if the mapping object has the key, key,
     and 0 otherwise.  This is equivalent to the Python expression:
     key in o.
1177

1178
     This function always succeeds.
1179 1180
       */

1181
     PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key);
1182 1183

       /*
1184 1185 1186
     Return 1 if the mapping object has the key, key,
     and 0 otherwise.  This is equivalent to the Python expression:
     key in o.
1187

1188
     This function always succeeds.
1189 1190 1191

       */

1192
     PyAPI_FUNC(PyObject *) PyMapping_Keys(PyObject *o);
1193

1194
       /*
1195 1196
     On success, return a list or tuple of the keys in object o.
     On failure, return NULL.
1197 1198
       */

1199
     PyAPI_FUNC(PyObject *) PyMapping_Values(PyObject *o);
1200

1201
       /*
1202 1203
     On success, return a list or tuple of the values in object o.
     On failure, return NULL.
1204 1205
       */

1206
     PyAPI_FUNC(PyObject *) PyMapping_Items(PyObject *o);
1207

1208
       /*
1209 1210 1211
     On success, return a list or tuple of the items in object o,
     where each item is a tuple containing a key-value pair.
     On failure, return NULL.
1212 1213 1214

       */

1215
     PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o, char *key);
1216 1217

       /*
1218 1219 1220
     Return element of o corresponding to the object, key, or NULL
     on failure. This is the equivalent of the Python expression:
     o[key].
1221 1222
       */

1223
     PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, char *key,
1224
                                            PyObject *value);
1225 1226

       /*
1227 1228 1229
     Map the object, key, to the value, v.  Returns
     -1 on failure.  This is the equivalent of the Python
     statement: o[key]=v.
1230 1231 1232
      */


1233
PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
1234 1235
      /* isinstance(object, typeorclass) */

1236
PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass);
1237 1238 1239
      /* issubclass(object, typeorclass) */


1240
#ifndef Py_LIMITED_API
1241 1242 1243 1244
PyAPI_FUNC(int) _PyObject_RealIsInstance(PyObject *inst, PyObject *cls);

PyAPI_FUNC(int) _PyObject_RealIsSubclass(PyObject *derived, PyObject *cls);

1245 1246 1247
PyAPI_FUNC(char *const *) _PySequence_BytesToCharpArray(PyObject* self);

PyAPI_FUNC(void) _Py_FreeCharPArray(char *const array[]);
1248
#endif
1249

1250 1251 1252 1253 1254 1255 1256
/* For internal use by buffer API functions */
PyAPI_FUNC(void) _Py_add_one_to_index_F(int nd, Py_ssize_t *index,
                                        const Py_ssize_t *shape);
PyAPI_FUNC(void) _Py_add_one_to_index_C(int nd, Py_ssize_t *index,
                                        const Py_ssize_t *shape);


Guido van Rossum's avatar
Guido van Rossum committed
1257 1258 1259
#ifdef __cplusplus
}
#endif
1260
#endif /* Py_ABSTRACTOBJECT_H */