Skip to content

Soft-deprecate sys.api_version and the C API's PYTHON_API_VERSION #121028

Closed
Closed
Soft-deprecate sys.api_version and the C API's PYTHON_API_VERSION#121028
Labels
docsDocumentation in the Doc dir

Description

@ncoghlan
ncoghlan
opened on Jun 26, 2024

PYTHON_API_VERSION and the related sys.api_version module attribute were last changed for Python 2.6.

At the moment they're not documented at all, so anyone stumbling across them (e.g. by running dir(sys)) may be legitimately confused as to what they're for.

They're not actually for anything, they're an old idea to help manage cross-version extension module compatibility checks that was superseded by the introduction of the stable ABI in PEP 384.

This ticket covers adding these values to the documentation specifically so they can be given an explicit soft deprecation notice (we don't have any plans to actually remove them, since their ongoing maintenance cost is essentially zero - prior to the Discourse thread linked below, I doubt anyone had even remembered these existed in the past decade)

(from https://discuss.python.org/t/should-we-document-that-python-api-version-sys-api-version-are-no-longer-updated/)

Linked PRs

Activity

  1. ncoghlan
    added
    docsDocumentation in the Doc dir
    on Jun 26, 2024

  2. hugovk commented on Jun 26, 2024

    @hugovk
    hugovk
    on Jun 26, 2024
    Member

    There's very little use in the top 8k PyPI projects:

    ❯ python3 ~/github/misc/cpython/search_pypi_top.py -q . "PYTHON_API_VERSION"
./apsw-3.45.1.0.tar.gz: apsw-3.45.1.0/src/apsw.c: m = apswmodule = PyModule_Create2(&apswmoduledef, PYTHON_API_VERSION);
./Cython-3.0.8.tar.gz: Cython-3.0.8/Cython/Compiler/ModuleNode.py: '%s = Py_InitModule4(%s, %s, %s, 0, PYTHON_API_VERSION); Py_XINCREF(%s);' % (
./gnureadline-8.1.2.tar.gz: gnureadline-8.1.2/Modules/2.x/readline.c: (PyObject *)NULL, PYTHON_API_VERSION);
./gnureadline-8.1.2.tar.gz: gnureadline-8.1.2/Modules/2.x/readline.c: (PyObject *)NULL, PYTHON_API_VERSION);
./MySQL-python-1.2.5.zip: MySQL-python-1.2.5/_mysql.c: (PyObject *)NULL, PYTHON_API_VERSION);
./catboost-1.2.2.tar.gz: catboost-1.2.2/catboost_all_src/contrib/python/numpy/py2/numpy/fft/fftpack_litemodule.c: (PyObject*)NULL,PYTHON_API_VERSION);
./catboost-1.2.2.tar.gz: catboost-1.2.2/catboost_all_src/contrib/python/numpy/py2/numpy/linalg/lapack_litemodule.c: "", (PyObject*)NULL,PYTHON_API_VERSION);
./orjson-3.9.14.tar.gz: orjson-3.9.14/include/cargo/pyo3-ffi-0.20.2/src/modsupport.rs: pub const PYTHON_API_VERSION: i32 = 1013;
./orjson-3.9.14.tar.gz: orjson-3.9.14/include/cargo/pyo3-ffi-0.20.2/src/modsupport.rs: PYTHON_API_VERSION
./orjson-3.9.14.tar.gz: orjson-3.9.14/include/cargo/pyo3-ffi-0.20.2/src/modsupport.rs: PYTHON_API_VERSION
./catboost-1.2.2.tar.gz: catboost-1.2.2/catboost_all_src/contrib/tools/cython/Cython/Compiler/ModuleNode.py: '%s = Py_InitModule4("%s", %s, %s, 0, PYTHON_API_VERSION); Py_XINCREF(%s);' % (
./catboost-1.2.2.tar.gz: catboost-1.2.2/catboost_all_src/contrib/tools/cython/patches/all-changes.patch: '%s = Py_InitModule4("%s", %s, %s, 0, PYTHON_API_VERSION); Py_XINCREF(%s);' % (
./Nuitka-2.0.3.tar.gz: Nuitka-2.0.3/nuitka/code_generation/templates/CodeTemplatesModules.py: PYTHON_API_VERSION
./pyobjc-framework-Metal-10.1.tar.gz: pyobjc-framework-Metal-10.1/Modules/_Metal_inlines.m: m = Py_InitModule4("_inlines", mod_methods, NULL, NULL, PYTHON_API_VERSION);
./pyobjc-framework-SceneKit-10.1.tar.gz: pyobjc-framework-SceneKit-10.1/Modules/_SceneKit_inlines.m: m = Py_InitModule4("_inlines", mod_methods, NULL, NULL, PYTHON_API_VERSION);
./pymqi-1.12.10.tar.gz: pymqi-1.12.10/code/pymqi/pymqe.c: (PyObject*)NULL,PYTHON_API_VERSION);
./ruamel.ordereddict-0.4.15.tar.gz: ruamel.ordereddict-0.4.15/ordereddict.c: // , NULL, PYTHON_API_VERSION
./pyobjc-framework-Cocoa-10.1.tar.gz: pyobjc-framework-Cocoa-10.1/Modules/_Foundation_inlines.m: m = Py_InitModule4("_inlines", mod_methods, NULL, NULL, PYTHON_API_VERSION);
./pyobjc-framework-Cocoa-10.1.tar.gz: pyobjc-framework-Cocoa-10.1/Modules/testhelper.m: m = Py_InitModule4("testhelper", mod_methods, NULL, NULL, PYTHON_API_VERSION);
./pyobjc-framework-CoreAudio-10.1.tar.gz: pyobjc-framework-CoreAudio-10.1/Modules/_CoreAudio_inlines.mm: m = Py_InitModule4("_inlines", mod_methods, NULL, NULL, PYTHON_API_VERSION);
./pycrypto-2.6.1.tar.gz: pycrypto-2.6.1/src/hash_template.c: #if PYTHON_API_VERSION < 1011
./pycrypto-2.6.1.tar.gz: pycrypto-2.6.1/src/block_template.c: #if PYTHON_API_VERSION < 1011
./pycrypto-2.6.1.tar.gz: pycrypto-2.6.1/src/stream_template.c: #if PYTHON_API_VERSION < 1011
./OpenEXR-1.3.9.tar.gz: OpenEXR-1.3.9/OpenEXR.cpp: #if PYTHON_API_VERSION >= 1007

Time: 0:00:27.554846
Found 24 matching lines in 15 projects
    ❯ python3 ~/github/misc/cpython/search_pypi_top.py -q . "sys\.api_version"
./Kivy-2.3.0.tar.gz: Kivy-2.3.0/kivy/tests/test_benchmark.py: benchmark.extra_info['python_api'] = str(sys.api_version)
./Kivy-2.3.0.tar.gz: Kivy-2.3.0/kivy/tools/benchmark.py: log('Python API      : %s' % sys.api_version)
./Kivy-2.3.0.tar.gz: Kivy-2.3.0/kivy/tools/report.py: report.append('Python API      : %s' % sys.api_version)
./numba-0.59.0.tar.gz: numba-0.59.0/numba/pycc/compiler.py: ir.Constant(lt._int32, sys.api_version)))
./werkzeug-3.0.1.tar.gz: werkzeug-3.0.1/src/werkzeug/testapp.py: "api_version": sys.api_version,

