PEP 743 – Add Py_COMPAT_API_VERSION to the Python C API

[vstinner]

PEP 743 – Add Py_COMPAT_API_VERSION to the Python C API: https://peps.python.org/pep-0743/

Abstract

Add Py_COMPAT_API_VERSION C macro that hides some deprecated and soft-deprecated symbols, allowing users to opt out of using API with known issues that other API solves. The macro is versioned, allowing users to update (or not) on their own pace.

Also, add namespaced alternatives for API without the Py_ prefix, and soft-deprecate the original names.

Vote

• @erlend-aasland
• @mdboom
• @serhiy-storchaka
• @zooba

@encukou and me abstain from voting since we wrote the PEP :-)

If the vote is positive, the PEP will be submitted to the Steering Council (see the SC discussion).

[zooba]

I think the proposal is too complicated, and there's no need for anything more than a simple "warn me about discouraged APIs" #define that will produce additional warnings for APIs that have alternatives. This would turn into a couple of macros for attributing deprecated functions or displaying a deprecation warning (e.g. in a particular header), rather than conditional checks everywhere.

Having additional version checks throughout our headers will make them much harder to read, and harder to keep things up to date. The chances of accidentally excluding a function by mistake are much higher. I'm not convinced that being able to set an earlier version is more helpful than getting warnings, and I'm not convinced these soft deprecations are sufficiently tied to a particular version to justify including/excluding them based on a version.

I'd be happy with a #define Py_WARN_ON_SOFT_DEPRECATION 1 that users can add to whichever build/file they want, and then rely on their /WX to turn them into build-time errors. My main concern is the complexity for us to maintain another set of conditions within our own headers.

[encukou]

Having additional version checks throughout our headers will make them much harder to read, and harder to keep things up to date.

Maybe the PEP should make it clearer that it proposes moving the affected definitions into a new header. They'd be #ifdef'd in blocks by version, and made easy to parse for linters.

Py_WARN_ON_SOFT_DEPRECATION

That could work for functions, but you can't really deprecate a macro.
(Also, one thing that this approach solves is unprefixed names, like getter: with this PEP the user can make them not clash with other code.)

[vstinner]

I'd be happy with a #define Py_WARN_ON_SOFT_DEPRECATION 1 that users can add to whichever build/file they want, and then rely on their /WX to turn them into build-time errors.

The problem of treating all warnings are errors is that you might have warnings unrelated to deprecation which may be annoying/painful to fix, especially if they come from 3rd party code (including the C library).

[zooba]

The problem of treating all warnings are errors is that you might have warnings unrelated to deprecation which may be annoying/painful to fix, especially if they come from 3rd party code

I'm very familiar with this "problem", as someone who works on projects that require all warnings and warn-as-error. I still think, given that context, that it would be better to discourage functions by making the deprecation warning optional rather than the entire definition.

Maybe the PEP should make it clearer that it proposes moving the affected definitions into a new header.

Sure. I'm even more opposed to that, so consider me -2 now.