The Steering Council has read and considered PEP 743 (Add Py_OMIT_LEGACY_API to the Python C API), and while we agree that the problem the PEP tries to solve is one worth solving, we’re not convinced this is the correct approach. We have decided to reject the PEP in its current form.
Soft deprecating APIs is important, and the current approach of documenting the soft deprecation and explaining the caveats is clearly not enough, but we have to be mindful of unnecessary churn and uncertainty any attempts to improve the situation would cause.
The SC sees a couple of problems with the proposal as-is:
- There’s no clear guidance – or even agreement in the discussion! – on how this feature should be used. Is this expected to be used in CI, or for local testing, or in released build environments (e.g. source tarballs)? What safeguards are there against “incorrect” use?
- There doesn’t seem to be much feedback from potential users that this is something they can and want to use.
- The lack of versioning in the symbol means anything that uses
Py_OMIT_LEGACY_APIin releases risks immediately breaking when users try to use it on newer Python versions, where it would otherwise remain usable. - Even with a versioned symbol, the granularity is pretty minimal: either you omit ALL legacy APIs (in that version), or none of them. This is fine for APIs where the decision is clear, like APIs that have a drop-in, superior replacement, but not so much for APIs that require other changes to the code or that are just widely used (for example,
PyDict_GetItem). - The user experience here is suboptimal, especially given most of the functions are only soft-deprecated at best: not defining the symbol gives no warnings about which functions are soft-deprecated, and defining the symbol makes all of them simply disappear, potentially leaving the C compiler to suggest wildly incorrect alternatives.
In the end, the SC is worried that the sharp edges of this approach mean it’ll just not get used. We think it needs better, more up-front UX, like a linter with editor integration, or compiler support for notifying developers without burdening users or emitting warnings without turning them into errors. We don’t think it’s up to the Python Core Team to provide such tooling, but clearly good integration is necessary, and we should perhaps consider providing information about soft deprecations in ways existing linters, IDEs, compilers and code search tools can use to provide the better UX.
For the whole SC,
Thomas.