[Python-Dev] Borrowed and Stolen References in API

[Georg Brandl]

On 05.05.2011 19:17, Amaury Forgeot d'Arc wrote:
> 2011/5/5 Guido van Rossum <guido at python.org>:
>> Seems you're in agreement with this. IMO when references are borrowed
>> it is not very interesting. The interesting thing is when calling a
>> function *steals* a reference. The other important thing to know is
>> whether the caller ends up owning the return value (if it is an
>> object) or not. I *think* you can tell the latter from the +1 for the
>> return value; but the former (whether it steals a reference) is
>> unclear from the data given. There's even an XXX comment about this in
>> the file:
>>
>> # XXX NOTE: the 0/+1/-1 refcount information for arguments is
>> # confusing!  Much more useful would be to indicate whether the
>> # function "steals" a reference to the argument or not.  Take for
>> # example PyList_SetItem(list, i, item).  This lists as a 0 change for
>> # both the list and the item arguments.  However, in fact it steals a
>> # reference to the item argument!
> 
> Should we change this file then?
> And only list functions that don't follow the usual conventions.
> 
> But I'm sure that there are external tools which already use refcounts.dat
> in its present format.

I doubt it.  And even if there are, the information in there is in parts
highly outdated (because the docs don't use parameter info), and large
numbers of functions are missing.

Let's remove the cruft, and only keep interesting info.  This will also make
the file much more manageable.

Georg