Title: Clarify refcounting semantics of PyDict_SetItem[String]
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: corona10, docs@python, miss-islington, ncoghlan, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2019-12-29 13:33 by ncoghlan, last changed 2020-01-30 15:49 by corona10. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 18220 merged nanjekyejoannah, 2020-01-27 22:23
PR 18246 merged miss-islington, 2020-01-29 11:21
Messages (6)
msg358988 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2019-12-29 13:33
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:

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

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
msg359008 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2019-12-29 21:44
The documentation for PyList_SetItem is explicit because its behavior is an exception from common rule and differs from PyList_SET_ITEM, so both should be documented explicitly.
msg359018 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2019-12-30 04:58
Right, that's why I don't think the other "*SetItem*" operations should get a Sphinx note - just a sentence, as was already done for PySequence_SetItem.

If it weren't for PyList_SetItem being different, none of the others would need the clarification at all.
msg360953 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2020-01-29 11:21
New changeset e1e80002e28e1055f399a20918c49d50d093709e by Joannah Nanjekye in branch 'master':
bpo-39153: Clarify C API *SetItem refcounting semantics (GH-18220)
msg360955 - (view) Author: miss-islington (miss-islington) Date: 2020-01-29 11:29
New changeset 526523c19322169a7f7507d9da291053df979412 by Miss Islington (bot) in branch '3.8':
bpo-39153: Clarify C API *SetItem refcounting semantics (GH-18220)
msg361074 - (view) Author: Dong-hee Na (corona10) * (Python committer) Date: 2020-01-30 15:49
Thanks for the update :)
Date User Action Args
2020-01-30 15:49:50corona10setstatus: open -> closed

nosy: + corona10
messages: + msg361074

resolution: fixed
stage: patch review -> resolved
2020-01-29 11:29:42miss-islingtonsetnosy: + miss-islington
messages: + msg360955
2020-01-29 11:21:20miss-islingtonsetpull_requests: + pull_request17625
2020-01-29 11:21:17ncoghlansetmessages: + msg360953
2020-01-27 22:23:22nanjekyejoannahsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request17600
2019-12-30 04:58:34ncoghlansetmessages: + msg359018
2019-12-29 21:44:40serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg359008
2019-12-29 13:34:20ncoghlansetnosy: + docs@python
versions: + Python 3.8, Python 3.9
assignee: docs@python
components: + Documentation
type: enhancement
stage: needs patch
2019-12-29 13:33:59ncoghlancreate