Stable ABI/Limited API for free-threaded builds

Core Development C API
32

Some alternatives I can see:

  1. abi3t makes PyObject opaque.

    Pros:

    • The PyObject memory layout for free-threaded builds does not have to be frozen. (!)
    • abi3t would be compatible with non-free-threaded builds. (abi3.abi3t wheel tags would still be needed for 3.14 and below)
    • no Py_OPAQUE_PYOBJECT define needed: “just” build (with free-threaded Python) to get an extension compatible with 3.15+ & 3.15t+.

    Cons:

    • Not API-compatible. Stable-ABI extensions would require implementing the PEP-793 export hook (or different new API solving the same issue) to support free-threaded builds. This could slow down adoption.

  2. The regular limited API makes PyObject opaque in 3.15

    Pros: as above, plus

    • no new abi3t tag to worry about

    Cons: as above, plus:

    • to use any 3.15 features, stable-ABI extenstions would need to implement the PEP-793 export hook (or different new API solving the same issue)

  3. PyObject is not made opaque.

    Pros:

    • Simple to implement. (This is the “don’t worry about technical debt” option.)

    Cons:

    • No extension can be compatible with both regular & free-threaded builds.
    • No movement toward getting PyObject memory layout out of stable ABI.

Notice that 1 & 2:

  • Both need PEP-793 (or similar)
  • The differences between these and the “main” proposal are mainly in filename/wheel tags and guarantees/documentation. Putting the #ifdef Py_OPAQUE_PYOBJECT lines in main would be rather useful for experimenting with these, even if they’re made obsolete & removed before RC.