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