Debian Codegraph @

Doc/c-api/object.rst

raw
1 .. highlight:: c
2
3 .. _object:
4
5 Object Protocol
6 ===============
7
8
9 .. c:function:: PyObject* Py_GetConstant(unsigned int constant_id)
10
11 Get a :term:`strong reference` to a constant.
12
13 Set an exception and return ``NULL`` if *constant_id* is invalid.
14
15 *constant_id* must be one of these constant identifiers:
16
17 .. c:namespace:: NULL
18
19 ======================================== ===== =========================
20 Constant Identifier Value Returned object
21 ======================================== ===== =========================
22 .. c:macro:: Py_CONSTANT_NONE ``0`` :py:data:`None`
23 .. c:macro:: Py_CONSTANT_FALSE ``1`` :py:data:`False`
24 .. c:macro:: Py_CONSTANT_TRUE ``2`` :py:data:`True`
25 .. c:macro:: Py_CONSTANT_ELLIPSIS ``3`` :py:data:`Ellipsis`
26 .. c:macro:: Py_CONSTANT_NOT_IMPLEMENTED ``4`` :py:data:`NotImplemented`
27 .. c:macro:: Py_CONSTANT_ZERO ``5`` ``0``
28 .. c:macro:: Py_CONSTANT_ONE ``6`` ``1``
29 .. c:macro:: Py_CONSTANT_EMPTY_STR ``7`` ``''``
30 .. c:macro:: Py_CONSTANT_EMPTY_BYTES ``8`` ``b''``
31 .. c:macro:: Py_CONSTANT_EMPTY_TUPLE ``9`` ``()``
32 ======================================== ===== =========================
33
34 Numeric values are only given for projects which cannot use the constant
35 identifiers.
36
37
38 .. versionadded:: 3.13
39
40 .. impl-detail::
41
42 In CPython, all of these constants are :term:`immortal`.
43
44
45 .. c:function:: PyObject* Py_GetConstantBorrowed(unsigned int constant_id)
46
47 Similar to :c:func:`Py_GetConstant`, but return a :term:`borrowed
48 reference`.
49
50 This function is primarily intended for backwards compatibility:
51 using :c:func:`Py_GetConstant` is recommended for new code.
52
53 The reference is borrowed from the interpreter, and is valid until the
54 interpreter finalization.
55
56 .. versionadded:: 3.13
57
58
59 .. c:var:: PyObject* Py_NotImplemented
60
61 The ``NotImplemented`` singleton, used to signal that an operation is
62 not implemented for the given type combination.
63
64
65 .. c:macro:: Py_RETURN_NOTIMPLEMENTED
66
67 Properly handle returning :c:data:`Py_NotImplemented` from within a C
68 function (that is, create a new :term:`strong reference`
69 to :const:`NotImplemented` and return it).
70
71
72 .. c:macro:: Py_PRINT_RAW
73
74 Flag to be used with multiple functions that print the object (like
75 :c:func:`PyObject_Print` and :c:func:`PyFile_WriteObject`).
76 If passed, these functions use the :func:`str` of the object
77 instead of the :func:`repr`.
78
79
80 .. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
81
82 Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags argument
83 is used to enable certain printing options. The only option currently supported
84 is :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
85 instead of the :func:`repr`.
86
87
88 .. c:function:: int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)
89
90 Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.
91 This is equivalent to the Python expression ``hasattr(o, attr_name)``.
92 On failure, return ``-1``.
93
94 .. versionadded:: 3.13
95
96
97 .. c:function:: int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)
98
99 This is the same as :c:func:`PyObject_HasAttrWithError`, but *attr_name* is
100 specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
101 rather than a :c:expr:`PyObject*`.
102
103 .. versionadded:: 3.13
104
105
106 .. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
107
108 Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.
109 This function always succeeds.
110
111 .. note::
112
113 Exceptions that occur when this calls :meth:`~object.__getattr__` and
114 :meth:`~object.__getattribute__` methods aren't propagated,
115 but instead given to :func:`sys.unraisablehook`.
116 For proper error handling, use :c:func:`PyObject_HasAttrWithError`,
117 :c:func:`PyObject_GetOptionalAttr` or :c:func:`PyObject_GetAttr` instead.
118
119
120 .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
121
122 This is the same as :c:func:`PyObject_HasAttr`, but *attr_name* is
123 specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
124 rather than a :c:expr:`PyObject*`.
125
126 .. note::
127
128 Exceptions that occur when this calls :meth:`~object.__getattr__` and
129 :meth:`~object.__getattribute__` methods or while creating the temporary
130 :class:`str` object are silently ignored.
131 For proper error handling, use :c:func:`PyObject_HasAttrStringWithError`,
132 :c:func:`PyObject_GetOptionalAttrString`
133 or :c:func:`PyObject_GetAttrString` instead.
134
135
136 .. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
137
138 Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
139 value on success, or ``NULL`` on failure. This is the equivalent of the Python
140 expression ``o.attr_name``.
141
142 If the missing attribute should not be treated as a failure, you can use
143 :c:func:`PyObject_GetOptionalAttr` instead.
144
145
146 .. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
147
148 This is the same as :c:func:`PyObject_GetAttr`, but *attr_name* is
149 specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
150 rather than a :c:expr:`PyObject*`.
151
152 If the missing attribute should not be treated as a failure, you can use
153 :c:func:`PyObject_GetOptionalAttrString` instead.
154
155
156 .. c:function:: int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);
157
158 Variant of :c:func:`PyObject_GetAttr` which doesn't raise
159 :exc:`AttributeError` if the attribute is not found.
160
161 If the attribute is found, return ``1`` and set *\*result* to a new
162 :term:`strong reference` to the attribute.
163 If the attribute is not found, return ``0`` and set *\*result* to ``NULL``;
164 the :exc:`AttributeError` is silenced.
165 If an error other than :exc:`AttributeError` is raised, return ``-1`` and
166 set *\*result* to ``NULL``.
167
168 .. versionadded:: 3.13
169
170
171 .. c:function:: int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);
172
173 This is the same as :c:func:`PyObject_GetOptionalAttr`, but *attr_name* is
174 specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
175 rather than a :c:expr:`PyObject*`.
176
177 .. versionadded:: 3.13
178
179 .. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
180
181 Generic attribute getter function that is meant to be put into a type
182 object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary
183 of classes in the object's MRO as well as an attribute in the object's
184 :attr:`~object.__dict__` (if present). As outlined in :ref:`descriptors`,
185 data descriptors take preference over instance attributes, while non-data
186 descriptors don't. Otherwise, an :exc:`AttributeError` is raised.
187
188
189 .. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
190
191 Set the value of the attribute named *attr_name*, for object *o*, to the value
192 *v*. Raise an exception and return ``-1`` on failure;
193 return ``0`` on success. This is the equivalent of the Python statement
194 ``o.attr_name = v``.
195
196 If *v* is ``NULL``, the attribute is deleted. This behaviour is deprecated
197 in favour of using :c:func:`PyObject_DelAttr`, but there are currently no
198 plans to remove it.
199
200
201 .. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
202
203 This is the same as :c:func:`PyObject_SetAttr`, but *attr_name* is
204 specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
205 rather than a :c:expr:`PyObject*`.
206
207 If *v* is ``NULL``, the attribute is deleted, but this feature is
208 deprecated in favour of using :c:func:`PyObject_DelAttrString`.
209
210 The number of different attribute names passed to this function
211 should be kept small, usually by using a statically allocated string
212 as *attr_name*.
213 For attribute names that aren't known at compile time, prefer calling
214 :c:func:`PyUnicode_FromString` and :c:func:`PyObject_SetAttr` directly.
215 For more details, see :c:func:`PyUnicode_InternFromString`, which may be
216 used internally to create a key object.
217
218 .. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
219
220 Generic attribute setter and deleter function that is meant
221 to be put into a type object's :c:member:`~PyTypeObject.tp_setattro`
222 slot. It looks for a data descriptor in the
223 dictionary of classes in the object's MRO, and if found it takes preference
224 over setting or deleting the attribute in the instance dictionary. Otherwise, the
225 attribute is set or deleted in the object's :attr:`~object.__dict__` (if present).
226 On success, ``0`` is returned, otherwise an :exc:`AttributeError`
227 is raised and ``-1`` is returned.
228
229
230 .. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
231
232 Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
233 This is the equivalent of the Python statement ``del o.attr_name``.
234
235
236 .. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
237
238 This is the same as :c:func:`PyObject_DelAttr`, but *attr_name* is
239 specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
240 rather than a :c:expr:`PyObject*`.
241
242 The number of different attribute names passed to this function
243 should be kept small, usually by using a statically allocated string
244 as *attr_name*.
245 For attribute names that aren't known at compile time, prefer calling
246 :c:func:`PyUnicode_FromString` and :c:func:`PyObject_DelAttr` directly.
247 For more details, see :c:func:`PyUnicode_InternFromString`, which may be
248 used internally to create a key object for lookup.
249
250
251 .. c:function:: PyObject* PyObject_GenericGetDict(PyObject *o, void *context)
252
253 A generic implementation for the getter of a ``__dict__`` descriptor. It
254 creates the dictionary if necessary.
255
256 This function may also be called to get the :py:attr:`~object.__dict__`
257 of the object *o*. Pass ``NULL`` for *context* when calling it.
258 Since this function may need to allocate memory for the
259 dictionary, it may be more efficient to call :c:func:`PyObject_GetAttr`
260 when accessing an attribute on the object.
261
262 On failure, returns ``NULL`` with an exception set.
263
264 .. versionadded:: 3.3
265
266
267 .. c:function:: int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)
268
269 A generic implementation for the setter of a ``__dict__`` descriptor. This
270 implementation does not allow the dictionary to be deleted.
271
272 .. versionadded:: 3.3
273
274
275 .. c:function:: PyObject** _PyObject_GetDictPtr(PyObject *obj)
276
277 Return a pointer to :py:attr:`~object.__dict__` of the object *obj*.
278 If there is no ``__dict__``, return ``NULL`` without setting an exception.
279
280 This function may need to allocate memory for the
281 dictionary, so it may be more efficient to call :c:func:`PyObject_GetAttr`
282 when accessing an attribute on the object.
283
284
285 .. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
286
287 Compare the values of *o1* and *o2* using the operation specified by *opid*,
288 which must be one of :c:macro:`Py_LT`, :c:macro:`Py_LE`, :c:macro:`Py_EQ`,
289 :c:macro:`Py_NE`, :c:macro:`Py_GT`, or :c:macro:`Py_GE`, corresponding to ``<``,
290 ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
291 the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
292 to *opid*. Returns the value of the comparison on success, or ``NULL`` on failure.
293
294
295 .. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
296
297 Compare the values of *o1* and *o2* using the operation specified by *opid*,
298 like :c:func:`PyObject_RichCompare`, but returns ``-1`` on error, ``0`` if
299 the result is false, ``1`` otherwise.
300
301 .. note::
302 If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool`
303 will always return ``1`` for :c:macro:`Py_EQ` and ``0`` for :c:macro:`Py_NE`.
304
305 .. c:function:: PyObject* PyObject_Format(PyObject *obj, PyObject *format_spec)
306
307 Format *obj* using *format_spec*. This is equivalent to the Python
308 expression ``format(obj, format_spec)``.
309
310 *format_spec* may be ``NULL``. In this case the call is equivalent
311 to ``format(obj)``.
312 Returns the formatted string on success, ``NULL`` on failure.
313
314 .. c:function:: PyObject* PyObject_Repr(PyObject *o)
315
316 .. index:: pair: built-in function; repr
317
318 Compute a string representation of object *o*. Returns the string
319 representation on success, ``NULL`` on failure. This is the equivalent of the
320 Python expression ``repr(o)``. Called by the :func:`repr` built-in function.
321
322 If argument is ``NULL``, return the string ``'<NULL>'``.
323
324 .. versionchanged:: 3.4
325 This function now includes a debug assertion to help ensure that it
326 does not silently discard an active exception.
327
328 .. c:function:: PyObject* PyObject_ASCII(PyObject *o)
329
330 .. index:: pair: built-in function; ascii
331
332 As :c:func:`PyObject_Repr`, compute a string representation of object *o*, but
333 escape the non-ASCII characters in the string returned by
334 :c:func:`PyObject_Repr` with ``\x``, ``\u`` or ``\U`` escapes. This generates
335 a string similar to that returned by :c:func:`PyObject_Repr` in Python 2.
336 Called by the :func:`ascii` built-in function.
337
338 If argument is ``NULL``, return the string ``'<NULL>'``.
339
340 .. index:: string; PyObject_Str (C function)
341
342
343 .. c:function:: PyObject* PyObject_Str(PyObject *o)
344
345 Compute a string representation of object *o*. Returns the string
346 representation on success, ``NULL`` on failure. This is the equivalent of the
347 Python expression ``str(o)``. Called by the :func:`str` built-in function
348 and, therefore, by the :func:`print` function.
349
350 If argument is ``NULL``, return the string ``'<NULL>'``.
351
352 .. versionchanged:: 3.4
353 This function now includes a debug assertion to help ensure that it
354 does not silently discard an active exception.
355
356
357 .. c:function:: PyObject* PyObject_Bytes(PyObject *o)
358
359 .. index:: pair: built-in function; bytes
360
361 Compute a bytes representation of object *o*. ``NULL`` is returned on
362 failure and a bytes object on success. This is equivalent to the Python
363 expression ``bytes(o)``, when *o* is not an integer. Unlike ``bytes(o)``,
364 a TypeError is raised when *o* is an integer instead of a zero-initialized
365 bytes object.
366
367 If argument is ``NULL``, return the :class:`bytes` object ``b'<NULL>'``.
368
369
370 .. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
371
372 Return ``1`` if the class *derived* is identical to or derived from the class
373 *cls*, otherwise return ``0``. In case of an error, return ``-1``.
374
375 If *cls* is a tuple, the check will be done against every entry in *cls*.
376 The result will be ``1`` when at least one of the checks returns ``1``,
377 otherwise it will be ``0``.
378
379 If *cls* has a :meth:`~type.__subclasscheck__` method, it will be called to
380 determine the subclass status as described in :pep:`3119`. Otherwise,
381 *derived* is a subclass of *cls* if it is a direct or indirect subclass,
382 i.e. contained in :attr:`cls.__mro__ <type.__mro__>`.
383
384 Normally only class objects, i.e. instances of :class:`type` or a derived
385 class, are considered classes. However, objects can override this by having
386 a :attr:`~type.__bases__` attribute (which must be a tuple of base classes).
387
388
389 .. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
390
391 Return ``1`` if *inst* is an instance of the class *cls* or a subclass of
392 *cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception.
393
394 If *cls* is a tuple, the check will be done against every entry in *cls*.
395 The result will be ``1`` when at least one of the checks returns ``1``,
396 otherwise it will be ``0``.
397
398 If *cls* has a :meth:`~type.__instancecheck__` method, it will be called to
399 determine the subclass status as described in :pep:`3119`. Otherwise, *inst*
400 is an instance of *cls* if its class is a subclass of *cls*.
401
402 An instance *inst* can override what is considered its class by having a
403 :attr:`~object.__class__` attribute.
404
405 An object *cls* can override if it is considered a class, and what its base
406 classes are, by having a :attr:`~type.__bases__` attribute (which must be a tuple
407 of base classes).
408
409
410 .. c:function:: Py_hash_t PyObject_Hash(PyObject *o)
411
412 .. index:: pair: built-in function; hash
413
414 Compute and return the hash value of an object *o*. On failure, return ``-1``.
415 This is the equivalent of the Python expression ``hash(o)``.
416
417 .. versionchanged:: 3.2
418 The return type is now Py_hash_t. This is a signed integer the same size
419 as :c:type:`Py_ssize_t`.
420
421
422 .. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o)
423
424 Set a :exc:`TypeError` indicating that ``type(o)`` is not :term:`hashable` and return ``-1``.
425 This function receives special treatment when stored in a ``tp_hash`` slot,
426 allowing a type to explicitly indicate to the interpreter that it is not
427 hashable.
428
429
430 .. c:function:: int PyObject_IsTrue(PyObject *o)
431
432 Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.
433 This is equivalent to the Python expression ``not not o``. On failure, return
434 ``-1``.
435
436
437 .. c:function:: int PyObject_Not(PyObject *o)
438
439 Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.
440 This is equivalent to the Python expression ``not o``. On failure, return
441 ``-1``.
442
443
444 .. c:function:: PyObject* PyObject_Type(PyObject *o)
445
446 .. index:: pair: built-in function; type
447
448 When *o* is non-``NULL``, returns a type object corresponding to the object type
449 of object *o*. On failure, raises :exc:`SystemError` and returns ``NULL``. This
450 is equivalent to the Python expression ``type(o)``.
451 This function creates a new :term:`strong reference` to the return value.
452 There's really no reason to use this
453 function instead of the :c:func:`Py_TYPE()` function, which returns a
454 pointer of type :c:expr:`PyTypeObject*`, except when a new
455 :term:`strong reference` is needed.
456
457
458 .. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
459
460 Return non-zero if the object *o* is of type *type* or a subtype of *type*, and
461 ``0`` otherwise. Both parameters must be non-``NULL``.
462
463
464 .. c:function:: Py_ssize_t PyObject_Size(PyObject *o)
465 Py_ssize_t PyObject_Length(PyObject *o)
466
467 .. index:: pair: built-in function; len
468
469 Return the length of object *o*. If the object *o* provides either the sequence
470 and mapping protocols, the sequence length is returned. On error, ``-1`` is
471 returned. This is the equivalent to the Python expression ``len(o)``.
472
473
474 .. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)
475
476 Return an estimated length for the object *o*. First try to return its
477 actual length, then an estimate using :meth:`~object.__length_hint__`, and
478 finally return the default value. On error return ``-1``. This is the
479 equivalent to the Python expression ``operator.length_hint(o, defaultvalue)``.
480
481 .. versionadded:: 3.4
482
483
484 .. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
485
486 Return element of *o* corresponding to the object *key* or ``NULL`` on failure.
487 This is the equivalent of the Python expression ``o[key]``.
488
489
490 .. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
491
492 Map the object *key* to the value *v*. Raise an exception and
493 return ``-1`` on failure; return ``0`` on success. This is the
494 equivalent of the Python statement ``o[key] = v``. This function *does
495 not* steal a reference to *v*.
496
497
498 .. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
499
500 Remove the mapping for the object *key* from the object *o*. Return ``-1``
501 on failure. This is equivalent to the Python statement ``del o[key]``.
502
503
504 .. c:function:: int PyObject_DelItemString(PyObject *o, const char *key)
505
506 This is the same as :c:func:`PyObject_DelItem`, but *key* is
507 specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
508 rather than a :c:expr:`PyObject*`.
509
510
511 .. c:function:: PyObject* PyObject_Dir(PyObject *o)
512
513 This is equivalent to the Python expression ``dir(o)``, returning a (possibly
514 empty) list of strings appropriate for the object argument, or ``NULL`` if there
515 was an error. If the argument is ``NULL``, this is like the Python ``dir()``,
516 returning the names of the current locals; in this case, if no execution frame
517 is active then ``NULL`` is returned but :c:func:`PyErr_Occurred` will return false.
518
519
520 .. c:function:: PyObject* PyObject_GetIter(PyObject *o)
521
522 This is equivalent to the Python expression ``iter(o)``. It returns a new
523 iterator for the object argument, or the object itself if the object is already
524 an iterator. Raises :exc:`TypeError` and returns ``NULL`` if the object cannot be
525 iterated.
526
527
528 .. c:function:: PyObject* PyObject_SelfIter(PyObject *obj)
529
530 This is equivalent to the Python ``__iter__(self): return self`` method.
531 It is intended for :term:`iterator` types, to be used in the :c:member:`PyTypeObject.tp_iter` slot.
532
533
534 .. c:function:: PyObject* PyObject_GetAIter(PyObject *o)
535
536 This is the equivalent to the Python expression ``aiter(o)``. Takes an
537 :class:`AsyncIterable` object and returns an :class:`AsyncIterator` for it.
538 This is typically a new iterator but if the argument is an
539 :class:`AsyncIterator`, this returns itself. Raises :exc:`TypeError` and
540 returns ``NULL`` if the object cannot be iterated.
541
542 .. versionadded:: 3.10
543
544 .. c:function:: void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)
545
546 Get a pointer to subclass-specific data reserved for *cls*.
547
548 The object *o* must be an instance of *cls*, and *cls* must have been
549 created using negative :c:member:`PyType_Spec.basicsize`.
550 Python does not check this.
551
552 On error, set an exception and return ``NULL``.
553
554 .. versionadded:: 3.12
555
556 .. c:function:: Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)
557
558 Return the size of the instance memory space reserved for *cls*, i.e. the size of the
559 memory :c:func:`PyObject_GetTypeData` returns.
560
561 This may be larger than requested using :c:member:`-PyType_Spec.basicsize <PyType_Spec.basicsize>`;
562 it is safe to use this larger size (e.g. with :c:func:`!memset`).
563
564 The type *cls* **must** have been created using
565 negative :c:member:`PyType_Spec.basicsize`.
566 Python does not check this.
567
568 On error, set an exception and return a negative value.
569
570 .. versionadded:: 3.12
571
572 .. c:function:: void *PyObject_GetItemData(PyObject *o)
573
574 Get a pointer to per-item data for a class with
575 :c:macro:`Py_TPFLAGS_ITEMS_AT_END`.
576
577 On error, set an exception and return ``NULL``.
578 :py:exc:`TypeError` is raised if *o* does not have
579 :c:macro:`Py_TPFLAGS_ITEMS_AT_END` set.
580
581 .. versionadded:: 3.12
582
583 .. c:function:: int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)
584
585 Visit the managed dictionary of *obj*.
586
587 This function must only be called in a traverse function of the type which
588 has the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag set.
589
590 .. versionadded:: 3.13
591
592 .. c:function:: void PyObject_ClearManagedDict(PyObject *obj)
593
594 Clear the managed dictionary of *obj*.
595
596 This function must only be called in a clear function of the type which
597 has the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag set.
598
599 .. versionadded:: 3.13
600
601 .. c:function:: int PyUnstable_Object_EnableDeferredRefcount(PyObject *obj)
602
603 Enable `deferred reference counting <https://peps.python.org/pep-0703/#deferred-reference-counting>`_ on *obj*,
604 if supported by the runtime. In the :term:`free-threaded <free threading>` build,
605 this allows the interpreter to avoid reference count adjustments to *obj*,
606 which may improve multi-threaded performance. The tradeoff is
607 that *obj* will only be deallocated by the tracing garbage collector, and
608 not when the interpreter no longer has any references to it.
609
610 This function returns ``1`` if deferred reference counting is enabled on *obj*,
611 and ``0`` if deferred reference counting is not supported or if the hint was
612 ignored by the interpreter, such as when deferred reference counting is already
613 enabled on *obj*. This function is thread-safe, and cannot fail.
614
615 This function does nothing on builds with the :term:`GIL` enabled, which do
616 not support deferred reference counting. This also does nothing if *obj* is not
617 an object tracked by the garbage collector (see :func:`gc.is_tracked` and
618 :c:func:`PyObject_GC_IsTracked`).
619
620 This function is intended to be used soon after *obj* is created,
621 by the code that creates it, such as in the object's :c:member:`~PyTypeObject.tp_new`
622 slot.
623
624 .. versionadded:: 3.14
625
626 .. c:function:: int PyUnstable_Object_IsUniqueReferencedTemporary(PyObject *obj)
627
628 Check if *obj* is a unique temporary object.
629 Returns ``1`` if *obj* is known to be a unique temporary object,
630 and ``0`` otherwise. This function cannot fail, but the check is
631 conservative, and may return ``0`` in some cases even if *obj* is a unique
632 temporary object.
633
634 If an object is a unique temporary, it is guaranteed that the current code
635 has the only reference to the object. For arguments to C functions, this
636 should be used instead of checking if the reference count is ``1``. Starting
637 with Python 3.14, the interpreter internally avoids some reference count
638 modifications when loading objects onto the operands stack by
639 :term:`borrowing <borrowed reference>` references when possible, which means
640 that a reference count of ``1`` by itself does not guarantee that a function
641 argument uniquely referenced.
642
643 In the example below, ``my_func`` is called with a unique temporary object
644 as its argument::
645
646 my_func([1, 2, 3])
647
648 In the example below, ``my_func`` is **not** called with a unique temporary
649 object as its argument, even if its refcount is ``1``::
650
651 my_list = [1, 2, 3]
652 my_func(my_list)
653
654 See also the function :c:func:`Py_REFCNT`.
655
656 .. versionadded:: 3.14
657
658 .. c:function:: int PyUnstable_IsImmortal(PyObject *obj)
659
660 This function returns non-zero if *obj* is :term:`immortal`, and zero
661 otherwise. This function cannot fail.
662
663 .. note::
664
665 Objects that are immortal in one CPython version are not guaranteed to
666 be immortal in another.
667
668 .. versionadded:: 3.14
669
670 .. c:function:: int PyUnstable_TryIncRef(PyObject *obj)
671
672 Increments the reference count of *obj* if it is not zero. Returns ``1``
673 if the object's reference count was successfully incremented. Otherwise,
674 this function returns ``0``.
675
676 :c:func:`PyUnstable_EnableTryIncRef` must have been called
677 earlier on *obj* or this function may spuriously return ``0`` in the
678 :term:`free-threaded build`.
679
680 This function is logically equivalent to the following C code, except that
681 it behaves atomically in the :term:`free-threaded build`::
682
683 if (Py_REFCNT(op) > 0) {
684 Py_INCREF(op);
685 return 1;
686 }
687 return 0;
688
689 This is intended as a building block for managing weak references
690 without the overhead of a Python :ref:`weak reference object <weakrefobjects>`.
691
692 Typically, correct use of this function requires support from *obj*'s
693 deallocator (:c:member:`~PyTypeObject.tp_dealloc`).
694 For example, the following sketch could be adapted to implement a
695 "weakmap" that works like a :py:class:`~weakref.WeakValueDictionary`
696 for a specific type:
697
698 .. code-block:: c
699
700 PyMutex mutex;
701
702 PyObject *
703 add_entry(weakmap_key_type *key, PyObject *value)
704 {
705 PyUnstable_EnableTryIncRef(value);
706 weakmap_type weakmap = ...;
707 PyMutex_Lock(&mutex);
708 weakmap_add_entry(weakmap, key, value);
709 PyMutex_Unlock(&mutex);
710 Py_RETURN_NONE;
711 }
712
713 PyObject *
714 get_value(weakmap_key_type *key)
715 {
716 weakmap_type weakmap = ...;
717 PyMutex_Lock(&mutex);
718 PyObject *result = weakmap_find(weakmap, key);
719 if (PyUnstable_TryIncRef(result)) {
720 // `result` is safe to use
721 PyMutex_Unlock(&mutex);
722 return result;
723 }
724 // if we get here, `result` is starting to be garbage-collected,
725 // but has not been removed from the weakmap yet
726 PyMutex_Unlock(&mutex);
727 return NULL;
728 }
729
730 // tp_dealloc function for weakmap values
731 void
732 value_dealloc(PyObject *value)
733 {
734 weakmap_type weakmap = ...;
735 PyMutex_Lock(&mutex);
736 weakmap_remove_value(weakmap, value);
737
738 ...
739 PyMutex_Unlock(&mutex);
740 }
741
742 .. versionadded:: 3.14
743
744 .. c:function:: void PyUnstable_EnableTryIncRef(PyObject *obj)
745
746 Enables subsequent uses of :c:func:`PyUnstable_TryIncRef` on *obj*. The
747 caller must hold a :term:`strong reference` to *obj* when calling this.
748
749 .. versionadded:: 3.14
750
751 .. c:function:: int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)
752
753 Determine if *op* only has one reference.
754
755 On GIL-enabled builds, this function is equivalent to
756 :c:expr:`Py_REFCNT(op) == 1`.
757
758 On a :term:`free-threaded build`, this checks if *op*'s
759 :term:`reference count` is equal to one and additionally checks if *op*
760 is only used by this thread. :c:expr:`Py_REFCNT(op) == 1` is **not**
761 thread-safe on free-threaded builds; prefer this function.
762
763 The caller must hold an :term:`attached thread state`, despite the fact
764 that this function doesn't call into the Python interpreter. This function
765 cannot fail.
766
767 .. versionadded:: 3.14