.. 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)
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)
.. 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.
.. 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)
.. 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``
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)
.. 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.
.. 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.
.. 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
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`.
.. 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)
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
projects / thirdparty / Python / cpython.git / commitdiff
