Include/abstract.h

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