[New-bugs-announce] [issue39153] Clarify refcounting semantics of PyDict_SetItem[String]

[Nick Coghlan]

New submission from Nick Coghlan <ncoghlan at gmail.com>:

The documentation for PyList_SetItem is explicit that it steals a reference to the passed in value, and drops the reference for any existing entry: https://docs.python.org/3.3/c-api/list.html?highlight=m#PyList_SetItem

The documentation for PyDict_SetItem leaves the semantics unspecified, forcing the reader to either make assumptions, or else go read the source code (as was done for the SO answer at https://stackoverflow.com/questions/40700251/reference-counting-using-pydict-setitemstring)

Since the default assumption is actually correct, I don't think a Sphinx note is warranted, but an extra explicit sentence would be helpful.

PySequence_SetItem has such a sentence already: "This function does *not* steal a reference to v."

My suggestion is that we also add that sentence to the documentation for:

* PyObject_SetItem
* PyMapping_SetItemString
* PyDict_SetItem
* PyDict_SetItemString

----------
messages: 358988
nosy: ncoghlan
priority: normal
severity: normal
status: open
title: Clarify refcounting semantics of PyDict_SetItem[String]

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue39153>
_______________________________________