Feb 4, 2026 · Feb 4, 2026 · Feb 4, 2026 · Feb 4, 2026 · Feb 4, 2026
diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst
 .. 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)
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst

   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`" areference to *val*.


 .. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst

   ..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


   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`.
   ..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

   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)

   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.
diff --git a/Doc/c-api/gen.rst b/Doc/c-api/gen.rst
 ..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* argumentmust not be ``NULL``.


 .. c:function:: PyCodeObject* PyGen_GetCode(PyGenObject *gen)
 ..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``
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
 .. 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.
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst

 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)
diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst

   ..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)

   ..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.
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst

 .. 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 referenceto *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.


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

   Similar to :c:func:`PyModule_AddObjectRef`, but stealsa 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
diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst
   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`.
diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst

   .. 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)

   .. 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.

   .. 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)
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst

   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.

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
   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.
      Generally, functions that "steal" an argument do so even if they fail.
      See also:ref:`api-refcountdetails`.

   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
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 ZeroIntensityFeb 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
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`" areference to val.


		.. c:function:: int PyDict_SetItemString(PyObject p, const char key, PyObject *val)
Expand Down
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 DownExpand 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 DownExpand 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:: PyObjectPyException_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
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:: PyObjectPyGen_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 argumentmust 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
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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -532,9 +532,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
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 referenceto 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 stealsa reference to
		value on success (if it returns ``0``).
		Similar to :c:func:`PyModule_AddObjectRef`, but:term:`steals<steal>`
		a reference tovalue 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
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
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 DownExpand 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
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