[Python-Dev] Highlighting reference-stealing APIs [was Re: cpython: Fix email post-commit review comments.]

[David Malcolm]

On Thu, 2012-04-19 at 10:48 +1200, Greg Ewing wrote:
> Antoine Pitrou wrote:
> 
> > (and here we see why reference-stealing APIs are a nuisance: because
> > you never know in advance whether a function will steal a reference or
> > not, and you have to read the docs for each and every C API call you
> > make)
> 
> Fortunately, they're very rare, so you don't encounter
> them often.
> 
> Unfortunately, they're very rare, so you're all the more
> likely to forget about them and get bitten.
> 
> Functions with ref-stealing APIs really ought to have
> a naming convention that makes them stand out and remind
> you to consult the documentation.
FWIW my refcount static analyzer adds various new compile-time
attributes to gcc:
http://gcc-python-plugin.readthedocs.org/en/latest/cpychecker.html#marking-functions-that-steal-references-to-their-arguments
so you can write declarations like these:

extern void bar(int i, PyObject *obj, int j, PyObject *other)
  CPYCHECKER_STEALS_REFERENCE_TO_ARG(2)
  CPYCHECKER_STEALS_REFERENCE_TO_ARG(4);

There's a similar attribute for functions that return borrowed
references:

  PyObject *foo(void)
    CPYCHECKER_RETURNS_BORROWED_REF;

Perhaps we should add such attributes to the headers for Python 3.3?
(perhaps with a different naming convention?)

Hope this is helpful
Dave