From bac70d806becfef3f50305267ed8bbc4d65c2578 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 18 Sep 2025 15:37:56 +0200 Subject: [PATCH 1/6] PEP 743: Make the macro a simple boolean Remove the version value. --- peps/pep-0743.rst | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/peps/pep-0743.rst b/peps/pep-0743.rst index b24d0f3558d..a8d26958425 100644 --- a/peps/pep-0743.rst +++ b/peps/pep-0743.rst @@ -18,7 +18,6 @@ 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. @@ -91,11 +90,6 @@ available API to a subset that compiles to stable ABI. (In hindsight, we should have used a different macro name for that particular kind of limiting, but it's too late to change that now.) -To prevent working code from breaking as we identify more “undesirable” API -and add safer alternatives to it, the opt-in macro should be *versioned*. -Users can choose a version they need based on their compatibility requirements, -and update it at their own pace. - To be clear, this mechanism is *not* a replacement for deprecation. Deprecation is for API that prevents new features or optimizations, or presents a security risk or maintenance burden. @@ -142,12 +136,6 @@ of CPython, and is finalized in each 3.x.0 Beta 1 release. In rare cases, entries can be removed (i.e. made available for use) at any time. -The macro should be defined to a version in the format used by -``PY_VERSION_HEX``, with the “micro”, “release” and “serial” fields -set to zero. -For example, to omit API deemed undesirable in 3.14.0b1, users should define -``Py_COMPAT_API_VERSION`` to ``0x030e0000``. - Requirements for omitted API ---------------------------- From 15022a8853014a0ab33e8ca8d85adbf5534a993f Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 18 Sep 2025 15:56:13 +0200 Subject: [PATCH 2/6] Update --- peps/pep-0743.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/peps/pep-0743.rst b/peps/pep-0743.rst index a8d26958425..011554227b3 100644 --- a/peps/pep-0743.rst +++ b/peps/pep-0743.rst @@ -188,8 +188,7 @@ Exceptions are possible if there is a good reason for them. Initial set ----------- -The following API will be omitted with ``Py_COMPAT_API_VERSION`` set to -``0x030e0000`` (3.14) or greater: +The following API will be omitted with ``Py_COMPAT_API_VERSION`` set: - Omit API returning borrowed references: From 798313e2857a8a8b915827a923e6146ff1ace714 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 18 Sep 2025 16:10:04 +0200 Subject: [PATCH 3/6] Rename the macro to Py_OMIT_LEGACY_API --- peps/pep-0743.rst | 25 +++++++++---------------- 1 file changed, 9 insertions(+), 16 deletions(-) diff --git a/peps/pep-0743.rst b/peps/pep-0743.rst index 011554227b3..de0add74714 100644 --- a/peps/pep-0743.rst +++ b/peps/pep-0743.rst @@ -1,5 +1,5 @@ PEP: 743 -Title: Add Py_COMPAT_API_VERSION to the Python C API +Title: Add Py_OMIT_LEGACY_API to the Python C API Author: Victor Stinner , Petr Viktorin , PEP-Delegate: C API Working Group @@ -15,7 +15,7 @@ Python-Version: 3.14 Abstract ======== -Add ``Py_COMPAT_API_VERSION`` C macro that hides some deprecated and +Add ``Py_OMIT_LEGACY_API`` 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. @@ -120,7 +120,7 @@ third-party libraries. Specification ============= -We introduce a ``Py_COMPAT_API_VERSION`` macro. +We introduce a ``Py_OMIT_LEGACY_API`` macro. If this macro is defined before ``#include ``, some API definitions -- as described below -- will be omitted from the Python header files. @@ -140,7 +140,7 @@ time. Requirements for omitted API ---------------------------- -An API that is omitted with ``Py_COMPAT_API_VERSION`` must: +An API that is omitted with ``Py_OMIT_LEGACY_API`` must: - be soft-deprecated (see :pep:`387`); - for all known use cases of the API, have a documented alternative @@ -152,7 +152,7 @@ An API that is omitted with ``Py_COMPAT_API_VERSION`` must: - be approved by the C API working group. (The WG may give blanket approvals for groups of related API; see *Initial set* below for examples.) -Note that ``Py_COMPAT_API_VERSION`` is meant for API that can be trivially +Note that ``Py_OMIT_LEGACY_API`` is meant for API that can be trivially replaced by a better alternative. API without a replacement should generally be deprecated instead. @@ -160,7 +160,7 @@ API without a replacement should generally be deprecated instead. Location -------- -All API definitions omitted by ``Py_COMPAT_API_VERSION`` will be moved to +All API definitions omitted by ``Py_OMIT_LEGACY_API`` will be moved to a new header, ``Include/legacy.h``. This is meant to help linter authors compile lists, so they can flag the API @@ -188,7 +188,7 @@ Exceptions are possible if there is a good reason for them. Initial set ----------- -The following API will be omitted with ``Py_COMPAT_API_VERSION`` set: +The following API will be omitted with ``Py_OMIT_LEGACY_API`` set: - Omit API returning borrowed references: @@ -276,7 +276,7 @@ The following API will be omitted with ``Py_COMPAT_API_VERSION`` set: The header file ``structmember.h``, which is not included from ```` and must be included separately, will ``#error`` if - ``Py_COMPAT_API_VERSION`` is defined. + ``Py_OMIT_LEGACY_API`` is defined. This affects the following API: ==================================== ============================== @@ -333,7 +333,7 @@ The following API will be omitted with ``Py_COMPAT_API_VERSION`` set: If any of these proposed replacements, or associated documentation, are not added in time for 3.14.0b1, they'll be omitted with later versions -of ``Py_COMPAT_API_VERSION``. +of ``Py_OMIT_LEGACY_API``. (We expect this for macros generated by ``configure``: ``HAVE_*``, ``WITH_*``, ``ALIGNOF_*``, ``SIZEOF_*``, and several without a common prefix.) @@ -344,13 +344,6 @@ Implementation TBD -Open issues -=========== - -The name ``Py_COMPAT_API_VERSION`` was taken from the earlier PEP; -it doesn't fit this version. - - Backwards Compatibility ======================= From 9dfb58338db06cd8604402993b6decd88665ef90 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 25 Sep 2025 11:49:07 +0200 Subject: [PATCH 4/6] Remove all deprecated APIs --- peps/pep-0743.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0743.rst b/peps/pep-0743.rst index de0add74714..eac3b4d6123 100644 --- a/peps/pep-0743.rst +++ b/peps/pep-0743.rst @@ -15,7 +15,7 @@ Python-Version: 3.14 Abstract ======== -Add ``Py_OMIT_LEGACY_API`` C macro that hides some deprecated and +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. From 0c1ed10edb1db37734d91291d6685d751b967e59 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 25 Sep 2025 11:57:22 +0200 Subject: [PATCH 5/6] Fix typo --- peps/pep-0743.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0743.rst b/peps/pep-0743.rst index eac3b4d6123..c096d404b26 100644 --- a/peps/pep-0743.rst +++ b/peps/pep-0743.rst @@ -80,7 +80,7 @@ It might be be sufficient to leave this to third-party linters. For that we'd need a good way to expose a list of (soft-)deprecated API to such linters. While adding that, we can -- rather easily -- do the linter's job directly -in CPython headers, avoiding the neel for an extra tool. +in CPython headers, avoiding the need for an extra tool. Unlike Python, C makes it rather easy to limit available API -- for a whole project or for each individual source file -- by having users define an “opt-in” macro. From c87fd57ca067ab3cf9b021f6681a22826a5be6f9 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Tue, 30 Sep 2025 14:15:49 +0200 Subject: [PATCH 6/6] Backwards Compatibility Co-Authored-by: Petr Viktorin --- peps/pep-0743.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/peps/pep-0743.rst b/peps/pep-0743.rst index c096d404b26..dab3cae0a4d 100644 --- a/peps/pep-0743.rst +++ b/peps/pep-0743.rst @@ -7,7 +7,7 @@ Discussions-To: https://discuss.python.org/t/pep-743-add-py-compat-api-version-t Status: Draft Type: Standards Track Created: 11-Mar-2024 -Python-Version: 3.14 +Python-Version: 3.15 .. highlight:: c @@ -351,6 +351,11 @@ The macro is backwards compatible. Developers can introduce and update the macro on their own pace, potentially for one source file at a time. +Future versions of CPython may add more API to the set that +``Py_OMIT_LEGACY_API`` hides, breaking user code. +The fix is to undefine the macro (which is safe to do) or rework the +code. + Discussions ===========