Include/abstract.h

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