[Python-ideas] PEP: Hide implementation details in the C API

Eric Snow ericsnowcurrently at gmail.com
Tue Jul 11 13:41:07 EDT 2017

On Tue, Jul 11, 2017 at 4:19 AM, Victor Stinner
<victor.stinner at gmail.com> wrote:
> Step 1: split Include/ into subdirectories
> ------------------------------------------
> Split the ``Include/`` directory of CPython:
> * ``python`` API: ``Include/Python.h`` remains the default C API
> * ``core`` API: ``Include/core/Python.h`` is a new C API designed for
>   building Python
> * ``stable`` API: ``Include/stable/Python.h`` is the stable ABI
> Expect declarations to be duplicated on purpose: ``#include`` should be
> not used to include files from a different API to prevent mistakes. In
> the past, too many functions were exposed *by mistake*, especially
> symbols exported to the stable ABI by mistake.
> At this point, ``Include/Python.h`` is not changed at all: zero risk of
> backward incompatibility.
> The ``core`` API is the most complete API exposing *all* implementation
> details and use macros for best performances.

FWIW, this is similar to something I've done while working on
gathering up the CPython global runtime state. [1]  I needed to share
some internal details across compilation modules.  Nick suggested a
separate Includes/internal directory for header files containing
"private" API.  There is a _Python.h file there that starts with:

  #ifndef Py_BUILD_CORE
  #error "Internal headers are not available externally."

In Includes/Python.h, Includes/internal/_Python.h gets included if
Py_BUILD_CORE is defined.

This approach makes a strict boundary that keeps internal details out
of the public API.  That way we don't accidentally leak private API.
It sounds similar to this part of your proposal (adding the "core"


[1] http://bugs.python.org/issue30860

More information about the Python-ideas mailing list