Skip to content

gh-144473: Add "steal" term to glossary; clarify "stealing" on error #144502

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
encukou wants to merge 3 commits into
base: main
Choose a base branch
from
+58 −37
Open

gh-144473: Add "steal" term to glossary; clarify "stealing" on error #144502

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b8fc5c3
Add "steal" term to glossary; clarify stealing on error
encukou Feb 4, 2026
d74ff52
Update Doc/c-api/list.rst
encukou Feb 5, 2026
6e0e498
The caller must not use that reference after the call.
encukou Feb 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions Doc/c-api/bytes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,10 +180,11 @@ called with a non-bytes parameter.
.. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)

Create a new bytes object in *\*bytes* containing the contents of *newpart*
appended to *bytes*; the caller will own the new reference. The reference to
the old value of *bytes* will be stolen. If the new object cannot be
created, the old reference to *bytes* will still be discarded and the value
of *\*bytes* will be set to ``NULL``; the appropriate exception will be set.
appended to *bytes*; the caller will own the new reference.
The reference to the old value of *bytes* will be ":term:`stolen <steal>`".
If the new object cannot be created, the old reference to *bytes* will still
be "stolen", the value of *\*bytes* will be set to ``NULL``, and
the appropriate exception will be set.


.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
Expand Down
4 changes: 2 additions & 2 deletions Doc/c-api/dict.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,8 @@ Dictionary Objects
Insert *val* into the dictionary *p* with a key of *key*. *key* must be
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
``0`` on success or ``-1`` on failure. This function *does not* steal a
reference to *val*.
``0`` on success or ``-1`` on failure.
This function *does not* ":term:`steal`" a reference to *val*.
.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
Expand Down
15 changes: 9 additions & 6 deletions Doc/c-api/exceptions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -503,7 +503,8 @@ Querying the error indicator

.. warning::

This call steals a reference to *exc*, which must be a valid exception.
This call ":term:`steals <steal>`" a reference to *exc*,
which must be a valid exception.

.. versionadded:: 3.12

Expand Down Expand Up @@ -641,7 +642,8 @@ Querying the error indicator

Set the exception info, as known from ``sys.exc_info()``. This refers
to an exception that was *already caught*, not to an exception that was
freshly raised. This function steals the references of the arguments.
freshly raised. This function ":term:`steals <steal>`" the references
of the arguments.
To clear the exception state, pass ``NULL`` for all three arguments.
This function is kept for backwards compatibility. Prefer using
:c:func:`PyErr_SetHandledException`.
Expand All @@ -658,8 +660,8 @@ Querying the error indicator
.. versionchanged:: 3.11
The ``type`` and ``traceback`` arguments are no longer used and
can be NULL. The interpreter now derives them from the exception
instance (the ``value`` argument). The function still steals
references of all three arguments.
instance (the ``value`` argument). The function still
":term:`steals <steal>`" references of all three arguments.


Signal Handling
Expand Down Expand Up @@ -844,7 +846,7 @@ Exception Objects

Set the context associated with the exception to *ctx*. Use ``NULL`` to clear
it. There is no type check to make sure that *ctx* is an exception instance.
This steals a reference to *ctx*.
This ":term:`steals <steal>`" a reference to *ctx*.


.. c:function:: PyObject* PyException_GetCause(PyObject *ex)
Expand All @@ -859,7 +861,8 @@ Exception Objects

Set the cause associated with the exception to *cause*. Use ``NULL`` to clear
it. There is no type check to make sure that *cause* is either an exception
instance or ``None``. This steals a reference to *cause*.
instance or ``None``.
This ":term:`steals <steal>`" a reference to *cause*.

The :attr:`~BaseException.__suppress_context__` attribute is implicitly set
to ``True`` by this function.
Expand Down
13 changes: 7 additions & 6 deletions Doc/c-api/gen.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,15 +35,15 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
.. c:function:: PyObject* PyGen_New(PyFrameObject *frame)
Create and return a new generator object based on the *frame* object.
A reference to *frame* is stolen by this function. The argument must not be
``NULL``.
A reference to *frame* is ":term:`stolen <steal>`" by this function (even
on error). The argument must not be ``NULL``.
.. c:function:: PyObject* PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)
Create and return a new generator object based on the *frame* object,
with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
A reference to *frame* is stolen by this function. The *frame* argument
must not be ``NULL``.
A reference to *frame* is ":term:`stolen <steal>`" by this function (even
on error). The *frame* argument must not be ``NULL``.
.. c:function:: PyCodeObject* PyGen_GetCode(PyGenObject *gen)
Expand All @@ -68,8 +68,9 @@ Asynchronous Generator Objects
.. c:function:: PyObject *PyAsyncGen_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)
Create a new asynchronous generator wrapping *frame*, with ``__name__`` and
``__qualname__`` set to *name* and *qualname*. *frame* is stolen by this
function and must not be ``NULL``.
``__qualname__`` set to *name* and *qualname*.
*frame* is ":term:`stolen <steal>`" by this function (even on error) and
must not be ``NULL``.
On success, this function returns a :term:`strong reference` to the
new asynchronous generator. On failure, this function returns ``NULL``
Expand Down
7 changes: 4 additions & 3 deletions Doc/c-api/init.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1481,9 +1481,10 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. c:function:: int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)

