Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/python3.14/object.h
1 #ifndef Py_OBJECT_H 2 #define Py_OBJECT_H 3 #ifdef __cplusplus 4 extern "C" { 5 #endif 6 7 8 /* Object and type object interface */ 9 10 /* 11 Objects are structures allocated on the heap. Special rules apply to 12 the use of objects to ensure they are properly garbage-collected. 13 Objects are never allocated statically or on the stack; they must be 14 accessed through special macros and functions only. (Type objects are 15 exceptions to the first rule; the standard types are represented by 16 statically initialized type objects, although work on type/class unification 17 for Python 2.2 made it possible to have heap-allocated type objects too). 18 19 An object has a 'reference count' that is increased or decreased when a 20 pointer to the object is copied or deleted; when the reference count 21 reaches zero there are no references to the object left and it can be 22 removed from the heap. 23 24 An object has a 'type' that determines what it represents and what kind 25 of data it contains. An object's type is fixed when it is created. 26 Types themselves are represented as objects; an object contains a 27 pointer to the corresponding type object. The type itself has a type 28 pointer pointing to the object representing the type 'type', which 29 contains a pointer to itself!. 30 31 Objects do not float around in memory; once allocated an object keeps 32 the same size and address. Objects that must hold variable-size data 33 can contain pointers to variable-size parts of the object. Not all 34 objects of the same type have the same size; but the size cannot change 35 after allocation. (These restrictions are made so a reference to an 36 object can be simply a pointer -- moving an object would require 37 updating all the pointers, and changing an object's size would require 38 moving it if there was another object right next to it.) 39 40 Objects are always accessed through pointers of the type 'PyObject *'. 41 The type 'PyObject' is a structure that only contains the reference count 42 and the type pointer. The actual memory allocated for an object 43 contains other data that can only be accessed after casting the pointer 44 to a pointer to a longer structure type. This longer type must start 45 with the reference count and type fields; the macro PyObject_HEAD should be 46 used for this (to accommodate for future changes). The implementation 47 of a particular object type can cast the object pointer to the proper 48 type and back. 49 50 A standard interface exists for objects that contain an array of items 51 whose size is determined when the object is allocated. 52 */ 53 54 /* Py_DEBUG implies Py_REF_DEBUG. */ 55 #if defined(Py_DEBUG) && !defined(Py_REF_DEBUG) 56 # define Py_REF_DEBUG 57 #endif 58 59 /* PyObject_HEAD defines the initial segment of every PyObject. */ 60 #define PyObject_HEAD PyObject ob_base; 61 62 // Kept for backward compatibility. It was needed by Py_TRACE_REFS build. 63 #define _PyObject_EXTRA_INIT 64 65 /* Make all uses of PyObject_HEAD_INIT immortal. 66 * 67 * Statically allocated objects might be shared between 68 * interpreters, so must be marked as immortal. 69 */ 70 #if defined(Py_GIL_DISABLED) 71 #define PyObject_HEAD_INIT(type) \ 72 { \ 73 0, \ 74 _Py_STATICALLY_ALLOCATED_FLAG, \ 75 { 0 }, \ 76 0, \ 77 _Py_IMMORTAL_REFCNT_LOCAL, \ 78 0, \ 79 (type), \ 80 }, 81 #else 82 #define PyObject_HEAD_INIT(type) \ 83 { \ 84 { _Py_STATIC_IMMORTAL_INITIAL_REFCNT }, \ 85 (type) \ 86 }, 87 #endif 88 89 #define PyVarObject_HEAD_INIT(type, size) \ 90 { \ 91 PyObject_HEAD_INIT(type) \ 92 (size) \ 93 }, 94 95 /* PyObject_VAR_HEAD defines the initial segment of all variable-size 96 * container objects. These end with a declaration of an array with 1 97 * element, but enough space is malloc'ed so that the array actually 98 * has room for ob_size elements. Note that ob_size is an element count, 99 * not necessarily a byte count. 100 */ 101 #define PyObject_VAR_HEAD PyVarObject ob_base; 102 #define Py_INVALID_SIZE (Py_ssize_t)-1 103 104 /* PyObjects are given a minimum alignment so that the least significant bits 105 * of an object pointer become available for other purposes. 106 * This must be an integer literal with the value (1 << _PyGC_PREV_SHIFT), number of bytes. 107 */ 108 #define _PyObject_MIN_ALIGNMENT 4 109 110 /* Nothing is actually declared to be a PyObject, but every pointer to 111 * a Python object can be cast to a PyObject*. This is inheritance built 112 * by hand. Similarly every pointer to a variable-size Python object can, 113 * in addition, be cast to PyVarObject*. 114 */ 115 #ifndef Py_GIL_DISABLED 116 struct _object { 117 #if (defined(__GNUC__) || defined(__clang__)) \ 118 && !(defined __STDC_VERSION__ && __STDC_VERSION__ >= 201112L) 119 // On C99 and older, anonymous union is a GCC and clang extension 120 __extension__ 121 #endif 122 #ifdef _MSC_VER 123 // Ignore MSC warning C4201: "nonstandard extension used: 124 // nameless struct/union" 125 __pragma(warning(push)) 126 __pragma(warning(disable: 4201)) 127 #endif 128 union { 129 #if SIZEOF_VOID_P > 4 130 PY_INT64_T ob_refcnt_full; /* This field is needed for efficient initialization with Clang on ARM */ 131 struct { 132 # if PY_BIG_ENDIAN 133 uint16_t ob_flags; 134 uint16_t ob_overflow; 135 uint32_t ob_refcnt; 136 # else 137 uint32_t ob_refcnt; 138 uint16_t ob_overflow; 139 uint16_t ob_flags; 140 # endif 141 }; 142 #else 143 Py_ssize_t ob_refcnt; 144 #endif 145 _Py_ALIGNED_DEF(_PyObject_MIN_ALIGNMENT, char) _aligner; 146 }; 147 #ifdef _MSC_VER 148 __pragma(warning(pop)) 149 #endif 150 151 PyTypeObject *ob_type; 152 }; 153 #else 154 // Objects that are not owned by any thread use a thread id (tid) of zero. 155 // This includes both immortal objects and objects whose reference count 156 // fields have been merged. 157 #define _Py_UNOWNED_TID 0 158 159 struct _object { 160 // ob_tid stores the thread id (or zero). It is also used by the GC and the 161 // trashcan mechanism as a linked list pointer and by the GC to store the 162 // computed "gc_refs" refcount. 163 _Py_ALIGNED_DEF(_PyObject_MIN_ALIGNMENT, uintptr_t) ob_tid; 164 uint16_t ob_flags; 165 PyMutex ob_mutex; // per-object lock 166 uint8_t ob_gc_bits; // gc-related state 167 uint32_t ob_ref_local; // local reference count 168 Py_ssize_t ob_ref_shared; // shared (atomic) reference count 169 PyTypeObject *ob_type; 170 }; 171 #endif 172 173 /* Cast argument to PyObject* type. */ 174 #define _PyObject_CAST(op) _Py_CAST(PyObject*, (op)) 175 176 typedef struct { 177 PyObject ob_base; 178 Py_ssize_t ob_size; /* Number of items in variable part */ 179 } PyVarObject; 180 181 /* Cast argument to PyVarObject* type. */ 182 #define _PyVarObject_CAST(op) _Py_CAST(PyVarObject*, (op)) 183 184 185 // Test if the 'x' object is the 'y' object, the same as "x is y" in Python. 186 PyAPI_FUNC(int) Py_Is(PyObject *x, PyObject *y); 187 #define Py_Is(x, y) ((x) == (y)) 188 189 #if defined(Py_GIL_DISABLED) && !defined(Py_LIMITED_API) 190 PyAPI_FUNC(uintptr_t) _Py_GetThreadLocal_Addr(void); 191 192 static inline uintptr_t 193 _Py_ThreadId(void) 194 { 195 uintptr_t tid; 196 #if defined(_MSC_VER) && defined(_M_X64) 197 tid = __readgsqword(48); 198 #elif defined(_MSC_VER) && defined(_M_IX86) 199 tid = __readfsdword(24); 200 #elif defined(_MSC_VER) && defined(_M_ARM64) 201 tid = __getReg(18); 202 #elif defined(__MINGW32__) && defined(_M_X64) 203 tid = __readgsqword(48); 204 #elif defined(__MINGW32__) && defined(_M_IX86) 205 tid = __readfsdword(24); 206 #elif defined(__MINGW32__) && defined(_M_ARM64) 207 tid = __getReg(18); 208 #elif defined(__i386__) 209 __asm__("{movl %%gs:0, %0|mov %0, dword ptr gs:[0]}" : "=r" (tid)); // 32-bit always uses GS 210 #elif defined(__MACH__) && defined(__x86_64__) 211 __asm__("{movq %%gs:0, %0|mov %0, qword ptr gs:[0]}" : "=r" (tid)); // x86_64 macOSX uses GS 212 #elif defined(__x86_64__) 213 __asm__("{movq %%fs:0, %0|mov %0, qword ptr fs:[0]}" : "=r" (tid)); // x86_64 Linux, BSD uses FS 214 #elif defined(__arm__) && __ARM_ARCH >= 7 215 __asm__ ("mrc p15, 0, %0, c13, c0, 3\nbic %0, %0, #3" : "=r" (tid)); 216 #elif defined(__aarch64__) && defined(__APPLE__) 217 __asm__ ("mrs %0, tpidrro_el0" : "=r" (tid)); 218 #elif defined(__aarch64__) 219 __asm__ ("mrs %0, tpidr_el0" : "=r" (tid)); 220 #elif defined(__powerpc64__) 221 #if defined(__clang__) && _Py__has_builtin(__builtin_thread_pointer) 222 tid = (uintptr_t)__builtin_thread_pointer(); 223 #else 224 // r13 is reserved for use as system thread ID by the Power 64-bit ABI. 225 register uintptr_t tp __asm__ ("r13"); 226 __asm__("" : "=r" (tp)); 227 tid = tp; 228 #endif 229 #elif defined(__powerpc__) 230 #if defined(__clang__) && _Py__has_builtin(__builtin_thread_pointer) 231 tid = (uintptr_t)__builtin_thread_pointer(); 232 #else 233 // r2 is reserved for use as system thread ID by the Power 32-bit ABI. 234 register uintptr_t tp __asm__ ("r2"); 235 __asm__ ("" : "=r" (tp)); 236 tid = tp; 237 #endif 238 #elif defined(__s390__) && defined(__GNUC__) 239 // Both GCC and Clang have supported __builtin_thread_pointer 240 // for s390 from long time ago. 241 tid = (uintptr_t)__builtin_thread_pointer(); 242 #elif defined(__riscv) 243 #if defined(__clang__) && _Py__has_builtin(__builtin_thread_pointer) 244 tid = (uintptr_t)__builtin_thread_pointer(); 245 #else 246 // tp is Thread Pointer provided by the RISC-V ABI. 247 __asm__ ("mv %0, tp" : "=r" (tid)); 248 #endif 249 #else 250 // Fallback to a portable implementation if we do not have a faster 251 // platform-specific implementation. 252 tid = _Py_GetThreadLocal_Addr(); 253 #endif 254 return tid; 255 } 256 257 static inline Py_ALWAYS_INLINE int 258 _Py_IsOwnedByCurrentThread(PyObject *ob) 259 { 260 #ifdef _Py_THREAD_SANITIZER 261 return _Py_atomic_load_uintptr_relaxed(&ob->ob_tid) == _Py_ThreadId(); 262 #else 263 return ob->ob_tid == _Py_ThreadId(); 264 #endif 265 } 266 #endif 267 268 // Py_TYPE() implementation for the stable ABI 269 PyAPI_FUNC(PyTypeObject*) Py_TYPE(PyObject *ob); 270 271 #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030e0000 272 // Stable ABI implements Py_TYPE() as a function call 273 // on limited C API version 3.14 and newer. 274 #else 275 static inline PyTypeObject* _Py_TYPE(PyObject *ob) 276 { 277 return ob->ob_type; 278 } 279 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000 280 # define Py_TYPE(ob) _Py_TYPE(_PyObject_CAST(ob)) 281 #else 282 # define Py_TYPE(ob) _Py_TYPE(ob) 283 #endif 284 #endif 285 286 PyAPI_DATA(PyTypeObject) PyLong_Type; 287 PyAPI_DATA(PyTypeObject) PyBool_Type; 288 289 // bpo-39573: The Py_SET_SIZE() function must be used to set an object size. 290 static inline Py_ssize_t Py_SIZE(PyObject *ob) { 291 assert(Py_TYPE(ob) != &PyLong_Type); 292 assert(Py_TYPE(ob) != &PyBool_Type); 293 return _PyVarObject_CAST(ob)->ob_size; 294 } 295 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000 296 # define Py_SIZE(ob) Py_SIZE(_PyObject_CAST(ob)) 297 #endif 298 299 static inline int Py_IS_TYPE(PyObject *ob, PyTypeObject *type) { 300 return Py_TYPE(ob) == type; 301 } 302 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000 303 # define Py_IS_TYPE(ob, type) Py_IS_TYPE(_PyObject_CAST(ob), (type)) 304 #endif 305 306 307 static inline void Py_SET_TYPE(PyObject *ob, PyTypeObject *type) { 308 ob->ob_type = type; 309 } 310 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000 311 # define Py_SET_TYPE(ob, type) Py_SET_TYPE(_PyObject_CAST(ob), type) 312 #endif 313 314 static inline void Py_SET_SIZE(PyVarObject *ob, Py_ssize_t size) { 315 assert(Py_TYPE(_PyObject_CAST(ob)) != &PyLong_Type); 316 assert(Py_TYPE(_PyObject_CAST(ob)) != &PyBool_Type); 317 #ifdef Py_GIL_DISABLED 318 _Py_atomic_store_ssize_relaxed(&ob->ob_size, size); 319 #else 320 ob->ob_size = size; 321 #endif 322 } 323 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000 324 # define Py_SET_SIZE(ob, size) Py_SET_SIZE(_PyVarObject_CAST(ob), (size)) 325 #endif 326 327 328 /* 329 Type objects contain a string containing the type name (to help somewhat 330 in debugging), the allocation parameters (see PyObject_New() and 331 PyObject_NewVar()), 332 and methods for accessing objects of the type. Methods are optional, a 333 nil pointer meaning that particular kind of access is not available for 334 this type. The Py_DECREF() macro uses the tp_dealloc method without 335 checking for a nil pointer; it should always be implemented except if 336 the implementation can guarantee that the reference count will never 337 reach zero (e.g., for statically allocated type objects). 338 339 NB: the methods for certain type groups are now contained in separate 340 method blocks. 341 */ 342 343 typedef PyObject * (*unaryfunc)(PyObject *); 344 typedef PyObject * (*binaryfunc)(PyObject *, PyObject *); 345 typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *); 346 typedef int (*inquiry)(PyObject *); 347 typedef Py_ssize_t (*lenfunc)(PyObject *); 348 typedef PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t); 349 typedef PyObject *(*ssizessizeargfunc)(PyObject *, Py_ssize_t, Py_ssize_t); 350 typedef int(*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *); 351 typedef int(*ssizessizeobjargproc)(PyObject *, Py_ssize_t, Py_ssize_t, PyObject *); 352 typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *); 353 354 typedef int (*objobjproc)(PyObject *, PyObject *); 355 typedef int (*visitproc)(PyObject *, void *); 356 typedef int (*traverseproc)(PyObject *, visitproc, void *); 357 358 359 typedef void (*freefunc)(void *); 360 typedef void (*destructor)(PyObject *); 361 typedef PyObject *(*getattrfunc)(PyObject *, char *); 362 typedef PyObject *(*getattrofunc)(PyObject *, PyObject *); 363 typedef int (*setattrfunc)(PyObject *, char *, PyObject *); 364 typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *); 365 typedef PyObject *(*reprfunc)(PyObject *); 366 typedef Py_hash_t (*hashfunc)(PyObject *); 367 typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int); 368 typedef PyObject *(*getiterfunc) (PyObject *); 369 typedef PyObject *(*iternextfunc) (PyObject *); 370 typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *); 371 typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *); 372 typedef int (*initproc)(PyObject *, PyObject *, PyObject *); 373 typedef PyObject *(*newfunc)(PyTypeObject *, PyObject *, PyObject *); 374 typedef PyObject *(*allocfunc)(PyTypeObject *, Py_ssize_t); 375 376 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030c0000 // 3.12 377 typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, 378 size_t nargsf, PyObject *kwnames); 379 #endif 380 381 typedef struct{ 382 int slot; /* slot id, see below */ 383 void *pfunc; /* function pointer */ 384 } PyType_Slot; 385 386 typedef struct{ 387 const char* name; 388 int basicsize; 389 int itemsize; 390 unsigned int flags; 391 PyType_Slot *slots; /* terminated by slot==0. */ 392 } PyType_Spec; 393 394 PyAPI_FUNC(PyObject*) PyType_FromSpec(PyType_Spec*); 395 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 396 PyAPI_FUNC(PyObject*) PyType_FromSpecWithBases(PyType_Spec*, PyObject*); 397 #endif 398 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03040000 399 PyAPI_FUNC(void*) PyType_GetSlot(PyTypeObject*, int); 400 #endif 401 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000 402 PyAPI_FUNC(PyObject*) PyType_FromModuleAndSpec(PyObject *, PyType_Spec *, PyObject *); 403 PyAPI_FUNC(PyObject *) PyType_GetModule(PyTypeObject *); 404 PyAPI_FUNC(void *) PyType_GetModuleState(PyTypeObject *); 405 #endif 406 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030B0000 407 PyAPI_FUNC(PyObject *) PyType_GetName(PyTypeObject *); 408 PyAPI_FUNC(PyObject *) PyType_GetQualName(PyTypeObject *); 409 #endif 410 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030D0000 411 PyAPI_FUNC(PyObject *) PyType_GetFullyQualifiedName(PyTypeObject *type); 412 PyAPI_FUNC(PyObject *) PyType_GetModuleName(PyTypeObject *type); 413 #endif 414 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030C0000 415 PyAPI_FUNC(PyObject *) PyType_FromMetaclass(PyTypeObject*, PyObject*, PyType_Spec*, PyObject*); 416 PyAPI_FUNC(void *) PyObject_GetTypeData(PyObject *obj, PyTypeObject *cls); 417 PyAPI_FUNC(Py_ssize_t) PyType_GetTypeDataSize(PyTypeObject *cls); 418 #endif 419 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030E0000 420 PyAPI_FUNC(int) PyType_GetBaseByToken(PyTypeObject *, void *, PyTypeObject **); 421 #define Py_TP_USE_SPEC NULL 422 #endif 423 424 /* Generic type check */ 425 PyAPI_FUNC(int) PyType_IsSubtype(PyTypeObject *, PyTypeObject *); 426 427 static inline int PyObject_TypeCheck(PyObject *ob, PyTypeObject *type) { 428 return Py_IS_TYPE(ob, type) || PyType_IsSubtype(Py_TYPE(ob), type); 429 } 430 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000 431 # define PyObject_TypeCheck(ob, type) PyObject_TypeCheck(_PyObject_CAST(ob), (type)) 432 #endif 433 434 PyAPI_DATA(PyTypeObject) PyType_Type; /* built-in 'type' */ 435 PyAPI_DATA(PyTypeObject) PyBaseObject_Type; /* built-in 'object' */ 436 PyAPI_DATA(PyTypeObject) PySuper_Type; /* built-in 'super' */ 437 438 PyAPI_FUNC(unsigned long) PyType_GetFlags(PyTypeObject*); 439 440 PyAPI_FUNC(int) PyType_Ready(PyTypeObject *); 441 PyAPI_FUNC(PyObject *) PyType_GenericAlloc(PyTypeObject *, Py_ssize_t); 442 PyAPI_FUNC(PyObject *) PyType_GenericNew(PyTypeObject *, 443 PyObject *, PyObject *); 444 PyAPI_FUNC(unsigned int) PyType_ClearCache(void); 445 PyAPI_FUNC(void) PyType_Modified(PyTypeObject *); 446 447 /* Generic operations on objects */ 448 PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *); 449 PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *); 450 PyAPI_FUNC(PyObject *) PyObject_ASCII(PyObject *); 451 PyAPI_FUNC(PyObject *) PyObject_Bytes(PyObject *); 452 PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int); 453 PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int); 454 PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *); 455 PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *); 456 PyAPI_FUNC(int) PyObject_DelAttrString(PyObject *v, const char *name); 457 PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *); 458 PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *); 459 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000 460 PyAPI_FUNC(int) PyObject_GetOptionalAttr(PyObject *, PyObject *, PyObject **); 461 PyAPI_FUNC(int) PyObject_GetOptionalAttrString(PyObject *, const char *, PyObject **); 462 #endif 463 PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *); 464 PyAPI_FUNC(int) PyObject_DelAttr(PyObject *v, PyObject *name); 465 PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *); 466 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000 467 PyAPI_FUNC(int) PyObject_HasAttrWithError(PyObject *, PyObject *); 468 PyAPI_FUNC(int) PyObject_HasAttrStringWithError(PyObject *, const char *); 469 #endif 470 PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *); 471 PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *); 472 PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *, PyObject *, PyObject *); 473 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 474 PyAPI_FUNC(int) PyObject_GenericSetDict(PyObject *, PyObject *, void *); 475 #endif 476 PyAPI_FUNC(Py_hash_t) PyObject_Hash(PyObject *); 477 PyAPI_FUNC(Py_hash_t) PyObject_HashNotImplemented(PyObject *); 478 PyAPI_FUNC(int) PyObject_IsTrue(PyObject *); 479 PyAPI_FUNC(int) PyObject_Not(PyObject *); 480 PyAPI_FUNC(int) PyCallable_Check(PyObject *); 481 PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *); 482 483 /* PyObject_Dir(obj) acts like Python builtins.dir(obj), returning a 484 list of strings. PyObject_Dir(NULL) is like builtins.dir(), 485 returning the names of the current locals. In this case, if there are 486 no current locals, NULL is returned, and PyErr_Occurred() is false. 487 */ 488 PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *); 489 490 /* Helpers for printing recursive container types */ 491 PyAPI_FUNC(int) Py_ReprEnter(PyObject *); 492 PyAPI_FUNC(void) Py_ReprLeave(PyObject *); 493 494 /* Flag bits for printing: */ 495 #define Py_PRINT_RAW 1 /* No string quotes etc. */ 496 497 /* 498 Type flags (tp_flags) 499 500 These flags are used to change expected features and behavior for a 501 particular type. 502 503 Arbitration of the flag bit positions will need to be coordinated among 504 all extension writers who publicly release their extensions (this will 505 be fewer than you might expect!). 506 507 Most flags were removed as of Python 3.0 to make room for new flags. (Some 508 flags are not for backwards compatibility but to indicate the presence of an 509 optional feature; these flags remain of course.) 510 511 Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value. 512 513 Code can use PyType_HasFeature(type_ob, flag_value) to test whether the 514 given type object has a specified feature. 515 */ 516 517 #ifndef Py_LIMITED_API 518 519 /* Track types initialized using _PyStaticType_InitBuiltin(). */ 520 #define _Py_TPFLAGS_STATIC_BUILTIN (1 << 1) 521 522 /* The values array is placed inline directly after the rest of 523 * the object. Implies Py_TPFLAGS_HAVE_GC. 524 */ 525 #define Py_TPFLAGS_INLINE_VALUES (1 << 2) 526 527 /* Placement of weakref pointers are managed by the VM, not by the type. 528 * The VM will automatically set tp_weaklistoffset. 529 */ 530 #define Py_TPFLAGS_MANAGED_WEAKREF (1 << 3) 531 532 /* Placement of dict (and values) pointers are managed by the VM, not by the type. 533 * The VM will automatically set tp_dictoffset. Implies Py_TPFLAGS_HAVE_GC. 534 */ 535 #define Py_TPFLAGS_MANAGED_DICT (1 << 4) 536 537 #define Py_TPFLAGS_PREHEADER (Py_TPFLAGS_MANAGED_WEAKREF | Py_TPFLAGS_MANAGED_DICT) 538 539 /* Set if instances of the type object are treated as sequences for pattern matching */ 540 #define Py_TPFLAGS_SEQUENCE (1 << 5) 541 /* Set if instances of the type object are treated as mappings for pattern matching */ 542 #define Py_TPFLAGS_MAPPING (1 << 6) 543 #endif 544 545 /* Disallow creating instances of the type: set tp_new to NULL and don't create 546 * the "__new__" key in the type dictionary. */ 547 #define Py_TPFLAGS_DISALLOW_INSTANTIATION (1UL << 7) 548 549 /* Set if the type object is immutable: type attributes cannot be set nor deleted */ 550 #define Py_TPFLAGS_IMMUTABLETYPE (1UL << 8) 551 552 /* Set if the type object is dynamically allocated */ 553 #define Py_TPFLAGS_HEAPTYPE (1UL << 9) 554 555 /* Set if the type allows subclassing */ 556 #define Py_TPFLAGS_BASETYPE (1UL << 10) 557 558 /* Set if the type implements the vectorcall protocol (PEP 590) */ 559 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030C0000 560 #define Py_TPFLAGS_HAVE_VECTORCALL (1UL << 11) 561 #ifndef Py_LIMITED_API 562 // Backwards compatibility alias for API that was provisional in Python 3.8 563 #define _Py_TPFLAGS_HAVE_VECTORCALL Py_TPFLAGS_HAVE_VECTORCALL 564 #endif 565 #endif 566 567 /* Set if the type is 'ready' -- fully initialized */ 568 #define Py_TPFLAGS_READY (1UL << 12) 569 570 /* Set while the type is being 'readied', to prevent recursive ready calls */ 571 #define Py_TPFLAGS_READYING (1UL << 13) 572 573 /* Objects support garbage collection (see objimpl.h) */ 574 #define Py_TPFLAGS_HAVE_GC (1UL << 14) 575 576 /* These two bits are preserved for Stackless Python, next after this is 17 */ 577 #ifdef STACKLESS 578 #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3UL << 15) 579 #else 580 #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0 581 #endif 582 583 /* Objects behave like an unbound method */ 584 #define Py_TPFLAGS_METHOD_DESCRIPTOR (1UL << 17) 585 586 /* Unused. Legacy flag */ 587 #define Py_TPFLAGS_VALID_VERSION_TAG (1UL << 19) 588 589 /* Type is abstract and cannot be instantiated */ 590 #define Py_TPFLAGS_IS_ABSTRACT (1UL << 20) 591 592 // This undocumented flag gives certain built-ins their unique pattern-matching 593 // behavior, which allows a single positional subpattern to match against the 594 // subject itself (rather than a mapped attribute on it): 595 #define _Py_TPFLAGS_MATCH_SELF (1UL << 22) 596 597 /* Items (ob_size*tp_itemsize) are found at the end of an instance's memory */ 598 #define Py_TPFLAGS_ITEMS_AT_END (1UL << 23) 599 600 /* These flags are used to determine if a type is a subclass. */ 601 #define Py_TPFLAGS_LONG_SUBCLASS (1UL << 24) 602 #define Py_TPFLAGS_LIST_SUBCLASS (1UL << 25) 603 #define Py_TPFLAGS_TUPLE_SUBCLASS (1UL << 26) 604 #define Py_TPFLAGS_BYTES_SUBCLASS (1UL << 27) 605 #define Py_TPFLAGS_UNICODE_SUBCLASS (1UL << 28) 606 #define Py_TPFLAGS_DICT_SUBCLASS (1UL << 29) 607 #define Py_TPFLAGS_BASE_EXC_SUBCLASS (1UL << 30) 608 #define Py_TPFLAGS_TYPE_SUBCLASS (1UL << 31) 609 610 #define Py_TPFLAGS_DEFAULT ( \ 611 Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \ 612 0) 613 614 /* NOTE: Some of the following flags reuse lower bits (removed as part of the 615 * Python 3.0 transition). */ 616 617 /* The following flags are kept for compatibility; in previous 618 * versions they indicated presence of newer tp_* fields on the 619 * type struct. 620 * Starting with 3.8, binary compatibility of C extensions across 621 * feature releases of Python is not supported anymore (except when 622 * using the stable ABI, in which all classes are created dynamically, 623 * using the interpreter's memory layout.) 624 * Note that older extensions using the stable ABI set these flags, 625 * so the bits must not be repurposed. 626 */ 627 #define Py_TPFLAGS_HAVE_FINALIZE (1UL << 0) 628 #define Py_TPFLAGS_HAVE_VERSION_TAG (1UL << 18) 629 630 631 #define Py_CONSTANT_NONE 0 632 #define Py_CONSTANT_FALSE 1 633 #define Py_CONSTANT_TRUE 2 634 #define Py_CONSTANT_ELLIPSIS 3 635 #define Py_CONSTANT_NOT_IMPLEMENTED 4 636 #define Py_CONSTANT_ZERO 5 637 #define Py_CONSTANT_ONE 6 638 #define Py_CONSTANT_EMPTY_STR 7 639 #define Py_CONSTANT_EMPTY_BYTES 8 640 #define Py_CONSTANT_EMPTY_TUPLE 9 641 642 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000 643 PyAPI_FUNC(PyObject*) Py_GetConstant(unsigned int constant_id); 644 PyAPI_FUNC(PyObject*) Py_GetConstantBorrowed(unsigned int constant_id); 645 #endif 646 647 648 /* 649 _Py_NoneStruct is an object of undefined type which can be used in contexts 650 where NULL (nil) is not suitable (since NULL often means 'error'). 651 */ 652 PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */ 653 654 #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030D0000 655 # define Py_None Py_GetConstantBorrowed(Py_CONSTANT_NONE) 656 #else 657 # define Py_None (&_Py_NoneStruct) 658 #endif 659 660 // Test if an object is the None singleton, the same as "x is None" in Python. 661 PyAPI_FUNC(int) Py_IsNone(PyObject *x); 662 #define Py_IsNone(x) Py_Is((x), Py_None) 663 664 /* Macro for returning Py_None from a function. 665 * Only treat Py_None as immortal in the limited C API 3.12 and newer. */ 666 #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 < 0x030c0000 667 # define Py_RETURN_NONE return Py_NewRef(Py_None) 668 #else 669 # define Py_RETURN_NONE return Py_None 670 #endif 671 672 /* 673 Py_NotImplemented is a singleton used to signal that an operation is 674 not implemented for a given type combination. 675 */ 676 PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */ 677 678 #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030D0000 679 # define Py_NotImplemented Py_GetConstantBorrowed(Py_CONSTANT_NOT_IMPLEMENTED) 680 #else 681 # define Py_NotImplemented (&_Py_NotImplementedStruct) 682 #endif 683 684 /* Macro for returning Py_NotImplemented from a function. Only treat 685 * Py_NotImplemented as immortal in the limited C API 3.12 and newer. */ 686 #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 < 0x030c0000 687 # define Py_RETURN_NOTIMPLEMENTED return Py_NewRef(Py_NotImplemented) 688 #else 689 # define Py_RETURN_NOTIMPLEMENTED return Py_NotImplemented 690 #endif 691 692 /* Rich comparison opcodes */ 693 #define Py_LT 0 694 #define Py_LE 1 695 #define Py_EQ 2 696 #define Py_NE 3 697 #define Py_GT 4 698 #define Py_GE 5 699 700 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000 701 /* Result of calling PyIter_Send */ 702 typedef enum { 703 PYGEN_RETURN = 0, 704 PYGEN_ERROR = -1, 705 PYGEN_NEXT = 1 706 } PySendResult; 707 #endif 708 709 /* 710 * Macro for implementing rich comparisons 711 * 712 * Needs to be a macro because any C-comparable type can be used. 713 */ 714 #define Py_RETURN_RICHCOMPARE(val1, val2, op) \ 715 do { \ 716 switch (op) { \ 717 case Py_EQ: if ((val1) == (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \ 718 case Py_NE: if ((val1) != (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \ 719 case Py_LT: if ((val1) < (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \ 720 case Py_GT: if ((val1) > (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \ 721 case Py_LE: if ((val1) <= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \ 722 case Py_GE: if ((val1) >= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \ 723 default: \ 724 Py_UNREACHABLE(); \ 725 } \ 726 } while (0) 727 728 729 /* 730 More conventions 731 ================ 732 733 Argument Checking 734 ----------------- 735 736 Functions that take objects as arguments normally don't check for nil 737 arguments, but they do check the type of the argument, and return an 738 error if the function doesn't apply to the type. 739 740 Failure Modes 741 ------------- 742 743 Functions may fail for a variety of reasons, including running out of 744 memory. This is communicated to the caller in two ways: an error string 745 is set (see errors.h), and the function result differs: functions that 746 normally return a pointer return NULL for failure, functions returning 747 an integer return -1 (which could be a legal return value too!), and 748 other functions return 0 for success and -1 for failure. 749 Callers should always check for errors before using the result. If 750 an error was set, the caller must either explicitly clear it, or pass 751 the error on to its caller. 752 753 Reference Counts 754 ---------------- 755 756 It takes a while to get used to the proper usage of reference counts. 757 758 Functions that create an object set the reference count to 1; such new 759 objects must be stored somewhere or destroyed again with Py_DECREF(). 760 Some functions that 'store' objects, such as PyTuple_SetItem() and 761 PyList_SetItem(), 762 don't increment the reference count of the object, since the most 763 frequent use is to store a fresh object. Functions that 'retrieve' 764 objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also 765 don't increment 766 the reference count, since most frequently the object is only looked at 767 quickly. Thus, to retrieve an object and store it again, the caller 768 must call Py_INCREF() explicitly. 769 770 NOTE: functions that 'consume' a reference count, like 771 PyList_SetItem(), consume the reference even if the object wasn't 772 successfully stored, to simplify error handling. 773 774 It seems attractive to make other functions that take an object as 775 argument consume a reference count; however, this may quickly get 776 confusing (even the current practice is already confusing). Consider 777 it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at 778 times. 779 */ 780 781 #ifndef Py_LIMITED_API 782 # define Py_CPYTHON_OBJECT_H 783 # include "cpython/object.h" 784 # undef Py_CPYTHON_OBJECT_H 785 #endif 786 787 788 static inline int 789 PyType_HasFeature(PyTypeObject *type, unsigned long feature) 790 { 791 unsigned long flags; 792 #ifdef Py_LIMITED_API 793 // PyTypeObject is opaque in the limited C API 794 flags = PyType_GetFlags(type); 795 #else 796 # ifdef Py_GIL_DISABLED 797 flags = _Py_atomic_load_ulong_relaxed(&type->tp_flags); 798 # else 799 flags = type->tp_flags; 800 # endif 801 #endif 802 return ((flags & feature) != 0); 803 } 804 805 #define PyType_FastSubclass(type, flag) PyType_HasFeature((type), (flag)) 806 807 static inline int PyType_Check(PyObject *op) { 808 return PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS); 809 } 810 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000 811 # define PyType_Check(op) PyType_Check(_PyObject_CAST(op)) 812 #endif 813 814 #define _PyType_CAST(op) \ 815 (assert(PyType_Check(op)), _Py_CAST(PyTypeObject*, (op))) 816 817 static inline int PyType_CheckExact(PyObject *op) { 818 return Py_IS_TYPE(op, &PyType_Type); 819 } 820 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000 821 # define PyType_CheckExact(op) PyType_CheckExact(_PyObject_CAST(op)) 822 #endif 823 824 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000 825 PyAPI_FUNC(PyObject *) PyType_GetModuleByDef(PyTypeObject *, PyModuleDef *); 826 #endif 827 828 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030e0000 829 PyAPI_FUNC(int) PyType_Freeze(PyTypeObject *type); 830 #endif 831 832 #ifdef __cplusplus 833 } 834 #endif 835 #endif // !Py_OBJECT_H
