Include/abstract.h

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