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 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 provides 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      DL_IMPORT(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      DL_IMPORT(int) PyCallable_Check(PyObject *o);
 275
 276        /*
 277          Determine if the object, o, is callable.  Return 1 if the
 278          object is callable and 0 otherwise.
 279
 280          This function always succeeds.
 281
 282        */
 283
 284
 285
 286      DL_IMPORT(PyObject *) PyObject_CallObject(PyObject *callable_object,
 287                                                PyObject *args);
 288
 289        /*
 290
 291          Call a callable Python object, callable_object, with
 292          arguments given by the tuple, args.  If no arguments are
 293          needed, then args may be NULL.  Returns the result of the
 294          call on success, or NULL on failure.  This is the equivalent
 295          of the Python expression: apply(o,args).
 296
 297        */
 298
 299      DL_IMPORT(PyObject *) PyObject_CallFunction(PyObject *callable_object,
 300                                                  char *format, ...);
 301
 302        /*
 303          Call a callable Python object, callable_object, with a
 304          variable number of C arguments. The C arguments are described
 305          using a mkvalue-style format string. The format may be NULL,
 306          indicating that no arguments are provided.  Returns the
 307          result of the call on success, or NULL on failure.  This is
 308          the equivalent of the Python expression: apply(o,args).
 309
 310        */
 311
 312
 313      DL_IMPORT(PyObject *) PyObject_CallMethod(PyObject *o, char *m,
 314                                                char *format, ...);
 315
 316        /*
 317          Call the method named m of object o with a variable number of
 318          C arguments.  The C arguments are described by a mkvalue
 319          format string.  The format may be NULL, indicating that no
 320          arguments are provided. Returns the result of the call on
 321          success, or NULL on failure.  This is the equivalent of the
 322          Python expression: o.method(args).
 323
 324          Note that Special method names, such as "__add__",
 325          "__getitem__", and so on are not supported. The specific
 326          abstract-object routines for these must be used.
 327
 328        */
 329
 330
 331      /* Implemented elsewhere:
 332
 333      long PyObject_Hash(PyObject *o);
 334
 335          Compute and return the hash, hash_value, of an object, o.  On
 336          failure, return -1.  This is the equivalent of the Python
 337          expression: hash(o).
 338
 339        */
 340
 341
 342      /* Implemented elsewhere:
 343
 344      int PyObject_IsTrue(PyObject *o);
 345
 346          Returns 1 if the object, o, is considered to be true, and
 347          0 otherwise. This is equivalent to the Python expression:
 348          not not o
 349
 350          This function always succeeds.
 351
 352        */
 353
 354      /* Implemented elsewhere:
 355
 356      int PyObject_Not(PyObject *o);
 357
 358          Returns 0 if the object, o, is considered to be true, and
 359          1 otherwise. This is equivalent to the Python expression:
 360          not o
 361
 362          This function always succeeds.
 363
 364        */
 365
 366      DL_IMPORT(PyObject *) PyObject_Type(PyObject *o);
 367
 368        /*
 369          On success, returns a type object corresponding to the object
 370          type of object o. On failure, returns NULL.  This is
 371          equivalent to the Python expression: type(o).
 372        */
 373
 374      DL_IMPORT(int) PyObject_Size(PyObject *o);
 375
 376        /*
 377          Return the size of object o.  If the object, o, provides
 378          both sequence and mapping protocols, the sequence size is
 379          returned. On error, -1 is returned.  This is the equivalent
 380          to the Python expression: len(o).
 381
 382        */
 383
 384        /* For DLL compatibility */
 385 #undef PyObject_Length
 386      DL_IMPORT(int) PyObject_Length(PyObject *o);
 387 #define PyObject_Length PyObject_Size
 388
 389
 390      DL_IMPORT(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
 391
 392        /*
 393          Return element of o corresponding to the object, key, or NULL
 394          on failure. This is the equivalent of the Python expression:
 395          o[key].
 396
 397        */
 398
 399      DL_IMPORT(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
 400
 401        /*
 402          Map the object, key, to the value, v.  Returns
 403          -1 on failure.  This is the equivalent of the Python
 404          statement: o[key]=v.
 405        */
 406
 407      DL_IMPORT(int) PyObject_DelItem(PyObject *o, PyObject *key);
 408
 409        /*
 410          Delete the mapping for key from *o.  Returns -1 on failure.
 411          This is the equivalent of the Python statement: del o[key].
 412        */
 413
 414      DL_IMPORT(int) PyObject_AsCharBuffer(PyObject *obj,
 415                                           const char **buffer,
 416                                           int *buffer_len);
 417
 418        /*
 419           Takes an arbitrary object which must support the (character,
 420           single segment) buffer interface and returns a pointer to a
 421           read-only memory location useable as character based input
 422           for subsequent processing.
 423
 424           0 is returned on success.  buffer and buffer_len are only
 425           set in case no error occurrs. Otherwise, -1 is returned and
 426           an exception set.
 427
 428        */
 429
 430      DL_IMPORT(int) PyObject_AsReadBuffer(PyObject *obj,
 431                                           const void **buffer,
 432                                           int *buffer_len);
 433
 434        /*
 435           Same as PyObject_AsCharBuffer() except that this API expects
 436           (readable, single segment) buffer interface and returns a
 437           pointer to a read-only memory location which can contain
 438           arbitrary data.
 439
 440           0 is returned on success.  buffer and buffer_len are only
 441           set in case no error occurrs.  Otherwise, -1 is returned and
 442           an exception set.
 443
 444        */
 445
 446      DL_IMPORT(int) PyObject_AsWriteBuffer(PyObject *obj,
 447                                            void **buffer,
 448                                            int *buffer_len);
 449
 450        /*
 451           Takes an arbitrary object which must support the (writeable,
 452           single segment) buffer interface and returns a pointer to a
 453           writeable memory location in buffer of size buffer_len.
 454
 455           0 is returned on success.  buffer and buffer_len are only
 456           set in case no error occurrs. Otherwise, -1 is returned and
 457           an exception set.
 458
 459        */
 460
 461 /*  Number Protocol:*/
 462
 463      DL_IMPORT(int) PyNumber_Check(PyObject *o);
 464
 465        /*
 466          Returns 1 if the object, o, provides numeric protocols, and
 467          false otherwise.
 468
 469          This function always succeeds.
 470
 471        */
 472
 473      DL_IMPORT(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);
 474
 475        /*
 476          Returns the result of adding o1 and o2, or null on failure.
 477          This is the equivalent of the Python expression: o1+o2.
 478
 479
 480        */
 481
 482      DL_IMPORT(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2);
 483
 484        /*
 485          Returns the result of subtracting o2 from o1, or null on
 486          failure.  This is the equivalent of the Python expression:
 487          o1-o2.
 488
 489        */
 490
 491      DL_IMPORT(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2);
 492
 493        /*
 494          Returns the result of multiplying o1 and o2, or null on
 495          failure.  This is the equivalent of the Python expression:
 496          o1*o2.
 497
 498
 499        */
 500
 501      DL_IMPORT(PyObject *) PyNumber_Divide(PyObject *o1, PyObject *o2);
 502
 503        /*
 504          Returns the result of dividing o1 by o2, or null on failure.
 505          This is the equivalent of the Python expression: o1/o2.
 506
 507
 508        */
 509
 510      DL_IMPORT(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);
 511
 512        /*
 513          Returns the remainder of dividing o1 by o2, or null on
 514          failure.  This is the equivalent of the Python expression:
 515          o1%o2.
 516
 517
 518        */
 519
 520      DL_IMPORT(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);
 521
 522        /*
 523          See the built-in function divmod.  Returns NULL on failure.
 524          This is the equivalent of the Python expression:
 525          divmod(o1,o2).
 526
 527
 528        */
 529
 530      DL_IMPORT(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,
 531                                           PyObject *o3);
 532
 533        /*
 534          See the built-in function pow.  Returns NULL on failure.
 535          This is the equivalent of the Python expression:
 536          pow(o1,o2,o3), where o3 is optional.
 537
 538        */
 539
 540      DL_IMPORT(PyObject *) PyNumber_Negative(PyObject *o);
 541
 542        /*
 543          Returns the negation of o on success, or null on failure.
 544          This is the equivalent of the Python expression: -o.
 545
 546        */
 547
 548      DL_IMPORT(PyObject *) PyNumber_Positive(PyObject *o);
 549
 550        /*
 551          Returns the (what?) of o on success, or NULL on failure.
 552          This is the equivalent of the Python expression: +o.
 553
 554        */
 555
 556      DL_IMPORT(PyObject *) PyNumber_Absolute(PyObject *o);
 557
 558        /*
 559          Returns the absolute value of o, or null on failure.  This is
 560          the equivalent of the Python expression: abs(o).
 561
 562        */
 563
 564      DL_IMPORT(PyObject *) PyNumber_Invert(PyObject *o);
 565
 566        /*
 567          Returns the bitwise negation of o on success, or NULL on
 568          failure.  This is the equivalent of the Python expression:
 569          ~o.
 570
 571
 572        */
 573
 574      DL_IMPORT(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);
 575
 576        /*
 577          Returns the result of left shifting o1 by o2 on success, or
 578          NULL on failure.  This is the equivalent of the Python
 579          expression: o1 << o2.
 580
 581
 582        */
 583
 584      DL_IMPORT(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);
 585
 586        /*
 587          Returns the result of right shifting o1 by o2 on success, or
 588          NULL on failure.  This is the equivalent of the Python
 589          expression: o1 >> o2.
 590
 591        */
 592
 593      DL_IMPORT(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);
 594
 595        /*
 596          Returns the result of bitwise and of o1 and o2 on success, or
 597          NULL on failure. This is the equivalent of the Python
 598          expression: o1&o2.
 599
 600
 601        */
 602
 603      DL_IMPORT(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);
 604
 605        /*
 606          Returns the bitwise exclusive or of o1 by o2 on success, or
 607          NULL on failure.  This is the equivalent of the Python
 608          expression: o1^o2.
 609
 610
 611        */
 612
 613      DL_IMPORT(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);
 614
 615        /*
 616          Returns the result of bitwise or or o1 and o2 on success, or
 617          NULL on failure.  This is the equivalent of the Python
 618          expression: o1|o2.
 619
 620        */
 621
 622      /* Implemented elsewhere:
 623
 624      int PyNumber_Coerce(PyObject **p1, PyObject **p2);
 625
 626          This function takes the addresses of two variables of type
 627          PyObject*.
 628
 629          If the objects pointed to by *p1 and *p2 have the same type,
 630          increment their reference count and return 0 (success).
 631          If the objects can be converted to a common numeric type,
 632          replace *p1 and *p2 by their converted value (with 'new'
 633          reference counts), and return 0.
 634          If no conversion is possible, or if some other error occurs,
 635          return -1 (failure) and don't increment the reference counts.
 636          The call PyNumber_Coerce(&o1, &o2) is equivalent to the Python
 637          statement o1, o2 = coerce(o1, o2).
 638
 639        */
 640
 641      DL_IMPORT(PyObject *) PyNumber_Int(PyObject *o);
 642
 643        /*
 644          Returns the o converted to an integer object on success, or
 645          NULL on failure.  This is the equivalent of the Python
 646          expression: int(o).
 647
 648        */
 649
 650      DL_IMPORT(PyObject *) PyNumber_Long(PyObject *o);
 651
 652        /*
 653          Returns the o converted to a long integer object on success,
 654          or NULL on failure.  This is the equivalent of the Python
 655          expression: long(o).
 656
 657        */
 658
 659      DL_IMPORT(PyObject *) PyNumber_Float(PyObject *o);
 660
 661        /*
 662          Returns the o converted to a float object on success, or NULL
 663          on failure.  This is the equivalent of the Python expression:
 664          float(o).
 665        */
 666
 667 /*  In-place variants of (some of) the above number protocol functions */
 668
 669      DL_IMPORT(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);
 670
 671        /*
 672          Returns the result of adding o2 to o1, possibly in-place, or null
 673          on failure.  This is the equivalent of the Python expression:
 674          o1 += o2.
 675
 676        */
 677
 678      DL_IMPORT(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);
 679
 680        /*
 681          Returns the result of subtracting o2 from o1, possibly in-place or
 682          null on failure.  This is the equivalent of the Python expression:
 683          o1 -= o2.
 684
 685        */
 686
 687      DL_IMPORT(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);
 688
 689        /*
 690          Returns the result of multiplying o1 by o2, possibly in-place, or
 691          null on failure.  This is the equivalent of the Python expression:
 692          o1 *= o2.
 693
 694        */
 695
 696      DL_IMPORT(PyObject *) PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2);
 697
 698        /*
 699          Returns the result of dividing o1 by o2, possibly in-place, or null
 700          on failure.  This is the equivalent of the Python expression:
 701          o1 /= o2.
 702
 703        */
 704
 705      DL_IMPORT(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);
 706
 707        /*
 708          Returns the remainder of dividing o1 by o2, possibly in-place, or
 709          null on failure.  This is the equivalent of the Python expression:
 710          o1 %= o2.
 711
 712        */
 713
 714      DL_IMPORT(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,
 715                                                  PyObject *o3);
 716
 717        /*
 718          Returns the result of raising o1 to the power of o2, possibly
 719          in-place, or null on failure.  This is the equivalent of the Python
 720          expression: o1 **= o2, or pow(o1, o2, o3) if o3 is present.
 721
 722        */
 723
 724      DL_IMPORT(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);
 725
 726        /*
 727          Returns the result of left shifting o1 by o2, possibly in-place, or
 728          null on failure.  This is the equivalent of the Python expression:
 729          o1 <<= o2.
 730
 731        */
 732
 733      DL_IMPORT(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);
 734
 735        /*
 736          Returns the result of right shifting o1 by o2, possibly in-place or
 737          null on failure.  This is the equivalent of the Python expression:
 738          o1 >>= o2.
 739
 740        */
 741
 742      DL_IMPORT(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);
 743
 744        /*
 745          Returns the result of bitwise and of o1 and o2, possibly in-place,
 746          or null on failure. This is the equivalent of the Python
 747          expression: o1 &= o2.
 748
 749        */
 750
 751      DL_IMPORT(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);
 752
 753        /*
 754          Returns the bitwise exclusive or of o1 by o2, possibly in-place, or
 755          null on failure.  This is the equivalent of the Python expression:
 756          o1 ^= o2.
 757
 758        */
 759
 760      DL_IMPORT(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);
 761
 762        /*
 763          Returns the result of bitwise or or o1 and o2, possibly in-place,
 764          or null on failure.  This is the equivalent of the Python
 765          expression: o1 |= o2.
 766
 767        */
 768
 769
 770 /*  Sequence protocol:*/
 771
 772      DL_IMPORT(int) PySequence_Check(PyObject *o);
 773
 774        /*
 775          Return 1 if the object provides sequence protocol, and zero
 776          otherwise.
 777
 778          This function always succeeds.
 779
 780        */
 781
 782      DL_IMPORT(int) PySequence_Size(PyObject *o);
 783
 784        /*
 785          Return the size of sequence object o, or -1 on failure.
 786
 787        */
 788
 789        /* For DLL compatibility */
 790 #undef PySequence_Length
 791      DL_IMPORT(int) PySequence_Length(PyObject *o);
 792 #define PySequence_Length PySequence_Size
 793
 794
 795      DL_IMPORT(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);
 796
 797        /*
 798          Return the concatenation of o1 and o2 on success, and NULL on
 799          failure.   This is the equivalent of the Python
 800          expression: o1+o2.
 801
 802        */
 803
 804      DL_IMPORT(PyObject *) PySequence_Repeat(PyObject *o, int count);
 805
 806        /*
 807          Return the result of repeating sequence object o count times,
 808          or NULL on failure.  This is the equivalent of the Python
 809          expression: o1*count.
 810
 811        */
 812
 813      DL_IMPORT(PyObject *) PySequence_GetItem(PyObject *o, int i);
 814
 815        /*
 816          Return the ith element of o, or NULL on failure. This is the
 817          equivalent of the Python expression: o[i].
 818        */
 819
 820      DL_IMPORT(PyObject *) PySequence_GetSlice(PyObject *o, int i1, int i2);
 821
 822        /*
 823          Return the slice of sequence object o between i1 and i2, or
 824          NULL on failure. This is the equivalent of the Python
 825          expression: o[i1:i2].
 826
 827        */
 828
 829      DL_IMPORT(int) PySequence_SetItem(PyObject *o, int i, PyObject *v);
 830
 831        /*
 832          Assign object v to the ith element of o.  Returns
 833          -1 on failure.  This is the equivalent of the Python
 834          statement: o[i]=v.
 835
 836        */
 837
 838      DL_IMPORT(int) PySequence_DelItem(PyObject *o, int i);
 839
 840        /*
 841          Delete the ith element of object v.  Returns
 842          -1 on failure.  This is the equivalent of the Python
 843          statement: del o[i].
 844        */
 845
 846      DL_IMPORT(int) PySequence_SetSlice(PyObject *o, int i1, int i2,
 847                                         PyObject *v);
 848
 849        /*
 850          Assign the sequence object, v, to the slice in sequence
 851          object, o, from i1 to i2.  Returns -1 on failure. This is the
 852          equivalent of the Python statement: o[i1:i2]=v.
 853        */
 854
 855      DL_IMPORT(int) PySequence_DelSlice(PyObject *o, int i1, int i2);
 856
 857        /*
 858          Delete the slice in sequence object, o, from i1 to i2.
 859          Returns -1 on failure. This is the equivalent of the Python
 860          statement: del o[i1:i2].
 861        */
 862
 863      DL_IMPORT(PyObject *) PySequence_Tuple(PyObject *o);
 864
 865        /*
 866          Returns the sequence, o, as a tuple on success, and NULL on failure.
 867          This is equivalent to the Python expression: tuple(o)
 868        */
 869
 870
 871      DL_IMPORT(PyObject *) PySequence_List(PyObject *o);
 872
 873        /*
 874          Returns the sequence, o, as a list on success, and NULL on failure.
 875          This is equivalent to the Python expression: list(o)
 876        */
 877
 878      DL_IMPORT(PyObject *) PySequence_Fast(PyObject *o, const char* m);
 879
 880        /*
 881          Returns the sequence, o, as a tuple, unless it's already a
 882          tuple or list.  Use PySequence_Fast_GET_ITEM to access the
 883          members of this list.
 884
 885          Returns NULL on failure.  If the object is not a sequence,
 886          raises a TypeError exception with m as the message text.
 887        */
 888
 889 #define PySequence_Fast_GET_ITEM(o, i)\
 890      (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i))
 891
 892        /*
 893          Return the ith element of o, assuming that o was returned by
 894          PySequence_Fast, and that i is within bounds.
 895        */
 896
 897      DL_IMPORT(int) PySequence_Count(PyObject *o, PyObject *value);
 898
 899        /*
 900          Return the number of occurrences on value on o, that is,
 901          return the number of keys for which o[key]==value.  On
 902          failure, return -1.  This is equivalent to the Python
 903          expression: o.count(value).
 904        */
 905
 906      DL_IMPORT(int) PySequence_Contains(PyObject *o, PyObject *value);
 907
 908 /* For DLL-level backwards compatibility */
 909 #undef PySequence_In
 910      DL_IMPORT(int) PySequence_In(PyObject *o, PyObject *value);
 911
 912 /* For source-level backwards compatibility */
 913 #define PySequence_In PySequence_Contains
 914
 915        /*
 916          Determine if o contains value.  If an item in o is equal to
 917          X, return 1, otherwise return 0.  On error, return -1.  This
 918          is equivalent to the Python expression: value in o.
 919        */
 920
 921      DL_IMPORT(int) PySequence_Index(PyObject *o, PyObject *value);
 922
 923        /*
 924          Return the first index for which o[i]=value.  On error,
 925          return -1.    This is equivalent to the Python
 926          expression: o.index(value).
 927        */
 928
 929 /* In-place versions of some of the above Sequence functions. */
 930
 931      DL_IMPORT(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);
 932
 933        /*
 934          Append o2 to o1, in-place when possible. Return the resulting
 935          object, which could be o1, or NULL on failure.  This is the
 936          equivalent of the Python expression: o1 += o2.
 937
 938        */
 939
 940      DL_IMPORT(PyObject *) PySequence_InPlaceRepeat(PyObject *o, int count);
 941
 942        /*
 943          Repeat o1 by count, in-place when possible. Return the resulting
 944          object, which could be o1, or NULL on failure.  This is the
 945          equivalent of the Python expression: o1 *= count.
 946
 947        */
 948
 949 /*  Mapping protocol:*/
 950
 951      DL_IMPORT(int) PyMapping_Check(PyObject *o);
 952
 953        /*
 954          Return 1 if the object provides mapping protocol, and zero
 955          otherwise.
 956
 957          This function always succeeds.
 958        */
 959
 960      DL_IMPORT(int) PyMapping_Size(PyObject *o);
 961
 962        /*
 963          Returns the number of keys in object o on success, and -1 on
 964          failure.  For objects that do not provide sequence protocol,
 965          this is equivalent to the Python expression: len(o).
 966        */
 967
 968        /* For DLL compatibility */
 969 #undef PyMapping_Length
 970      DL_IMPORT(int) PyMapping_Length(PyObject *o);
 971 #define PyMapping_Length PyMapping_Size
 972
 973
 974      /* implemented as a macro:
 975
 976      int PyMapping_DelItemString(PyObject *o, char *key);
 977
 978          Remove the mapping for object, key, from the object *o.
 979          Returns -1 on failure.  This is equivalent to
 980          the Python statement: del o[key].
 981        */
 982 #define PyMapping_DelItemString(O,K) PyDict_DelItemString((O),(K))
 983
 984      /* implemented as a macro:
 985
 986      int PyMapping_DelItem(PyObject *o, PyObject *key);
 987
 988          Remove the mapping for object, key, from the object *o.
 989          Returns -1 on failure.  This is equivalent to
 990          the Python statement: del o[key].
 991        */
 992 #define PyMapping_DelItem(O,K) PyDict_DelItem((O),(K))
 993
 994      DL_IMPORT(int) PyMapping_HasKeyString(PyObject *o, char *key);
 995
 996        /*
 997          On success, return 1 if the mapping object has the key, key,
 998          and 0 otherwise.  This is equivalent to the Python expression:
 999          o.has_key(key).
1000
1001          This function always succeeds.
1002        */
1003
1004      DL_IMPORT(int) PyMapping_HasKey(PyObject *o, PyObject *key);
1005
1006        /*
1007          Return 1 if the mapping object has the key, key,
1008          and 0 otherwise.  This is equivalent to the Python expression:
1009          o.has_key(key).
1010
1011          This function always succeeds.
1012
1013        */
1014
1015      /* Implemented as macro:
1016
1017      PyObject *PyMapping_Keys(PyObject *o);
1018
1019          On success, return a list of the keys in object o.  On
1020          failure, return NULL. This is equivalent to the Python
1021          expression: o.keys().
1022        */
1023 #define PyMapping_Keys(O) PyObject_CallMethod(O,"keys",NULL)
1024
1025      /* Implemented as macro:
1026
1027      PyObject *PyMapping_Values(PyObject *o);
1028
1029          On success, return a list of the values in object o.  On
1030          failure, return NULL. This is equivalent to the Python
1031          expression: o.values().
1032        */
1033 #define PyMapping_Values(O) PyObject_CallMethod(O,"values",NULL)
1034
1035      /* Implemented as macro:
1036
1037      PyObject *PyMapping_Items(PyObject *o);
1038
1039          On success, return a list of the items in object o, where
1040          each item is a tuple containing a key-value pair.  On
1041          failure, return NULL. This is equivalent to the Python
1042          expression: o.items().
1043
1044        */
1045 #define PyMapping_Items(O) PyObject_CallMethod(O,"items",NULL)
1046
1047      DL_IMPORT(PyObject *) PyMapping_GetItemString(PyObject *o, char *key);
1048
1049        /*
1050          Return element of o corresponding to the object, key, or NULL
1051          on failure. This is the equivalent of the Python expression:
1052          o[key].
1053        */
1054
1055      DL_IMPORT(int) PyMapping_SetItemString(PyObject *o, char *key,
1056                                             PyObject *value);
1057
1058        /*
1059          Map the object, key, to the value, v.  Returns
1060          -1 on failure.  This is the equivalent of the Python
1061          statement: o[key]=v.
1062       */
1063
1064
1065 #ifdef __cplusplus
1066 }
1067 #endif
1068 #endif /* Py_ABSTRACTOBJECT_H */