# Should we document that \`PYTHON\_API\_VERSION\` & \`sys.api\_version\` are no longer updated? **URL:** \ **Category:** Core Development\ **Created:** [June 23, 2024, 5:37am UTC](https://discuss.python.org/t/should-we-document-that-python-api-version-sys-api-version-are-no-longer-updated/56448 "2024-06-23T05:37:00Z")\ **Posts on this page:** 5\ **Page:** 1
**Author:** ![ncoghlan](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/ncoghlan/32/14266_2.png) [@ncoghlan](https://discuss.python.org/u/ncoghlan)\ **Post date:** [June 23, 2024, 5:37am UTC](https://discuss.python.org/t/should-we-document-that-python-api-version-sys-api-version-are-no-longer-updated/56448/1 "2024-06-23T05:37:00Z")
While looking into some `sys` module details for the discussion in [PEP 2026: Calendar versioning for Python](https://discuss.python.org/t/pep-2026-calendar-versioning-for-python/55782) 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](https://github.com/python/cpython/blob/96ead91f0f0db59a942b8b34da9cc980c05588a2/Include/modsupport.h#L59) 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](https://docs.python.org/3/library/sys.html) 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](https://github.com/python/cpython/issues/52365) 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](https://docs.python.org/3/c-api/module.html#single-phase-initialization) ), 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. ---
**Author:** ![FFY00](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/ffy00/32/4007_2.png) [@FFY00](https://discuss.python.org/u/FFY00)\ **Post date:** [June 23, 2024, 6:46pm UTC](https://discuss.python.org/t/should-we-document-that-python-api-version-sys-api-version-are-no-longer-updated/56448/2 "2024-06-23T18:46:18Z")
I think the right path forward is probably documenting this and have the macro issue a warning. ---
**Author:** ![encukou](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/encukou/32/2461_2.png) [@encukou](https://discuss.python.org/u/encukou)\ **Post date:** [June 24, 2024, 9:17am UTC](https://discuss.python.org/t/should-we-document-that-python-api-version-sys-api-version-are-no-longer-updated/56448/3 "2024-06-24T09:17:00Z")
> [@ncoghlan](#): > > 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](https://docs.python.org/3/c-api/module.html#single-phase-initialization) ), but mainly just to advise against using them. 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.) > [@ncoghlan](#): > > 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. That is not true: with the stable ABI, the version [is replaced](https://github.com/python/cpython/blob/96ead91f0f0db59a942b8b34da9cc980c05588a2/Include/modsupport.h#L115C36-L115C54) by [the number 3](https://github.com/python/cpython/blob/96ead91f0f0db59a942b8b34da9cc980c05588a2/Include/modsupport.h#L108). * * * IMO there are two ways to go: - [“Soft deprecation”](https://peps.python.org/pep-0387/#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](https://discuss.python.org/t/55845) 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`). ---
**Author:** ![steve.dower](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/steve.dower/32/56_2.png) [@steve.dower](https://discuss.python.org/u/steve.dower)\ **Post date:** [June 24, 2024, 12:02pm UTC](https://discuss.python.org/t/should-we-document-that-python-api-version-sys-api-version-are-no-longer-updated/56448/4 "2024-06-24T12:02:11Z")
I doubt we could revive it to today’s needs without making it some kind of string, so probably best to soft deprecate it. ---
**Author:** ![ncoghlan](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/ncoghlan/32/14266_2.png) [@ncoghlan](https://discuss.python.org/u/ncoghlan)\ **Post date:** [June 26, 2024, 6:43am UTC](https://discuss.python.org/t/should-we-document-that-python-api-version-sys-api-version-are-no-longer-updated/56448/5 "2024-06-26T06:43:02Z")
> [@encukou](#): > > [“Soft deprecation”](https://peps.python.org/pep-0387/#soft-deprecation): just a note in the docs that this mechanism is not necessary any more. (No need for any warnings, IMO.) 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](https://github.com/python/cpython/issues/121028) We could also document that the shorthand versions pass a different value based on whether they’re built with the limited API or not.