PEP 743 – Add Py_OMIT_LEGACY_API to the Python C API

[vstinner]

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

Abstract

Add Py_OMIT_LEGACY_API C macro that hides deprecated and soft-deprecated symbols, allowing users to opt out of using API with known issues that other API solves.

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

Vote

• @erlend-aasland
• @mdboom (abstain)
• @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).

Update: the macro Py_COMPAT_API_VERSION name was changed to Py_OMIT_LEGACY_API.

[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.

[vstinner]

@erlend-aasland @mdboom @serhiy-storchaka: Do you have an opinion on this PEP?

[erlend-aasland]

+1 from me. I like Alyssa's suggested naming Py_RECOMMENDED_API slightly better than Py_COMPAT_API_VERSION, though.

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

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

Why?

[zooba]

Because another layer of headers is more obfuscating than anything else. It doesn't provide any benefit to contributors (beyond what some kind of "deprecated" macro or comment would offer), and provides no benefit to users (beyond what documentation offers).

If we want to admit that our comments and documentation are worthless, then sure, encode that information into the file structure. But as it is, there's no configuration where these APIs would be omitted (the limited API actually makes APIs inaccessible at runtime), we just want people to be aware that they're using them. Moving around in header files doesn't at all help with that.

[vstinner]

cc @malemburg

[encukou]

Let's make this a simple boolean setting that hides all* deprecated definitions for the CPython version you're building for.

[vstinner]

Let's make this a simple boolean setting

Ok, I prepared a PR for that: python/peps#4595

[vstinner]

Ok, I prepared a PR for that: python/peps#4595

Done, merged.

@erlend-aasland @zooba: What do you think of the updated PEP?

[zooba]

LGTM, thanks!

[vstinner]

Ping @mdboom @serhiy-storchaka.