gh-121028: Soft-deprecate sys.api_version

[encukou]

This copies the note from the corresponding C API.
I added that note in GH-135126.

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

---

📚 Documentation preview 📚: https://cpython-previews--136463.org.readthedocs.build/

[StanFromIreland]

Is this really "deprecation" if it is not explicitly said it is? To me, it currently reads as: this serves no purpose, but something (e.g. it may be used) in the future may change.

If this is to be soft-deprecated, then it should it not be stated as so (less soft-), and added to the pending removal in a future version file?

[encukou]

Please see PEP 387, especially the definition of soft deprecation and the part that says “If the expected maintenance overhead and security risk of the deprecated behavior is small [, deprecated API] can stay indefinitely”.

I admit that is not a typical soft-deprecation: it doesn't promise that the API “will not be developed further”. That's intentional: if we ever need an API version number we might as well pick up this one again, so I don't want people to rely on it being constant forever.

Also see typical usage (more in the issue):

kivy/tools/report.py: report.append('Python API      : %s' % sys.api_version)

There's no value in bothering users with deprecation warnings and removals.

[miss-islington-app]

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

[bedevere-app]

GH-136928 is a backport of this pull request to the 3.14 branch.