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