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      PyAPI_FUNC(int) PyObject_Cmp(PyObject *o1, PyObject *o2, int *result);
 232
 233        /*
 234          Compare the values of o1 and o2 using a routine provided by
 235          o1, if one exists, otherwise with a routine provided by o2.
 236          The result of the comparison is returned in result.  Returns
 237          -1 on failure.  This is the equivalent of the Python
 238          statement: result=cmp(o1,o2).
 239
 240        */
 241
 242      /* Implemented elsewhere:
 243
 244      int PyObject_Compare(PyObject *o1, PyObject *o2);
 245
 246          Compare the values of o1 and o2 using a routine provided by
 247          o1, if one exists, otherwise with a routine provided by o2.
 248          Returns the result of the comparison on success.  On error,
 249          the value returned is undefined. This is equivalent to the
 250          Python expression: cmp(o1,o2).
 251
 252        */
 253
 254      /* Implemented elsewhere:
 255
 256      PyObject *PyObject_Repr(PyObject *o);
 257
 258          Compute the string representation of object, o.  Returns the
 259          string representation on success, NULL on failure.  This is
 260          the equivalent of the Python expression: repr(o).
 261
 262          Called by the repr() built-in function and by reverse quotes.
 263
 264        */
 265
 266      /* Implemented elsewhere:
 267
 268      PyObject *PyObject_Str(PyObject *o);
 269
 270          Compute the string representation of object, o.  Returns the
 271          string representation on success, NULL on failure.  This is
 272          the equivalent of the Python expression: str(o).)
 273
 274          Called by the str() built-in function and by the print
 275          statement.
 276
 277        */
 278
 279      /* Implemented elsewhere:
 280
 281      PyObject *PyObject_Unicode(PyObject *o);
 282
 283          Compute the unicode representation of object, o.  Returns the
 284          unicode representation on success, NULL on failure.  This is
 285          the equivalent of the Python expression: unistr(o).)
 286
 287          Called by the unistr() built-in function.
 288
 289        */
 290
 291        /* Declared elsewhere
 292
 293      PyAPI_FUNC(int) PyCallable_Check(PyObject *o);
 294
 295          Determine if the object, o, is callable.  Return 1 if the
 296          object is callable and 0 otherwise.
 297
 298          This function always succeeds.
 299
 300        */
 301
 302
 303
 304      PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable_object,
 305                                          PyObject *args, PyObject *kw);
 306
 307        /*
 308          Call a callable Python object, callable_object, with
 309          arguments and keywords arguments.  The 'args' argument can not be
 310          NULL, but the 'kw' argument can be NULL.
 311
 312        */
 313
 314      PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable_object,
 315                                                PyObject *args);
 316
 317        /*
 318          Call a callable Python object, callable_object, with
 319          arguments given by the tuple, args.  If no arguments are
 320          needed, then args may be NULL.  Returns the result of the
 321          call on success, or NULL on failure.  This is the equivalent
 322          of the Python expression: apply(o,args).
 323
 324        */
 325
 326      PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable_object,
 327                                                  char *format, ...);
 328
 329        /*
 330          Call a callable Python object, callable_object, with a
 331          variable number of C arguments. The C arguments are described
 332          using a mkvalue-style format string. The format may be NULL,
 333          indicating that no arguments are provided.  Returns the
 334          result of the call on success, or NULL on failure.  This is
 335          the equivalent of the Python expression: apply(o,args).
 336
 337        */
 338
 339
 340      PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *o, char *m,
 341                                                char *format, ...);
 342
 343        /*
 344          Call the method named m of object o with a variable number of
 345          C arguments.  The C arguments are described by a mkvalue
 346          format string.  The format may be NULL, indicating that no
 347          arguments are provided. Returns the result of the call on
 348          success, or NULL on failure.  This is the equivalent of the
 349          Python expression: o.method(args).
 350        */
 351
 352      PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,
 353                                                          char *format, ...);
 354      PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *o,
 355                                                        char *name,
 356                                                        char *format, ...);
 357
 358      PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,
 359                                                         ...);
 360
 361        /*
 362          Call a callable Python object, callable_object, with a
 363          variable number of C arguments.  The C arguments are provided
 364          as PyObject * values, terminated by a NULL.  Returns the
 365          result of the call on success, or NULL on failure.  This is
 366          the equivalent of the Python expression: apply(o,args).
 367        */
 368
 369
 370      PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(PyObject *o,
 371                                                       PyObject *m, ...);
 372
 373        /*
 374          Call the method named m of object o with a variable number of
 375          C arguments.  The C arguments are provided as PyObject *
 376          values, terminated by NULL.  Returns the result of the call
 377          on success, or NULL on failure.  This is the equivalent of
 378          the Python expression: o.method(args).
 379        */
 380
 381
 382      /* Implemented elsewhere:
 383
 384      long PyObject_Hash(PyObject *o);
 385
 386          Compute and return the hash, hash_value, of an object, o.  On
 387          failure, return -1.  This is the equivalent of the Python
 388          expression: hash(o).
 389
 390        */
 391
 392
 393      /* Implemented elsewhere:
 394
 395      int PyObject_IsTrue(PyObject *o);
 396
 397          Returns 1 if the object, o, is considered to be true, 0 if o is
 398          considered to be false and -1 on failure. This is equivalent to the
 399          Python expression: not not o
 400
 401        */
 402
 403      /* Implemented elsewhere:
 404
 405      int PyObject_Not(PyObject *o);
 406
 407          Returns 0 if the object, o, is considered to be true, 1 if o is
 408          considered to be false and -1 on failure. This is equivalent to the
 409          Python expression: not o
 410
 411        */
 412
 413      PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o);
 414
 415        /*
 416          On success, returns a type object corresponding to the object
 417          type of object o. On failure, returns NULL.  This is
 418          equivalent to the Python expression: type(o).
 419        */
 420
 421      PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);
 422
 423        /*
 424          Return the size of object o.  If the object, o, provides
 425          both sequence and mapping protocols, the sequence size is
 426          returned. On error, -1 is returned.  This is the equivalent
 427          to the Python expression: len(o).
 428
 429        */
 430
 431        /* For DLL compatibility */
 432 #undef PyObject_Length
 433      PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);
 434 #define PyObject_Length PyObject_Size
 435
 436      PyAPI_FUNC(Py_ssize_t) _PyObject_LengthHint(PyObject *o);
 437
 438        /*
 439          Return the size of object o.  If the object, o, provides
 440          both sequence and mapping protocols, the sequence size is
 441          returned. On error, -1 is returned.  If the object provides
 442          a __length_hint__() method, its value is returned.  This is an
 443          internal undocumented API provided for performance reasons;
 444          for compatibility, don't use it outside the core.  This is the
 445          equivalent to the Python expression:
 446                 try:
 447                         return len(o)
 448                 except (AttributeError, TypeError):
 449                         exc_type, exc_value, exc_tb = sys.exc_info()
 450                         try:
 451                                 return o.__length_hint__()
 452                         except:
 453                                 pass
 454                         raise exc_type, exc_value, exc_tb
 455        */
 456
 457      PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
 458
 459        /*
 460          Return element of o corresponding to the object, key, or NULL
 461          on failure. This is the equivalent of the Python expression:
 462          o[key].
 463
 464        */
 465
 466      PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
 467
 468        /*
 469          Map the object, key, to the value, v.  Returns
 470          -1 on failure.  This is the equivalent of the Python
 471          statement: o[key]=v.
 472        */
 473
 474      PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, char *key);
 475
 476        /*
 477          Remove the mapping for object, key, from the object *o.
 478          Returns -1 on failure.  This is equivalent to
 479          the Python statement: del o[key].
 480        */
 481
 482      PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
 483
 484        /*
 485          Delete the mapping for key from *o.  Returns -1 on failure.
 486          This is the equivalent of the Python statement: del o[key].
 487        */
 488
 489      PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,
 490                                           const char **buffer,
 491                                           Py_ssize_t *buffer_len);
 492
 493        /*
 494           Takes an arbitrary object which must support the (character,
 495           single segment) buffer interface and returns a pointer to a
 496           read-only memory location useable as character based input
 497           for subsequent processing.
 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
 505      PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);
 506
 507       /*
 508           Checks whether an arbitrary object supports the (character,
 509           single segment) buffer interface.  Returns 1 on success, 0
 510           on failure.
 511
 512       */
 513
 514      PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,
 515                                           const void **buffer,
 516                                           Py_ssize_t *buffer_len);
 517
 518        /*
 519           Same as PyObject_AsCharBuffer() except that this API expects
 520           (readable, single segment) buffer interface and returns a
 521           pointer to a read-only memory location which can contain
 522           arbitrary data.
 523
 524           0 is returned on success.  buffer and buffer_len are only
 525           set in case no error occurrs.  Otherwise, -1 is returned and
 526           an exception set.
 527
 528        */
 529
 530      PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,
 531                                            void **buffer,
 532                                            Py_ssize_t *buffer_len);
 533
 534        /*
 535           Takes an arbitrary object which must support the (writeable,
 536           single segment) buffer interface and returns a pointer to a
 537           writeable memory location in buffer of size buffer_len.
 538
 539           0 is returned on success.  buffer and buffer_len are only
 540           set in case no error occurrs. Otherwise, -1 is returned and
 541           an exception set.
 542
 543        */
 544
 545 /* Iterators */
 546
 547      PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);
 548      /* Takes an object and returns an iterator for it.
 549         This is typically a new iterator but if the argument
 550         is an iterator, this returns itself. */
 551
 552 #define PyIter_Check(obj) \
 553     (PyType_HasFeature((obj)->ob_type, Py_TPFLAGS_HAVE_ITER) && \
 554      (obj)->ob_type->tp_iternext != NULL)
 555
 556      PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);
 557      /* Takes an iterator object and calls its tp_iternext slot,
 558         returning the next value.  If the iterator is exhausted,
 559         this returns NULL without setting an exception.
 560         NULL with an exception means an error occurred. */
 561
 562 /*  Number Protocol:*/
 563
 564      PyAPI_FUNC(int) PyNumber_Check(PyObject *o);
 565
 566        /*
 567          Returns 1 if the object, o, provides numeric protocols, and
 568          false otherwise.
 569
 570          This function always succeeds.
 571
 572        */
 573
 574      PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);
 575
 576        /*
 577          Returns the result of adding o1 and o2, or null on failure.
 578          This is the equivalent of the Python expression: o1+o2.
 579
 580
 581        */
 582
 583      PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2);
 584
 585        /*
 586          Returns the result of subtracting o2 from o1, or null on
 587          failure.  This is the equivalent of the Python expression:
 588          o1-o2.
 589
 590        */
 591
 592      PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2);
 593
 594        /*
 595          Returns the result of multiplying o1 and o2, or null on
 596          failure.  This is the equivalent of the Python expression:
 597          o1*o2.
 598
 599
 600        */
 601
 602      PyAPI_FUNC(PyObject *) PyNumber_Divide(PyObject *o1, PyObject *o2);
 603
 604        /*
 605          Returns the result of dividing o1 by o2, or null on failure.
 606          This is the equivalent of the Python expression: o1/o2.
 607
 608
 609        */
 610
 611      PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2);
 612
 613        /*
 614          Returns the result of dividing o1 by o2 giving an integral result,
 615          or null on failure.
 616          This is the equivalent of the Python expression: o1//o2.
 617
 618
 619        */
 620
 621      PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2);
 622
 623        /*
 624          Returns the result of dividing o1 by o2 giving a float result,
 625          or null on failure.
 626          This is the equivalent of the Python expression: o1/o2.
 627
 628
 629        */
 630
 631      PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);
 632
 633        /*
 634          Returns the remainder of dividing o1 by o2, or null on
 635          failure.  This is the equivalent of the Python expression:
 636          o1%o2.
 637
 638
 639        */
 640
 641      PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);
 642
 643        /*
 644          See the built-in function divmod.  Returns NULL on failure.
 645          This is the equivalent of the Python expression:
 646          divmod(o1,o2).
 647
 648
 649        */
 650
 651      PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,
 652                                           PyObject *o3);
 653
 654        /*
 655          See the built-in function pow.  Returns NULL on failure.
 656          This is the equivalent of the Python expression:
 657          pow(o1,o2,o3), where o3 is optional.
 658
 659        */
 660
 661      PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o);
 662
 663        /*
 664          Returns the negation of o on success, or null on failure.
 665          This is the equivalent of the Python expression: -o.
 666
 667        */
 668
 669      PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o);
 670
 671        /*
 672          Returns the (what?) of o on success, or NULL on failure.
 673          This is the equivalent of the Python expression: +o.
 674
 675        */
 676
 677      PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o);
 678
 679        /*
 680          Returns the absolute value of o, or null on failure.  This is
 681          the equivalent of the Python expression: abs(o).
 682
 683        */
 684
 685      PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o);
 686
 687        /*
 688          Returns the bitwise negation of o on success, or NULL on
 689          failure.  This is the equivalent of the Python expression:
 690          ~o.
 691
 692
 693        */
 694
 695      PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);
 696
 697        /*
 698          Returns the result of left shifting o1 by o2 on success, or
 699          NULL on failure.  This is the equivalent of the Python
 700          expression: o1 << o2.
 701
 702
 703        */
 704
 705      PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);
 706
 707        /*
 708          Returns the result of right shifting o1 by o2 on success, or
 709          NULL on failure.  This is the equivalent of the Python
 710          expression: o1 >> o2.
 711
 712        */
 713
 714      PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);
 715
 716        /*
 717          Returns the result of bitwise and of o1 and o2 on success, or
 718          NULL on failure. This is the equivalent of the Python
 719          expression: o1&o2.
 720
 721
 722        */
 723
 724      PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);
 725
 726        /*
 727          Returns the bitwise exclusive or of o1 by o2 on success, or
 728          NULL on failure.  This is the equivalent of the Python
 729          expression: o1^o2.
 730
 731
 732        */
 733
 734      PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);
 735
 736        /*
 737          Returns the result of bitwise or on o1 and o2 on success, or
 738          NULL on failure.  This is the equivalent of the Python
 739          expression: o1|o2.
 740
 741        */
 742
 743      /* Implemented elsewhere:
 744
 745      int PyNumber_Coerce(PyObject **p1, PyObject **p2);
 746
 747          This function takes the addresses of two variables of type
 748          PyObject*.
 749
 750          If the objects pointed to by *p1 and *p2 have the same type,
 751          increment their reference count and return 0 (success).
 752          If the objects can be converted to a common numeric type,
 753          replace *p1 and *p2 by their converted value (with 'new'
 754          reference counts), and return 0.
 755          If no conversion is possible, or if some other error occurs,
 756          return -1 (failure) and don't increment the reference counts.
 757          The call PyNumber_Coerce(&o1, &o2) is equivalent to the Python
 758          statement o1, o2 = coerce(o1, o2).
 759
 760        */
 761
 762 #define PyIndex_Check(obj) \
 763    ((obj)->ob_type->tp_as_number != NULL && \
 764     PyType_HasFeature((obj)->ob_type, Py_TPFLAGS_HAVE_INDEX) && \
 765     (obj)->ob_type->tp_as_number->nb_index != NULL)
 766
 767      PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o);
 768
 769        /*
 770          Returns the object converted to a Python long or int
 771          or NULL with an error raised on failure.
 772        */
 773
 774      PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc);
 775
 776        /*
 777         Returns the object converted to Py_ssize_t by going through
 778         PyNumber_Index first.  If an overflow error occurs while
 779         converting the int-or-long to Py_ssize_t, then the second argument
 780         is the error-type to return.  If it is NULL, then the overflow error
 781         is cleared and the value is clipped.
 782        */
 783
 784      PyAPI_FUNC(PyObject *) PyNumber_Int(PyObject *o);
 785
 786        /*
 787          Returns the o converted to an integer object on success, or
 788          NULL on failure.  This is the equivalent of the Python
 789          expression: int(o).
 790
 791        */
 792
 793      PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);
 794
 795        /*
 796          Returns the o converted to a long integer object on success,
 797          or NULL on failure.  This is the equivalent of the Python
 798          expression: long(o).
 799
 800        */
 801
 802      PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);
 803
 804        /*
 805          Returns the o converted to a float object on success, or NULL
 806          on failure.  This is the equivalent of the Python expression:
 807          float(o).
 808        */
 809
 810 /*  In-place variants of (some of) the above number protocol functions */
 811
 812      PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);
 813
 814        /*
 815          Returns the result of adding o2 to o1, possibly in-place, or null
 816          on failure.  This is the equivalent of the Python expression:
 817          o1 += o2.
 818
 819        */
 820
 821      PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);
 822
 823        /*
 824          Returns the result of subtracting o2 from o1, possibly in-place or
 825          null on failure.  This is the equivalent of the Python expression:
 826          o1 -= o2.
 827
 828        */
 829
 830      PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);
 831
 832        /*
 833          Returns the result of multiplying o1 by o2, possibly in-place, or
 834          null on failure.  This is the equivalent of the Python expression:
 835          o1 *= o2.
 836
 837        */
 838
 839      PyAPI_FUNC(PyObject *) PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2);
 840
 841        /*
 842          Returns the result of dividing o1 by o2, possibly in-place, or null
 843          on failure.  This is the equivalent of the Python expression:
 844          o1 /= o2.
 845
 846        */
 847
 848      PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1,
 849                                                        PyObject *o2);
 850
 851        /*
 852          Returns the result of dividing o1 by o2 giving an integral result,
 853          possibly in-place, or null on failure.
 854          This is the equivalent of the Python expression:
 855          o1 /= o2.
 856
 857        */
 858
 859      PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1,
 860                                                       PyObject *o2);
 861
 862        /*
 863          Returns the result of dividing o1 by o2 giving a float result,
 864          possibly in-place, or null on failure.
 865          This is the equivalent of the Python expression:
 866          o1 /= o2.
 867
 868        */
 869
 870      PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);
 871
 872        /*
 873          Returns the remainder of dividing o1 by o2, possibly in-place, or
 874          null on failure.  This is the equivalent of the Python expression:
 875          o1 %= o2.
 876
 877        */
 878
 879      PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,
 880                                                  PyObject *o3);
 881
 882        /*
 883          Returns the result of raising o1 to the power of o2, possibly
 884          in-place, or null on failure.  This is the equivalent of the Python
 885          expression: o1 **= o2, or pow(o1, o2, o3) if o3 is present.
 886
 887        */
 888
 889      PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);
 890
 891        /*
 892          Returns the result of left shifting o1 by o2, possibly in-place, or
 893          null on failure.  This is the equivalent of the Python expression:
 894          o1 <<= o2.
 895
 896        */
 897
 898      PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);
 899
 900        /*
 901          Returns the result of right shifting o1 by o2, possibly in-place or
 902          null on failure.  This is the equivalent of the Python expression:
 903          o1 >>= o2.
 904
 905        */
 906
 907      PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);
 908
 909        /*
 910          Returns the result of bitwise and of o1 and o2, possibly in-place,
 911          or null on failure. This is the equivalent of the Python
 912          expression: o1 &= o2.
 913
 914        */
 915
 916      PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);
 917
 918        /*
 919          Returns the bitwise exclusive or of o1 by o2, possibly in-place, or
 920          null on failure.  This is the equivalent of the Python expression:
 921          o1 ^= o2.
 922
 923        */
 924
 925      PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);
 926
 927        /*
 928          Returns the result of bitwise or of o1 and o2, possibly in-place,
 929          or null on failure.  This is the equivalent of the Python
 930          expression: o1 |= o2.
 931
 932        */
 933
 934
 935 /*  Sequence protocol:*/
 936
 937      PyAPI_FUNC(int) PySequence_Check(PyObject *o);
 938
 939        /*
 940          Return 1 if the object provides sequence protocol, and zero
 941          otherwise.
 942
 943          This function always succeeds.
 944
 945        */
 946
 947      PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);
 948
 949        /*
 950          Return the size of sequence object o, or -1 on failure.
 951
 952        */
 953
 954        /* For DLL compatibility */
 955 #undef PySequence_Length
 956      PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);
 957 #define PySequence_Length PySequence_Size
 958
 959
 960      PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);
 961
 962        /*
 963          Return the concatenation of o1 and o2 on success, and NULL on
 964          failure.   This is the equivalent of the Python
 965          expression: o1+o2.
 966
 967        */
 968
 969      PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count);
 970
 971        /*
 972          Return the result of repeating sequence object o count times,
 973          or NULL on failure.  This is the equivalent of the Python
 974          expression: o1*count.
 975
 976        */
 977
 978      PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i);
 979
 980        /*
 981          Return the ith element of o, or NULL on failure. This is the
 982          equivalent of the Python expression: o[i].
 983        */
 984
 985      PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
 986
 987        /*
 988          Return the slice of sequence object o between i1 and i2, or
 989          NULL on failure. This is the equivalent of the Python
 990          expression: o[i1:i2].
 991
 992        */
 993
 994      PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);
 995
 996        /*
 997          Assign object v to the ith element of o.  Returns
 998          -1 on failure.  This is the equivalent of the Python
 999          statement: o[i]=v.
1000
1001        */
1002
1003      PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);
1004
1005        /*
1006          Delete the ith element of object v.  Returns
1007          -1 on failure.  This is the equivalent of the Python
1008          statement: del o[i].
1009        */
1010
1011      PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2,
1012                                         PyObject *v);
1013
1014        /*
1015          Assign the sequence object, v, to the slice in sequence
1016          object, o, from i1 to i2.  Returns -1 on failure. This is the
1017          equivalent of the Python statement: o[i1:i2]=v.
1018        */
1019
1020      PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);
1021
1022        /*
1023          Delete the slice in sequence object, o, from i1 to i2.
1024          Returns -1 on failure. This is the equivalent of the Python
1025          statement: del o[i1:i2].
1026        */
1027
1028      PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);
1029
1030        /*
1031          Returns the sequence, o, as a tuple on success, and NULL on failure.
1032          This is equivalent to the Python expression: tuple(o)
1033        */
1034
1035
1036      PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);
1037        /*
1038          Returns the sequence, o, as a list on success, and NULL on failure.
1039          This is equivalent to the Python expression: list(o)
1040        */
1041
1042      PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
1043        /*
1044          Returns the sequence, o, as a tuple, unless it's already a
1045          tuple or list.  Use PySequence_Fast_GET_ITEM to access the
1046          members of this list, and PySequence_Fast_GET_SIZE to get its length.
1047
1048          Returns NULL on failure.  If the object does not support iteration,
1049          raises a TypeError exception with m as the message text.
1050        */
1051
1052 #define PySequence_Fast_GET_SIZE(o) \
1053         (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o))
1054        /*
1055          Return the size of o, assuming that o was returned by
1056          PySequence_Fast and is not NULL.
1057        */
1058
1059 #define PySequence_Fast_GET_ITEM(o, i)\
1060      (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i))
1061        /*
1062          Return the ith element of o, assuming that o was returned by
1063          PySequence_Fast, and that i is within bounds.
1064        */
1065
1066 #define PySequence_ITEM(o, i)\
1067         ( o->ob_type->tp_as_sequence->sq_item(o, i) )
1068        /* Assume tp_as_sequence and sq_item exist and that i does not
1069           need to be corrected for a negative index
1070        */
1071
1072 #define PySequence_Fast_ITEMS(sf) \
1073         (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \
1074                           : ((PyTupleObject *)(sf))->ob_item)
1075         /* Return a pointer to the underlying item array for
1076            an object retured by PySequence_Fast */
1077
1078      PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value);
1079
1080        /*
1081          Return the number of occurrences on value on o, that is,
1082          return the number of keys for which o[key]==value.  On
1083          failure, return -1.  This is equivalent to the Python
1084          expression: o.count(value).
1085        */
1086
1087      PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob);
1088        /*
1089          Return -1 if error; 1 if ob in seq; 0 if ob not in seq.
1090          Use __contains__ if possible, else _PySequence_IterSearch().
1091        */
1092
1093 #define PY_ITERSEARCH_COUNT    1
1094 #define PY_ITERSEARCH_INDEX    2
1095 #define PY_ITERSEARCH_CONTAINS 3
1096      PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq,
1097                                         PyObject *obj, int operation);
1098         /*
1099           Iterate over seq.  Result depends on the operation:
1100           PY_ITERSEARCH_COUNT:  return # of times obj appears in seq; -1 if
1101                 error.
1102           PY_ITERSEARCH_INDEX:  return 0-based index of first occurrence of
1103                 obj in seq; set ValueError and return -1 if none found;
1104                 also return -1 on error.
1105           PY_ITERSEARCH_CONTAINS:  return 1 if obj in seq, else 0; -1 on
1106                 error.
1107         */
1108
1109 /* For DLL-level backwards compatibility */
1110 #undef PySequence_In
1111      PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value);
1112
1113 /* For source-level backwards compatibility */
1114 #define PySequence_In PySequence_Contains
1115
1116        /*
1117          Determine if o contains value.  If an item in o is equal to
1118          X, return 1, otherwise return 0.  On error, return -1.  This
1119          is equivalent to the Python expression: value in o.
1120        */
1121
1122      PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value);
1123
1124        /*
1125          Return the first index for which o[i]=value.  On error,
1126          return -1.    This is equivalent to the Python
1127          expression: o.index(value).
1128        */
1129
1130 /* In-place versions of some of the above Sequence functions. */
1131
1132      PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);
1133
1134        /*
1135          Append o2 to o1, in-place when possible. Return the resulting
1136          object, which could be o1, or NULL on failure.  This is the
1137          equivalent of the Python expression: o1 += o2.
1138
1139        */
1140
1141      PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count);
1142
1143        /*
1144          Repeat o1 by count, in-place when possible. Return the resulting
1145          object, which could be o1, or NULL on failure.  This is the
1146          equivalent of the Python expression: o1 *= count.
1147
1148        */
1149
1150 /*  Mapping protocol:*/
1151
1152      PyAPI_FUNC(int) PyMapping_Check(PyObject *o);
1153
1154        /*
1155          Return 1 if the object provides mapping protocol, and zero
1156          otherwise.
1157
1158          This function always succeeds.
1159        */
1160
1161      PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
1162
1163        /*
1164          Returns the number of keys in object o on success, and -1 on
1165          failure.  For objects that do not provide sequence protocol,
1166          this is equivalent to the Python expression: len(o).
1167        */
1168
1169        /* For DLL compatibility */
1170 #undef PyMapping_Length
1171      PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
1172 #define PyMapping_Length PyMapping_Size
1173
1174
1175      /* implemented as a macro:
1176
1177      int PyMapping_DelItemString(PyObject *o, char *key);
1178
1179          Remove the mapping for object, key, from the object *o.
1180          Returns -1 on failure.  This is equivalent to
1181          the Python statement: del o[key].
1182        */
1183 #define PyMapping_DelItemString(O,K) PyObject_DelItemString((O),(K))
1184
1185      /* implemented as a macro:
1186
1187      int PyMapping_DelItem(PyObject *o, PyObject *key);
1188
1189          Remove the mapping for object, key, from the object *o.
1190          Returns -1 on failure.  This is equivalent to
1191          the Python statement: del o[key].
1192        */
1193 #define PyMapping_DelItem(O,K) PyObject_DelItem((O),(K))
1194
1195      PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, char *key);
1196
1197        /*
1198          On success, return 1 if the mapping object has the key, key,
1199          and 0 otherwise.  This is equivalent to the Python expression:
1200          o.has_key(key).
1201
1202          This function always succeeds.
1203        */
1204
1205      PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key);
1206
1207        /*
1208          Return 1 if the mapping object has the key, key,
1209          and 0 otherwise.  This is equivalent to the Python expression:
1210          o.has_key(key).
1211
1212          This function always succeeds.
1213
1214        */
1215
1216      /* Implemented as macro:
1217
1218      PyObject *PyMapping_Keys(PyObject *o);
1219
1220          On success, return a list of the keys in object o.  On
1221          failure, return NULL. This is equivalent to the Python
1222          expression: o.keys().
1223        */
1224 #define PyMapping_Keys(O) PyObject_CallMethod(O,"keys",NULL)
1225
1226      /* Implemented as macro:
1227
1228      PyObject *PyMapping_Values(PyObject *o);
1229
1230          On success, return a list of the values in object o.  On
1231          failure, return NULL. This is equivalent to the Python
1232          expression: o.values().
1233        */
1234 #define PyMapping_Values(O) PyObject_CallMethod(O,"values",NULL)
1235
1236      /* Implemented as macro:
1237
1238      PyObject *PyMapping_Items(PyObject *o);
1239
1240          On success, return a list of the items in object o, where
1241          each item is a tuple containing a key-value pair.  On
1242          failure, return NULL. This is equivalent to the Python
1243          expression: o.items().
1244
1245        */
1246 #define PyMapping_Items(O) PyObject_CallMethod(O,"items",NULL)
1247
1248      PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o, char *key);
1249
1250        /*
1251          Return element of o corresponding to the object, key, or NULL
1252          on failure. This is the equivalent of the Python expression:
1253          o[key].
1254        */
1255
1256      PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, char *key,
1257                                             PyObject *value);
1258
1259        /*
1260          Map the object, key, to the value, v.  Returns
1261          -1 on failure.  This is the equivalent of the Python
1262          statement: o[key]=v.
1263       */
1264
1265
1266 PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass);
1267       /* isinstance(object, typeorclass) */
1268
1269 PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass);
1270       /* issubclass(object, typeorclass) */
1271
1272
1273 #ifdef __cplusplus
1274 }
1275 #endif
1276 #endif /* Py_ABSTRACTOBJECT_H */