Glad to help! Thank you Guido, Antoine, Serhiy, and Victor for your insights and scrutinising :) E On 25 Mar 2021, at 18:15, Guido van Rossum <guido@python.org<mailto:guido@python.org>> wrote: I’m glad there is more clarity here. And thanks to Erlend Egeberg Aasland for championing the PR! —Guido On Thu, Mar 25, 2021 at 09:30 Victor Stinner <vstinner@python.org<mailto:vstinner@python.org>> wrote: Hi, A new Include/README.rst file was just added to document the 3 C API provided by CPython: * Include/: Limited C API * Include/cpython/: CPython implementation details * Include/internal/: The internal API I would like to note that *new* public C API functions must no longer steal references or return borrowed references. Don't worry, there is no plan to deprecate or remove existing functions which do that, like PyModule_AddObject() (streal a reference) or PyDict_GetItem() (return a borrowed reference). The policy is only to *add* new functions. IMO for the *internal* C API, it's fine to continue doing that for best performances. Moreover, the limited C API must not expose "implementation details". For example, structure members must not be accessed directly, because most structures are excluded from the limited C API. A function call hiding implementation details is usually better. Here is a copy of the current Include/README.rst file: The Python C API ================ The C API is divided into three sections: 1. ``Include/`` 2. ``Include/cpython/`` 3. ``Include/internal/`` Include: Limited API ==================== ``Include/``, excluding the ``cpython`` and ``internal`` subdirectories, contains the public Limited API (Application Programming Interface). The Limited API is a subset of the C API, designed to guarantee ABI stability across Python 3 versions, and is defined in :pep:`384`. Guidelines for expanding the Limited API: - Functions *must not* steal references - Functions *must not* return borrowed references - Functions returning references *must* return a strong reference - Macros should not expose implementation details - Please start a public discussion before expanding the API - Functions or macros with a ``_Py`` prefix do not belong in ``Include/``. It is possible to add a function or macro to the Limited API from a given Python version. For example, to add a function to the Limited API from Python 3.10 and onwards, wrap it with ``#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000``. Include/cpython: CPython implementation details =============================================== ``Include/cpython/`` contains the public API that is excluded from the Limited API and the Stable ABI. Guidelines for expanding the public API: - Functions *must not* steal references - Functions *must not* return borrowed references - Functions returning references *must* return a strong reference Include/internal: The internal API ================================== With PyAPI_FUNC or PyAPI_DATA ----------------------------- Functions or structures in ``Include/internal/`` defined with ``PyAPI_FUNC`` or ``PyAPI_DATA`` are internal functions which are exposed only for specific use cases like debuggers and profilers. With the extern keyword ----------------------- Functions in ``Include/internal/`` defined with the ``extern`` keyword *must not and can not* be used outside the CPython code base. Only built-in stdlib extensions (built with the ``Py_BUILD_CORE_BUILTIN`` macro defined) can use such functions. When in doubt, new internal C functions should be defined in ``Include/internal`` using the ``extern`` keyword. Victor -- Night gathers, and now my watch begins. It shall not end until my death. _______________________________________________ Python-Dev mailing list -- python-dev@python.org<mailto:python-dev@python.org> To unsubscribe send an email to python-dev-leave@python.org<mailto:python-dev-leave@python.org> https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/QKFDGIAF... Code of Conduct: http://python.org/psf/codeofconduct/ -- --Guido (mobile) _______________________________________________ Python-Dev mailing list -- python-dev@python.org<mailto:python-dev@python.org> To unsubscribe send an email to python-dev-leave@python.org<mailto:python-dev-leave@python.org> https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/6TEXVP6C... Code of Conduct: http://python.org/psf/codeofconduct/