bpo-39153: Clarify C API *SetItem refcounting semantics (GH-18220)
Some of the *SetItem methods in the C API steal a reference to the given value. This annotates the better behaved ones to assure the reader that these are not the ones with the inconsistent behaviour. * 📜🤖 Added by blurb_it. * make docs consistent with signature Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
This commit is contained in:
parent
d07d9f4c43
commit
e1e80002e2
|
@ -62,19 +62,20 @@ Dictionary Objects
|
|||
|
||||
.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
|
||||
|
||||
Insert *value* into the dictionary *p* with a key of *key*. *key* must be
|
||||
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.
|
||||
``0`` on success or ``-1`` on failure. This function *does not* steal a
|
||||
reference to *val*.
|
||||
|
||||
|
||||
.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
|
||||
|
||||
.. index:: single: PyUnicode_FromString()
|
||||
|
||||
Insert *value* into the dictionary *p* using *key* as a key. *key* should
|
||||
Insert *val* into the dictionary *p* using *key* as a key. *key* should
|
||||
be a :c:type:`const char\*`. The key object is created using
|
||||
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
|
||||
failure.
|
||||
failure. This function *does not* steal a reference to *val*.
|
||||
|
||||
|
||||
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
|
||||
|
|
|
@ -37,7 +37,8 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
|
|||
|
||||
Map the string *key* to the value *v* in object *o*. Returns ``-1`` on
|
||||
failure. This is the equivalent of the Python statement ``o[key] = v``.
|
||||
See also :c:func:`PyObject_SetItem`.
|
||||
See also :c:func:`PyObject_SetItem`. This function *does not* steal a
|
||||
reference to *v*.
|
||||
|
||||
|
||||
.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
|
||||
|
|
|
@ -331,7 +331,8 @@ Object Protocol
|
|||
|
||||
Map the object *key* to the value *v*. Raise an exception and
|
||||
return ``-1`` on failure; return ``0`` on success. This is the
|
||||
equivalent of the Python statement ``o[key] = v``.
|
||||
equivalent of the Python statement ``o[key] = v``. This function *does
|
||||
not* steal a reference to *v*.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
|
||||
|
|
|
@ -0,0 +1,5 @@
|
|||
Clarify refcounting semantics for the following functions:
|
||||
- PyObject_SetItem
|
||||
- PyMapping_SetItemString
|
||||
- PyDict_SetItem
|
||||
- PyDict_SetItemString
|
Loading…
Reference in New Issue