Asynchronously raise an exception in a thread. The *id* argument is the thread
id of the target thread; *exc* is the exception object to be raised. This
function does not steal any references to *exc*. To prevent naive misuse, you
must write your own C extension to call this. Must be called with an :term:`attached thread state`.
id of the target thread; *exc* is the exception object to be raised.
This function does not :term:`steal` any references to *exc*.
To prevent naive misuse, you must write your own C extension to call this.
Must be called with an :term:`attached thread state`.
Returns the number of thread states modified; this is normally one, but will be
zero if the thread id isn't found. If *exc* is ``NULL``, the pending
exception (if any) for the thread is cleared. This raises no exceptions.
Expand Down
9 changes: 6 additions & 3 deletions Doc/c-api/intro.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -628,9 +628,12 @@ the caller is said to *borrow* the reference. Nothing needs to be done for a

Conversely, when a calling function passes in a reference to an object, there
are two possibilities: the function *steals* a reference to the object, or it
does not. *Stealing a reference* means that when you pass a reference to a
function, that function assumes that it now owns that reference, and you are not
responsible for it any longer.
does not.

*Stealing a reference* means that when you pass a reference to a
function, that function assumes that it now owns that reference.
Since the new owner can use :c:func:`!Py_DECREF` at its discretion,
you (the caller) must not use that reference after the call.

.. index::
single: PyList_SetItem (C function)
Expand Down
8 changes: 5 additions & 3 deletions Doc/c-api/list.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,10 @@ List Objects

.. note::

This function "steals" a reference to *item* and discards a reference to
an item already in the list at the affected position.
This function ":term:`steals <steal>`" a reference to *item*,
even on error.
On success, it discards a reference to an item already in the list
at the affected position (unless it was ``NULL``).


.. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
Expand All @@ -103,7 +105,7 @@ List Objects

.. note::

This macro "steals" a reference to *item*, and, unlike
This macro ":term:`steals <steal>`" a reference to *item*, and, unlike
:c:func:`PyList_SetItem`, does *not* discard a reference to any item that
is being replaced; any reference in *list* at position *i* will be
leaked.
Expand Down
8 changes: 4 additions & 4 deletions Doc/c-api/module.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -900,8 +900,8 @@ or code that creates modules dynamically.

.. c:function:: int PyModule_Add(PyObject *module, const char *name, PyObject *value)

Similar to :c:func:`PyModule_AddObjectRef`, but "steals" a reference
to *value*.
Similar to :c:func:`PyModule_AddObjectRef`, but ":term:`steals <steal>`"
a reference to *value* (even on error).
It can be called with a result of function that returns a new reference
without bothering to check its result or even saving it to a variable.

Expand All @@ -916,8 +916,8 @@ or code that creates modules dynamically.

.. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)

Similar to :c:func:`PyModule_AddObjectRef`, but steals a reference to
*value* on success (if it returns ``0``).
Similar to :c:func:`PyModule_AddObjectRef`, but :term:`steals <steal>`
a reference to *value* on success (if it returns ``0``).

The new :c:func:`PyModule_Add` or :c:func:`PyModule_AddObjectRef`
functions are recommended, since it is
Expand Down
2 changes: 1 addition & 1 deletion Doc/c-api/sequence.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ Sequence Protocol
Assign object *v* to the *i*\ th element of *o*. Raise an exception
and return ``-1`` on failure; return ``0`` on success. This
is the equivalent of the Python statement ``o[i] = v``. This function *does
not* steal a reference to *v*.
not* ":term:`steal`" a reference to *v*.

If *v* is ``NULL``, the element is deleted, but this feature is
deprecated in favour of using :c:func:`PySequence_DelItem`.
Expand Down
9 changes: 5 additions & 4 deletions Doc/c-api/tuple.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,9 @@ Tuple Objects

.. note::

This function "steals" a reference to *o* and discards a reference to
an item already in the tuple at the affected position.
This function ":term:`steals <steal>`" a reference to *o* and discards
a reference to an item already in the tuple at the affected position
(unless it was NULL).


.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
Expand All @@ -117,7 +118,7 @@ Tuple Objects

.. note::

This function "steals" a reference to *o*, and, unlike
This function ":term:`steals <steal>`" a reference to *o*, and, unlike
:c:func:`PyTuple_SetItem`, does *not* discard a reference to any item that
is being replaced; any reference in the tuple at position *pos* will be
leaked.
Expand Down Expand Up @@ -260,7 +261,7 @@ type.

.. note::

This function "steals" a reference to *o*.
This function ":term:`steals <steal>`" a reference to *o*.


.. c:function:: void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)
Expand Down
3 changes: 2 additions & 1 deletion Doc/c-api/unicode.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -679,7 +679,8 @@ APIs:

Append the string *right* to the end of *p_left*.
*p_left* must point to a :term:`strong reference` to a Unicode object;
:c:func:`!PyUnicode_Append` releases ("steals") this reference.
:c:func:`!PyUnicode_Append` releases (":term:`steals <steal>`")
this reference.

On error, set *\*p_left* to ``NULL`` and set an exception.

Expand Down
8 changes: 8 additions & 0 deletions Doc/glossary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1481,6 +1481,14 @@ Glossary
stdlib
An abbreviation of :term:`standard library`.

steal
In Python's C API, "*stealing*" an argument means that ownership of the
argument is transferred to the called function.
The caller must not use that reference after the call.
Generally, functions that "steal" an argument do so even if they fail.

See :ref:`api-refcountdetails` for a full explanation.

strong reference
In Python's C API, a strong reference is a reference to an object
which is owned by the code holding the reference. The strong
Expand Down
Loading