[Python-Dev] Are undocumented functions part of the stable ABI?

[Nick Coghlan]

On 10 April 2018 at 15:34, Jeroen Demeyer <J.Demeyer at ugent.be> wrote:
> On 2018-04-08 05:17, Nick Coghlan wrote:
>>
>> Changing macro definitions doesn't break the stable ABI, as long as
>> the *old* macro expansions still do the right thing.
>
>
> To me, it looks like a bad idea to change macros. Imagine that the
> PyCFunction_Check macro changes in Python 3.8. Then an extension module
> compiled on 3.7 (but run on 3.8) would behave differently from the same
> extension compiled on 3.8. I cannot imagine that this is in line with the
> "stable ABI" philosophy.

It's fine, as the stable ABI philosophy is simply that extension
modules compiled against a given version of the stable ABI (as defined
by Py_LIMITED_API) will be binary compatible with all interpreter
versions that support that ABI.

So if a macro is changed to reference a newly exported symbol, then
the new definition *must* be put behind an "#if
!defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03080000" guard.

If it's only a semantic level change in the way the macro gets
expanded, then whether or not it needs an ABI version guard gets
judged on a case-by-case basis, and in this particular case, my view
would be that developers should be able to write extensions using the
stable ABI that accept function subclasses on 3.8+, without having to
*require* the use of 3.8+ to import their module.

For folks that explicitly *don't* want to allow subclasses, even when
compiled with 3.8+, we can offer the following snippet in the Python
3.8 porting guide:

    #ifndef PyCFunction_CheckExact
        #define PyCFunction_CheckExact PyCFunction_Check
    #endif

And then doing a search-and-replace on their code to use the "*Exact"
variant. Ideally stable ABI users won't need to do that though, since
the stable ABI hides struct internals, and all the public PyCFunction
APIs should be updated to cope with subclasses properly.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia