Skip to content

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

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

Closed
encukou wants to merge 13 commits into from
+2,910 −1,938
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
9ae5989
Add "steal" term to glossary; clarify stealing on error
encukou Feb 4, 2026
960b427
Update Doc/c-api/list.rst
encukou Feb 5, 2026
3fd84ba
gh-140824: Fix _Py_DumpExtensionModules() to ignore sub-modules (#144…
vstinner Feb 4, 2026
0b91f57
gh-141984: Reword and reorganize Subscription (and Slicing) docs (GH-…
encukou Feb 4, 2026
7c17691
gh-141004: Document remaining `pyport.h` utility macros (GH-144279)
ZeroIntensity Feb 4, 2026
088b86a
gh-106318: Add examples for `str.startswith()` method (#144369)
adorilson Feb 4, 2026
2032b38
gh-143962: Improve name suggestions for not normalized names (GH-144154)
serhiy-storchaka Feb 4, 2026
ca530a4
gh-123471: Make concurrent iteration over `itertools.permutations` an…
eendebakpt Feb 4, 2026
ad344ca
Itertools recipes: Replace the tabulate() example with running_mean(…
rhettinger Feb 4, 2026
cc6697f
GH-144179: Use recorded values to make optimizer more robust (GH-144437)
markshannon Feb 5, 2026
e6b8fcc
gh-144330: Initialize classmethod and staticmethod in new (#144469)
vstinner Feb 5, 2026
aa549fb
gh-144363: Update bundled libexpat to 2.7.4 (#144365)
StanFromIreland Feb 5, 2026
06f18b7
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>`".
Copy link
Member

@ZeroIntensity ZeroIntensity Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not a huge fan of putting "steal(s)" in quotations. If the user is confused about the term, then they can just click it to go to the glossary. Otherwise, the user knows the term, so it shouldn't be in scare quotes.

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
105 changes: 102 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 @@ -167,6 +167,35 @@ complete listing.

.. versionadded:: 3.3

.. c:macro:: Py_ALIGNED(num)

Specify alignment to *num* bytes on compilers that support it.

Consider using the C11 standard ``_Alignas`` specifier over this macro.

.. c:macro:: Py_ARITHMETIC_RIGHT_SHIFT(type, integer, positions)

Similar to ``integer >> positions``, but forces sign extension, as the C
standard does not define whether a right-shift of a signed integer will
perform sign extension or a zero-fill.

*integer* should be any signed integer type.
*positions* is the number of positions to shift to the right.

Both *integer* and *positions* can be evaluated more than once;
consequently, avoid directly passing a function call or some other
operation with side-effects to this macro. Instead, store the result as a
variable and then pass it.

*type* is unused and only kept for backwards compatibility. Historically,
*type* was used to cast *integer*.

.. versionchanged:: 3.1

This macro is now valid for all signed integer types, not just those for
which ``unsigned type`` is legal. As a result, *type* is no longer
used.

.. c:macro:: Py_ALWAYS_INLINE

Ask the compiler to always inline a static inline function. The compiler can
Expand All @@ -189,6 +218,15 @@ complete listing.

.. versionadded:: 3.11

.. c:macro:: Py_CAN_START_THREADS

If this macro is defined, then the current system is able to start threads.

Currently, all systems supported by CPython (per :pep:`11`), with the
exception of some WebAssembly platforms, support starting threads.

.. versionadded:: 3.13

.. c:macro:: Py_CHARMASK(c)

Argument must be a character or an integer in the range [-128, 127] or [0,
Expand All @@ -206,11 +244,35 @@ complete listing.
.. versionchanged:: 3.8
MSVC support was added.

.. c:macro:: Py_FORCE_EXPANSION(X)

This is equivalent to ``X``, which is useful for token-pasting in
macros, as macro expansions in *X* are forcefully evaluated by the
preprocessor.

.. c:macro:: Py_GCC_ATTRIBUTE(name)

Use a GCC attribute *name*, hiding it from compilers that don't support GCC
attributes (such as MSVC).

This expands to ``__attribute__((name))`` on a GCC compiler, and expands
to nothing on compilers that don't support GCC attributes.

.. c:macro:: Py_GETENV(s)

Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the
command line (see :c:member:`PyConfig.use_environment`).

.. c:macro:: Py_LL(number)

Use *number* as a ``long long`` integer literal.

This usally expands to *number* followed by ``LL``, but will expand to some
compiler-specific suffixes (such as ``I64``) on older compilers.

In modern versions of Python, this macro is not very useful, as C99 and
later require the ``LL`` suffix to be valid for an integer.

.. c:macro:: Py_LOCAL(type)

Declare a function returning the specified *type* using a fast-calling
Expand Down Expand Up @@ -268,13 +330,37 @@ complete listing.

.. versionadded:: 3.11

.. c:macro:: Py_SAFE_DOWNCAST(value, larger, smaller)

Cast *value* to type *smaller* from type *larger*, validating that no
information was lost.

On release builds of Python, this is roughly equivalent to
``(smaller) value`` (in C++, ``static_cast<smaller>(value)`` will be
used instead).

On debug builds (implying that :c:macro:`Py_DEBUG` is defined), this asserts
that no information was lost with the cast from *larger* to *smaller*.

*value*, *larger*, and *smaller* may all be evaluated more than once in the
expression; consequently, do not pass an expression with side-effects directly to
this macro.

.. c:macro:: Py_STRINGIFY(x)

Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns
``"123"``.

.. versionadded:: 3.4

.. c:macro:: Py_ULL(number)

Similar to :c:macro:`Py_LL`, but *number* will be an ``unsigned long long``
literal instead. This is done by appending ``U`` to the result of ``Py_LL``.

In modern versions of Python, this macro is not very useful, as C99 and
later require the ``ULL``/``LLU`` suffixes to be valid for an integer.

.. c:macro:: Py_UNREACHABLE()

Use this when you have a code path that cannot be reached by design.
Expand Down Expand Up @@ -415,6 +501,16 @@ complete listing.
This macro is intended for defining CPython's C API itself;
extension modules should not use it for their own symbols.

.. c:macro:: Py_VA_COPY

This is a :term:`soft deprecated` alias to the C99-standard ``va_copy``
function.

Historically, this would use a compiler-specific method to copy a ``va_list``.

.. versionchanged:: 3.6
This is now an alias to ``va_copy``.


.. _api-objects:

Expand Down Expand Up @@ -532,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
Loading
Loading