classification
Title: Fix refcounting details in Py3k C API documentation
Type: Stage:
Components: Versions:
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, fdrake, ncoghlan
Priority: normal Keywords:

Created on 2010-09-03 11:43 by ncoghlan, last changed 2016-06-02 03:03 by fdrake.

Messages (3)
msg115441 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2010-09-03 11:43
As noted in [1] the refcount data for the C API documentation is contained in a separate file at Doc/data/refcounts.dat.

This file is not mentioned in "Documenting Python" and hence has not been correctly updated for Py3k (e.g. none of the PyString methods have been renamed to PyUnicode in that file, so the relevant refcount changes are not documented correctly).

There are several possible improvements to be considered in this area
1. Mention this file and its purpose in "Documenting Python"
2. Update the Sphinx extension to warn if a C API function is not found in this file
3. Update the Sphinx extension to allow this information to be expressed inline in the function definition rather than off in a separate file (if practical)
4. Address Skip's comment from that file by allowing "-0" to indicate stolen references for arguments and "+0" for borrowed references as return values
5. Perhaps add a mechanism to indicate when PyMem_Free needs to be called on a return value or pointer output value.

[1] http://mail.python.org/pipermail/python-dev/2010-September/103429.html
msg115475 - (view) Author: Skip Montanaro (skip.montanaro) * (Python triager) Date: 2010-09-03 17:39
I thought Fred Drake wrote the code that generated that file, but that
was a long time ago in a galaxy far, far away.  Perhaps Georg has
subsumed it into his Sphinx/Python doc workflow?

(making Fred "nosy" so he sees this thread...)

S
msg266867 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2016-06-02 03:03
As mentioned in issue 18085, the original file was not generated, but crafted by hand (though I don't think that really matters).
History
Date User Action Args
2016-06-02 03:03:39fdrakesetmessages: + msg266867
2011-03-19 19:11:21skip.montanarosetnosy: - skip.montanaro
2010-09-03 17:39:59skip.montanarosetnosy: + fdrake, skip.montanaro
messages: + msg115475
2010-09-03 11:44:30ncoghlansetassignee: docs@python

nosy: + docs@python
2010-09-03 11:43:41ncoghlancreate