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