Include/abstract.h

   1 #ifndef Py_ABSTRACTOBJECT_H
   2 #define Py_ABSTRACTOBJECT_H
   3 #ifdef __cplusplus
   4 extern "C" {
   5 #endif
   6
   7 /***********************************************************
   8 Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam,
   9 The Netherlands.
  10
  11                         All Rights Reserved
  12
  13 Permission to use, copy, modify, and distribute this software and its
  14 documentation for any purpose and without fee is hereby granted,
  15 provided that the above copyright notice appear in all copies and that
  16 both that copyright notice and this permission notice appear in
  17 supporting documentation, and that the names of Stichting Mathematisch
  18 Centrum or CWI or Corporation for National Research Initiatives or
  19 CNRI not be used in advertising or publicity pertaining to
  20 distribution of the software without specific, written prior
  21 permission.
  22
  23 While CWI is the initial source for this software, a modified version
  24 is made available by the Corporation for National Research Initiatives
  25 (CNRI) at the Internet address ftp://ftp.python.org.
  26
  27 STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
  28 REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
  29 MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
  30 CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
  31 DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  32 PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  33 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  34 PERFORMANCE OF THIS SOFTWARE.
  35
  36 ******************************************************************/
  37
  38 /* Abstract Object Interface (many thanks to Jim Fulton) */
  39
  40 /*
  41    PROPOSAL: A Generic Python Object Interface for Python C Modules
  42
  43 Problem
  44
  45   Python modules written in C that must access Python objects must do
  46   so through routines whose interfaces are described by a set of
  47   include files.  Unfortunately, these routines vary according to the
  48   object accessed.  To use these routines, the C programmer must check
  49   the type of the object being used and must call a routine based on
  50   the object type.  For example, to access an element of a sequence,
  51   the programmer must determine whether the sequence is a list or a
  52   tuple:
  53
  54     if(is_tupleobject(o))
  55       e=gettupleitem(o,i)
  56     else if(is_listitem(o))
  57       e=getlistitem(o,i)
  58
  59   If the programmer wants to get an item from another type of object
  60   that provides sequence behavior, there is no clear way to do it
  61   correctly.
  62
  63   The persistent programmer may peruse object.h and find that the
  64   _typeobject structure provides a means of invoking up to (currently
  65   about) 41 special operators.  So, for example, a routine can get an
  66   item from any object that provides sequence behavior. However, to
  67   use this mechanism, the programmer must make their code dependent on
  68   the current Python implementation.
  69
  70   Also, certain semantics, especially memory management semantics, may
  71   differ by the type of object being used.  Unfortunately, these
  72   semantics are not clearly described in the current include files.
  73   An abstract interface providing more consistent semantics is needed.
  74
  75 Proposal
  76
  77   I propose the creation of a standard interface (with an associated
  78   library of routines and/or macros) for generically obtaining the
  79   services of Python objects.  This proposal can be viewed as one
  80   components of a Python C interface consisting of several components.
  81
  82   From the viewpoint of of C access to Python services, we have (as
  83   suggested by Guido in off-line discussions):
  84
  85   - "Very high level layer": two or three functions that let you exec or
  86     eval arbitrary Python code given as a string in a module whose name is
  87     given, passing C values in and getting C values out using
  88     mkvalue/getargs style format strings.  This does not require the user
  89     to declare any variables of type "PyObject *".  This should be enough
  90     to write a simple application that gets Python code from the user,
  91     execs it, and returns the output or errors.  (Error handling must also
  92     be part of this API.)
  93
  94   - "Abstract objects layer": which is the subject of this proposal.
  95     It has many functions operating on objects, and lest you do many
  96     things from C that you can also write in Python, without going
  97     through the Python parser.
  98
  99   - "Concrete objects layer": This is the public type-dependent
 100     interface provided by the standard built-in types, such as floats,
 101     strings, and lists.  This interface exists and is currently
 102     documented by the collection of include files provides with the
 103     Python distributions.
 104
 105   From the point of view of Python accessing services provided by C
 106   modules:
 107
 108   - "Python module interface": this interface consist of the basic
 109     routines used to define modules and their members.  Most of the
 110     current extensions-writing guide deals with this interface.
 111
 112   - "Built-in object interface": this is the interface that a new
 113     built-in type must provide and the mechanisms and rules that a
 114     developer of a new built-in type must use and follow.
 115
 116   This proposal is a "first-cut" that is intended to spur
 117   discussion. See especially the lists of notes.
 118
 119   The Python C object interface will provide four protocols: object,
 120   numeric, sequence, and mapping.  Each protocol consists of a
 121   collection of related operations.  If an operation that is not
 122   provided by a particular type is invoked, then a standard exception,
 123   NotImplementedError is raised with a operation name as an argument.
 124   In addition, for convenience this interface defines a set of
 125   constructors for building objects of built-in types.  This is needed
 126   so new objects can be returned from C functions that otherwise treat
 127   objects generically.
 128
 129 Memory Management
 130
 131   For all of the functions described in this proposal, if a function
 132   retains a reference to a Python object passed as an argument, then the
 133   function will increase the reference count of the object.  It is
 134   unnecessary for the caller to increase the reference count of an
 135   argument in anticipation of the object's retention.
 136
 137   All Python objects returned from functions should be treated as new
 138   objects.  Functions that return objects assume that the caller will
 139   retain a reference and the reference count of the object has already
 140   been incremented to account for this fact.  A caller that does not
 141   retain a reference to an object that is returned from a function
 142   must decrement the reference count of the object (using
 143   DECREF(object)) to prevent memory leaks.
 144
 145   Note that the behavior mentioned here is different from the current
 146   behavior for some objects (e.g. lists and tuples) when certain
 147   type-specific routines are called directly (e.g. setlistitem).  The
 148   proposed abstraction layer will provide a consistent memory
 149   management interface, correcting for inconsistent behavior for some
 150   built-in types.
 151
 152 Protocols
 153
 154 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/
 155
 156 /*  Object Protocol: */
 157
 158      /* Implemented elsewhere:
 159
 160      int PyObject_Print(PyObject *o, FILE *fp, int flags);
 161
 162          Print an object, o, on file, fp.  Returns -1 on
 163          error.  The flags argument is used to enable certain printing
 164          options. The only option currently supported is Py_Print_RAW.
 165
 166          (What should be said about Py_Print_RAW?)
 167
 168        */
 169
 170      /* Implemented elsewhere:
 171
 172      int PyObject_HasAttrString(PyObject *o, char *attr_name);
 173
 174          Returns 1 if o has the attribute attr_name, and 0 otherwise.
 175          This is equivalent to the Python expression:
 176          hasattr(o,attr_name).
 177
 178          This function always succeeds.
 179
 180        */
 181
 182      /* Implemented elsewhere:
 183
 184      PyObject* PyObject_GetAttrString(PyObject *o, char *attr_name);
 185
 186          Retrieve an attributed named attr_name form object o.
 187          Returns the attribute value on success, or NULL on failure.
 188          This is the equivalent of the Python expression: o.attr_name.
 189
 190        */
 191
 192      /* Implemented elsewhere:
 193
 194      int PyObject_HasAttr(PyObject *o, PyObject *attr_name);
 195
 196          Returns 1 if o has the attribute attr_name, and 0 otherwise.
 197          This is equivalent to the Python expression:
 198          hasattr(o,attr_name).
 199
 200          This function always succeeds.
 201
 202        */
 203
 204      /* Implemented elsewhere:
 205
 206      PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name);
 207
 208          Retrieve an attributed named attr_name form object o.
 209          Returns the attribute value on success, or NULL on failure.
 210          This is the equivalent of the Python expression: o.attr_name.
 211
 212        */
 213
 214
 215      /* Implemented elsewhere:
 216
 217      int PyObject_SetAttrString(PyObject *o, char *attr_name, PyObject *v);
 218
 219          Set the value of the attribute named attr_name, for object o,
 220          to the value, v. Returns -1 on failure.  This is
 221          the equivalent of the Python statement: o.attr_name=v.
 222
 223        */
 224
 225      /* Implemented elsewhere:
 226
 227      int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v);
 228
 229          Set the value of the attribute named attr_name, for object o,
 230          to the value, v. Returns -1 on failure.  This is
 231          the equivalent of the Python statement: o.attr_name=v.
 232
 233        */
 234
 235      /* implemented as a macro:
 236
 237      int PyObject_DelAttrString(PyObject *o, char *attr_name);
 238
 239          Delete attribute named attr_name, for object o. Returns
 240          -1 on failure.  This is the equivalent of the Python
 241          statement: del o.attr_name.
 242
 243        */
 244 #define  PyObject_DelAttrString(O,A) PyObject_SetAttrString((O),(A),NULL)
 245
 246      /* implemented as a macro:
 247
 248      int PyObject_DelAttr(PyObject *o, PyObject *attr_name);
 249
 250          Delete attribute named attr_name, for object o. Returns -1
 251          on failure.  This is the equivalent of the Python
 252          statement: del o.attr_name.
 253
 254        */
 255 #define  PyObject_DelAttr(O,A) PyObject_SetAttr((O),(A),NULL)
 256
 257      DL_IMPORT(int) PyObject_Cmp Py_PROTO((PyObject *o1, PyObject *o2, int *result));
 258
 259        /*
 260          Compare the values of o1 and o2 using a routine provided by
 261          o1, if one exists, otherwise with a routine provided by o2.
 262          The result of the comparison is returned in result.  Returns
 263          -1 on failure.  This is the equivalent of the Python
 264          statement: result=cmp(o1,o2).
 265
 266        */
 267
 268      /* Implemented elsewhere:
 269
 270      int PyObject_Compare(PyObject *o1, PyObject *o2);
 271
 272          Compare the values of o1 and o2 using a routine provided by
 273          o1, if one exists, otherwise with a routine provided by o2.
 274          Returns the result of the comparison on success.  On error,
 275          the value returned is undefined. This is equivalent to the
 276          Python expression: cmp(o1,o2).
 277
 278        */
 279
 280      /* Implemented elsewhere:
 281
 282      PyObject *PyObject_Repr(PyObject *o);
 283
 284          Compute the string representation of object, o.  Returns the
 285          string representation on success, NULL on failure.  This is
 286          the equivalent of the Python expression: repr(o).
 287
 288          Called by the repr() built-in function and by reverse quotes.
 289
 290        */
 291
 292      /* Implemented elsewhere:
 293
 294      PyObject *PyObject_Str(PyObject *o);
 295
 296          Compute the string representation of object, o.  Returns the
 297          string representation on success, NULL on failure.  This is
 298          the equivalent of the Python expression: str(o).)
 299
 300          Called by the str() built-in function and by the print
 301          statement.
 302
 303        */
 304
 305      DL_IMPORT(int) PyCallable_Check Py_PROTO((PyObject *o));
 306
 307        /*
 308          Determine if the object, o, is callable.  Return 1 if the
 309          object is callable and 0 otherwise.
 310
 311          This function always succeeds.
 312
 313        */
 314
 315
 316
 317      DL_IMPORT(PyObject *) PyObject_CallObject Py_PROTO((PyObject *callable_object,
 318                                              PyObject *args));
 319
 320        /*
 321
 322          Call a callable Python object, callable_object, with
 323          arguments given by the tuple, args.  If no arguments are
 324          needed, then args may be NULL.  Returns the result of the
 325          call on success, or NULL on failure.  This is the equivalent
 326          of the Python expression: apply(o,args).
 327
 328        */
 329
 330      DL_IMPORT(PyObject *) PyObject_CallFunction Py_PROTO((PyObject *callable_object,
 331                                                char *format, ...));
 332
 333        /*
 334          Call a callable Python object, callable_object, with a
 335          variable number of C arguments. The C arguments are described
 336          using a mkvalue-style format string. The format may be NULL,
 337          indicating that no arguments are provided.  Returns the
 338          result of the call on success, or NULL on failure.  This is
 339          the equivalent of the Python expression: apply(o,args).
 340
 341        */
 342
 343
 344      DL_IMPORT(PyObject *) PyObject_CallMethod Py_PROTO((PyObject *o, char *m,
 345                                              char *format, ...));
 346
 347        /*
 348          Call the method named m of object o with a variable number of
 349          C arguments.  The C arguments are described by a mkvalue
 350          format string.  The format may be NULL, indicating that no
 351          arguments are provided. Returns the result of the call on
 352          success, or NULL on failure.  This is the equivalent of the
 353          Python expression: o.method(args).
 354
 355          Note that Special method names, such as "__add__",
 356          "__getitem__", and so on are not supported. The specific
 357          abstract-object routines for these must be used.
 358
 359        */
 360
 361
 362      /* Implemented elsewhere:
 363
 364      long PyObject_Hash(PyObject *o);
 365
 366          Compute and return the hash, hash_value, of an object, o.  On
 367          failure, return -1.  This is the equivalent of the Python
 368          expression: hash(o).
 369
 370        */
 371
 372
 373      /* Implemented elsewhere:
 374
 375      int PyObject_IsTrue(PyObject *o);
 376
 377          Returns 1 if the object, o, is considered to be true, and
 378          0 otherwise. This is equivalent to the Python expression:
 379          not not o
 380
 381          This function always succeeds.
 382
 383        */
 384
 385      /* Implemented elsewhere:
 386
 387      int PyObject_Not(PyObject *o);
 388
 389          Returns 0 if the object, o, is considered to be true, and
 390          1 otherwise. This is equivalent to the Python expression:
 391          not o
 392
 393          This function always succeeds.
 394
 395        */
 396
 397      DL_IMPORT(PyObject *) PyObject_Type Py_PROTO((PyObject *o));
 398
 399        /*
 400          On success, returns a type object corresponding to the object
 401          type of object o. On failure, returns NULL.  This is
 402          equivalent to the Python expression: type(o).
 403        */
 404
 405      DL_IMPORT(int) PyObject_Length Py_PROTO((PyObject *o));
 406
 407        /*
 408          Return the length of object o.  If the object, o, provides
 409          both sequence and mapping protocols, the sequence length is
 410          returned. On error, -1 is returned.  This is the equivalent
 411          to the Python expression: len(o).
 412
 413        */
 414
 415      DL_IMPORT(PyObject *) PyObject_GetItem Py_PROTO((PyObject *o, PyObject *key));
 416
 417        /*
 418          Return element of o corresponding to the object, key, or NULL
 419          on failure. This is the equivalent of the Python expression:
 420          o[key].
 421
 422        */
 423
 424      DL_IMPORT(int) PyObject_SetItem Py_PROTO((PyObject *o, PyObject *key, PyObject *v));
 425
 426        /*
 427          Map the object, key, to the value, v.  Returns
 428          -1 on failure.  This is the equivalent of the Python
 429          statement: o[key]=v.
 430        */
 431
 432      DL_IMPORT(int) PyObject_DelItem Py_PROTO((PyObject *o, PyObject *key));
 433
 434        /*
 435          Delete the mapping for key from *o.  Returns -1 on failure.
 436          This is the equivalent of the Python statement: del o[key].
 437        */
 438
 439
 440 /*  Number Protocol:*/
 441
 442      DL_IMPORT(int) PyNumber_Check Py_PROTO((PyObject *o));
 443
 444        /*
 445          Returns 1 if the object, o, provides numeric protocols, and
 446          false otherwise.
 447
 448          This function always succeeds.
 449
 450        */
 451
 452      DL_IMPORT(PyObject *) PyNumber_Add Py_PROTO((PyObject *o1, PyObject *o2));
 453
 454        /*
 455          Returns the result of adding o1 and o2, or null on failure.
 456          This is the equivalent of the Python expression: o1+o2.
 457
 458
 459        */
 460
 461      DL_IMPORT(PyObject *) PyNumber_Subtract Py_PROTO((PyObject *o1, PyObject *o2));
 462
 463        /*
 464          Returns the result of subtracting o2 from o1, or null on
 465          failure.  This is the equivalent of the Python expression:
 466          o1-o2.
 467
 468        */
 469
 470      DL_IMPORT(PyObject *) PyNumber_Multiply Py_PROTO((PyObject *o1, PyObject *o2));
 471
 472        /*
 473          Returns the result of multiplying o1 and o2, or null on
 474          failure.  This is the equivalent of the Python expression:
 475          o1*o2.
 476
 477
 478        */
 479
 480      DL_IMPORT(PyObject *) PyNumber_Divide Py_PROTO((PyObject *o1, PyObject *o2));
 481
 482        /*
 483          Returns the result of dividing o1 by o2, or null on failure.
 484          This is the equivalent of the Python expression: o1/o2.
 485
 486
 487        */
 488
 489      DL_IMPORT(PyObject *) PyNumber_Remainder Py_PROTO((PyObject *o1, PyObject *o2));
 490
 491        /*
 492          Returns the remainder of dividing o1 by o2, or null on
 493          failure.  This is the equivalent of the Python expression:
 494          o1%o2.
 495
 496
 497        */
 498
 499      DL_IMPORT(PyObject *) PyNumber_Divmod Py_PROTO((PyObject *o1, PyObject *o2));
 500
 501        /*
 502          See the built-in function divmod.  Returns NULL on failure.
 503          This is the equivalent of the Python expression:
 504          divmod(o1,o2).
 505
 506
 507        */
 508
 509      DL_IMPORT(PyObject *) PyNumber_Power Py_PROTO((PyObject *o1, PyObject *o2, PyObject *o3));
 510
 511        /*
 512          See the built-in function pow.  Returns NULL on failure.
 513          This is the equivalent of the Python expression:
 514          pow(o1,o2,o3), where o3 is optional.
 515
 516        */
 517
 518      DL_IMPORT(PyObject *) PyNumber_Negative Py_PROTO((PyObject *o));
 519
 520        /*
 521          Returns the negation of o on success, or null on failure.
 522          This is the equivalent of the Python expression: -o.
 523
 524        */
 525
 526      DL_IMPORT(PyObject *) PyNumber_Positive Py_PROTO((PyObject *o));
 527
 528        /*
 529          Returns the (what?) of o on success, or NULL on failure.
 530          This is the equivalent of the Python expression: +o.
 531
 532        */
 533
 534      DL_IMPORT(PyObject *) PyNumber_Absolute Py_PROTO((PyObject *o));
 535
 536        /*
 537          Returns the absolute value of o, or null on failure.  This is
 538          the equivalent of the Python expression: abs(o).
 539
 540        */
 541
 542      DL_IMPORT(PyObject *) PyNumber_Invert Py_PROTO((PyObject *o));
 543
 544        /*
 545          Returns the bitwise negation of o on success, or NULL on
 546          failure.  This is the equivalent of the Python expression:
 547          ~o.
 548
 549
 550        */
 551
 552      DL_IMPORT(PyObject *) PyNumber_Lshift Py_PROTO((PyObject *o1, PyObject *o2));
 553
 554        /*
 555          Returns the result of left shifting o1 by o2 on success, or
 556          NULL on failure.  This is the equivalent of the Python
 557          expression: o1 << o2.
 558
 559
 560        */
 561
 562      DL_IMPORT(PyObject *) PyNumber_Rshift Py_PROTO((PyObject *o1, PyObject *o2));
 563
 564        /*
 565          Returns the result of right shifting o1 by o2 on success, or
 566          NULL on failure.  This is the equivalent of the Python
 567          expression: o1 >> o2.
 568
 569        */
 570
 571      DL_IMPORT(PyObject *) PyNumber_And Py_PROTO((PyObject *o1, PyObject *o2));
 572
 573        /*
 574          Returns the result of bitwise and of o1 and o2 on success, or
 575          NULL on failure. This is the equivalent of the Python
 576          expression: o1&o2.
 577
 578
 579        */
 580
 581      DL_IMPORT(PyObject *) PyNumber_Xor Py_PROTO((PyObject *o1, PyObject *o2));
 582
 583        /*
 584          Returns the bitwise exclusive or of o1 by o2 on success, or
 585          NULL on failure.  This is the equivalent of the Python
 586          expression: o1^o2.
 587
 588
 589        */
 590
 591      DL_IMPORT(PyObject *) PyNumber_Or Py_PROTO((PyObject *o1, PyObject *o2));
 592
 593        /*
 594          Returns the result of bitwise or or o1 and o2 on success, or
 595          NULL on failure.  This is the equivalent of the Python
 596          expression: o1|o2.
 597
 598        */
 599
 600      /* Implemented elsewhere:
 601
 602      int PyNumber_Coerce(PyObject **p1, PyObject **p2);
 603
 604          This function takes the addresses of two variables of type
 605          PyObject*.
 606
 607          If the objects pointed to by *p1 and *p2 have the same type,
 608          increment their reference count and return 0 (success).
 609          If the objects can be converted to a common numeric type,
 610          replace *p1 and *p2 by their converted value (with 'new'
 611          reference counts), and return 0.
 612          If no conversion is possible, or if some other error occurs,
 613          return -1 (failure) and don't increment the reference counts.
 614          The call PyNumber_Coerce(&o1, &o2) is equivalent to the Python
 615          statement o1, o2 = coerce(o1, o2).
 616
 617        */
 618
 619      DL_IMPORT(PyObject *) PyNumber_Int Py_PROTO((PyObject *o));
 620
 621        /*
 622          Returns the o converted to an integer object on success, or
 623          NULL on failure.  This is the equivalent of the Python
 624          expression: int(o).
 625
 626        */
 627
 628      DL_IMPORT(PyObject *) PyNumber_Long Py_PROTO((PyObject *o));
 629
 630        /*
 631          Returns the o converted to a long integer object on success,
 632          or NULL on failure.  This is the equivalent of the Python
 633          expression: long(o).
 634
 635        */
 636
 637      DL_IMPORT(PyObject *) PyNumber_Float Py_PROTO((PyObject *o));
 638
 639        /*
 640          Returns the o converted to a float object on success, or NULL
 641          on failure.  This is the equivalent of the Python expression:
 642          float(o).
 643        */
 644
 645
 646 /*  Sequence protocol:*/
 647
 648      DL_IMPORT(int) PySequence_Check Py_PROTO((PyObject *o));
 649
 650        /*
 651          Return 1 if the object provides sequence protocol, and zero
 652          otherwise.
 653
 654          This function always succeeds.
 655
 656        */
 657
 658      DL_IMPORT(int) PySequence_Length Py_PROTO((PyObject *o));
 659
 660        /*
 661          Return the length of sequence object o, or -1 on failure.
 662
 663        */
 664
 665      DL_IMPORT(PyObject *) PySequence_Concat Py_PROTO((PyObject *o1, PyObject *o2));
 666
 667        /*
 668          Return the concatination of o1 and o2 on success, and NULL on
 669          failure.   This is the equivalent of the Python
 670          expression: o1+o2.
 671
 672        */
 673
 674      DL_IMPORT(PyObject *) PySequence_Repeat Py_PROTO((PyObject *o, int count));
 675
 676        /*
 677          Return the result of repeating sequence object o count times,
 678          or NULL on failure.  This is the equivalent of the Python
 679          expression: o1*count.
 680
 681        */
 682
 683      DL_IMPORT(PyObject *) PySequence_GetItem Py_PROTO((PyObject *o, int i));
 684
 685        /*
 686          Return the ith element of o, or NULL on failure. This is the
 687          equivalent of the Python expression: o[i].
 688
 689        */
 690
 691      DL_IMPORT(PyObject *) PySequence_GetSlice Py_PROTO((PyObject *o, int i1, int i2));
 692
 693        /*
 694          Return the slice of sequence object o between i1 and i2, or
 695          NULL on failure. This is the equivalent of the Python
 696          expression: o[i1:i2].
 697
 698        */
 699
 700      DL_IMPORT(int) PySequence_SetItem Py_PROTO((PyObject *o, int i, PyObject *v));
 701
 702        /*
 703          Assign object v to the ith element of o.  Returns
 704          -1 on failure.  This is the equivalent of the Python
 705          statement: o[i]=v.
 706
 707        */
 708
 709      DL_IMPORT(int) PySequence_DelItem Py_PROTO((PyObject *o, int i));
 710
 711        /*
 712          Delete the ith element of object v.  Returns
 713          -1 on failure.  This is the equivalent of the Python
 714          statement: del o[i].
 715        */
 716
 717      DL_IMPORT(int) PySequence_SetSlice Py_PROTO((PyObject *o, int i1, int i2, PyObject *v));
 718
 719        /*
 720          Assign the sequence object, v, to the slice in sequence
 721          object, o, from i1 to i2.  Returns -1 on failure. This is the
 722          equivalent of the Python statement: o[i1:i2]=v.
 723        */
 724
 725      DL_IMPORT(int) PySequence_DelSlice Py_PROTO((PyObject *o, int i1, int i2));
 726
 727        /*
 728          Delete the slice in sequence object, o, from i1 to i2.
 729          Returns -1 on failure. This is the equivalent of the Python
 730          statement: del o[i1:i2].
 731        */
 732
 733      DL_IMPORT(PyObject *) PySequence_Tuple Py_PROTO((PyObject *o));
 734
 735        /*
 736          Returns the sequence, o, as a tuple on success, and NULL on failure.
 737          This is equivalent to the Python expression: tuple(o)
 738        */
 739
 740      DL_IMPORT(PyObject *) PySequence_List Py_PROTO((PyObject *o));
 741
 742        /*
 743          Returns the sequence, o, as a list on success, and NULL on failure.
 744          This is equivalent to the Python expression: list(o)
 745        */
 746
 747      DL_IMPORT(int) PySequence_Count Py_PROTO((PyObject *o, PyObject *value));
 748
 749        /*
 750          Return the number of occurrences on value on o, that is,
 751          return the number of keys for which o[key]==value.  On
 752          failure, return -1.  This is equivalent to the Python
 753          expression: o.count(value).
 754        */
 755
 756      DL_IMPORT(int) PySequence_Contains Py_PROTO((PyObject *o, PyObject *value));
 757 #define PySequence_In PySequence_Contains
 758
 759        /*
 760          Determine if o contains value.  If an item in o is equal to
 761          X, return 1, otherwise return 0.  On error, return -1.  This
 762          is equivalent to the Python expression: value in o.
 763        */
 764
 765      DL_IMPORT(int) PySequence_Index Py_PROTO((PyObject *o, PyObject *value));
 766
 767        /*
 768          Return the first index for which o[i]=value.  On error,
 769          return -1.    This is equivalent to the Python
 770          expression: o.index(value).
 771        */
 772
 773 /*  Mapping protocol:*/
 774
 775      DL_IMPORT(int) PyMapping_Check Py_PROTO((PyObject *o));
 776
 777        /*
 778          Return 1 if the object provides mapping protocol, and zero
 779          otherwise.
 780
 781          This function always succeeds.
 782        */
 783
 784      DL_IMPORT(int) PyMapping_Length Py_PROTO((PyObject *o));
 785
 786        /*
 787          Returns the number of keys in object o on success, and -1 on
 788          failure.  For objects that do not provide sequence protocol,
 789          this is equivalent to the Python expression: len(o).
 790        */
 791
 792      /* implemented as a macro:
 793
 794      int PyMapping_DelItemString Py_PROTO((PyObject *o, char *key));
 795
 796          Remove the mapping for object, key, from the object *o.
 797          Returns -1 on failure.  This is equivalent to
 798          the Python statement: del o[key].
 799        */
 800 #define PyMapping_DelItemString(O,K) PyDict_DelItemString((O),(K))
 801
 802      /* implemented as a macro:
 803
 804      int PyMapping_DelItem Py_PROTO((PyObject *o, PyObject *key));
 805
 806          Remove the mapping for object, key, from the object *o.
 807          Returns -1 on failure.  This is equivalent to
 808          the Python statement: del o[key].
 809        */
 810 #define PyMapping_DelItem(O,K) PyDict_DelItem((O),(K))
 811
 812      DL_IMPORT(int) PyMapping_HasKeyString Py_PROTO((PyObject *o, char *key));
 813
 814        /*
 815          On success, return 1 if the mapping object has the key, key,
 816          and 0 otherwise.  This is equivalent to the Python expression:
 817          o.has_key(key).
 818
 819          This function always succeeds.
 820        */
 821
 822      DL_IMPORT(int) PyMapping_HasKey Py_PROTO((PyObject *o, PyObject *key));
 823
 824        /*
 825          Return 1 if the mapping object has the key, key,
 826          and 0 otherwise.  This is equivalent to the Python expression:
 827          o.has_key(key).
 828
 829          This function always succeeds.
 830
 831        */
 832
 833      /* Implemented as macro:
 834
 835      PyObject *PyMapping_Keys(PyObject *o);
 836
 837          On success, return a list of the keys in object o.  On
 838          failure, return NULL. This is equivalent to the Python
 839          expression: o.keys().
 840        */
 841 #define PyMapping_Keys(O) PyObject_CallMethod(O,"keys",NULL)
 842
 843      /* Implemented as macro:
 844
 845      PyObject *PyMapping_Values(PyObject *o);
 846
 847          On success, return a list of the values in object o.  On
 848          failure, return NULL. This is equivalent to the Python
 849          expression: o.values().
 850        */
 851 #define PyMapping_Values(O) PyObject_CallMethod(O,"values",NULL)
 852
 853      /* Implemented as macro:
 854
 855      PyObject *PyMapping_Items(PyObject *o);
 856
 857          On success, return a list of the items in object o, where
 858          each item is a tuple containing a key-value pair.  On
 859          failure, return NULL. This is equivalent to the Python
 860          expression: o.items().
 861
 862        */
 863 #define PyMapping_Items(O) PyObject_CallMethod(O,"items",NULL)
 864
 865      DL_IMPORT(PyObject *) PyMapping_GetItemString Py_PROTO((PyObject *o, char *key));
 866
 867        /*
 868          Return element of o corresponding to the object, key, or NULL
 869          on failure. This is the equivalent of the Python expression:
 870          o[key].
 871        */
 872
 873      DL_IMPORT(int) PyMapping_SetItemString Py_PROTO((PyObject *o, char *key,
 874                                            PyObject *value));
 875
 876        /*
 877          Map the object, key, to the value, v.  Returns
 878          -1 on failure.  This is the equivalent of the Python
 879          statement: o[key]=v.
 880       */
 881
 882
 883 #ifdef __cplusplus
 884 }
 885 #endif
 886 #endif /* Py_ABSTRACTOBJECT_H */