From e1e80002e28e1055f399a20918c49d50d093709e Mon Sep 17 00:00:00 2001
From: Joannah Nanjekye <33177550+nanjekyejoannah@users.noreply.github.com>
Date: Wed, 29 Jan 2020 07:20:53 -0400
Subject: bpo-39153: Clarify C API *SetItem refcounting semantics (GH-18220)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 Doc/c-api/dict.rst                                               | 9 +++++----
 Doc/c-api/mapping.rst                                            | 3 ++-
 Doc/c-api/object.rst                                             | 3 ++-
 .../next/Documentation/2020-01-27-22-24-51.bpo-39153.Pjl8jV.rst  | 5 +++++
 4 files changed, 14 insertions(+), 6 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2020-01-27-22-24-51.bpo-39153.Pjl8jV.rst

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
-- 
cgit v0.12