homepage

It can be cumbersome to embed Python in a program which also #includes
a config.h from autoconf, because Python's and the program's autoconf
macros may interfere with each other. Assuming it compiles at all,
both could define the same features, sometimes the same way and
sometimes differently. Or one could be compiled with a feature macro
undefined and another with it defined, resulting in binary
incompatibility with the library which was compiled with the macro
undefined.
So one has to do something like: put the Python calls in one set of
files, the calls to the embedding program in another set, and make
them communicate via some glue code.
For this reason, please do not declare/#define symbols other than
those starting with 'py' in the include files that an embedded program
needs. Thus, do not #include at least pyconfig.h, pymath.h and
pyport.h as they are today.
Or to keep backwards compatibility, wrap such definitions in
 #ifndef PYTHON_NAMESPACE_ONLY
which an application can #define before #including Python files.
Instead, you can #define/declare symbols that match the current
autoconf symbols but are prefixed with PY_, and make use of those in
#ifdefs in the include files. The files defining this can hopefully
be autogenerated, e.g. generate a .c file like
 #include "pyconfig.h"
 int main() {
 #ifdef HAVE_WHATEVER
 puts("PY_HAVE_WHATEVER");
 #endif
 ...
 }
Things like acosh() from pymath.h which you define if the system lacks
it, could become something like this:
 #include <math.h> /* get acosh etc */
 ...
 extern double py_acosh(double); /* always present in python */
 #if !defined(PYTHON_NAMESPACE_ONLY) && !defined(HAVE_ACOSH)
 /* an other package's autoconf might do the same, so hide this
 * if requested */
 extern double acosh(double);
 #endif
 #if !defined(PYTHON_NAMESPACE_ONLY) || defined(HAVE_ACOSH)
 #define py_acosh acosh /* optimization - hide wrapper function */
 #endif

Duh, I should of course have said defined(PY_HAVE_ACOSH)
and not defined(HAVE_ACOSH), that was the whole point:-)
And the puts() should print "#define PY_HAVE_WHATEVER 1".
Hopefully there are not too many #defines which would
need to get corresponding PY_* variants.
For that matter, PYTHON_NAMESPACE_ONLY could offer a
reduced Python C API - omitting parts it would be
cumbersome to get right with only py* symbols.

Would this break existing code? Are the benefits worth it?

Daniel Diniz writes:
> Would this break existing code?
Source code? Not if you use the PYTHON_NAMESPACE_ONLY trick. Old
programs will receive all old definitions in addition to the new
autoconf symbols, since they didn't #define PYTHON_NAMESPACE_ONLY.
Programs that do #define PYTHON_NAMESPACE_ONLY will lose symbols you
can't offer because you couldn't be bothered to make them independent
of autoconf. BTW, another "reduced API" variant would be to throw
autoconf-independent symbols out to separate .h files. #include those
files from the .h files they come from, and document that programs can
#include them instead of Python.h.

Hallvard,
There is ongoing discussion on separating public and private headers:
http://groups.google.com/group/unladen-swallow/t/f3a89fc723411c49
Also see #2897, #4805, #5748 and #896330 for (sometimes slightly)
related issues.

Since this issue has been reported, a lot of work has been done to cleanup Python header files. In Python 3.8, we created Include/cpython/ and Include/internal/ subdirectories to clarify the intent and usage of header files. I close this issue.
See bpo-2897 for the specific case of structmember.h.