classification
Title: Clarify refcounting semantics of PyDict_SetItem[String]
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8
process
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: 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
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)
https://github.com/python/cpython/commit/e1e80002e28e1055f399a20918c49d50d093709e
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)
https://github.com/python/cpython/commit/526523c19322169a7f7507d9da291053df979412
msg361074 - (view) Author: Dong-hee Na (corona10) * (Python committer) Date: 2020-01-30 15:49
@nanjekyejoannah 
Thanks for the update :)
History
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