[Doc-SIG] Reference Counting "reference"?

[skip@mojam.com (Skip Montanaro)]

I don't write tons of extension modules, so Python's reference counting
details aren't emblazoned on my frontal lobe or encoded in my DNA.  Whenever
I have trouble with refcounts I find I also have trouble figuring out what
the behavior of various functions is by reading the documentation.

While there are a couple treatises on reference counting

    http://www.python.org/doc/api/refcountDetails.html
    http://www.python.org/doc/ext/refcounts.html

in the docs, I generally still have trouble finding what I'm looking for and
find I have to reread all the available materials pretty carefully to
convince myself I understand things.  (It would be nice if there was only a
single treatise with pointers from other places...)

I would find it helpful to have one table that identifies the exceptional
cases.  This table could have columns for "return borrowed" and "steal
reference":

    Function			returns		steals
    or Macro			borrowed	reference
    -----------------------------------------------------
    PyList_SetItem				XXX
    PyTuple_SetItem				XXX
    PyList_GetItem		XXX
    PyTuple_GetItem		XXX
    PyList_SET_ITEM				XXX
    PyTuple_SET_ITEM				XXX

It may be that those functions and macros are the only special cases.  A
simple footnote that indicates that all other functions borrow input
arguments and return owned references would suffice to sum up the entire
state of affairs for someone needing to look up the behavior of a particular
function they are unsure about.

Skip Montanaro	| Mojam: "Uniting the World of Music" http://www.mojam.com/
skip@mojam.com  | Musi-Cal: http://www.musi-cal.com/
518-372-5583