diff options
| author | Joannah Nanjekye <33177550+nanjekyejoannah@users.noreply.github.com> | 2020-01-29 11:20:53 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2020-01-29 11:20:53 (GMT) |
| commit | e1e80002e28e1055f399a20918c49d50d093709e (patch) | |
| tree | 67dbe51a2c6e242f1e68019a611257fe88c2e02e | |
| parent | d07d9f4c43bc85a77021bcc7d77643f8ebb605cf (diff) | |
| download | cpython-e1e80002e28e1055f399a20918c49d50d093709e.zip cpython-e1e80002e28e1055f399a20918c49d50d093709e.tar.gz cpython-e1e80002e28e1055f399a20918c49d50d093709e.tar.bz2 | |
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>
| -rw-r--r-- | Doc/c-api/dict.rst | 9 | ||||
| -rw-r--r-- | Doc/c-api/mapping.rst | 3 | ||||
| -rw-r--r-- | Doc/c-api/object.rst | 3 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Documentation/2020-01-27-22-24-51.bpo-39153.Pjl8jV.rst | 5 |
4 files changed, 14 insertions, 6 deletions
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index e7922dc..e48c11d 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -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) diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst index 6a80b03..682160d 100644 --- a/Doc/c-api/mapping.rst +++ b/Doc/c-api/mapping.rst @@ -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) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index ca9db1a..2905fbb 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -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) diff --git a/Misc/NEWS.d/next/Documentation/2020-01-27-22-24-51.bpo-39153.Pjl8jV.rst b/Misc/NEWS.d/next/Documentation/2020-01-27-22-24-51.bpo-39153.Pjl8jV.rst new file mode 100644 index 0000000..95be00b --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2020-01-27-22-24-51.bpo-39153.Pjl8jV.rst @@ -0,0 +1,5 @@ +Clarify refcounting semantics for the following functions:
+- PyObject_SetItem
+- PyMapping_SetItemString
+- PyDict_SetItem
+- PyDict_SetItemString
\ No newline at end of file |