Time: 0:00:27.072367
Found 5 matching lines in 3 projects
  3. encukou
    added a commit that references this issue on Jul 9, 2025

    pythongh-121028: Soft-deprecate sys.api_version

    a521d24

  4. encukou commented on Jul 9, 2025

    @encukou
    encukou
    on Jul 9, 2025
    Member

    I documented PYTHON_API_VERSION & PYTHON_ABI_VERSION a while back, after forgetting about that discussion and sys.api_version...
    PR to finish this: #136463

  5. encukou
    added a commit that references this issue on Jul 21, 2025

    gh-121028: Soft-deprecate sys.api_version (GH-136463)

    658599c
  6. miss-islington
    added a commit that references this issue on Jul 21, 2025

    pythongh-121028: Soft-deprecate sys.api_version (pythonGH-136463)

    1847882
  7. encukou
    added a commit that references this issue on Jul 21, 2025

    [3.14] gh-121028: Soft-deprecate sys.api_version (GH-136463) (GH-136928)

    0d87bb6
  8. encukou
    closed this as completedon Jul 21, 2025
  9. taegyunkim
    added a commit that references this issue on Aug 4, 2025

    pythongh-121028: Soft-deprecate sys.api_version (pythonGH-136463)

    ad25fce
  10. Agent-Hellboy
    added a commit that references this issue on Aug 19, 2025

    pythongh-121028: Soft-deprecate sys.api_version (pythonGH-136463)

    04e65b7
  11. kumaraditya303
    added a commit that references this issue on Sep 9, 2025

    [3.14] pythongh-121028: Soft-deprecate sys.api_version (pythonGH-136463…

    d18396d
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc dir

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions