1/* Abstract Object Interface (many thanks to Jim Fulton) */ 2 3#ifndef Py_ABSTRACTOBJECT_H 4#define Py_ABSTRACTOBJECT_H 5#ifdef __cplusplus 6extern "C" { 7#endif 8 9/* === Object Protocol ================================================== */ 10 11/* Implemented elsewhere: 12 13 int PyObject_Print(PyObject *o, FILE *fp, int flags); 14 15 Print an object 'o' on file 'fp'. Returns -1 on error. The flags argument 16 is used to enable certain printing options. The only option currently 17 supported is Py_Print_RAW. 18 19 (What should be said about Py_Print_RAW?). */ 20 21 22/* Implemented elsewhere: 23 24 int PyObject_HasAttrString(PyObject *o, const char *attr_name); 25 26 Returns 1 if object 'o' has the attribute attr_name, and 0 otherwise. 27 28 This is equivalent to the Python expression: hasattr(o,attr_name). 29 30 This function always succeeds. */ 31 32 33/* Implemented elsewhere: 34 35 PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name); 36 37 Retrieve an attributed named attr_name form object o. 38 Returns the attribute value on success, or NULL on failure. 39 40 This is the equivalent of the Python expression: o.attr_name. */ 41 42 43/* Implemented elsewhere: 44 45 int PyObject_HasAttr(PyObject *o, PyObject *attr_name); 46 47 Returns 1 if o has the attribute attr_name, and 0 otherwise. 48 49 This is equivalent to the Python expression: hasattr(o,attr_name). 50 51 This function always succeeds. */ 52 53/* Implemented elsewhere: 54 55 PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name); 56 57 Retrieve an attributed named 'attr_name' form object 'o'. 58 Returns the attribute value on success, or NULL on failure. 59 60 This is the equivalent of the Python expression: o.attr_name. */ 61 62 63/* Implemented elsewhere: 64 65 int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v); 66 67 Set the value of the attribute named attr_name, for object 'o', 68 to the value 'v'. Raise an exception and return -1 on failure; return 0 on 69 success. 70 71 This is the equivalent of the Python statement o.attr_name=v. */ 72 73 74/* Implemented elsewhere: 75 76 int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v); 77 78 Set the value of the attribute named attr_name, for object 'o', to the value 79 'v'. an exception and return -1 on failure; return 0 on success. 80 81 This is the equivalent of the Python statement o.attr_name=v. */ 82 83/* Implemented as a macro: 84 85 int PyObject_DelAttrString(PyObject *o, const char *attr_name); 86 87 Delete attribute named attr_name, for object o. Returns 88 -1 on failure. 89 90 This is the equivalent of the Python statement: del o.attr_name. */ 91#define PyObject_DelAttrString(O,A) PyObject_SetAttrString((O),(A), NULL) 92 93 94/* Implemented as a macro: 95 96 int PyObject_DelAttr(PyObject *o, PyObject *attr_name); 97 98 Delete attribute named attr_name, for object o. Returns -1 99 on failure. This is the equivalent of the Python 100 statement: del o.attr_name. */ 101#define PyObject_DelAttr(O,A) PyObject_SetAttr((O),(A), NULL) 102 103 104/* Implemented elsewhere: 105 106 PyObject *PyObject_Repr(PyObject *o); 107 108 Compute the string representation of object 'o'. Returns the 109 string representation on success, NULL on failure. 110 111 This is the equivalent of the Python expression: repr(o). 112 113 Called by the repr() built-in function. */ 114 115 116/* Implemented elsewhere: 117 118 PyObject *PyObject_Str(PyObject *o); 119 120 Compute the string representation of object, o. Returns the 121 string representation on success, NULL on failure. 122 123 This is the equivalent of the Python expression: str(o). 124 125 Called by the str() and print() built-in functions. */ 126 127 128/* Declared elsewhere 129 130 PyAPI_FUNC(int) PyCallable_Check(PyObject *o); 131 132 Determine if the object, o, is callable. Return 1 if the object is callable 133 and 0 otherwise. 134 135 This function always succeeds. */ 136 137 138#ifdef PY_SSIZE_T_CLEAN 139# define PyObject_CallFunction _PyObject_CallFunction_SizeT 140# define PyObject_CallMethod _PyObject_CallMethod_SizeT 141#endif 142 143 144#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000 145/* Call a callable Python object without any arguments */ 146PyAPI_FUNC(PyObject *) PyObject_CallNoArgs(PyObject *func); 147#endif 148 149 150/* Call a callable Python object 'callable' with arguments given by the 151 tuple 'args' and keywords arguments given by the dictionary 'kwargs'. 152 153 'args' must not be NULL, use an empty tuple if no arguments are 154 needed. If no named arguments are needed, 'kwargs' can be NULL. 155 156 This is the equivalent of the Python expression: 157 callable(*args, **kwargs). */ 158PyAPI_FUNC(PyObject *) PyObject_Call(PyObject *callable, 159 PyObject *args, PyObject *kwargs); 160 161 162/* Call a callable Python object 'callable', with arguments given by the 163 tuple 'args'. If no arguments are needed, then 'args' can be NULL. 164 165 Returns the result of the call on success, or NULL on failure. 166 167 This is the equivalent of the Python expression: 168 callable(*args). */ 169PyAPI_FUNC(PyObject *) PyObject_CallObject(PyObject *callable, 170 PyObject *args); 171 172/* Call a callable Python object, callable, with a variable number of C 173 arguments. The C arguments are described using a mkvalue-style format 174 string. 175 176 The format may be NULL, indicating that no arguments are provided. 177 178 Returns the result of the call on success, or NULL on failure. 179 180 This is the equivalent of the Python expression: 181 callable(arg1, arg2, ...). */ 182PyAPI_FUNC(PyObject *) PyObject_CallFunction(PyObject *callable, 183 const char *format, ...); 184 185/* Call the method named 'name' of object 'obj' with a variable number of 186 C arguments. The C arguments are described by a mkvalue format string. 187 188 The format can be NULL, indicating that no arguments are provided. 189 190 Returns the result of the call on success, or NULL on failure. 191 192 This is the equivalent of the Python expression: 193 obj.name(arg1, arg2, ...). */ 194PyAPI_FUNC(PyObject *) PyObject_CallMethod(PyObject *obj, 195 const char *name, 196 const char *format, ...); 197 198PyAPI_FUNC(PyObject *) _PyObject_CallFunction_SizeT(PyObject *callable, 199 const char *format, 200 ...); 201 202PyAPI_FUNC(PyObject *) _PyObject_CallMethod_SizeT(PyObject *obj, 203 const char *name, 204 const char *format, 205 ...); 206 207/* Call a callable Python object 'callable' with a variable number of C 208 arguments. The C arguments are provided as PyObject* values, terminated 209 by a NULL. 210 211 Returns the result of the call on success, or NULL on failure. 212 213 This is the equivalent of the Python expression: 214 callable(arg1, arg2, ...). */ 215PyAPI_FUNC(PyObject *) PyObject_CallFunctionObjArgs(PyObject *callable, 216 ...); 217 218/* Call the method named 'name' of object 'obj' with a variable number of 219 C arguments. The C arguments are provided as PyObject* values, terminated 220 by NULL. 221 222 Returns the result of the call on success, or NULL on failure. 223 224 This is the equivalent of the Python expression: obj.name(*args). */ 225 226PyAPI_FUNC(PyObject *) PyObject_CallMethodObjArgs( 227 PyObject *obj, 228 PyObject *name, 229 ...); 230 231 232/* Implemented elsewhere: 233 234 Py_hash_t PyObject_Hash(PyObject *o); 235 236 Compute and return the hash, hash_value, of an object, o. On 237 failure, return -1. 238 239 This is the equivalent of the Python expression: hash(o). */ 240 241 242/* Implemented elsewhere: 243 244 int PyObject_IsTrue(PyObject *o); 245 246 Returns 1 if the object, o, is considered to be true, 0 if o is 247 considered to be false and -1 on failure. 248 249 This is equivalent to the Python expression: not not o. */ 250 251 252/* Implemented elsewhere: 253 254 int PyObject_Not(PyObject *o); 255 256 Returns 0 if the object, o, is considered to be true, 1 if o is 257 considered to be false and -1 on failure. 258 259 This is equivalent to the Python expression: not o. */ 260 261 262/* Get the type of an object. 263 264 On success, returns a type object corresponding to the object type of object 265 'o'. On failure, returns NULL. 266 267 This is equivalent to the Python expression: type(o) */ 268PyAPI_FUNC(PyObject *) PyObject_Type(PyObject *o); 269 270 271/* Return the size of object 'o'. If the object 'o' provides both sequence and 272 mapping protocols, the sequence size is returned. 273 274 On error, -1 is returned. 275 276 This is the equivalent to the Python expression: len(o) */ 277PyAPI_FUNC(Py_ssize_t) PyObject_Size(PyObject *o); 278 279 280/* For DLL compatibility */ 281#undef PyObject_Length 282PyAPI_FUNC(Py_ssize_t) PyObject_Length(PyObject *o); 283#define PyObject_Length PyObject_Size 284 285/* Return element of 'o' corresponding to the object 'key'. Return NULL 286 on failure. 287 288 This is the equivalent of the Python expression: o[key] */ 289PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key); 290 291 292/* Map the object 'key' to the value 'v' into 'o'. 293 294 Raise an exception and return -1 on failure; return 0 on success. 295 296 This is the equivalent of the Python statement: o[key]=v. */ 297PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v); 298 299/* Remove the mapping for the string 'key' from the object 'o'. 300 Returns -1 on failure. 301 302 This is equivalent to the Python statement: del o[key]. */ 303PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, const char *key); 304 305/* Delete the mapping for the object 'key' from the object 'o'. 306 Returns -1 on failure. 307 308 This is the equivalent of the Python statement: del o[key]. */ 309PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key); 310 311 312/* === Old Buffer API ============================================ */ 313 314/* FIXME: usage of these should all be replaced in Python itself 315 but for backwards compatibility we will implement them. 316 Their usage without a corresponding "unlock" mechanism 317 may create issues (but they would already be there). */ 318 319/* Takes an arbitrary object which must support the (character, single segment) 320 buffer interface and returns a pointer to a read-only memory location 321 usable as character based input for subsequent processing. 322 323 Return 0 on success. buffer and buffer_len are only set in case no error 324 occurs. Otherwise, -1 is returned and an exception set. */ 325Py_DEPRECATED(3.0) 326PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj, 327 const char **buffer, 328 Py_ssize_t *buffer_len); 329 330/* Checks whether an arbitrary object supports the (character, single segment) 331 buffer interface. 332 333 Returns 1 on success, 0 on failure. */ 334Py_DEPRECATED(3.0) PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj); 335 336/* Same as PyObject_AsCharBuffer() except that this API expects (readable, 337 single segment) buffer interface and returns a pointer to a read-only memory 338 location which can contain arbitrary data. 339 340 0 is returned on success. buffer and buffer_len are only set in case no 341 error occurs. Otherwise, -1 is returned and an exception set. */ 342Py_DEPRECATED(3.0) 343PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj, 344 const void **buffer, 345 Py_ssize_t *buffer_len); 346 347/* Takes an arbitrary object which must support the (writable, single segment) 348 buffer interface and returns a pointer to a writable memory location in 349 buffer of size 'buffer_len'. 350 351 Return 0 on success. buffer and buffer_len are only set in case no error 352 occurs. Otherwise, -1 is returned and an exception set. */ 353Py_DEPRECATED(3.0) 354PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj, 355 void **buffer, 356 Py_ssize_t *buffer_len); 357 358 359/* === New Buffer API ============================================ */ 360 361/* Takes an arbitrary object and returns the result of calling 362 obj.__format__(format_spec). */ 363PyAPI_FUNC(PyObject *) PyObject_Format(PyObject *obj, 364 PyObject *format_spec); 365 366 367/* ==== Iterators ================================================ */ 368 369/* Takes an object and returns an iterator for it. 370 This is typically a new iterator but if the argument is an iterator, this 371 returns itself. */ 372PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *); 373 374/* Takes an AsyncIterable object and returns an AsyncIterator for it. 375 This is typically a new iterator but if the argument is an AsyncIterator, 376 this returns itself. */ 377PyAPI_FUNC(PyObject *) PyObject_GetAIter(PyObject *); 378 379/* Returns non-zero if the object 'obj' provides iterator protocols, and 0 otherwise. 380 381 This function always succeeds. */ 382PyAPI_FUNC(int) PyIter_Check(PyObject *); 383 384/* Returns non-zero if the object 'obj' provides AsyncIterator protocols, and 0 otherwise. 385 386 This function always succeeds. */ 387PyAPI_FUNC(int) PyAIter_Check(PyObject *); 388 389/* Takes an iterator object and calls its tp_iternext slot, 390 returning the next value. 391 392 If the iterator is exhausted, this returns NULL without setting an 393 exception. 394 395 NULL with an exception means an error occurred. */ 396PyAPI_FUNC(PyObject *) PyIter_Next(PyObject *); 397 398#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000 399 400/* Takes generator, coroutine or iterator object and sends the value into it. 401 Returns: 402 - PYGEN_RETURN (0) if generator has returned. 403 'result' parameter is filled with return value 404 - PYGEN_ERROR (-1) if exception was raised. 405 'result' parameter is NULL 406 - PYGEN_NEXT (1) if generator has yielded. 407 'result' parameter is filled with yielded value. */ 408PyAPI_FUNC(PySendResult) PyIter_Send(PyObject *, PyObject *, PyObject **); 409#endif 410 411 412/* === Number Protocol ================================================== */ 413 414/* Returns 1 if the object 'o' provides numeric protocols, and 0 otherwise. 415 416 This function always succeeds. */ 417PyAPI_FUNC(int) PyNumber_Check(PyObject *o); 418 419/* Returns the result of adding o1 and o2, or NULL on failure. 420 421 This is the equivalent of the Python expression: o1 + o2. */ 422PyAPI_FUNC(PyObject *) PyNumber_Add(PyObject *o1, PyObject *o2); 423 424/* Returns the result of subtracting o2 from o1, or NULL on failure. 425 426 This is the equivalent of the Python expression: o1 - o2. */ 427PyAPI_FUNC(PyObject *) PyNumber_Subtract(PyObject *o1, PyObject *o2); 428 429/* Returns the result of multiplying o1 and o2, or NULL on failure. 430 431 This is the equivalent of the Python expression: o1 * o2. */ 432PyAPI_FUNC(PyObject *) PyNumber_Multiply(PyObject *o1, PyObject *o2); 433 434#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000 435/* This is the equivalent of the Python expression: o1 @ o2. */ 436PyAPI_FUNC(PyObject *) PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2); 437#endif 438 439/* Returns the result of dividing o1 by o2 giving an integral result, 440 or NULL on failure. 441 442 This is the equivalent of the Python expression: o1 // o2. */ 443PyAPI_FUNC(PyObject *) PyNumber_FloorDivide(PyObject *o1, PyObject *o2); 444 445/* Returns the result of dividing o1 by o2 giving a float result, or NULL on 446 failure. 447 448 This is the equivalent of the Python expression: o1 / o2. */ 449PyAPI_FUNC(PyObject *) PyNumber_TrueDivide(PyObject *o1, PyObject *o2); 450 451/* Returns the remainder of dividing o1 by o2, or NULL on failure. 452 453 This is the equivalent of the Python expression: o1 % o2. */ 454PyAPI_FUNC(PyObject *) PyNumber_Remainder(PyObject *o1, PyObject *o2); 455 456/* See the built-in function divmod. 457 458 Returns NULL on failure. 459 460 This is the equivalent of the Python expression: divmod(o1, o2). */ 461PyAPI_FUNC(PyObject *) PyNumber_Divmod(PyObject *o1, PyObject *o2); 462 463/* See the built-in function pow. Returns NULL on failure. 464 465 This is the equivalent of the Python expression: pow(o1, o2, o3), 466 where o3 is optional. */ 467PyAPI_FUNC(PyObject *) PyNumber_Power(PyObject *o1, PyObject *o2, 468 PyObject *o3); 469 470/* Returns the negation of o on success, or NULL on failure. 471 472 This is the equivalent of the Python expression: -o. */ 473PyAPI_FUNC(PyObject *) PyNumber_Negative(PyObject *o); 474 475/* Returns the positive of o on success, or NULL on failure. 476 477 This is the equivalent of the Python expression: +o. */ 478PyAPI_FUNC(PyObject *) PyNumber_Positive(PyObject *o); 479 480/* Returns the absolute value of 'o', or NULL on failure. 481 482 This is the equivalent of the Python expression: abs(o). */ 483PyAPI_FUNC(PyObject *) PyNumber_Absolute(PyObject *o); 484 485/* Returns the bitwise negation of 'o' on success, or NULL on failure. 486 487 This is the equivalent of the Python expression: ~o. */ 488PyAPI_FUNC(PyObject *) PyNumber_Invert(PyObject *o); 489 490/* Returns the result of left shifting o1 by o2 on success, or NULL on failure. 491 492 This is the equivalent of the Python expression: o1 << o2. */ 493PyAPI_FUNC(PyObject *) PyNumber_Lshift(PyObject *o1, PyObject *o2); 494 495/* Returns the result of right shifting o1 by o2 on success, or NULL on 496 failure. 497 498 This is the equivalent of the Python expression: o1 >> o2. */ 499PyAPI_FUNC(PyObject *) PyNumber_Rshift(PyObject *o1, PyObject *o2); 500 501/* Returns the result of bitwise and of o1 and o2 on success, or NULL on 502 failure. 503 504 This is the equivalent of the Python expression: o1 & o2. */ 505PyAPI_FUNC(PyObject *) PyNumber_And(PyObject *o1, PyObject *o2); 506 507/* Returns the bitwise exclusive or of o1 by o2 on success, or NULL on failure. 508 509 This is the equivalent of the Python expression: o1 ^ o2. */ 510PyAPI_FUNC(PyObject *) PyNumber_Xor(PyObject *o1, PyObject *o2); 511 512/* Returns the result of bitwise or on o1 and o2 on success, or NULL on 513 failure. 514 515 This is the equivalent of the Python expression: o1 | o2. */ 516PyAPI_FUNC(PyObject *) PyNumber_Or(PyObject *o1, PyObject *o2); 517 518/* Returns 1 if obj is an index integer (has the nb_index slot of the 519 tp_as_number structure filled in), and 0 otherwise. */ 520PyAPI_FUNC(int) PyIndex_Check(PyObject *); 521 522/* Returns the object 'o' converted to a Python int, or NULL with an exception 523 raised on failure. */ 524PyAPI_FUNC(PyObject *) PyNumber_Index(PyObject *o); 525 526/* Returns the object 'o' converted to Py_ssize_t by going through 527 PyNumber_Index() first. 528 529 If an overflow error occurs while converting the int to Py_ssize_t, then the 530 second argument 'exc' is the error-type to return. If it is NULL, then the 531 overflow error is cleared and the value is clipped. */ 532PyAPI_FUNC(Py_ssize_t) PyNumber_AsSsize_t(PyObject *o, PyObject *exc); 533 534/* Returns the object 'o' converted to an integer object on success, or NULL 535 on failure. 536 537 This is the equivalent of the Python expression: int(o). */ 538PyAPI_FUNC(PyObject *) PyNumber_Long(PyObject *o); 539 540/* Returns the object 'o' converted to a float object on success, or NULL 541 on failure. 542 543 This is the equivalent of the Python expression: float(o). */ 544PyAPI_FUNC(PyObject *) PyNumber_Float(PyObject *o); 545 546 547/* --- In-place variants of (some of) the above number protocol functions -- */ 548 549/* Returns the result of adding o2 to o1, possibly in-place, or NULL 550 on failure. 551 552 This is the equivalent of the Python expression: o1 += o2. */ 553PyAPI_FUNC(PyObject *) PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2); 554 555/* Returns the result of subtracting o2 from o1, possibly in-place or 556 NULL on failure. 557 558 This is the equivalent of the Python expression: o1 -= o2. */ 559PyAPI_FUNC(PyObject *) PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2); 560 561/* Returns the result of multiplying o1 by o2, possibly in-place, or NULL on 562 failure. 563 564 This is the equivalent of the Python expression: o1 *= o2. */ 565PyAPI_FUNC(PyObject *) PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2); 566 567#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000 568/* This is the equivalent of the Python expression: o1 @= o2. */ 569PyAPI_FUNC(PyObject *) PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2); 570#endif 571 572/* Returns the result of dividing o1 by o2 giving an integral result, possibly 573 in-place, or NULL on failure. 574 575 This is the equivalent of the Python expression: o1 /= o2. */ 576PyAPI_FUNC(PyObject *) PyNumber_InPlaceFloorDivide(PyObject *o1, 577 PyObject *o2); 578 579/* Returns the result of dividing o1 by o2 giving a float result, possibly 580 in-place, or null on failure. 581 582 This is the equivalent of the Python expression: o1 /= o2. */ 583PyAPI_FUNC(PyObject *) PyNumber_InPlaceTrueDivide(PyObject *o1, 584 PyObject *o2); 585 586/* Returns the remainder of dividing o1 by o2, possibly in-place, or NULL on 587 failure. 588 589 This is the equivalent of the Python expression: o1 %= o2. */ 590PyAPI_FUNC(PyObject *) PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2); 591 592/* Returns the result of raising o1 to the power of o2, possibly in-place, 593 or NULL on failure. 594 595 This is the equivalent of the Python expression: o1 **= o2, 596 or o1 = pow(o1, o2, o3) if o3 is present. */ 597PyAPI_FUNC(PyObject *) PyNumber_InPlacePower(PyObject *o1, PyObject *o2, 598 PyObject *o3); 599 600/* Returns the result of left shifting o1 by o2, possibly in-place, or NULL 601 on failure. 602 603 This is the equivalent of the Python expression: o1 <<= o2. */ 604PyAPI_FUNC(PyObject *) PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2); 605 606/* Returns the result of right shifting o1 by o2, possibly in-place or NULL 607 on failure. 608 609 This is the equivalent of the Python expression: o1 >>= o2. */ 610PyAPI_FUNC(PyObject *) PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2); 611 612/* Returns the result of bitwise and of o1 and o2, possibly in-place, or NULL 613 on failure. 614 615 This is the equivalent of the Python expression: o1 &= o2. */ 616PyAPI_FUNC(PyObject *) PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2); 617 618/* Returns the bitwise exclusive or of o1 by o2, possibly in-place, or NULL 619 on failure. 620 621 This is the equivalent of the Python expression: o1 ^= o2. */ 622PyAPI_FUNC(PyObject *) PyNumber_InPlaceXor(PyObject *o1, PyObject *o2); 623 624/* Returns the result of bitwise or of o1 and o2, possibly in-place, 625 or NULL on failure. 626 627 This is the equivalent of the Python expression: o1 |= o2. */ 628PyAPI_FUNC(PyObject *) PyNumber_InPlaceOr(PyObject *o1, PyObject *o2); 629 630/* Returns the integer n converted to a string with a base, with a base 631 marker of 0b, 0o or 0x prefixed if applicable. 632 633 If n is not an int object, it is converted with PyNumber_Index first. */ 634PyAPI_FUNC(PyObject *) PyNumber_ToBase(PyObject *n, int base); 635 636 637/* === Sequence protocol ================================================ */ 638 639/* Return 1 if the object provides sequence protocol, and zero 640 otherwise. 641 642 This function always succeeds. */ 643PyAPI_FUNC(int) PySequence_Check(PyObject *o); 644 645/* Return the size of sequence object o, or -1 on failure. */ 646PyAPI_FUNC(Py_ssize_t) PySequence_Size(PyObject *o); 647 648/* For DLL compatibility */ 649#undef PySequence_Length 650PyAPI_FUNC(Py_ssize_t) PySequence_Length(PyObject *o); 651#define PySequence_Length PySequence_Size 652 653 654/* Return the concatenation of o1 and o2 on success, and NULL on failure. 655 656 This is the equivalent of the Python expression: o1 + o2. */ 657PyAPI_FUNC(PyObject *) PySequence_Concat(PyObject *o1, PyObject *o2); 658 659/* Return the result of repeating sequence object 'o' 'count' times, 660 or NULL on failure. 661 662 This is the equivalent of the Python expression: o * count. */ 663PyAPI_FUNC(PyObject *) PySequence_Repeat(PyObject *o, Py_ssize_t count); 664 665/* Return the ith element of o, or NULL on failure. 666 667 This is the equivalent of the Python expression: o[i]. */ 668PyAPI_FUNC(PyObject *) PySequence_GetItem(PyObject *o, Py_ssize_t i); 669 670/* Return the slice of sequence object o between i1 and i2, or NULL on failure. 671 672 This is the equivalent of the Python expression: o[i1:i2]. */ 673PyAPI_FUNC(PyObject *) PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2); 674 675/* Assign object 'v' to the ith element of the sequence 'o'. Raise an exception 676 and return -1 on failure; return 0 on success. 677 678 This is the equivalent of the Python statement o[i] = v. */ 679PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v); 680 681/* Delete the 'i'-th element of the sequence 'v'. Returns -1 on failure. 682 683 This is the equivalent of the Python statement: del o[i]. */ 684PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i); 685 686/* Assign the sequence object 'v' to the slice in sequence object 'o', 687 from 'i1' to 'i2'. Returns -1 on failure. 688 689 This is the equivalent of the Python statement: o[i1:i2] = v. */ 690PyAPI_FUNC(int) PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, 691 PyObject *v); 692 693/* Delete the slice in sequence object 'o' from 'i1' to 'i2'. 694 Returns -1 on failure. 695 696 This is the equivalent of the Python statement: del o[i1:i2]. */ 697PyAPI_FUNC(int) PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2); 698 699/* Returns the sequence 'o' as a tuple on success, and NULL on failure. 700 701 This is equivalent to the Python expression: tuple(o). */ 702PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o); 703 704/* Returns the sequence 'o' as a list on success, and NULL on failure. 705 This is equivalent to the Python expression: list(o) */ 706PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o); 707 708/* Return the sequence 'o' as a list, unless it's already a tuple or list. 709 710 Use PySequence_Fast_GET_ITEM to access the members of this list, and 711 PySequence_Fast_GET_SIZE to get its length. 712 713 Returns NULL on failure. If the object does not support iteration, raises a 714 TypeError exception with 'm' as the message text. */ 715PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m); 716 717/* Return the size of the sequence 'o', assuming that 'o' was returned by 718 PySequence_Fast and is not NULL. */ 719#define PySequence_Fast_GET_SIZE(o) \ 720 (PyList_Check(o) ? PyList_GET_SIZE(o) : PyTuple_GET_SIZE(o)) 721 722/* Return the 'i'-th element of the sequence 'o', assuming that o was returned 723 by PySequence_Fast, and that i is within bounds. */ 724#define PySequence_Fast_GET_ITEM(o, i)\ 725 (PyList_Check(o) ? PyList_GET_ITEM(o, i) : PyTuple_GET_ITEM(o, i)) 726 727/* Return a pointer to the underlying item array for 728 an object returned by PySequence_Fast */ 729#define PySequence_Fast_ITEMS(sf) \ 730 (PyList_Check(sf) ? ((PyListObject *)(sf))->ob_item \ 731 : ((PyTupleObject *)(sf))->ob_item) 732 733/* Return the number of occurrences on value on 'o', that is, return 734 the number of keys for which o[key] == value. 735 736 On failure, return -1. This is equivalent to the Python expression: 737 o.count(value). */ 738PyAPI_FUNC(Py_ssize_t) PySequence_Count(PyObject *o, PyObject *value); 739 740/* Return 1 if 'ob' is in the sequence 'seq'; 0 if 'ob' is not in the sequence 741 'seq'; -1 on error. 742 743 Use __contains__ if possible, else _PySequence_IterSearch(). */ 744PyAPI_FUNC(int) PySequence_Contains(PyObject *seq, PyObject *ob); 745 746/* For DLL-level backwards compatibility */ 747#undef PySequence_In 748/* Determine if the sequence 'o' contains 'value'. If an item in 'o' is equal 749 to 'value', return 1, otherwise return 0. On error, return -1. 750 751 This is equivalent to the Python expression: value in o. */ 752PyAPI_FUNC(int) PySequence_In(PyObject *o, PyObject *value); 753 754/* For source-level backwards compatibility */ 755#define PySequence_In PySequence_Contains 756 757 758/* Return the first index for which o[i] == value. 759 On error, return -1. 760 761 This is equivalent to the Python expression: o.index(value). */ 762PyAPI_FUNC(Py_ssize_t) PySequence_Index(PyObject *o, PyObject *value); 763 764 765/* --- In-place versions of some of the above Sequence functions --- */ 766 767/* Append sequence 'o2' to sequence 'o1', in-place when possible. Return the 768 resulting object, which could be 'o1', or NULL on failure. 769 770 This is the equivalent of the Python expression: o1 += o2. */ 771PyAPI_FUNC(PyObject *) PySequence_InPlaceConcat(PyObject *o1, PyObject *o2); 772 773/* Repeat sequence 'o' by 'count', in-place when possible. Return the resulting 774 object, which could be 'o', or NULL on failure. 775 776 This is the equivalent of the Python expression: o1 *= count. */ 777PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count); 778 779 780/* === Mapping protocol ================================================= */ 781 782/* Return 1 if the object provides mapping protocol, and 0 otherwise. 783 784 This function always succeeds. */ 785PyAPI_FUNC(int) PyMapping_Check(PyObject *o); 786 787/* Returns the number of keys in mapping object 'o' on success, and -1 on 788 failure. This is equivalent to the Python expression: len(o). */ 789PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o); 790 791/* For DLL compatibility */ 792#undef PyMapping_Length 793PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o); 794#define PyMapping_Length PyMapping_Size 795 796 797/* Implemented as a macro: 798 799 int PyMapping_DelItemString(PyObject *o, const char *key); 800 801 Remove the mapping for the string 'key' from the mapping 'o'. Returns -1 on 802 failure. 803 804 This is equivalent to the Python statement: del o[key]. */ 805#define PyMapping_DelItemString(O,K) PyObject_DelItemString((O),(K)) 806 807/* Implemented as a macro: 808 809 int PyMapping_DelItem(PyObject *o, PyObject *key); 810 811 Remove the mapping for the object 'key' from the mapping object 'o'. 812 Returns -1 on failure. 813 814 This is equivalent to the Python statement: del o[key]. */ 815#define PyMapping_DelItem(O,K) PyObject_DelItem((O),(K)) 816 817/* On success, return 1 if the mapping object 'o' has the key 'key', 818 and 0 otherwise. 819 820 This is equivalent to the Python expression: key in o. 821 822 This function always succeeds. */ 823PyAPI_FUNC(int) PyMapping_HasKeyString(PyObject *o, const char *key); 824 825/* Return 1 if the mapping object has the key 'key', and 0 otherwise. 826 827 This is equivalent to the Python expression: key in o. 828 829 This function always succeeds. */ 830PyAPI_FUNC(int) PyMapping_HasKey(PyObject *o, PyObject *key); 831 832/* On success, return a list or tuple of the keys in mapping object 'o'. 833 On failure, return NULL. */ 834PyAPI_FUNC(PyObject *) PyMapping_Keys(PyObject *o); 835 836/* On success, return a list or tuple of the values in mapping object 'o'. 837 On failure, return NULL. */ 838PyAPI_FUNC(PyObject *) PyMapping_Values(PyObject *o); 839 840/* On success, return a list or tuple of the items in mapping object 'o', 841 where each item is a tuple containing a key-value pair. On failure, return 842 NULL. */ 843PyAPI_FUNC(PyObject *) PyMapping_Items(PyObject *o); 844 845/* Return element of 'o' corresponding to the string 'key' or NULL on failure. 846 847 This is the equivalent of the Python expression: o[key]. */ 848PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o, 849 const char *key); 850 851/* Map the string 'key' to the value 'v' in the mapping 'o'. 852 Returns -1 on failure. 853 854 This is the equivalent of the Python statement: o[key]=v. */ 855PyAPI_FUNC(int) PyMapping_SetItemString(PyObject *o, const char *key, 856 PyObject *value); 857 858/* isinstance(object, typeorclass) */ 859PyAPI_FUNC(int) PyObject_IsInstance(PyObject *object, PyObject *typeorclass); 860 861/* issubclass(object, typeorclass) */ 862PyAPI_FUNC(int) PyObject_IsSubclass(PyObject *object, PyObject *typeorclass); 863 864#ifndef Py_LIMITED_API 865# define Py_CPYTHON_ABSTRACTOBJECT_H 866# include "cpython/abstract.h" 867# undef Py_CPYTHON_ABSTRACTOBJECT_H 868#endif 869 870#ifdef __cplusplus 871} 872#endif 873#endif /* Py_ABSTRACTOBJECT_H */ 874