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, Py_ssize_t);

   437 

   438        /*

   439          Guess the size of object o using len(o) or o.__length_hint__().

   440          If neither of those return a non-negative value, then return the

   441          default value.  This function never fails. All exceptions are cleared.

   442        */

   443 

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

   445 

   446        /*

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

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

   449 	 o[key].

   450 

   451        */

   452 

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

   454 

   455        /*

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

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

   458 	 statement: o[key]=v.

   459        */

   460 

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

   462 

   463        /*

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

   465          Returns -1 on failure.  This is equivalent to

   466          the Python statement: del o[key].

   467        */

   468 

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

   470 

   471        /*

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

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

   474        */

   475 

   476      PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,

   477 					  const char **buffer,

   478 					  Py_ssize_t *buffer_len);

   479 

   480        /* 

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

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

   483 	  read-only memory location useable as character based input

   484 	  for subsequent processing.

   485 

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

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

   488 	  an exception set.

   489 

   490        */

   491 

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

   493 

   494       /*  

   495 	  Checks whether an arbitrary object supports the (character,

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

   497 	  on failure.

   498 

   499       */

   500 

   501      PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,

   502 					  const void **buffer,

   503 					  Py_ssize_t *buffer_len);

   504 

   505        /* 

   506 	  Same as PyObject_AsCharBuffer() except that this API expects

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

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

   509 	  arbitrary data.

   510 

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

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

   513 	  an exception set.

   514 

   515        */

   516 

   517      PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,

   518 					   void **buffer,

   519 					   Py_ssize_t *buffer_len);

   520 

   521        /* 

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

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

   524 	  writeable memory location in buffer of size buffer_len.

   525 

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

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

   528 	  an exception set.

   529 

   530        */

   531 

   532 	/* new buffer API */

   533 

   534 #define PyObject_CheckBuffer(obj) \

   535 	(((obj)->ob_type->tp_as_buffer != NULL) &&			\

   536 	 (PyType_HasFeature((obj)->ob_type, Py_TPFLAGS_HAVE_NEWBUFFER)) && \

   537 	 ((obj)->ob_type->tp_as_buffer->bf_getbuffer != NULL))

   538 			    

   539 	/* Return 1 if the getbuffer function is available, otherwise 

   540 	   return 0 */

   541 

   542      PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view, 

   543 					int flags);

   544 

   545 	/* This is a C-API version of the getbuffer function call.  It checks

   546        	   to make sure object has the required function pointer and issues the

   547 	   call.  Returns -1 and raises an error on failure and returns 0 on 

   548 	   success

   549         */

   550 

   551 

   552      PyAPI_FUNC(void *) PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices);

   553         

   554         /* Get the memory area pointed to by the indices for the buffer given. 

   555            Note that view->ndim is the assumed size of indices 

   556         */

   557 

   558      PyAPI_FUNC(int) PyBuffer_SizeFromFormat(const char *);

   559 		

   560 	/* Return the implied itemsize of the data-format area from a 

   561 	   struct-style description */

   562     

   563 

   564 	

   565      PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, Py_buffer *view,

   566     					   Py_ssize_t len, char fort);

   567 

   568      PyAPI_FUNC(int) PyBuffer_FromContiguous(Py_buffer *view, void *buf, 

   569     					     Py_ssize_t len, char fort);

   570 

   571 

   572 	/* Copy len bytes of data from the contiguous chunk of memory

   573 	   pointed to by buf into the buffer exported by obj.  Return

   574 	   0 on success and return -1 and raise a PyBuffer_Error on

   575 	   error (i.e. the object does not have a buffer interface or

   576 	   it is not working).

   577 

   578 	   If fort is 'F' and the object is multi-dimensional,

   579 	   then the data will be copied into the array in

   580 	   Fortran-style (first dimension varies the fastest).  If

   581 	   fort is 'C', then the data will be copied into the array

   582 	   in C-style (last dimension varies the fastest).  If fort

   583 	   is 'A', then it does not matter and the copy will be made

   584 	   in whatever way is more efficient.

   585 

   586         */

   587 

   588      PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);

   589         

   590         /* Copy the data from the src buffer to the buffer of destination

   591          */

   592 

   593      PyAPI_FUNC(int) PyBuffer_IsContiguous(Py_buffer *view, char fort);

   594 

   595 

   596      PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims, 

   597 	  					    Py_ssize_t *shape, 

   598 						    Py_ssize_t *strides,

   599 	                                            int itemsize,

   600 	     					    char fort);

   601 

   602        	/*  Fill the strides array with byte-strides of a contiguous

   603             (Fortran-style if fort is 'F' or C-style otherwise)

   604             array of the given shape with the given number of bytes

   605             per element.

   606         */

   607 

   608      PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf,

   609 		             	       Py_ssize_t len, int readonly,

   610 				       int flags);

   611 

   612         /* Fills in a buffer-info structure correctly for an exporter

   613            that can only share a contiguous chunk of memory of

   614            "unsigned bytes" of the given length. Returns 0 on success

   615            and -1 (with raising an error) on error.

   616          */

   617 

   618      PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);

   619 

   620        /* Releases a Py_buffer obtained from getbuffer ParseTuple's s*.

   621         */

   622 

   623      PyAPI_FUNC(PyObject *) PyObject_Format(PyObject* obj,

   624 					    PyObject *format_spec);

   625        /*

   626 	 Takes an arbitrary object and returns the result of

   627 	 calling obj.__format__(format_spec).

   628        */

   629 

   630 /* Iterators */

   631 

   632      PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);

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

   634         This is typically a new iterator but if the argument

   635 	is an iterator, this returns itself. */

   636 

   637 #define PyIter_Check(obj) \

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

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

   640 

   641      PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *);

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

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

   644 	this returns NULL without setting an exception.

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

   646 

   647 /*  Number Protocol:*/

   648 

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

   650 

   651        /*

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

   653 	 false otherwise. 

   654 

   655 	 This function always succeeds.

   656 

   657        */

   658 

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

   660 

   661        /*

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

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

   664 

   665 

   666        */

   667 

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

   669 

   670        /*

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

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

   673 	 o1-o2.

   674 

   675        */

   676 

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

   678 

   679        /*

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

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

   682 	 o1*o2.

   683 

   684 

   685        */

   686 

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

   688 

   689        /*

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

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

   692 

   693 

   694        */

   695 

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

   697 

   698        /*

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

   700 	 or null on failure.

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

   702 

   703 

   704        */

   705 

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

   707 

   708        /*

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

   710 	 or null on failure.

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

   712 

   713 

   714        */

   715 

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

   717 

   718        /*

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

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

   721 	 o1%o2.

   722 

   723 

   724        */

   725 

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

   727 

   728        /*

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

   730 	 This is the equivalent of the Python expression:

   731 	 divmod(o1,o2).

   732 

   733 

   734        */

   735 

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

   737                                           PyObject *o3);

   738 

   739        /*

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

   741 	 This is the equivalent of the Python expression:

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

   743 

   744        */

   745 

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

   747 

   748        /*

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

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

   751 

   752        */

   753 

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

   755 

   756        /*

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

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

   759 

   760        */

   761 

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

   763 

   764        /*

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

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

   767 

   768        */

   769 

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

   771 

   772        /*

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

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

   775 	 ~o.

   776 

   777 

   778        */

   779 

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

   781 

   782        /*

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

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

   785 	 expression: o1 << o2.

   786 

   787 

   788        */

   789 

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

   791 

   792        /*

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

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

   795 	 expression: o1 >> o2.

   796 

   797        */

   798 

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

   800 

   801        /*

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

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

   804 	 expression: o1&o2.

   805 

   806 

   807        */

   808 

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

   810 

   811        /*

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

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

   814 	 expression: o1^o2.

   815 

   816 

   817        */

   818 

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

   820 

   821        /*

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

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

   824 	 expression: o1|o2.

   825 

   826        */

   827 

   828      /* Implemented elsewhere:

   829 

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

   831 

   832 	 This function takes the addresses of two variables of type

   833 	 PyObject*.

   834 

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

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

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

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

   839 	 reference counts), and return 0.

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

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

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

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

   844 

   845        */

   846 

   847 #define PyIndex_Check(obj) \

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

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

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

   851         

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

   853 

   854        /*

   855 	 Returns the object converted to a Python long or int

   856 	 or NULL with an error raised on failure.

   857        */

   858 

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

   860 

   861        /*

   862          Returns the Integral instance converted to an int. The

   863          instance is expected to be int or long or have an __int__

   864          method. Steals integral's reference. error_format will be

   865          used to create the TypeError if integral isn't actually an

   866          Integral instance. error_format should be a format string

   867          that can accept a char* naming integral's type.

   868        */

   869 

   870      PyAPI_FUNC(PyObject *) _PyNumber_ConvertIntegralToInt(

   871              PyObject *integral,

   872              const char* error_format);

   873 

   874        /*

   875         Returns the object converted to Py_ssize_t by going through

   876         PyNumber_Index first.  If an overflow error occurs while

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

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

   879         is cleared and the value is clipped. 

   880        */

   881 

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

   883 

   884        /*

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

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

   887 	 expression: int(o).

   888 

   889        */

   890 

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

   892 

   893        /*

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

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

   896 	 expression: long(o).

   897 

   898        */

   899 

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

   901 

   902        /*

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

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

   905 	 float(o).

   906        */

   907 	 

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

   909 

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

   911 

   912        /*

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

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

   915 	 o1 += o2.

   916 

   917        */

   918 

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

   920 

   921        /*

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

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

   924 	 o1 -= o2.

   925 

   926        */

   927 

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

   929 

   930        /*

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

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

   933 	 o1 *= o2.

   934 

   935        */

   936 

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

   938 

   939        /*

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

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

   942 	 o1 /= o2.

   943 

   944        */

   945 

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

   947 						       PyObject *o2);

   948 

   949        /*

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

   951 	 possibly in-place, or null on failure.

   952 	 This is the equivalent of the Python expression:

   953 	 o1 /= o2.

   954 

   955        */

   956 

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

   958 						      PyObject *o2);

   959 

   960        /*

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

   962 	 possibly in-place, or null on failure.

   963 	 This is the equivalent of the Python expression:

   964 	 o1 /= o2.

   965 

   966        */

   967 

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

   969 

   970        /*

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

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

   973 	 o1 %= o2.

   974 

   975        */

   976 

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

   978      						 PyObject *o3);

   979 

   980        /*

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

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

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

   984 

   985        */

   986 

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

   988 

   989        /*

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

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

   992 	 o1 <<= o2.

   993 

   994        */

   995 

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

   997 

   998        /*

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

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

  1001 	 o1 >>= o2.

  1002 

  1003        */

  1004 

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

  1006 

  1007        /*

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

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

  1010 	 expression: o1 &= o2.

  1011 

  1012        */

  1013 

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

  1015 

  1016        /*

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

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

  1019 	 o1 ^= o2.

  1020 

  1021        */

  1022 

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

  1024 

  1025        /*

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

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

  1028 	 expression: o1 |= o2.

  1029 

  1030        */

  1031 

  1032 

  1033      PyAPI_FUNC(PyObject *) PyNumber_ToBase(PyObject *n, int base);

  1034 

  1035        /*

  1036 	 Returns the integer n converted to a string with a base, with a base

  1037 	 marker of 0b, 0o or 0x prefixed if applicable.

  1038 	 If n is not an int object, it is converted with PyNumber_Index first.

  1039        */

  1040 

  1041 

  1042 /*  Sequence protocol:*/

  1043 

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

  1045 

  1046        /*

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

  1048 	 otherwise.  

  1049 

  1050 	 This function always succeeds.

  1051 

  1052        */

  1053 

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

  1055 

  1056        /*

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

  1058 

  1059        */

  1060 

  1061        /* For DLL compatibility */

  1062 #undef PySequence_Length

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

  1064 #define PySequence_Length PySequence_Size

  1065 

  1066 

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

  1068 

  1069        /*

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

  1071 	 failure.   This is the equivalent of the Python

  1072 	 expression: o1+o2.

  1073 

  1074        */

  1075 

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

  1077 

  1078        /*

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

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

  1081 	 expression: o1*count.

  1082 

  1083        */

  1084 

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

  1086 

  1087        /*

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

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

  1090        */

  1091 

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

  1093 

  1094        /*

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

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

  1097 	 expression: o[i1:i2].

  1098 

  1099        */

  1100 

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

  1102 

  1103        /*

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

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

  1106 	 statement: o[i]=v.

  1107 

  1108        */

  1109 

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

  1111 

  1112        /*

  1113 	 Delete the ith element of object v.  Returns

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

  1115 	 statement: del o[i].

  1116        */

  1117 

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

  1119                                         PyObject *v);

  1120 

  1121        /*

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

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

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

  1125        */

  1126 

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

  1128 

  1129        /*

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

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

  1132 	 statement: del o[i1:i2].

  1133        */

  1134 

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