[Python-Dev] C API doc question (original) (raw)

Nick Coghlan ncoghlan at gmail.com
Fri Sep 3 13:44:51 CEST 2010

On Fri, Sep 3, 2010 at 9:19 PM, Amaury Forgeot d'Arc <amauryfa at gmail.com> wrote:

2010/9/3 Nick Coghlan <ncoghlan at gmail.com>:

Due to the Unicode API discussion, I happened to be looking at the C API docs at http://docs.python.org/dev/c-api/unicode.html#plain-py-unicode and noticed that out of:

PyUnicodeFromUnicode PyUnicodeFromStringAndSize PyUnicodeFromString PyUnicodeFromFormat PyUnicodeFromFormatV PyUnicodeFromEncodedObject PyUnicodeFromObject only the first and the last two are flagged in the online docs as returning a new reference. The other 4 are not (but probably should be). However, I can't see anything in the markup which is even causing those "Return value: New reference" markings to appear in the first place, nor any clues in the Documenting Python info. What am I missing? This information is in the file:  Doc/data/refcounts.dat There is a extension to sphinx that reads this file and generates the annotation in the documentation. This file is not very well known, even by core developers...

Nope, never knew it existed until just now :)

Since it does exist, how hard would it be to get the extension to emit a warning if a C API function isn't listed in that file, or if a function listed in that file doesn't appear anywhere in the docs? Currently it appears to default to reporting no effect on references if a function isn't mentioned, which is potentially misleading (as the above examples show, this file completely missed out on the PyString->PyUnicode rename).

From a more wish-list point of view, how hard would it be to modify the extension to support having this markup inline with the function documentation rather than having it off in a separate file? Or addressing Skip's comment by allowing "-0" to indicate cases where item references are stolen?

I created http://bugs.python.org/issue9755 to cover these questions.

Cheers, Nick.

-- Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia

More information about the Python-Dev mailing list