[Python-checkins] bpo-39153: Clarify C API *SetItem refcounting semantics (GH-18220)
Joannah Nanjekye
webhook-mailer at python.org
Wed Jan 29 06:21:19 EST 2020
https://github.com/python/cpython/commit/e1e80002e28e1055f399a20918c49d50d093709e
commit: e1e80002e28e1055f399a20918c49d50d093709e
branch: master
author: Joannah Nanjekye <33177550+nanjekyejoannah at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2020-01-29T21:20:53+10:00
summary:
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>
files:
A Misc/NEWS.d/next/Documentation/2020-01-27-22-24-51.bpo-39153.Pjl8jV.rst
M Doc/c-api/dict.rst
M Doc/c-api/mapping.rst
M Doc/c-api/object.rst
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index e7922dc0c73f2..e48c11d336b8c 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 6a80b033b651e..682160d1475c1 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 ca9db1aee2f87..2905fbbd0f70c 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 0000000000000..95be00b4b777f
--- /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
More information about the Python-checkins
mailing list