1 #ifndef Py_ABSTRACTOBJECT_H

     2 #define Py_ABSTRACTOBJECT_H

     3 #ifdef __cplusplus

     4 extern "C" {

     5 #endif

     6 

     7 #ifdef PY_SSIZE_T_CLEAN

     8 #define PyObject_CallFunction _PyObject_CallFunction_SizeT

     9 #define PyObject_CallMethod _PyObject_CallMethod_SizeT

    10 #endif

    11 

    12 /* Abstract Object Interface (many thanks to Jim Fulton) */

    13 

    14 /*

    15    PROPOSAL: A Generic Python Object Interface for Python C Modules

    16 

    17 Problem

    18 

    19   Python modules written in C that must access Python objects must do

    20   so through routines whose interfaces are described by a set of

    21   include files.  Unfortunately, these routines vary according to the

    22   object accessed.  To use these routines, the C programmer must check

    23   the type of the object being used and must call a routine based on

    24   the object type.  For example, to access an element of a sequence,

    25   the programmer must determine whether the sequence is a list or a

    26   tuple:

    27 

    28     if(is_tupleobject(o))

    29       e=gettupleitem(o,i)

    30     else if(is_listitem(o))

    31       e=getlistitem(o,i)

    32 

    33   If the programmer wants to get an item from another type of object

    34   that provides sequence behavior, there is no clear way to do it

    35   correctly.  

    36 

    37   The persistent programmer may peruse object.h and find that the

    38   _typeobject structure provides a means of invoking up to (currently

    39   about) 41 special operators.  So, for example, a routine can get an

    40   item from any object that provides sequence behavior. However, to

    41   use this mechanism, the programmer must make their code dependent on

    42   the current Python implementation.

    43 

    44   Also, certain semantics, especially memory management semantics, may

    45   differ by the type of object being used.  Unfortunately, these

    46   semantics are not clearly described in the current include files.

    47   An abstract interface providing more consistent semantics is needed. 

    48 

    49 Proposal

    50 

    51   I propose the creation of a standard interface (with an associated

    52   library of routines and/or macros) for generically obtaining the

    53   services of Python objects.  This proposal can be viewed as one

    54   components of a Python C interface consisting of several components.

    55 

    56   From the viewpoint of C access to Python services, we have (as

    57   suggested by Guido in off-line discussions):

    58 

    59   - "Very high level layer": two or three functions that let you exec or

    60     eval arbitrary Python code given as a string in a module whose name is

    61     given, passing C values in and getting C values out using

    62     mkvalue/getargs style format strings.  This does not require the user

    63     to declare any variables of type "PyObject *".  This should be enough

    64     to write a simple application that gets Python code from the user,

    65     execs it, and returns the output or errors.  (Error handling must also

    66     be part of this API.)

    67 

    68   - "Abstract objects layer": which is the subject of this proposal.

    69     It has many functions operating on objects, and lest you do many

    70     things from C that you can also write in Python, without going

    71     through the Python parser.

    72 

    73   - "Concrete objects layer": This is the public type-dependent

    74     interface provided by the standard built-in types, such as floats,

    75     strings, and lists.  This interface exists and is currently

    76     documented by the collection of include files provided with the

    77     Python distributions.

    78 

    79   From the point of view of Python accessing services provided by C

    80   modules: 

    81 

    82   - "Python module interface": this interface consist of the basic

    83     routines used to define modules and their members.  Most of the

    84     current extensions-writing guide deals with this interface.

    85 

    86   - "Built-in object interface": this is the interface that a new

    87     built-in type must provide and the mechanisms and rules that a

    88     developer of a new built-in type must use and follow.

    89 

    90   This proposal is a "first-cut" that is intended to spur

    91   discussion. See especially the lists of notes.

    92 

    93   The Python C object interface will provide four protocols: object,

    94   numeric, sequence, and mapping.  Each protocol consists of a

    95   collection of related operations.  If an operation that is not

    96   provided by a particular type is invoked, then a standard exception,

    97   NotImplementedError is raised with a operation name as an argument.

    98   In addition, for convenience this interface defines a set of

    99   constructors for building objects of built-in types.  This is needed

   100   so new objects can be returned from C functions that otherwise treat

   101   objects generically.

   102 

   103 Memory Management

   104 

   105   For all of the functions described in this proposal, if a function

   106   retains a reference to a Python object passed as an argument, then the

   107   function will increase the reference count of the object.  It is

   108   unnecessary for the caller to increase the reference count of an

   109   argument in anticipation of the object's retention.

   110 

   111   All Python objects returned from functions should be treated as new

   112   objects.  Functions that return objects assume that the caller will

   113   retain a reference and the reference count of the object has already

   114   been incremented to account for this fact.  A caller that does not

   115   retain a reference to an object that is returned from a function

   116   must decrement the reference count of the object (using

   117   DECREF(object)) to prevent memory leaks.

   118 

   119   Note that the behavior mentioned here is different from the current

   120   behavior for some objects (e.g. lists and tuples) when certain

   121   type-specific routines are called directly (e.g. setlistitem).  The

   122   proposed abstraction layer will provide a consistent memory

   123   management interface, correcting for inconsistent behavior for some

   124   built-in types.

   125 

   126 Protocols

   127 

   128 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/

   129 

   130 /*  Object Protocol: */

   131 

   132      /* Implemented elsewhere:

   133 

   134      int PyObject_Print(PyObject *o, FILE *fp, int flags);

   135 

   136          Print an object, o, on file, fp.  Returns -1 on

   137 	 error.  The flags argument is used to enable certain printing

   138 	 options. The only option currently supported is Py_Print_RAW. 

   139 

   140          (What should be said about Py_Print_RAW?)	

   141 

   142        */

   143 

   144      /* Implemented elsewhere:

   145 

   146      int PyObject_HasAttrString(PyObject *o, char *attr_name);

   147 

   148          Returns 1 if o has the attribute attr_name, and 0 otherwise.

   149 	 This is equivalent to the Python expression:

   150 	 hasattr(o,attr_name). 

   151 

   152 	 This function always succeeds.

   153 

   154        */

   155 

   156      /* Implemented elsewhere:

   157 

   158      PyObject* PyObject_GetAttrString(PyObject *o, char *attr_name);

   159 

   160 	 Retrieve an attributed named attr_name form object o.

   161 	 Returns the attribute value on success, or NULL on failure.

   162 	 This is the equivalent of the Python expression: o.attr_name.

   163 

   164        */

   165 

   166      /* Implemented elsewhere:

   167 

   168      int PyObject_HasAttr(PyObject *o, PyObject *attr_name);

   169 

   170          Returns 1 if o has the attribute attr_name, and 0 otherwise.

   171 	 This is equivalent to the Python expression:

   172 	 hasattr(o,attr_name). 

   173 

   174 	 This function always succeeds.

   175 

   176        */

   177 

   178      /* Implemented elsewhere:

   179 

   180      PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name);

   181 

   182 	 Retrieve an attributed named attr_name form object o.

   183 	 Returns the attribute value on success, or NULL on failure.

   184 	 This is the equivalent of the Python expression: o.attr_name.

   185 

   186        */

   187 

   188 

   189      /* Implemented elsewhere:

   190 

   191      int PyObject_SetAttrString(PyObject *o, char *attr_name, PyObject *v);

   192 

   193 	 Set the value of the attribute named attr_name, for object o,

   194 	 to the value, v. Returns -1 on failure.  This is

   195 	 the equivalent of the Python statement: o.attr_name=v.

   196 

   197        */

   198 

   199      /* Implemented elsewhere:

   200 

   201      int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v);

   202 

   203 	 Set the value of the attribute named attr_name, for object o,

   204 	 to the value, v. Returns -1 on failure.  This is

   205 	 the equivalent of the Python statement: o.attr_name=v.

   206 

   207        */

   208 

   209      /* implemented as a macro:

   210 

   211      int PyObject_DelAttrString(PyObject *o, char *attr_name);

   212 

   213 	 Delete attribute named attr_name, for object o. Returns

   214 	 -1 on failure.  This is the equivalent of the Python

   215 	 statement: del o.attr_name.

   216 

   217        */

   218 #define  PyObject_DelAttrString(O,A) PyObject_SetAttrString((O),(A),NULL)

   219 

   220      /* implemented as a macro:

   221 

   222      int PyObject_DelAttr(PyObject *o, PyObject *attr_name);

   223 

   224 	 Delete attribute named attr_name, for object o. Returns -1

   225 	 on failure.  This is the equivalent of the Python

   226 	 statement: del o.attr_name.

   227 

   228        */

   229 #define  PyObject_DelAttr(O,A) PyObject_SetAttr((O),(A),NULL)

   230 

   231      PyAPI_FUNC(int) PyObject_Cmp(PyObject *o1, PyObject *o2, int *result);

   232 

   233        /*

   234 	 Compare the values of o1 and o2 using a routine provided by

   235 	 o1, if one exists, otherwise with a routine provided by o2.

   236 	 The result of the comparison is returned in result.  Returns

   237 	 -1 on failure.  This is the equivalent of the Python

   238 	 statement: result=cmp(o1,o2).

   239 

   240        */

   241 

   242      /* Implemented elsewhere:

   243 

   244      int PyObject_Compare(PyObject *o1, PyObject *o2);

   245 

   246 	 Compare the values of o1 and o2 using a routine provided by

   247 	 o1, if one exists, otherwise with a routine provided by o2.

   248 	 Returns the result of the comparison on success.  On error,

   249 	 the value returned is undefined. This is equivalent to the

   250 	 Python expression: cmp(o1,o2).

   251 

   252        */

   253 

   254      /* Implemented elsewhere:

   255 

   256      PyObject *PyObject_Repr(PyObject *o);

   257 

   258 	 Compute the string representation of object, o.  Returns the

   259 	 string representation on success, NULL on failure.  This is

   260 	 the equivalent of the Python expression: repr(o).

   261 

   262 	 Called by the repr() built-in function and by reverse quotes.

   263 

   264        */

   265 

   266      /* Implemented elsewhere:

   267 

   268      PyObject *PyObject_Str(PyObject *o);

   269 

   270 	 Compute the string representation of object, o.  Returns the

   271 	 string representation on success, NULL on failure.  This is

   272 	 the equivalent of the Python expression: str(o).)

   273 

   274 	 Called by the str() built-in function and by the print

   275 	 statement.

   276 

   277        */

   278 

   279      /* Implemented elsewhere:

   280 

   281      PyObject *PyObject_Unicode(PyObject *o);

   282 

   283 	 Compute the unicode representation of object, o.  Returns the

   284 	 unicode representation on success, NULL on failure.  This is

   285 	 the equivalent of the Python expression: unistr(o).)

   286 

   287 	 Called by the unistr() built-in function.

   288 

   289        */

   290 

   291        /* Declared elsewhere

   292 

   293      PyAPI_FUNC(int) PyCallable_Check(PyObject *o);

   294 

   295 	 Determine if the object, o, is callable.  Return 1 if the

   296 	 object is callable and 0 otherwise.

   297 

   298 	 This function always succeeds.

   299 

   300        */

   301 

   302 

   303 

   304      PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable_object,

   305 					 PyObject *args, PyObject *kw);

   306 

   307        /*

   308 	 Call a callable Python object, callable_object, with

   309 	 arguments and keywords arguments.  The 'args' argument can not be

   310 	 NULL, but the 'kw' argument can be NULL.

   311 

   312        */

   313      

   314      PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable_object,

   315                                                PyObject *args);

   316 

   317        /*

   318 	 Call a callable Python object, callable_object, with

   319 	 arguments given by the tuple, args.  If no arguments are

   320 	 needed, then args may be NULL.  Returns the result of the

   321 	 call on success, or NULL on failure.  This is the equivalent

   322 	 of the Python expression: apply(o,args).

   323 

   324        */

   325 

   326      PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable_object,

   327                                                  char *format, ...);

   328 

   329        /*

   330 	 Call a callable Python object, callable_object, with a

   331 	 variable number of C arguments. The C arguments are described

   332 	 using a mkvalue-style format string. The format may be NULL,

   333 	 indicating that no arguments are provided.  Returns the

   334 	 result of the call on success, or NULL on failure.  This is

   335 	 the equivalent of the Python expression: apply(o,args).

   336 

   337        */

   338 

   339 

   340      PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *o, char *m,

   341                                                char *format, ...);

   342 

   343        /*

   344 	 Call the method named m of object o with a variable number of

   345 	 C arguments.  The C arguments are described by a mkvalue

   346 	 format string.  The format may be NULL, indicating that no

   347 	 arguments are provided. Returns the result of the call on

   348 	 success, or NULL on failure.  This is the equivalent of the

   349 	 Python expression: o.method(args).

   350        */

   351 

   352      PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable,

   353 							 char *format, ...);

   354      PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *o,

   355 						       char *name,

   356 						       char *format, ...);

   357 

   358      PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable,

   359                                                         ...);

   360 

   361        /*

   362 	 Call a callable Python object, callable_object, with a

   363 	 variable number of C arguments.  The C arguments are provided

   364 	 as PyObject * values, terminated by a NULL.  Returns the

   365 	 result of the call on success, or NULL on failure.  This is

   366 	 the equivalent of the Python expression: apply(o,args).

   367        */

   368 

   369 

   370      PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs(PyObject *o,

   371                                                       PyObject *m, ...);

   372 

   373        /*

   374 	 Call the method named m of object o with a variable number of

   375 	 C arguments.  The C arguments are provided as PyObject *

   376 	 values, terminated by NULL.  Returns the result of the call

   377 	 on success, or NULL on failure.  This is the equivalent of

   378 	 the Python expression: o.method(args).

   379        */

   380 

   381 

   382      /* Implemented elsewhere:

   383 

   384      long PyObject_Hash(PyObject *o);

   385 

   386          Compute and return the hash, hash_value, of an object, o.  On

   387 	 failure, return -1.  This is the equivalent of the Python

   388 	 expression: hash(o).

   389 

   390        */

   391 

   392 

   393      /* Implemented elsewhere:

   394 

   395      int PyObject_IsTrue(PyObject *o);

   396 

   397 	 Returns 1 if the object, o, is considered to be true, 0 if o is

   398 	 considered to be false and -1 on failure. This is equivalent to the

   399 	 Python expression: not not o

   400 

   401        */

   402 

   403      /* Implemented elsewhere:

   404 

   405      int PyObject_Not(PyObject *o);

   406 

   407 	 Returns 0 if the object, o, is considered to be true, 1 if o is

   408 	 considered to be false and -1 on failure. This is equivalent to the

   409 	 Python expression: not o

   410 

   411        */

   412 

   413      PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o);

   414 

   415        /*

   416 	 On success, returns a type object corresponding to the object

   417 	 type of object o. On failure, returns NULL.  This is

   418 	 equivalent to the Python expression: type(o).

   419        */

   420 

   421      PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o);

   422 

   423        /*

   424          Return the size of object o.  If the object, o, provides

   425 	 both sequence and mapping protocols, the sequence size is

   426 	 returned. On error, -1 is returned.  This is the equivalent

   427 	 to the Python expression: len(o).

   428 

   429        */

   430 

   431        /* For DLL compatibility */

   432 #undef PyObject_Length

   433      PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o);

   434 #define PyObject_Length PyObject_Size

   435 

   436      PyAPI_FUNC(Py_ssize_t) _PyObject_LengthHint(PyObject *o);

   437 

   438        /*

   439          Return the size of object o.  If the object, o, provides

   440 	 both sequence and mapping protocols, the sequence size is

   441 	 returned. On error, -1 is returned.  If the object provides

   442 	 a __length_hint__() method, its value is returned.  This is an

   443 	 internal undocumented API provided for performance reasons;

   444 	 for compatibility, don't use it outside the core.  This is the

   445 	 equivalent to the Python expression: 

   446 		try:

   447 			return len(o)

   448 		except (AttributeError, TypeError):

   449 			exc_type, exc_value, exc_tb = sys.exc_info()

   450 			try:

   451 				return o.__length_hint__()

   452 			except:

   453 				pass

   454 			raise exc_type, exc_value, exc_tb

   455        */

   456 

   457      PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);

   458 

   459        /*

   460 	 Return element of o corresponding to the object, key, or NULL

   461 	 on failure. This is the equivalent of the Python expression:

   462 	 o[key].

   463 

   464        */

   465 

   466      PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);

   467 

   468        /*

   469 	 Map the object, key, to the value, v.  Returns

   470 	 -1 on failure.  This is the equivalent of the Python

   471 	 statement: o[key]=v.

   472        */

   473 

   474      PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, char *key);

   475 

   476        /*

   477          Remove the mapping for object, key, from the object *o.

   478          Returns -1 on failure.  This is equivalent to

   479          the Python statement: del o[key].

   480        */

   481 

   482      PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);

   483 

   484        /*

   485 	 Delete the mapping for key from *o.  Returns -1 on failure.

   486 	 This is the equivalent of the Python statement: del o[key].

   487        */

   488 

   489      PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,

   490 					  const char **buffer,

   491 					  Py_ssize_t *buffer_len);

   492 

   493        /* 

   494 	  Takes an arbitrary object which must support the (character,

   495 	  single segment) buffer interface and returns a pointer to a

   496 	  read-only memory location useable as character based input

   497 	  for subsequent processing.

   498 

   499 	  0 is returned on success.  buffer and buffer_len are only

   500 	  set in case no error occurs. Otherwise, -1 is returned and

   501 	  an exception set.

   502 

   503        */

   504 

   505      PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);

   506 

   507       /*  

   508 	  Checks whether an arbitrary object supports the (character,

   509 	  single segment) buffer interface.  Returns 1 on success, 0

   510 	  on failure.

   511 

   512       */

   513 

   514      PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,

   515 					  const void **buffer,

   516 					  Py_ssize_t *buffer_len);

   517 

   518        /* 

   519 	  Same as PyObject_AsCharBuffer() except that this API expects

   520 	  (readable, single segment) buffer interface and returns a

   521 	  pointer to a read-only memory location which can contain

   522 	  arbitrary data.

   523 

   524 	  0 is returned on success.  buffer and buffer_len are only

   525 	  set in case no error occurrs.  Otherwise, -1 is returned and

   526 	  an exception set.

   527 

   528        */

   529 

   530      PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,

   531 					   void **buffer,

   532 					   Py_ssize_t *buffer_len);

   533 

   534        /* 

   535 	  Takes an arbitrary object which must support the (writeable,

   536 	  single segment) buffer interface and returns a pointer to a

   537 	  writeable memory location in buffer of size buffer_len.

   538 

   539 	  0 is returned on success.  buffer and buffer_len are only

   540 	  set in case no error occurrs. Otherwise, -1 is returned and

   541 	  an exception set.

   542 

   543        */

   544 

   545 /* Iterators */

   546 

   547      PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);

   548      /* Takes an object and returns an iterator for it.

   549         This is typically a new iterator but if the argument

   550 	is an iterator, this returns itself. */

   551 

   552 #define PyIter_Check(obj) \

   553     (PyType_HasFeature((obj)->ob_type, Py_TPFLAGS_HAVE_ITER) && \

   554      (obj)->ob_type->tp_iternext != NULL)

   555 

   556      PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);

   557      /* Takes an iterator object and calls its tp_iternext slot,

   558 	returning the next value.  If the iterator is exhausted,

   559 	this returns NULL without setting an exception.

   560 	NULL with an exception means an error occurred. */

   561 

   562 /*  Number Protocol:*/

   563 

   564      PyAPI_FUNC(int) PyNumber_Check(PyObject *o);

   565 

   566        /*

   567          Returns 1 if the object, o, provides numeric protocols, and

   568 	 false otherwise. 

   569 

   570 	 This function always succeeds.

   571 

   572        */

   573 

   574      PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2);

   575 

   576        /*

   577 	 Returns the result of adding o1 and o2, or null on failure.

   578 	 This is the equivalent of the Python expression: o1+o2.

   579 

   580 

   581        */

   582 

   583      PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2);

   584 

   585        /*

   586 	 Returns the result of subtracting o2 from o1, or null on

   587 	 failure.  This is the equivalent of the Python expression:

   588 	 o1-o2.

   589 

   590        */

   591 

   592      PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2);

   593 

   594        /*

   595 	 Returns the result of multiplying o1 and o2, or null on

   596 	 failure.  This is the equivalent of the Python expression:

   597 	 o1*o2.

   598 

   599 

   600        */

   601 

   602      PyAPI_FUNC(PyObject *) PyNumber_Divide(PyObject *o1, PyObject *o2);

   603 

   604        /*

   605 	 Returns the result of dividing o1 by o2, or null on failure.

   606 	 This is the equivalent of the Python expression: o1/o2.

   607 

   608 

   609        */

   610 

   611      PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2);

   612 

   613        /*

   614 	 Returns the result of dividing o1 by o2 giving an integral result,

   615 	 or null on failure.

   616 	 This is the equivalent of the Python expression: o1//o2.

   617 

   618 

   619        */

   620 

   621      PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2);

   622 

   623        /*

   624 	 Returns the result of dividing o1 by o2 giving a float result,

   625 	 or null on failure.

   626 	 This is the equivalent of the Python expression: o1/o2.

   627 

   628 

   629        */

   630 

   631      PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2);

   632 

   633        /*

   634 	 Returns the remainder of dividing o1 by o2, or null on

   635 	 failure.  This is the equivalent of the Python expression:

   636 	 o1%o2.

   637 

   638 

   639        */

   640 

   641      PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2);

   642 

   643        /*

   644 	 See the built-in function divmod.  Returns NULL on failure.

   645 	 This is the equivalent of the Python expression:

   646 	 divmod(o1,o2).

   647 

   648 

   649        */

   650 

   651      PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2,

   652                                           PyObject *o3);

   653 

   654        /*

   655 	 See the built-in function pow.  Returns NULL on failure.

   656 	 This is the equivalent of the Python expression:

   657 	 pow(o1,o2,o3), where o3 is optional.

   658 

   659        */

   660 

   661      PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o);

   662 

   663        /*

   664 	 Returns the negation of o on success, or null on failure.

   665 	 This is the equivalent of the Python expression: -o.

   666 

   667        */

   668 

   669      PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o);

   670 

   671        /*

   672          Returns the (what?) of o on success, or NULL on failure.

   673 	 This is the equivalent of the Python expression: +o.

   674 

   675        */

   676 

   677      PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o);

   678 

   679        /*

   680 	 Returns the absolute value of o, or null on failure.  This is

   681 	 the equivalent of the Python expression: abs(o).

   682 

   683        */

   684 

   685      PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o);

   686 

   687        /*

   688 	 Returns the bitwise negation of o on success, or NULL on

   689 	 failure.  This is the equivalent of the Python expression:

   690 	 ~o.

   691 

   692 

   693        */

   694 

   695      PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2);

   696 

   697        /*

   698 	 Returns the result of left shifting o1 by o2 on success, or

   699 	 NULL on failure.  This is the equivalent of the Python

   700 	 expression: o1 << o2.

   701 

   702 

   703        */

   704 

   705      PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2);

   706 

   707        /*

   708 	 Returns the result of right shifting o1 by o2 on success, or

   709 	 NULL on failure.  This is the equivalent of the Python

   710 	 expression: o1 >> o2.

   711 

   712        */

   713 

   714      PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2);

   715 

   716        /*

   717 	 Returns the result of bitwise and of o1 and o2 on success, or

   718 	 NULL on failure. This is the equivalent of the Python

   719 	 expression: o1&o2.

   720 

   721 

   722        */

   723 

   724      PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2);

   725 

   726        /*

   727 	 Returns the bitwise exclusive or of o1 by o2 on success, or

   728 	 NULL on failure.  This is the equivalent of the Python

   729 	 expression: o1^o2.

   730 

   731 

   732        */

   733 

   734      PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2);

   735 

   736        /*

   737 	 Returns the result of bitwise or on o1 and o2 on success, or

   738 	 NULL on failure.  This is the equivalent of the Python

   739 	 expression: o1|o2.

   740 

   741        */

   742 

   743      /* Implemented elsewhere:

   744 

   745      int PyNumber_Coerce(PyObject **p1, PyObject **p2);

   746 

   747 	 This function takes the addresses of two variables of type

   748 	 PyObject*.

   749 

   750 	 If the objects pointed to by *p1 and *p2 have the same type,

   751 	 increment their reference count and return 0 (success).

   752 	 If the objects can be converted to a common numeric type,

   753 	 replace *p1 and *p2 by their converted value (with 'new'

   754 	 reference counts), and return 0.

   755 	 If no conversion is possible, or if some other error occurs,

   756 	 return -1 (failure) and don't increment the reference counts.

   757 	 The call PyNumber_Coerce(&o1, &o2) is equivalent to the Python

   758 	 statement o1, o2 = coerce(o1, o2).

   759 

   760        */

   761 

   762 #define PyIndex_Check(obj) \

   763    ((obj)->ob_type->tp_as_number != NULL && \

   764     PyType_HasFeature((obj)->ob_type, Py_TPFLAGS_HAVE_INDEX) && \

   765     (obj)->ob_type->tp_as_number->nb_index != NULL)

   766         

   767      PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o);

   768 

   769        /*

   770 	 Returns the object converted to a Python long or int

   771 	 or NULL with an error raised on failure.

   772        */

   773 

   774      PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc);

   775 

   776        /*

   777         Returns the object converted to Py_ssize_t by going through

   778         PyNumber_Index first.  If an overflow error occurs while

   779         converting the int-or-long to Py_ssize_t, then the second argument

   780         is the error-type to return.  If it is NULL, then the overflow error

   781         is cleared and the value is clipped. 

   782        */

   783 

   784      PyAPI_FUNC(PyObject *) PyNumber_Int(PyObject *o);

   785 

   786        /*

   787 	 Returns the o converted to an integer object on success, or

   788 	 NULL on failure.  This is the equivalent of the Python

   789 	 expression: int(o).

   790 

   791        */

   792 

   793      PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o);

   794 

   795        /*

   796 	 Returns the o converted to a long integer object on success,

   797 	 or NULL on failure.  This is the equivalent of the Python

   798 	 expression: long(o).

   799 

   800        */

   801 

   802      PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o);

   803 

   804        /*

   805 	 Returns the o converted to a float object on success, or NULL

   806 	 on failure.  This is the equivalent of the Python expression:

   807 	 float(o).

   808        */

   809 	 

   810 /*  In-place variants of (some of) the above number protocol functions */

   811 

   812      PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2);

   813 

   814        /*

   815 	 Returns the result of adding o2 to o1, possibly in-place, or null

   816 	 on failure.  This is the equivalent of the Python expression:

   817 	 o1 += o2.

   818 

   819        */

   820 

   821      PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2);

   822 

   823        /*

   824 	 Returns the result of subtracting o2 from o1, possibly in-place or

   825 	 null on failure.  This is the equivalent of the Python expression:

   826 	 o1 -= o2.

   827 

   828        */

   829 

   830      PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2);

   831 

   832        /*

   833 	 Returns the result of multiplying o1 by o2, possibly in-place, or

   834 	 null on failure.  This is the equivalent of the Python expression:

   835 	 o1 *= o2.

   836 

   837        */

   838 

   839      PyAPI_FUNC(PyObject *) PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2);

   840 

   841        /*

   842 	 Returns the result of dividing o1 by o2, possibly in-place, or null

   843 	 on failure.  This is the equivalent of the Python expression:

   844 	 o1 /= o2.

   845 

   846        */

   847 

   848      PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1,

   849 						       PyObject *o2);

   850 

   851        /*

   852 	 Returns the result of dividing o1 by o2 giving an integral result,

   853 	 possibly in-place, or null on failure.

   854 	 This is the equivalent of the Python expression:

   855 	 o1 /= o2.

   856 

   857        */

   858 

   859      PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1,

   860 						      PyObject *o2);

   861 

   862        /*

   863 	 Returns the result of dividing o1 by o2 giving a float result,

   864 	 possibly in-place, or null on failure.

   865 	 This is the equivalent of the Python expression:

   866 	 o1 /= o2.

   867 

   868        */

   869 

   870      PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2);

   871 

   872        /*

   873 	 Returns the remainder of dividing o1 by o2, possibly in-place, or

   874 	 null on failure.  This is the equivalent of the Python expression:

   875 	 o1 %= o2.

   876 

   877        */

   878 

   879      PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2,

   880      						 PyObject *o3);

   881 

   882        /*

   883 	 Returns the result of raising o1 to the power of o2, possibly

   884 	 in-place, or null on failure.  This is the equivalent of the Python

   885 	 expression: o1 **= o2, or pow(o1, o2, o3) if o3 is present.

   886 

   887        */

   888 

   889      PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2);

   890 

   891        /*

   892 	 Returns the result of left shifting o1 by o2, possibly in-place, or

   893 	 null on failure.  This is the equivalent of the Python expression:

   894 	 o1 <<= o2.

   895 

   896        */

   897 

   898      PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2);

   899 

   900        /*

   901 	 Returns the result of right shifting o1 by o2, possibly in-place or

   902 	 null on failure.  This is the equivalent of the Python expression:

   903 	 o1 >>= o2.

   904 

   905        */

   906 

   907      PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2);

   908 

   909        /*

   910 	 Returns the result of bitwise and of o1 and o2, possibly in-place,

   911 	 or null on failure. This is the equivalent of the Python

   912 	 expression: o1 &= o2.

   913 

   914        */

   915 

   916      PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2);

   917 

   918        /*

   919 	 Returns the bitwise exclusive or of o1 by o2, possibly in-place, or

   920 	 null on failure.  This is the equivalent of the Python expression:

   921 	 o1 ^= o2.

   922 

   923        */

   924 

   925      PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2);

   926 

   927        /*

   928 	 Returns the result of bitwise or of o1 and o2, possibly in-place,

   929 	 or null on failure.  This is the equivalent of the Python

   930 	 expression: o1 |= o2.

   931 

   932        */

   933 

   934 

   935 /*  Sequence protocol:*/

   936 

   937      PyAPI_FUNC(int) PySequence_Check(PyObject *o);

   938 

   939        /*

   940          Return 1 if the object provides sequence protocol, and zero

   941 	 otherwise.  

   942 

   943 	 This function always succeeds.

   944 

   945        */

   946 

   947      PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o);

   948 

   949        /*

   950          Return the size of sequence object o, or -1 on failure.

   951 

   952        */

   953 

   954        /* For DLL compatibility */

   955 #undef PySequence_Length

   956      PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o);

   957 #define PySequence_Length PySequence_Size

   958 

   959 

   960      PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2);

   961 

   962        /*

   963 	 Return the concatenation of o1 and o2 on success, and NULL on

   964 	 failure.   This is the equivalent of the Python

   965 	 expression: o1+o2.

   966 

   967        */

   968 

   969      PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count);

   970 

   971        /*

   972 	 Return the result of repeating sequence object o count times,

   973 	 or NULL on failure.  This is the equivalent of the Python

   974 	 expression: o1*count.

   975 

   976        */

   977 

   978      PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i);

   979 

   980        /*

   981 	 Return the ith element of o, or NULL on failure. This is the

   982 	 equivalent of the Python expression: o[i].

   983        */

   984 

   985      PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);

   986 

   987        /*

   988 	 Return the slice of sequence object o between i1 and i2, or

   989 	 NULL on failure. This is the equivalent of the Python

   990 	 expression: o[i1:i2].

   991 

   992        */

   993 

   994      PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v);

   995 

   996        /*

   997 	 Assign object v to the ith element of o.  Returns

   998 	 -1 on failure.  This is the equivalent of the Python

   999 	 statement: o[i]=v.

  1000 

  1001        */

  1002 

  1003      PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);

  1004 

  1005        /*

  1006 	 Delete the ith element of object v.  Returns

  1007 	 -1 on failure.  This is the equivalent of the Python

  1008 	 statement: del o[i].

  1009        */

  1010 

  1011      PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2,

  1012                                         PyObject *v);

  1013 

  1014        /*

  1015          Assign the sequence object, v, to the slice in sequence

  1016 	 object, o, from i1 to i2.  Returns -1 on failure. This is the

  1017 	 equivalent of the Python statement: o[i1:i2]=v.

  1018        */

  1019 

  1020      PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2);

  1021 

  1022        /*

  1023 	 Delete the slice in sequence object, o, from i1 to i2.

  1024 	 Returns -1 on failure. This is the equivalent of the Python

  1025 	 statement: del o[i1:i2].

  1026        */

  1027 

  1028      PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);

  1029 

  1030        /*

  1031 	 Returns the sequence, o, as a tuple on success, and NULL on failure.

  1032 	 This is equivalent to the Python expression: tuple(o)

  1033        */

  1034 

  1035 

  1036      PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);

  1037        /*

  1038 	 Returns the sequence, o, as a list on success, and NULL on failure.

  1039 	 This is equivalent to the Python expression: list(o)

  1040        */

  1041 

  1042      PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);

  1043        /*

  1044          Returns the sequence, o, as a tuple, unless it's already a

  1045          tuple or list.  Use PySequence_Fast_GET_ITEM to access the

  1046          members of this list, and PySequence_Fast_GET_SIZE to get its length.

  1047 

  1048          Returns NULL on failure.  If the object does not support iteration,

  1049          raises a TypeError exception with m as the message text.

  1050        */

  1051 

  1052 #define PySequence_Fast_GET_SIZE(o) \

  1053 	(PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o))

  1054        /*

  1055 	 Return the size of o, assuming that o was returned by

  1056          PySequence_Fast and is not NULL.

  1057        */

  1058 

  1059 #define PySequence_Fast_GET_ITEM(o, i)\

  1060      (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i))

  1061        /*

  1062 	 Return the ith element of o, assuming that o was returned by

  1063          PySequence_Fast, and that i is within bounds.

  1064        */

  1065 

  1066 #define PySequence_ITEM(o, i)\

  1067 	( o->ob_type->tp_as_sequence->sq_item(o, i) )

  1068        /* Assume tp_as_sequence and sq_item exist and that i does not

  1069 	  need to be corrected for a negative index

  1070        */     

  1071 

  1072 #define PySequence_Fast_ITEMS(sf) \

  1073 	(PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \

  1074 			  : ((PyTupleObject *)(sf))->ob_item)

  1075 	/* Return a pointer to the underlying item array for

  1076            an object retured by PySequence_Fast */

  1077 

  1078      PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value);

  1079 

  1080        /*

  1081          Return the number of occurrences on value on o, that is,

  1082 	 return the number of keys for which o[key]==value.  On

  1083 	 failure, return -1.  This is equivalent to the Python

  1084 	 expression: o.count(value).

  1085        */

  1086 

  1087      PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob);

  1088        /*

  1089          Return -1 if error; 1 if ob in seq; 0 if ob not in seq.

  1090          Use __contains__ if possible, else _PySequence_IterSearch().

  1091        */

  1092 

  1093 #define PY_ITERSEARCH_COUNT    1

  1094 #define PY_ITERSEARCH_INDEX    2

  1095 #define PY_ITERSEARCH_CONTAINS 3

  1096      PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq,

  1097      					PyObject *obj, int operation);

  1098 	/*

  1099 	  Iterate over seq.  Result depends on the operation:

  1100 	  PY_ITERSEARCH_COUNT:  return # of times obj appears in seq; -1 if

  1101 	  	error.

  1102 	  PY_ITERSEARCH_INDEX:  return 0-based index of first occurrence of

  1103 	  	obj in seq; set ValueError and return -1 if none found;

  1104 	  	also return -1 on error.

  1105 	  PY_ITERSEARCH_CONTAINS:  return 1 if obj in seq, else 0; -1 on

  1106 	  	error.

  1107 	*/

  1108 

  1109 /* For DLL-level backwards compatibility */

  1110 #undef PySequence_In

  1111      PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value);

  1112 

  1113 /* For source-level backwards compatibility */

  1114 #define PySequence_In PySequence_Contains

  1115 

  1116        /*

  1117 	 Determine if o contains value.  If an item in o is equal to

  1118 	 X, return 1, otherwise return 0.  On error, return -1.  This

  1119 	 is equivalent to the Python expression: value in o.

  1120        */

  1121 

  1122      PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value);

  1123 

  1124        /*

  1125 	 Return the first index for which o[i]=value.  On error,

  1126 	 return -1.    This is equivalent to the Python

  1127 	 expression: o.index(value).

  1128        */

  1129 

  1130 /* In-place versions of some of the above Sequence functions. */

  1131 

  1132      PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2);

  1133 

  1134        /*

  1135 	 Append o2 to o1, in-place when possible. Return the resulting