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