[Python-Dev] Procedure for adding new public C API

[Paul Moore]

On 21 May 2018 at 13:41, Serhiy Storchaka <storchaka at gmail.com> wrote:
> Please don't forgot to perform the following steps when add a  new public C
> API:
>
> * Document it in Doc/c-api/.
>
> * Add an entry in the What's New document.
>
> * Add it in Doc/data/refcounts.dat.
>
> * Add it in PC/python3.def.

I thought python3.def should only contain symbols in the limited ABI
(it defines the API of python3.dll, doesn't it?)

> If you want to include it in the limited API, wrap its declaration with:
>
>    #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03080000
>    #endif
>
> (use the correct Python version of introducing a feature in the comparison)
>
> If you don't want to include it in the limited API, wrap its declaration
> with:
>
>    #ifndef Py_LIMITED_API
>    #endif

Is it even acceptable to add a symbol into the limited ABI? I thought
the idea was that if I linked with python3.dll, my code would work
with any version of Python 3? By introducing new symbols, code linked
with the python3.dll shipped with (say) Python 3.8 would fail to run
if executed with the python3.dll from Python 3.5.

I have code that links with python3.dll, which is expected to run with
any version of Python 3, so this isn't theoretical. (I'm not 100% sure
whether, if I build with a Python 3.5 version of the headers, my code
will link with a python3.dll with extra symbols - but even if that's
the case, requiring cross-version binaries to be built with the oldest
version of Python that they support seems restrictive at best.

> You are free of adding private C API, but its name should start with _Py or
> _PY and its declaration should be wrapped with:
>
>    #ifndef Py_LIMITED_API
>    #endif

Paul