1#ifndef Py_ABSTRACTOBJECT_H 2#define Py_ABSTRACTOBJECT_H 3#ifdef __cplusplus 4extern "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 17Problem 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 49Proposal 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 103Memory 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 126Protocols 127 128xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx*/ 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. If one of the calls fails, this function returns -1. 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 occurs. 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 occurs. 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 (obj)->ob_type->tp_iternext != &_PyObject_NextNotImplemented) 641 642 PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *); 643 /* Takes an iterator object and calls its tp_iternext slot, 644 returning the next value. If the iterator is exhausted, 645 this returns NULL without setting an exception. 646 NULL with an exception means an error occurred. */ 647 648/* Number Protocol:*/ 649 650 PyAPI_FUNC(int) PyNumber_Check(PyObject *o); 651 652 /* 653 Returns 1 if the object, o, provides numeric protocols, and 654 false otherwise. 655 656 This function always succeeds. 657 658 */ 659 660 PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2); 661 662 /* 663 Returns the result of adding o1 and o2, or null on failure. 664 This is the equivalent of the Python expression: o1+o2. 665 666 667 */ 668 669 PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2); 670 671 /* 672 Returns the result of subtracting o2 from o1, or null on 673 failure. This is the equivalent of the Python expression: 674 o1-o2. 675 676 */ 677 678 PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2); 679 680 /* 681 Returns the result of multiplying o1 and o2, or null on 682 failure. This is the equivalent of the Python expression: 683 o1*o2. 684 685 686 */ 687 688 PyAPI_FUNC(PyObject *) PyNumber_Divide(PyObject *o1, PyObject *o2); 689 690 /* 691 Returns the result of dividing o1 by o2, or null on failure. 692 This is the equivalent of the Python expression: o1/o2. 693 694 695 */ 696 697 PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2); 698 699 /* 700 Returns the result of dividing o1 by o2 giving an integral result, 701 or null on failure. 702 This is the equivalent of the Python expression: o1//o2. 703 704 705 */ 706 707 PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2); 708 709 /* 710 Returns the result of dividing o1 by o2 giving a float result, 711 or null on failure. 712 This is the equivalent of the Python expression: o1/o2. 713 714 715 */ 716 717 PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2); 718 719 /* 720 Returns the remainder of dividing o1 by o2, or null on 721 failure. This is the equivalent of the Python expression: 722 o1%o2. 723 724 725 */ 726 727 PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2); 728 729 /* 730 See the built-in function divmod. Returns NULL on failure. 731 This is the equivalent of the Python expression: 732 divmod(o1,o2). 733 734 735 */ 736 737 PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2, 738 PyObject *o3); 739 740 /* 741 See the built-in function pow. Returns NULL on failure. 742 This is the equivalent of the Python expression: 743 pow(o1,o2,o3), where o3 is optional. 744 745 */ 746 747 PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o); 748 749 /* 750 Returns the negation of o on success, or null on failure. 751 This is the equivalent of the Python expression: -o. 752 753 */ 754 755 PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o); 756 757 /* 758 Returns the (what?) of o on success, or NULL on failure. 759 This is the equivalent of the Python expression: +o. 760 761 */ 762 763 PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o); 764 765 /* 766 Returns the absolute value of o, or null on failure. This is 767 the equivalent of the Python expression: abs(o). 768 769 */ 770 771 PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o); 772 773 /* 774 Returns the bitwise negation of o on success, or NULL on 775 failure. This is the equivalent of the Python expression: 776 ~o. 777 778 779 */ 780 781 PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2); 782 783 /* 784 Returns the result of left shifting o1 by o2 on success, or 785 NULL on failure. This is the equivalent of the Python 786 expression: o1 << o2. 787 788 789 */ 790 791 PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2); 792 793 /* 794 Returns the result of right shifting o1 by o2 on success, or 795 NULL on failure. This is the equivalent of the Python 796 expression: o1 >> o2. 797 798 */ 799 800 PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2); 801 802 /* 803 Returns the result of bitwise and of o1 and o2 on success, or 804 NULL on failure. This is the equivalent of the Python 805 expression: o1&o2. 806 807 808 */ 809 810 PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2); 811 812 /* 813 Returns the bitwise exclusive or of o1 by o2 on success, or 814 NULL on failure. This is the equivalent of the Python 815 expression: o1^o2. 816 817 818 */ 819 820 PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2); 821 822 /* 823 Returns the result of bitwise or on o1 and o2 on success, or 824 NULL on failure. This is the equivalent of the Python 825 expression: o1|o2. 826 827 */ 828 829 /* Implemented elsewhere: 830 831 int PyNumber_Coerce(PyObject **p1, PyObject **p2); 832 833 This function takes the addresses of two variables of type 834 PyObject*. 835 836 If the objects pointed to by *p1 and *p2 have the same type, 837 increment their reference count and return 0 (success). 838 If the objects can be converted to a common numeric type, 839 replace *p1 and *p2 by their converted value (with 'new' 840 reference counts), and return 0. 841 If no conversion is possible, or if some other error occurs, 842 return -1 (failure) and don't increment the reference counts. 843 The call PyNumber_Coerce(&o1, &o2) is equivalent to the Python 844 statement o1, o2 = coerce(o1, o2). 845 846 */ 847 848#define PyIndex_Check(obj) \ 849 ((obj)->ob_type->tp_as_number != NULL && \ 850 PyType_HasFeature((obj)->ob_type, Py_TPFLAGS_HAVE_INDEX) && \ 851 (obj)->ob_type->tp_as_number->nb_index != NULL) 852 853 PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o); 854 855 /* 856 Returns the object converted to a Python long or int 857 or NULL with an error raised on failure. 858 */ 859 860 PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc); 861 862 /* 863 Returns the Integral instance converted to an int. The 864 instance is expected to be int or long or have an __int__ 865 method. Steals integral's reference. error_format will be 866 used to create the TypeError if integral isn't actually an 867 Integral instance. error_format should be a format string 868 that can accept a char* naming integral's type. 869 */ 870 871 PyAPI_FUNC(PyObject *) _PyNumber_ConvertIntegralToInt( 872 PyObject *integral, 873 const char* error_format); 874 875 /* 876 Returns the object converted to Py_ssize_t by going through 877 PyNumber_Index first. If an overflow error occurs while 878 converting the int-or-long to Py_ssize_t, then the second argument 879 is the error-type to return. If it is NULL, then the overflow error 880 is cleared and the value is clipped. 881 */ 882 883 PyAPI_FUNC(PyObject *) PyNumber_Int(PyObject *o); 884 885 /* 886 Returns the o converted to an integer object on success, or 887 NULL on failure. This is the equivalent of the Python 888 expression: int(o). 889 890 */ 891 892 PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o); 893 894 /* 895 Returns the o converted to a long integer object on success, 896 or NULL on failure. This is the equivalent of the Python 897 expression: long(o). 898 899 */ 900 901 PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o); 902 903 /* 904 Returns the o converted to a float object on success, or NULL 905 on failure. This is the equivalent of the Python expression: 906 float(o). 907 */ 908 909/* In-place variants of (some of) the above number protocol functions */ 910 911 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2); 912 913 /* 914 Returns the result of adding o2 to o1, possibly in-place, or null 915 on failure. This is the equivalent of the Python expression: 916 o1 += o2. 917 918 */ 919 920 PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2); 921 922 /* 923 Returns the result of subtracting o2 from o1, possibly in-place or 924 null on failure. This is the equivalent of the Python expression: 925 o1 -= o2. 926 927 */ 928 929 PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2); 930 931 /* 932 Returns the result of multiplying o1 by o2, possibly in-place, or 933 null on failure. This is the equivalent of the Python expression: 934 o1 *= o2. 935 936 */ 937 938 PyAPI_FUNC(PyObject *) PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2); 939 940 /* 941 Returns the result of dividing o1 by o2, possibly in-place, or null 942 on failure. This is the equivalent of the Python expression: 943 o1 /= o2. 944 945 */ 946 947 PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1, 948 PyObject *o2); 949 950 /* 951 Returns the result of dividing o1 by o2 giving an integral result, 952 possibly in-place, or null on failure. 953 This is the equivalent of the Python expression: 954 o1 /= o2. 955 956 */ 957 958 PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1, 959 PyObject *o2); 960 961 /* 962 Returns the result of dividing o1 by o2 giving a float result, 963 possibly in-place, or null on failure. 964 This is the equivalent of the Python expression: 965 o1 /= o2. 966 967 */ 968 969 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2); 970 971 /* 972 Returns the remainder of dividing o1 by o2, possibly in-place, or 973 null on failure. This is the equivalent of the Python expression: 974 o1 %= o2. 975 976 */ 977 978 PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2, 979 PyObject *o3); 980 981 /* 982 Returns the result of raising o1 to the power of o2, possibly 983 in-place, or null on failure. This is the equivalent of the Python 984 expression: o1 **= o2, or pow(o1, o2, o3) if o3 is present. 985 986 */ 987 988 PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2); 989 990 /* 991 Returns the result of left shifting o1 by o2, possibly in-place, or 992 null on failure. This is the equivalent of the Python expression: 993 o1 <<= o2. 994 995 */ 996 997 PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2); 998 999 /* 1000 Returns the result of right shifting o1 by o2, possibly in-place or 1001 null on failure. This is the equivalent of the Python expression: 1002 o1 >>= o2. 1003 1004 */ 1005 1006 PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2); 1007 1008 /* 1009 Returns the result of bitwise and of o1 and o2, possibly in-place, 1010 or null on failure. This is the equivalent of the Python 1011 expression: o1 &= o2. 1012 1013 */ 1014 1015 PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2); 1016 1017 /* 1018 Returns the bitwise exclusive or of o1 by o2, possibly in-place, or 1019 null on failure. This is the equivalent of the Python expression: 1020 o1 ^= o2. 1021 1022 */ 1023 1024 PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2); 1025 1026 /* 1027 Returns the result of bitwise or of o1 and o2, possibly in-place, 1028 or null on failure. This is the equivalent of the Python 1029 expression: o1 |= o2. 1030 1031 */ 1032 1033 1034 PyAPI_FUNC(PyObject *) PyNumber_ToBase(PyObject *n, int base); 1035 1036 /* 1037 Returns the integer n converted to a string with a base, with a base 1038 marker of 0b, 0o or 0x prefixed if applicable. 1039 If n is not an int object, it is converted with PyNumber_Index first. 1040 */ 1041 1042 1043/* Sequence protocol:*/ 1044 1045 PyAPI_FUNC(int) PySequence_Check(PyObject *o); 1046 1047 /* 1048 Return 1 if the object provides sequence protocol, and zero 1049 otherwise. 1050 1051 This function always succeeds. 1052 1053 */ 1054 1055 PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o); 1056 1057 /* 1058 Return the size of sequence object o, or -1 on failure. 1059 1060 */ 1061 1062 /* For DLL compatibility */ 1063#undef PySequence_Length 1064 PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o); 1065#define PySequence_Length PySequence_Size 1066 1067 1068 PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2); 1069 1070 /* 1071 Return the concatenation of o1 and o2 on success, and NULL on 1072 failure. This is the equivalent of the Python 1073 expression: o1+o2. 1074 1075 */ 1076 1077 PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count); 1078 1079 /* 1080 Return the result of repeating sequence object o count times, 1081 or NULL on failure. This is the equivalent of the Python 1082 expression: o1*count. 1083 1084 */ 1085 1086 PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i); 1087 1088 /* 1089 Return the ith element of o, or NULL on failure. This is the 1090 equivalent of the Python expression: o[i]. 1091 */ 1092 1093 PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2); 1094 1095 /* 1096 Return the slice of sequence object o between i1 and i2, or 1097 NULL on failure. This is the equivalent of the Python 1098 expression: o[i1:i2]. 1099 1100 */ 1101 1102 PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v); 1103 1104 /* 1105 Assign object v to the ith element of o. Returns 1106 -1 on failure. This is the equivalent of the Python 1107 statement: o[i]=v. 1108 1109 */ 1110 1111 PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i); 1112 1113 /* 1114 Delete the ith element of object v. Returns 1115 -1 on failure. This is the equivalent of the Python 1116 statement: del o[i]. 1117 */ 1118 1119 PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, 1120 PyObject *v); 1121 1122 /* 1123 Assign the sequence object, v, to the slice in sequence 1124 object, o, from i1 to i2. Returns -1 on failure. This is the 1125 equivalent of the Python statement: o[i1:i2]=v. 1126 */ 1127 1128 PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2); 1129 1130 /* 1131 Delete the slice in sequence object, o, from i1 to i2. 1132 Returns -1 on failure. This is the equivalent of the Python 1133 statement: del o[i1:i2]. 1134 */ 1135 1136 PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o); 1137 1138 /* 1139 Returns the sequence, o, as a tuple on success, and NULL on failure. 1140 This is equivalent to the Python expression: tuple(o) 1141 */ 1142 1143 1144 PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o); 1145 /* 1146 Returns the sequence, o, as a list on success, and NULL on failure. 1147 This is equivalent to the Python expression: list(o) 1148 */ 1149 1150 PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m); 1151 /* 1152 Returns the sequence, o, as a tuple, unless it's already a 1153 tuple or list. Use PySequence_Fast_GET_ITEM to access the 1154 members of this list, and PySequence_Fast_GET_SIZE to get its length. 1155 1156 Returns NULL on failure. If the object does not support iteration, 1157 raises a TypeError exception with m as the message text. 1158 */ 1159 1160#define PySequence_Fast_GET_SIZE(o) \ 1161 (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o)) 1162 /* 1163 Return the size of o, assuming that o was returned by 1164 PySequence_Fast and is not NULL. 1165 */ 1166 1167#define PySequence_Fast_GET_ITEM(o, i)\ 1168 (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i)) 1169 /* 1170 Return the ith element of o, assuming that o was returned by 1171 PySequence_Fast, and that i is within bounds. 1172 */ 1173 1174#define PySequence_ITEM(o, i)\ 1175 ( Py_TYPE(o)->tp_as_sequence->sq_item(o, i) ) 1176 /* Assume tp_as_sequence and sq_item exist and that i does not 1177 need to be corrected for a negative index 1178 */ 1179 1180#define PySequence_Fast_ITEMS(sf) \ 1181 (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \ 1182 : ((PyTupleObject *)(sf))->ob_item) 1183 /* Return a pointer to the underlying item array for 1184 an object retured by PySequence_Fast */ 1185 1186 PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value); 1187 1188 /* 1189 Return the number of occurrences on value on o, that is, 1190 return the number of keys for which o[key]==value. On 1191 failure, return -1. This is equivalent to the Python 1192 expression: o.count(value). 1193 */ 1194 1195 PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob); 1196 /* 1197 Return -1 if error; 1 if ob in seq; 0 if ob not in seq. 1198 Use __contains__ if possible, else _PySequence_IterSearch(). 1199 */ 1200 1201#define PY_ITERSEARCH_COUNT 1 1202#define PY_ITERSEARCH_INDEX 2 1203#define PY_ITERSEARCH_CONTAINS 3 1204 PyAPI_FUNC(Py_ssize_t) _PySequence_IterSearch(PyObject *seq, 1205 PyObject *obj, int operation); 1206 /* 1207 Iterate over seq. Result depends on the operation: 1208 PY_ITERSEARCH_COUNT: return # of times obj appears in seq; -1 if 1209 error. 1210 PY_ITERSEARCH_INDEX: return 0-based index of first occurrence of 1211 obj in seq; set ValueError and return -1 if none found; 1212 also return -1 on error. 1213 PY_ITERSEARCH_CONTAINS: return 1 if obj in seq, else 0; -1 on 1214 error. 1215 */ 1216 1217/* For DLL-level backwards compatibility */ 1218#undef PySequence_In 1219 PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value); 1220 1221/* For source-level backwards compatibility */ 1222#define PySequence_In PySequence_Contains 1223 1224 /* 1225 Determine if o contains value. If an item in o is equal to 1226 X, return 1, otherwise return 0. On error, return -1. This 1227 is equivalent to the Python expression: value in o. 1228 */ 1229 1230 PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value); 1231 1232 /* 1233 Return the first index for which o[i]=value. On error, 1234 return -1. This is equivalent to the Python 1235 expression: o.index(value). 1236 */ 1237 1238/* In-place versions of some of the above Sequence functions. */ 1239 1240 PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2); 1241 1242 /* 1243 Append o2 to o1, in-place when possible. Return the resulting 1244 object, which could be o1, or NULL on failure. This is the 1245 equivalent of the Python expression: o1 += o2. 1246 1247 */ 1248 1249 PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count); 1250 1251 /* 1252 Repeat o1 by count, in-place when possible. Return the resulting 1253 object, which could be o1, or NULL on failure. This is the 1254 equivalent of the Python expression: o1 *= count. 1255 1256 */ 1257 1258/* Mapping protocol:*/ 1259 1260 PyAPI_FUNC(int) PyMapping_Check(PyObject *o); 1261 1262 /* 1263 Return 1 if the object provides mapping protocol, and zero 1264 otherwise. 1265 1266 This function always succeeds. 1267 */ 1268 1269 PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o); 1270 1271 /* 1272 Returns the number of keys in object o on success, and -1 on 1273 failure. For objects that do not provide sequence protocol, 1274 this is equivalent to the Python expression: len(o). 1275 */ 1276 1277 /* For DLL compatibility */ 1278#undef PyMapping_Length 1279 PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o); 1280#define PyMapping_Length PyMapping_Size 1281 1282 1283 /* implemented as a macro: 1284 1285 int PyMapping_DelItemString(PyObject *o, char *key); 1286 1287 Remove the mapping for object, key, from the object *o. 1288 Returns -1 on failure. This is equivalent to 1289 the Python statement: del o[key]. 1290 */ 1291#define PyMapping_DelItemString(O,K) PyObject_DelItemString((O),(K)) 1292 1293 /* implemented as a macro: 1294 1295 int PyMapping_DelItem(PyObject *o, PyObject *key); 1296 1297 Remove the mapping for object, key, from the object *o. 1298 Returns -1 on failure. This is equivalent to 1299 the Python statement: del o[key]. 1300 */ 1301#define PyMapping_DelItem(O,K) PyObject_DelItem((O),(K)) 1302 1303 PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, char *key); 1304 1305 /* 1306 On success, return 1 if the mapping object has the key, key, 1307 and 0 otherwise. This is equivalent to the Python expression: 1308 o.has_key(key). 1309 1310 This function always succeeds. 1311 */ 1312 1313 PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key); 1314 1315 /* 1316 Return 1 if the mapping object has the key, key, 1317 and 0 otherwise. This is equivalent to the Python expression: 1318 o.has_key(key). 1319 1320 This function always succeeds. 1321 1322 */ 1323 1324 /* Implemented as macro: 1325 1326 PyObject *PyMapping_Keys(PyObject *o); 1327 1328 On success, return a list of the keys in object o. On 1329 failure, return NULL. This is equivalent to the Python 1330 expression: o.keys(). 1331 */ 1332#define PyMapping_Keys(O) PyObject_CallMethod(O,"keys",NULL) 1333 1334 /* Implemented as macro: 1335 1336 PyObject *PyMapping_Values(PyObject *o); 1337 1338 On success, return a list of the values in object o. On 1339 failure, return NULL. This is equivalent to the Python 1340 expression: o.values(). 1341 */ 1342#define PyMapping_Values(O) PyObject_CallMethod(O,"values",NULL) 1343 1344 /* Implemented as macro: 1345 1346 PyObject *PyMapping_Items(PyObject *o); 1347 1348 On success, return a list of the items in object o, where 1349 each item is a tuple containing a key-value pair. On 1350 failure, return NULL. This is equivalent to the Python 1351 expression: o.items(). 1352 1353 */ 1354#define PyMapping_Items(O) PyObject_CallMethod(O,"items",NULL) 1355 1356 PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o, char *key); 1357 1358 /* 1359 Return element of o corresponding to the object, key, or NULL 1360 on failure. This is the equivalent of the Python expression: 1361 o[key]. 1362 */ 1363 1364 PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, char *key, 1365 PyObject *value); 1366 1367 /* 1368 Map the object, key, to the value, v. Returns 1369 -1 on failure. This is the equivalent of the Python 1370 statement: o[key]=v. 1371 */ 1372 1373 1374PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass); 1375 /* isinstance(object, typeorclass) */ 1376 1377PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass); 1378 /* issubclass(object, typeorclass) */ 1379 1380 1381PyAPI_FUNC(int) _PyObject_RealIsInstance(PyObject *inst, PyObject *cls); 1382 1383PyAPI_FUNC(int) _PyObject_RealIsSubclass(PyObject *derived, PyObject *cls); 1384 1385 1386/* For internal use by buffer API functions */ 1387PyAPI_FUNC(void) _Py_add_one_to_index_F(int nd, Py_ssize_t *index, 1388 const Py_ssize_t *shape); 1389PyAPI_FUNC(void) _Py_add_one_to_index_C(int nd, Py_ssize_t *index, 1390 const Py_ssize_t *shape); 1391 1392 1393#ifdef __cplusplus 1394} 1395#endif 1396#endif /* Py_ABSTRACTOBJECT_H */ 1397