Should we document that `PYTHON_API_VERSION` & `sys.api_version` are no longer updated?

Core Development
1

While looking into some sys module details for the discussion in PEP 2026: Calendar versioning for Python I stumbled across of a piece of C API arcana I don’t recall ever encountering before: the PYTHON_API_VERSION C #define and the corresponding sys.api_version attribute.

The macro definition is in modsupport.h and was last updated in 2006 (when it was set to its current value of 1013).

The sys module attribute is not documented in sys — System-specific parameters and functions — Python 3.12.4 documentation

Bumping the API version for Python 2.7 was mentioned in an issue, but never actually happened: PYTHON_API_VERSION needs to be bumped? · Issue #52365 · python/cpython · GitHub

The C API module create docs do mention the APIs that accept an API version (e.g. see
Module Objects — Python 3.12.4 documentation ), but mainly just to advise against using them.

Since the stable ABI has been introduced, we can’t actually change this number any more, since any module built against an older version using the stable ABI would start emitting runtime warnings.

Actually getting rid of these entirely is almost certainly more trouble than it would be worth, but updating the docs (and code comments) to say that they’re kept solely for backwards compatibility, haven’t changed since Python 2.6, and won’t ever change again is potentially more reasonable.

4 Likes
2

I think the right path forward is probably documenting this and have the macro issue a warning.

3

The macro injects a version check “transparently” – i.e. if you write PyModule_Create, you’re actually calling PyModule_Create2 with the right argument. AFAIK, the warning in the docs is only against using PyModule_Create2 directly.
(Since this involves macros, wrappers for non-C/C++ languages might do something similar – or not since the version check doesn’t do much nowadays.)

That is not true: with the stable ABI, the version is replaced by the number 3.

IMO there are two ways to go:

  • “Soft deprecation”: just a note in the docs that this mechanism is not necessary any more. (No need for any warnings, IMO.)
  • Revive the mechanism:
    • Identifiyng the ABI (and checking the identifier) would need to be more involved today: it’d need to be either CPython version or minimum stable ABI version, plus any settings that affect the ABI (see a recent topic on this).
    • Document that PyModule_Create is a macro that calls PyModule_Create2, and give enough information to allow non-C wrappers to reimplement the macro.
    • Use the same mechanism in a “chokepoint” for stable ABI extensions (PyModuleDef_Init).
2 Likes
4

I doubt we could revive it to today’s needs without making it some kind of string, so probably best to soft deprecate it.

5

This is what I was thinking, too. Issue filed: Soft-deprecate `sys.api_version` and the C API's `PYTHON_API_VERSION` · Issue #121028 · python/cpython · GitHub

We could also document that the shorthand versions pass a different value based on whether they’re built with the limited API or not.

1 Like