On Tue, Jul 11, 2017 at 4:19 AM, Victor Stinner email@example.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.  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." #endif
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" API).