I have an application where I locate a python shared library, link to 
it, and bind a few symbols at runtime in order to run some Python 
code.  I need to be able to use Py_INCREF and Py_DECREF from 
this code (to show nice output if there is an exception), but since it 
is done dynamically my code has no idea what the definitions of 
those macros were.  This is especially bad because they are 
different for a debugging build.

I would like Py_INCREF and Py_DECREF to be available as exported 
functions *somewhere* in the Python shared library.

Logged In: YES 
user_id=11105

Bob, I understand your desire and will support it.  Would
you like to work on a patch?

Logged In: YES 
user_id=139309

Here's a patch.. Py_IncRef and Py_DecRef for Py_XINCREF and 
Py_XDECREF respectively.

Logged In: YES 
user_id=11105

Docs are missing ;-)

Logged In: YES 
user_id=139309

Where do those go?  Does it *need* to be well documented right away?  
It's not useful very often ;)

Logged In: YES 
user_id=11105

IMO every function should be documented, or at least listed
in the docs.

I'd suggest src/Doc/api/refcounting.tex, near Py_INCREF and
Py_DECREF.

While we're at it, did you miss Py_XDECREF by accident?

Logged In: YES 
user_id=139309

I'm not sure what you mean by "miss Py_XDECREF", but I did make a 
typo in the patch.  Yes I know in the feature request I say Py_*REF but 
the implementation says Py_X*REF.  I just didn't see a reason to use the 
"fast" version when function call overhead is there anyways.

A new patch (which should actually compile, in theory) is attached, 
including documentation(!).

Logged In: YES 
user_id=11105

And I wasn't reading your patch carefully, but now I
understand.  Heck, I didn't even know that Py_XINCREF
existed ;-), I've never used it somewhere.

The only suggestion I have now: I think the functions should
be named Py_XIncRef and Py_XDecRef.

Logged In: YES 
user_id=35752

There's no need to provide the Py_X* versions, IMHO.  It's easy
enough (and faster) to write "obj != NULL && Py_IncRef(obj)" in
the extension module.

Logged In: YES 
user_id=139309

I don't see any reason to name them Py_X*.  The X doesn't really mean 
anything.  I also don't see any reason that it should use Py_INCREF 
instead of Py_XINCREF.  It is NOT SUPPOSED TO BE FAST, and I don't see 
any reason to leave out the convenience.  If you want it to be fast,  you 
need to link directly to the Python framework or at least use macros for 
a particular configuration of Python.

This is for the very limited use case where you don't know or care how 
Python was configured.  I want to use it for the OS X python bootstrap 
(something like py2exe / freeze) and the reference counting is ONLY 
used to extract information from an uncaught exception (if there is one) 
when the script fails to execute.  It doesn't link directly to Python 
because the idea is that you shouldn't need a compiler to make a Python-
based application, and there's no real good reason to wait for gcc to 
compile+link the same thing over and over again.

Logged In: YES 
user_id=11105

The X does mean something - you *can* pass a NULL pointer. 
And I think functions should do exactly the same as the
macros with the same name - that's the reason why I
suggested the name change.

Whether we expose the Py_(INC|DEC)REF or the
Py_X(INC|DEC)REF macros as functions, or both pairs, I have
no preference.

Logged In: YES 
user_id=43607

I'd say, only provide versions that are equivalent to
Py_X{INC,DEC}REF.  Defensive programming!
Also, the extra overhead of checking for a NULL pointer is
completely dwarfed by the overhead of calling a function.

Logged In: YES 
user_id=139309

I think that the X prefix only applies to macros.  AFAIK there are no 
Python *functions* that use the X prefix, but most of them check input.  I 
am not using the MACRO CAPITALIZATION, so I don't think I should need 
to use XMACRO XPREFIXES either.  They're ugly.

sjoerd clearly explains why I chose the X versions in his comment below.  

In short, I think it's a bad idea to functionify Py_(INC|DEC)REF, but I don't 
want to pay the XPENALTY for making the right choice.

Logged In: YES 
user_id=11105

Ok, I'll buy that.  And the docs Bob has provided explain
that the functions wrap the Py_X... macros.
If nobody objects, I can check this in tomorrow.

Logged In: YES 
user_id=11105

Checked into CVS.
Thanks.