# PEP 743 – Add Py\_COMPAT\_API\_VERSION to the Python C API (take 2)

**URL:** <https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323>\
**Category:** PEPs\
**Created:** [July 27, 2024, 3:28pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323 "2024-07-27T15:28:23Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![encukou](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/encukou/32/2461_2.png) [@encukou](https://discuss.python.org/u/encukou)\
**Post date:** [July 27, 2024, 3:28pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/1 "2024-07-27T15:28:23Z")

</div>

Since the [previous version of this PEP](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api/48243), I’ve teamed up with Victor to rewrite it. The result is available as the [current version of PEP 743](https://peps.python.org/pep-0743/), and quoted below.

In short, we propose a single macro that will:

- Hide “non-recommended API” – API that’s soft-deprecated, and easy to replace with a variant. In effect, we’re playing the role of a rudimentary linter (but the aim is also to provide better, dogfooded data for _actual_ linters, which can do advanced things like ignore individual warnings).
- Hide deprecated API.
- Hide API that lacks the `Py` prefix, so it can clash with other libraries. Note that this is something a linter can’t help with.

The macro is _versioned_, so users can upgrade (or not) at their own pace. Each version is frozen at 3.x.0b1.

The macro name is kept from the previous version of the PEP; it’s up for bikeshedding.

What do y’all think?

> **Click for full text (with broken ReST formatting)**
>
> # 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.
> 
> # Motivation
> 
> Some of Python’s C API has flaws that are only obvious in hindsight.
> 
> If an API prevents adding features or optimizations, or presents a serious  
> security risk or maintenance burden, we can deprecate and remove it as  
> described in :pep:`387`.
> 
> However, this leaves us with some API that has “sharp edges” – it works fine  
> for its current users, but should be avoided in new code.  
> For example:
> 
> - API that cannot signal an exception, so failures are either ignored or  
> exit the process with a fatal error. For example `PyObject_HasAttr`.
> - API that is not thread-safe, for example by borrowing references from  
> mutable objects, or exposing unfinished mutable objects. For example  
> `PyDict_GetItemWithError`.
> - API with names that don’t use the `Py`/`_Py` prefix, and so can clash  
> with other code. For example: `setter`.
> 
> It is important to note that despite such flaws, it’s usually possible  
> to use the API correctly. For example, in a single-threaded environment,  
> thread safety is not an issue.  
> We do not want to break working code, even if it uses API that would be wrong  
> in some – or even _most_ – other contexts.
> 
> On the other hand, we want to steer users away from such “undesirable” API  
> in _new_ code, especially if a safer alternative exists.
> 
> ## Adding the `Py` prefix
> 
> Some names defined in CPython headers is not namespaced: it that lacks the  
> `Py` prefix (or a variant: `_Py`, and alternative capitalizations).  
> For example, we declare a function type named simply `setter`.
> 
> While such names are not exported in the ABI (as checked by `make smelly`),  
> they can clash with user code and, more importantly, with libraries linked  
> to third-party extensions.
> 
> While it would be possible to provide namespaced aliases and (soft-)deprecate  
> these names, the only way to make them not clash with third-party code is to  
> not define them in Python headers at all.
> 
> # Rationale
> 
> We want to allow an easy way for users to avoid “undesirable” API if they  
> choose to do so.
> 
> 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.  
> 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.
> 
> We already do something similar with `Py_LIMITED_API`, which limits the  
> 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.  
> This mechanism, on the other hand, is meant for cases where “we found  
> a slightly better way of doing things” – perhaps one that’s harder to misuse,  
> or just has a less misleading name.  
> (On a lighter note: many people configure a code quality checker to shout at  
> them about the number of blank lines between functions. Let’s help them  
> identify more substantial “code smells”!)
> 
> The proposed macro does not _change_ any API definitions; it only _hides_ them.  
> So, if code compiles with the macro, it’ll also compile without it, with  
> identical behaviour.  
> This has implications for core devs: to deal with undesirable behaviour,  
> we’ll need to introduce new, better API, and _then_ discourage the old one.  
> In turn, this implies that we should look at an individual API and fix all its  
> known issues at once, rather than do codebase-wide sweeps for a single kind of  
> issue, so that we avoid multiple renames of the same function.
> 
> ## Adding the `Py` prefix
> 
> An opt-in macro allows us to omit definitions that could clash with  
> third-party libraries.
> 
> # Specification
> 
> We introduce a `Py_COMPAT_API_VERSION` macro.  
> If this macro is defined before `#include <Python.h>`, some API definitions  
> – as described below – will be omitted from the Python header files.
> 
> The macro only omits complete top-level definitions exposed from `<Python.h>`.  
> Other things (the ABI, structure definitions, macro expansions, static inline  
> function bodies, etc.) are not affected.
> 
> The C API working group (:pep:`731`) has authority over the set of omitted  
> definitions.
> 
> The set of omitted definitions will be tied to a particular feature release  
> 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
> 
> An API that is omitted with `Py_COMPAT_API_VERSION` must:
> 
> - be soft-deprecated (see :pep:`387`);
> - for all known use cases of the API, have a documented alternative  
> or workaround;
> - have tests to ensure it keeps working (except for 1:1 renames using  
> `#define` or `typedef`);
> - be documented (except if it was never mentioned in previous versions of the  
> documentation); and
> - 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  
> replaced by a better alternative.  
> API without a replacement should generally be deprecated instead.
> 
> ## Location
> 
> All API definitions omitted by `Py_COMPAT_API_VERSION` 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  
> with warnings rather than errors.
> 
> Note that for simple renaming of source-only constructs (macros, types), we  
> expect names to be omitted in the same version – or the same PR – that adds  
> a replacement.  
> This means that the original definition will be renamed, and a `typedef`  
> or `#define` for the old name added to `Include/legacy.h`.
> 
> ## Documentation
> 
> Documentation for omitted API should generally:
> 
> - appear after the recommended replacement,
> - reference the replacement (e.g. “Similar to X, but…”), and
> - focus on differences from the replacement and migration advice.
> 
> 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:
> 
> - Omit API returning borrowed references:
> 
> - Omit deprecated APIs:
> 
> - Soft-deprecate and omit APIs:
> 
> - Omit `<structmember.h>` legacy API:
> 
> - Omit soft deprecated macros:
> 
> - Soft-deprecate and omit typedefs without the `Py`/`_Py` prefix  
> (`getter`, `setter`, `allocfunc`, …), in favour of _new_ ones  
> that add the prefix (`Py_getter` , etc.)
> 
> - Soft-deprecate and omit macros without the `Py`/`_Py` prefix  
> (`METH_O`, `CO_COROUTINE`, `FUTURE_ANNOTATIONS`, `WAIT_LOCK`, …),  
> favour of _new_ ones that add the prefix (`Py_METH_O` , etc.).
> 
> - Any others approved by the C API workgroup
> 
> 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`.  
> (We expect this for macros generated by `configure`: `HAVE_*`, `WITH_*`,  
> `ALIGNOF_*`, `SIZEOF_*`, and several without a common prefix.)
> 
> # Implementation
> 
> TBD
> 
> # Open issues
> 
> The name `Py_COMPAT_API_VERSION` was taken from the earlier PEP;  
> it doesn’t fit this version.
> 
> # Backwards Compatibility
> 
> The macro is backwards compatible.  
> Developers can introduce and update the macro on their own pace, potentially  
> for one source file at a time.
> 
> # Discussions
> 
> - C API Evolutions: `Macro to hide deprecated functions <https://github.com/capi-workgroup/api-evolution/issues/24>`\_  
> (October 2023)
> - C API Problems: `Opt-in macro for a new clean API? Subset of functions with no known issues <https://github.com/capi-workgroup/problems/issues/54>`\_  
> (June 2023)
> - `Finishing the Great Renaming <https://discuss.python.org/t/finishing-the-great-renaming/54082>`\_  
> (May 2024)
> 
> # Prior Art
> 
> - `Py_LIMITED_API` macro of :pep:`384` “Defining a Stable ABI”.
> - Rejected :pep:`606` “Python Compatibility Version” which has a global  
> scope.
> 
> # Copyright
> 
> This document is placed in the public domain or under the  
> CC0-1.0-Universal license, whichever is more permissive.

---

<div class="post-metadata">

**Author:** ![ncoghlan](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/ncoghlan/32/14266_2.png) [@ncoghlan](https://discuss.python.org/u/ncoghlan)\
**Post date:** [July 27, 2024, 4:00pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/2 "2024-07-27T16:00:17Z")

</div>

My suggestion for the opt-in macro bikeshed colour: `Py_RECOMMENDED_API`

The PEP itself looks good to me. PEP 667 lists a few borrowed-reference APIs that have recommended replacements as of Python 3.13, so could also go in the initial set of no longer recommended APIs (only `PyEval_GetLocals` is going to be hard deprecated, the rest are only soft-deprecated)

---

<div class="post-metadata">

**Author:** ![encukou](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/encukou/32/2461_2.png) [@encukou](https://discuss.python.org/u/encukou)\
**Post date:** [July 30, 2025, 1:26pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/3 "2025-07-30T13:26:41Z")

</div>

The PEP ran into [opposition on the C API WG](https://github.com/capi-workgroup/decisions/issues/49#issuecomment-2506777163) issue.  
In particular, Steve instead wants a `#define Py_WARN_ON_SOFT_DEPRECATION 1` that would _warn_, rather than hide API.  
Let’s move the discussion back here.

@steve.dower, two questions for you:

- How would you handle macros?
- What would be your solution to unprefixed names, like `getter`, that can clash with other libraries?

Another thing that came up is that API deprecated this way could be moved to a separate header, to be more easily usable as data for linters, to consolidate the `#if` blocks, and to remove cruft from the other headers.  
(For the record, I admit that our documentation does not provide a list of soft-deprecated API.)

---

<div class="post-metadata">

**Author:** ![steve.dower](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/steve.dower/32/56_2.png) [@steve.dower](https://discuss.python.org/u/steve.dower)\
**Post date:** [July 30, 2025, 2:48pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/4 "2025-07-30T14:48:19Z")

</div>

> [@encukou](#):
>
> @steve.dower, two questions for you:
> 
> - How would you handle macros?

Presumably you mean how to warn people that they’re deprecated? Which is exactly the same question as how to do it under any other deprecation? So my answer is, “the same as every other time we deprecate a macro”.

If you actually _want_ a warning, then I’d say they get deprecated and turned into an inline function, which can be annotated with a deprecation marker. With very few exceptions, we ought to be able to rely on optimisers to inline them, and if users have performance concerns then they can stop using deprecated macros and switch to the non-deprecated one whenever they like.

> [@encukou](#):
>
> - What would be your solution to unprefixed names, like `getter`, that can clash with other libraries?

Uh… same thing? If we can annotate it, then we annotate it. If we can’t, then we just publish a list of names that are going away and people will eventually discover it when they update.

* * *

FTR, I’m +1 on “don’t do this at all”, +0 on “warn rather than hide”, and -1 on “add more orthogonal macros to our headers” (the original proposal). So that’s why I’m quite happy to just exclude complicated bits - because I’m quite happy to just exclude _everything_ from this proposal!

---

<div class="post-metadata">

**Author:** ![vstinner](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/vstinner/32/15130_2.png) [@vstinner](https://discuss.python.org/u/vstinner)\
**Post date:** [September 30, 2025, 3:29pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/5 "2025-09-30T15:29:45Z")

</div>

[The PEP](https://peps.python.org/pep-0743/) has been updated:

- The macro `Py_COMPAT_API_VERSION` was renamed to `Py_OMIT_LEGACY_API`.
- The macro has no value anymore. Previously, it required a Python version.

The macro usage should now be simpler and its intent (macro name) as well.

---

<div class="post-metadata">

**Author:** ![encukou](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/encukou/32/2461_2.png) [@encukou](https://discuss.python.org/u/encukou)\
**Post date:** [October 22, 2025, 11:58am UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/6 "2025-10-22T11:58:10Z")

</div>

I’ve submitted the PEP to the SC: [PEP 743 – Add Py\_OMIT\_LEGACY\_API to the Python C API · Issue #315 · python/steering-council · GitHub](https://github.com/python/steering-council/issues/315)

---

<div class="post-metadata">

**Author:** ![Locked-chess-official](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/locked-chess-official/32/27037_2.png) [@Locked-chess-official](https://discuss.python.org/u/Locked-chess-official)\
**Post date:** [November 13, 2025, 7:57am UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/7 "2025-11-13T07:57:40Z")

</div>

Here is an [attempt](https://github.com/Locked-chess-official/cpython/tree/PEP743_implement) for build a struct of it:

Here is a thorny issues: some header files require the macros in “pyconfig.h” which are non-standard so that these macros in “pyconfig.h” cannot “do not be defined at first”, so I use a tool, when user define the macro “Py\_OMIT\_LEGACY\_API”, the “legacy.h” will undefine them at last.

We can use the code below to find them:

```python
import os
import subprocess
import re

repo_root = subprocess.check_output(
    ["git", "rev-parse", "--show-toplevel"],
    text=True
).strip()
os.chdir(repo_root)
print(f"Switched to repo root: {repo_root}")

grep_cmd = [
    "git", "grep", "-nE", r"^[[:space:]]*#ifn?def[[:space:]]+[A-Za-z_][A-Za-z0-9_]*",
    "--", "Include/"
]
result = subprocess.run(grep_cmd, capture_output=True, text=True)

lines = result.stdout.splitlines()
pattern = re.compile(r"#ifn?def\s+([A-Za-z_][A-Za-z0-9_]*)")

filtered = []
for line in lines:
    match = pattern.search(line)
    if not match:
        continue
    macro = match.group(1)
    if macro.startswith(("Py", "PY", "_Py", "_PY")):
        continue
    if macro == "__cplusplus":
        continue
    filtered.append(line)

output_path = os.path.join(repo_root, "non_py_macros.txt")
with open(output_path, "w", encoding="utf-8") as f:
    f.write("\n".join(filtered))

print(f"Done. Found {len(filtered)} non-Py macros.")
print(f"Result saved to: {output_path}")

```

Finally you can get (some of the macros which start with “HAVE\_”, “WITH\_” are defined in “pyconfig.h”):

```python
Include/Python.h:26:#ifdef HAVE_SYS_TYPES_H
Include/Python.h:63:#ifdef _MSC_VER
Include/Python.h:151:#ifdef _MSC_VER
Include/cpython/initconfig.h:91:#ifdef MS_WINDOWS
Include/cpython/initconfig.h:175:#ifdef MS_WINDOWS
Include/cpython/initconfig.h:184:#ifdef __APPLE__
Include/cpython/object.h:397:#ifdef NDEBUG
Include/cpython/pthread_stubs.h:8:#ifndef _POSIX_THREADS
Include/cpython/pthread_stubs.h:21:#ifdef __wasi__
Include/cpython/pthread_stubs.h:95:#ifndef PTHREAD_KEYS_MAX
Include/cpython/pydebug.h:24:#ifdef MS_WINDOWS
Include/cpython/pyerrors.h:64:#ifdef MS_WINDOWS
Include/cpython/pyerrors.h:88:#ifdef MS_WINDOWS
Include/cpython/pymem.h:22:#ifdef WITH_PYMALLOC
Include/cpython/pymem.h:26:#ifdef WITH_MIMALLOC
Include/cpython/pythread.h:15:#ifdef HAVE_PTHREAD_H
Include/datetime.h:4:#ifndef DATETIME_H
Include/dynamic_annotations.h:56:#ifndef __DYNAMIC_ANNOTATIONS_H__
Include/dynamic_annotations.h:59:#ifndef DYNAMIC_ANNOTATIONS_ENABLED
Include/fileutils.h:8:#ifdef HAVE_SYS_STAT_H
Include/fileutils.h:14:#ifndef S_IFMT
Include/fileutils.h:18:#ifndef S_IFLNK
Include/fileutils.h:23:#ifndef S_ISREG
Include/fileutils.h:26:#ifndef S_ISDIR
Include/fileutils.h:29:#ifndef S_ISCHR
Include/fileutils.h:32:#ifndef S_ISLNK
Include/internal/mimalloc/mimalloc.h:8:#ifndef MIMALLOC_H
Include/internal/mimalloc/mimalloc/atomic.h:8:#ifndef MIMALLOC_ATOMIC_H
Include/internal/mimalloc/mimalloc/atomic.h:139:#ifdef _WIN64
Include/internal/mimalloc/mimalloc/atomic.h:239:#ifdef _WIN64
Include/internal/mimalloc/mimalloc/atomic.h:363:#ifdef __APPLE__
Include/internal/mimalloc/mimalloc/internal.h:8:#ifndef MIMALLOC_INTERNAL_H
Include/internal/mimalloc/mimalloc/internal.h:214:#ifndef __has_builtin
Include/internal/mimalloc/mimalloc/internal.h:226:#ifndef EAGAIN // double free
Include/internal/mimalloc/mimalloc/internal.h:229:#ifndef ENOMEM // out of memory
Include/internal/mimalloc/mimalloc/internal.h:232:#ifndef EFAULT // corrupted free-list or meta-data
Include/internal/mimalloc/mimalloc/internal.h:235:#ifndef EINVAL // trying to free an invalid pointer
Include/internal/mimalloc/mimalloc/internal.h:238:#ifndef EOVERFLOW // count*size overflow
Include/internal/mimalloc/mimalloc/internal.h:636: #ifdef MI_ENCODE_FREELIST
Include/internal/mimalloc/mimalloc/internal.h:648: #ifdef MI_ENCODE_FREELIST
Include/internal/mimalloc/mimalloc/internal.h:658: #ifdef MI_ENCODE_FREELIST
Include/internal/mimalloc/mimalloc/internal.h:674: #ifdef MI_ENCODE_FREELIST
Include/internal/mimalloc/mimalloc/prim.h:8:#ifndef MIMALLOC_PRIM_H
Include/internal/mimalloc/mimalloc/prim.h:134:#ifdef MI_PRIM_THREAD_ID
Include/internal/mimalloc/mimalloc/prim.h:282: #ifdef __GNUC__
Include/internal/mimalloc/mimalloc/track.h:8:#ifndef MIMALLOC_TRACK_H
Include/internal/mimalloc/mimalloc/track.h:108:#ifndef mi_track_resize
Include/internal/mimalloc/mimalloc/track.h:112:#ifndef mi_track_align
Include/internal/mimalloc/mimalloc/track.h:116:#ifndef mi_track_init
Include/internal/mimalloc/mimalloc/track.h:120:#ifndef mi_track_mem_defined
Include/internal/mimalloc/mimalloc/track.h:124:#ifndef mi_track_mem_undefined
Include/internal/mimalloc/mimalloc/track.h:128:#ifndef mi_track_mem_noaccess
Include/internal/mimalloc/mimalloc/types.h:8:#ifndef MIMALLOC_TYPES_H
Include/internal/mimalloc/mimalloc/types.h:26:#ifdef _MSC_VER
Include/internal/mimalloc/mimalloc/types.h:32:#ifndef MI_MAX_ALIGN_SIZE
Include/internal/mimalloc/mimalloc/types.h:634:#ifndef MI_STAT
Include/internal/pycore_bitutils.h:28:#ifdef _MSC_VER
Include/internal/pycore_ceval.h:67:#ifdef HAVE_FORK
Include/internal/pycore_condvar.h:11:#ifdef _POSIX_THREADS
Include/internal/pycore_condvar.h:17:#ifdef HAVE_PTHREAD_H
Include/internal/pycore_condvar.h:34:#ifndef WIN32_LEAN_AND_MEAN
Include/internal/pycore_faulthandler.h:11:#ifdef HAVE_SIGACTION
Include/internal/pycore_faulthandler.h:16:#ifndef MS_WINDOWS
Include/internal/pycore_faulthandler.h:24:#ifdef HAVE_SIGACTION
Include/internal/pycore_faulthandler.h:36:#ifdef FAULTHANDLER_USER
Include/internal/pycore_faulthandler.h:56:#ifdef MS_WINDOWS
Include/internal/pycore_faulthandler.h:79:#ifdef FAULTHANDLER_USER
Include/internal/pycore_faulthandler.h:83:#ifdef FAULTHANDLER_USE_ALT_STACK
Include/internal/pycore_fileutils.h:16:#ifdef _MSC_VER
Include/internal/pycore_fileutils.h:63:#ifdef MS_WINDOWS
Include/internal/pycore_fileutils.h:135:#ifdef HAVE_READLINK
Include/internal/pycore_fileutils.h:144:#ifdef HAVE_REALPATH
Include/internal/pycore_fileutils.h:176:#ifdef MS_WINDOWS
Include/internal/pycore_fileutils.h:240:#ifdef HAVE_NON_UNICODE_WCHAR_T_REPRESENTATION
Include/internal/pycore_fileutils.h:254:#ifdef MS_WINDOWS
Include/internal/pycore_fileutils.h:310:#ifndef MS_WINDOWS
Include/internal/pycore_fileutils_windows.h:11:#ifdef MS_WINDOWS
Include/internal/pycore_gc.h:230:#ifndef NDEBUG
Include/internal/pycore_gc.h:275:#ifndef NDEBUG
Include/internal/pycore_gil.h:55:#ifdef FORCE_SWITCHING
Include/internal/pycore_import.h:35:#ifdef HAVE_DLOPEN
Include/internal/pycore_importdl.h:17:#ifdef HAVE_DYNAMIC_LOADING
Include/internal/pycore_importdl.h:29:#ifdef MS_WINDOWS
Include/internal/pycore_importdl.h:67:#ifndef MS_WINDOWS
Include/internal/pycore_importdl.h:92:#ifdef HAVE_DYNAMIC_LOADING
Include/internal/pycore_importdl.h:128:#ifdef HAVE_DYNAMIC_LOADING
Include/internal/pycore_importdl.h:142:#ifdef MS_WINDOWS
Include/internal/pycore_initconfig.h:16:#ifdef _MSC_VER
Include/internal/pycore_initconfig.h:55:#ifndef NDEBUG
Include/internal/pycore_interp_structs.h:312:#ifdef HAVE_DLOPEN
Include/internal/pycore_interp_structs.h:411:#ifndef PRIVATE_MEM
Include/internal/pycore_interp_structs.h:874:#ifdef HAVE_FORK
Include/internal/pycore_interpframe.h:230:#ifndef NDEBUG
Include/internal/pycore_mimalloc.h:22:#ifdef WITH_MIMALLOC
Include/internal/pycore_object.h:528:#ifdef NDEBUG
Include/internal/pycore_obmalloc.h:175:#ifdef WITH_MEMORY_LIMITS
Include/internal/pycore_obmalloc.h:176:#ifndef SMALL_MEMORY_LIMIT
Include/internal/pycore_obmalloc.h:210:#ifdef USE_LARGE_ARENAS
Include/internal/pycore_obmalloc.h:218:#ifdef WITH_MEMORY_LIMITS
Include/internal/pycore_obmalloc.h:225:#ifdef USE_LARGE_POOLS
Include/internal/pycore_obmalloc.h:579:#ifdef USE_INTERIOR_NODES
Include/internal/pycore_obmalloc.h:632:#ifdef USE_INTERIOR_NODES
Include/internal/pycore_obmalloc.h:647:#ifdef USE_INTERIOR_NODES
Include/internal/pycore_obmalloc.h:693:#ifdef WITH_PYMALLOC
Include/internal/pycore_opcode_metadata.h:36:#ifdef NEED_OPCODE_METADATA
Include/internal/pycore_opcode_metadata.h:519:#ifdef NEED_OPCODE_METADATA
Include/internal/pycore_opcode_metadata.h:1069:#ifdef NEED_OPCODE_METADATA
Include/internal/pycore_opcode_metadata.h:1317:#ifdef NEED_OPCODE_METADATA
Include/internal/pycore_opcode_metadata.h:1506:#ifdef NEED_OPCODE_METADATA
Include/internal/pycore_opcode_metadata.h:1748:#ifdef NEED_OPCODE_METADATA
Include/internal/pycore_opcode_metadata.h:1773:#ifdef NEED_OPCODE_METADATA
Include/internal/pycore_opcode_metadata.h:2073:#ifdef NEED_OPCODE_METADATA
Include/internal/pycore_pyhash.h:74:#ifndef MS_WINDOWS
Include/internal/pycore_pylifecycle.h:21:#ifdef MS_WINDOWS
Include/internal/pycore_pymath.h:86:#ifdef HAVE_GCC_ASM_FOR_X87
Include/internal/pycore_pymath.h:143:#ifdef HAVE_GCC_ASM_FOR_MC68881
Include/internal/pycore_pystate.h:97:#ifndef NDEBUG
Include/internal/pycore_pystate.h:251:#ifdef HAVE_FORK
Include/internal/pycore_pystate.h:296:#ifndef NDEBUG
Include/internal/pycore_pythread.h:62:#ifdef _USE_PTHREADS
Include/internal/pycore_pythread.h:90:#ifdef HAVE_FORK
Include/internal/pycore_runtime.h:24:#ifdef HAVE_FORK
Include/internal/pycore_runtime_structs.h:50:#ifndef MS_WINDOWS
Include/internal/pycore_semaphore.h:12:#ifdef MS_WINDOWS
Include/internal/pycore_signal.h:20:#ifdef _SIG_MAXSIG
Include/internal/pycore_signal.h:47:#ifdef MS_WINDOWS
Include/internal/pycore_signal.h:58:#ifdef MS_WINDOWS
Include/internal/pycore_signal.h:71:#ifdef MS_WINDOWS
Include/internal/pycore_signal.h:82:#ifdef MS_WINDOWS
Include/internal/pycore_signal.h:99:#ifdef MS_WINDOWS
Include/internal/pycore_stackref.h:680:#ifdef _WIN32
Include/internal/pycore_stackref.h:774:#ifdef _WIN32
Include/internal/pycore_stackref.h:808:#ifdef _WIN32
Include/internal/pycore_stackref.h:840:#ifdef _WIN32
Include/internal/pycore_time.h:62:#ifdef __clang__
Include/internal/pycore_time.h:174:#ifdef MS_WINDOWS
Include/internal/pycore_time.h:180:#ifndef MS_WINDOWS
Include/internal/pycore_tracemalloc.h:40:#ifdef __GNUC__
Include/internal/pycore_tracemalloc.h:49:#ifdef _MSC_VER
Include/internal/pycore_uop_metadata.h:21:#ifdef NEED_OPCODE_METADATA
Include/intrcheck.h:9:#ifdef HAVE_FORK
Include/methodobject.h:119:#ifdef STACKLESS
Include/object.h:584:#ifdef STACKLESS
Include/osdefs.h:16:#ifdef MS_WINDOWS
Include/osdefs.h:23:#ifdef __VXWORKS__
Include/osdefs.h:28:#ifndef SEP
Include/osdefs.h:33:#ifdef __hpux
Include/osdefs.h:41:#ifndef MAXPATHLEN
Include/osdefs.h:50:#ifndef DELIM
Include/py_curses.h:5:#ifdef __APPLE__
Include/py_curses.h:10:#ifdef _BSD_WCHAR_T_DEFINED_
Include/py_curses.h:53:#ifdef NCURSES_VERSION
Include/py_curses.h:65:#ifndef MVWDELCH_IS_EXPRESSION
Include/py_curses.h:88:#ifdef CURSES_MODULE
Include/pydtrace.h:9:#ifdef WITH_DTRACE
Include/pyerrors.h:145:#ifdef MS_WINDOWS
Include/pyerrors.h:192:#ifdef MS_WINDOWS
Include/pylifecycle.h:40:#ifdef MS_WINDOWS
Include/pymacconfig.h:8:#ifdef __APPLE__
Include/pymacconfig.h:33:#ifndef __LP64__
Include/pymacconfig.h:38:#ifdef __LP64__
Include/pymacconfig.h:73:#ifdef __BIG_ENDIAN__
Include/pymacro.h:197:#ifdef WITH_DOC_STRINGS
Include/pyport.h:4:#ifndef UCHAR_MAX
Include/pyport.h:16:#ifdef __has_builtin
Include/pyport.h:24:#ifdef __has_attribute
Include/pyport.h:114:#ifndef HAVE_LONG_LONG
Include/pyport.h:153:#ifdef HAVE_PY_SSIZE_T
Include/pyport.h:242:#ifdef SIGNED_RIGHT_SHIFT_ZERO_FILLS
Include/pyport.h:401:#ifndef INT_MAX
Include/pyport.h:405:#ifndef LONG_MAX
Include/pyport.h:415:#ifndef LONG_MIN
Include/pyport.h:419:#ifndef LONG_BIT
Include/pyport.h:458:#ifdef __SUNPRO_C
Include/pyport.h:478:#ifdef WORDS_BIGENDIAN
Include/pyport.h:486:#ifdef __ANDROID__
Include/pyport.h:499:#ifndef WITH_THREAD
Include/pyport.h:511:#ifdef WITH_THREAD
Include/pystrcmp.h:11:#ifdef MS_WINDOWS
Include/pythonrun.h:27:#ifdef USE_STACKCHECK
Include/unicodeobject.h:63:#ifndef SIZEOF_WCHAR_T
Include/unicodeobject.h:86:#ifdef HAVE_USABLE_WCHAR_T
Include/unicodeobject.h:253:#ifdef HAVE_WCHAR_H
Include/unicodeobject.h:613:#ifdef MS_WINDOWS

```

So I apply for that the macros in “pyconfig.h” will have a different way to be handled.

---

<div class="post-metadata">

**Author:** ![da-woods](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/da-woods/32/7507_2.png) [@da-woods](https://discuss.python.org/u/da-woods)\
**Post date:** [November 13, 2025, 1:39pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/8 "2025-11-13T13:39:04Z")

</div>

I think you may be missing the main point of this PEP.

It’s really about providing C extension authors with an way to test that they’re still using the best practices and that their extension will keep working into the future (without having to wait for the future).

It isn’t really about “undefing everything in pyconfig.h”.

The cleanup doesn’t have to be comprehensive to be useful (if you believe the PEP will be useful…), it doesn’t have to be done in one go, and the most value is probably in covering deprecated Python functions (i.e. the stuff packages are actually using) instead of all the odd names brought in by the C config.

---

<div class="post-metadata">

**Author:** ![Locked-chess-official](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/locked-chess-official/32/27037_2.png) [@Locked-chess-official](https://discuss.python.org/u/Locked-chess-official)\
**Post date:** [November 13, 2025, 1:51pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/9 "2025-11-13T13:51:30Z")

</div>

So, the warning file is also easy to generate.  
Here is the tool script to handle the “pyconfig.h”. Take me some day to finish it, and it can finish it in an easier way.

> [@da-woods](#):
>
> and the most value is probably in covering deprecated Python functions

But I have no right to decide it. The [issue](https://github.com/python/cpython/issues/141004) to add the document for C-functions is active now, and before it, there is no idea of which function should be add to “legacy.h”.

---

<div class="post-metadata">

**Author:** ![da-woods](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/da-woods/32/7507_2.png) [@da-woods](https://discuss.python.org/u/da-woods)\
**Post date:** [November 13, 2025, 3:59pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/10 "2025-11-13T15:59:19Z")

</div>

> [@Locked-chess-official](#):
>
> > [@da-woods](#):
> >
> > and the most value is probably in covering deprecated Python functions
> 
> But I have no right to decide it […]

There’s already a long list of deprecated c API (e.g. [What’s new in Python 3.14 — Python 3.14.0 documentation](https://docs.python.org/3/whatsnew/3.14.html#deprecated-c-apis) ) so there’s no need to decide anything new

---

<div class="post-metadata">

**Author:** ![Locked-chess-official](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/locked-chess-official/32/27037_2.png) [@Locked-chess-official](https://discuss.python.org/u/Locked-chess-official)\
**Post date:** [November 14, 2025, 1:49am UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/11 "2025-11-14T01:49:24Z")

</div>

> [@da-woods](#):
>
> There’s already a long list of deprecated c API (e.g. [What’s new in Python 3.14 — Python 3.14.0 documentation](https://docs.python.org/3/whatsnew/3.14.html#deprecated-c-apis) ) so there’s no need to decide anything new

The deprecated APIs are already known — agreed.  
But implementing all of them inside the PEP 743 PR mixes structural changes with behavioral ones.

Even with no new decisions to make, that would create an oversized, high-risk PR.

The PEP 743 infrastructure should land first.  
Deprecated API removals should follow in separate, focused PRs.

Now it only handles “pyconfig.h” because it can use this struct to simplify implement, the other deperecating need extra PRs.

---

<div class="post-metadata">

**Author:** ![savannahostrowski](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/savannahostrowski/32/25496_2.png) [@savannahostrowski](https://discuss.python.org/u/savannahostrowski)\
**Post date:** [January 21, 2026, 11:31pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/12 "2026-01-21T23:31:34Z")

</div>

Hey Petr and Victor,

The Steering Council has discussed PEP 743 – Add `Py_OMIT_LEGACY_API` to the Python C API.

A few specific comments about the PEP as it’s written:

- The abstract makes it seem like the PEP proposes two distinct items (partly because of the paragraph break and partly because there’s no causal link between the two items.

- The “Adding the Py prefix” section talks about unprefixed names being a problem when linking to third-party libraries, but since the smelly names are not part of the ABI (as mentioned in that section), they would not be a problem when _linking_ (but rather when including headers during compile, or just “using”).

- The last paragraph of the “Initial Set” section still mentions 3.14.0b1.

- An earlier draft of the PEP gave the macro a value, a specific version to target. This was removed later, presumably based on feedback, but the feedback wasn’t recorded, and the notion isn’t represented in the current PEP at all. We also can’t find that feedback anywhere. Can you explain why that was removed?

There’s currently no discussion how you expect people to _use_ this in practice. Is the expectation that users set this globally in their project? Per file before they include `Python.h`? In their CI or test environment only? Should they be distributing extensions with this defined, and if so, wouldn’t their source be less future proof, since it would fail to build much sooner on newer Python versions than would otherwise be the case?

We’d like to hear from potential users before making a decision. Do you have signals from specific projects that would enable `Py_OMIT_LEGACY_API`? Getting them to chime in with how they’d use it would help us feel more comfortable with adding another macro to the C API surface.

---

<div class="post-metadata">

**Author:** ![encukou](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/encukou/32/2461_2.png) [@encukou](https://discuss.python.org/u/encukou)\
**Post date:** [January 22, 2026, 2:24pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/13 "2026-01-22T14:24:26Z")

</div>

## Two distinct items

The PEP does propose two distinct items.  
The link is that second doesn’t make much sense without the first; this is in Motivation section:

> While it would be possible to provide namespaced aliases and (soft-)deprecate  
> these names, the only way to make them not clash with third-party code is to  
> not define them in Python headers at all.

Do you think the link needs to be in the Abstract?

## linking vs using

Will fix, thanks!

## 3.14 reference

Will fix, thanks!

## Versioning

Yes, that would be a good Rejected Ideas section. Here’s a draft:

A previous version of this PEP specified a versioning mechanism: a `Py_COMPAT_API_VERSION` macro that users would set to a particular version (similar to `Py_PACK_VERSION` format), causing all APIs deprecated up that CPython version to be omitted.

This mechanism would help when maintainers update to a new Python version that adds additional deprecations. With `Py_OMIT_LEGACY_API` (as proposed in this PEP), the maintainer must either migrate away from newly-deprecated code immediately, or remove the  
`Py_OMIT_LEGACY_API` macro and risk regressions (that is, using APIs that were soft-deprecated long ago). A `Py_COMPAT_API_VERSION` could be set to the old (working) version, leaving the maintainer to update their code (or not) at their own pace.

This was rejected in [C API WG issue #49](https://github.com/capi-workgroup/decisions/issues/49#issuecomment-2506777163%3E):

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

## Intended use

The ideal intended use of this macro is for new projects to define `Py_OMIT_LEGACY_API` globally (in compiler flags, or before `#include <Python.h>` in a common header), to avoid “footguns” in code that doesn’t (yet) have backwards compatibility concerns.

When a new CPython version omits more API, and it’s not feasible to update the code immediately, the macro can be safely removed. (Build systems may also be convinced to only set `Py_OMIT_LEGACY_API` on older Python versions.)

Projects concerned with “code quality” (ones that use linters and formatters despite the inevitable churn such tools cause) can also set `Py_OMIT_LEGACY_API` – either globally, or gradually per file.

If only a few files in a project use the problematic APIs, the macro can be set globally, and _un_defined per file (before the `#include <Python.h>`).

> [@savannahostrowski](#):
>
> Should they be distributing extensions with this defined, and if so, wouldn’t their source be less future proof, since it would fail to build much sooner on newer Python versions than would otherwise be the case?

This is similar as compiling with `-Werror`, or calling a linter/formatter as part of tests.  
If people can separate sdist build flags from CI flags, I would recommend that they use this in CI only. But I don’t think that’s common; it’s more realistic that the failures will be found in betas/RCs.

## Potential users

The floor is yours, people :‍)

I guess _I_ count as a potential user, too:  
If this gets in, my next goal will be to get the API to a state where if you define `Py_OMIT_LEGACY_API`, you won’t need to remember all the individual edge cases around borrowed or stolen references.  
I still spend too much effort in reviews double-checking refcount handling notes in docs. Victor (and others) spent a lot of time adding “predictable” variants of lots of functions; but they’re not that useful if I can’t ensure I’m not using the old ones.

---

<div class="post-metadata">

**Author:** ![hroncok](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/hroncok/32/18696_2.png) [@hroncok](https://discuss.python.org/u/hroncok)\
**Post date:** [January 22, 2026, 4:04pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/14 "2026-01-22T16:04:30Z")

</div>

I am a bit worried about this hypothetical situation:

1. A diligent developer who likes things nice opts in to define `Py_OMIT_LEGACY_API` in their project.
2. Time passes by, and more APIs are declared legacy in future Python versions.
3. The developer moves to greener pastures, is busy, or otherwise is not yet ready to omit the use of the APIs newly considered legacy or to remove the `Py_OMIT_LEGACY_API` definition from their code base.
4. Users pip-install the project on new Python. It fails to build.

Personally, as a redistributor\[1\], I can trivially sed/patch the definition away when this happens, yet I still worry that we might need to do that too often when we test builds with new alphas and betas. As a user, I would not be in such an easy position, especially if I install packages directly from PyPI (as I would guess most users do).

I would be much more relaxed if the proposal for intended use was to do something like `export CFLAGS=-DPy_OMIT_LEGACY_API ${CFLAGS:-}` on the CI, or on the developer’s personal machine.\[2\]

* * *

1. I co-maintain the Python stack in Fedora and handle the rebuilds for new Python versions. 

2. Of course, that does not give the ability to be file-specific about this ☹

---

<div class="post-metadata">

**Author:** ![vstinner](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/vstinner/32/15130_2.png) [@vstinner](https://discuss.python.org/u/vstinner)\
**Post date:** [January 22, 2026, 4:11pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/15 "2026-01-22T16:11:52Z")

</div>

> [@hroncok](#):
>
> I would be much more relaxed if the proposal for intended use was to do something like `export CFLAGS=-DPy_OMIT_LEGACY_API ${CFLAGS:-}` on the CI, or on the developer’s personal machine.

IMO that’s the intended usage of `Py_OMIT_LEGACY_API`: enable it on CI, not on `pip install`.

---

<div class="post-metadata">

**Author:** ![hroncok](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/hroncok/32/18696_2.png) [@hroncok](https://discuss.python.org/u/hroncok)\
**Post date:** [January 22, 2026, 8:14pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/16 "2026-01-22T20:14:26Z")

</div>

That was not entirely clear to me when I read the _Intended use_ reply by Petr. (And still isn’t, honestly.)

---

<div class="post-metadata">

**Author:** ![encukou](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/encukou/32/2461_2.png) [@encukou](https://discuss.python.org/u/encukou)\
**Post date:** [January 23, 2026, 7:43am UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/18 "2026-01-23T07:43:58Z")

</div>

Yeah, for _always_ enabling it, a versioned macro would be better.

For `Py_OMIT_LEGACY_API` you’d ideally have a separate lint-like build on the CI (where you can pin the Python version).  
I wonder if that’s worth the trouble for users, though.

---

<div class="post-metadata">

**Author:** ![steve.dower](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/steve.dower/32/56_2.png) [@steve.dower](https://discuss.python.org/u/steve.dower)\
**Post date:** [January 23, 2026, 10:46am UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/19 "2026-01-23T10:46:20Z")

</div>

> [@hroncok](#):
>
> That was not entirely clear to me when I read the _Intended use_ reply by Petr

That’s probably because I’ve been the one pushing that use, not Petr.

I don’t want to see arbitrary “warnings-as-errors” popping up on user installs, whether because a user is trying to install on a newer runtime,\[1\] or because we screwed up a version check in the headers.\[2\]

So this flag should not be set permanently or passed by default by build backends, but _may_ be passed for testing, at the same kind of time you’d request warnings-as-errors from your compiler.

Most build backends don’t have obvious options for this, and historically projects have used their own environment variables and `setup.py`s to inject these kinds of options. Right now, permanently setting options that impact “thorough CI testing” in the same way as “regular users who are trying to get a different (but transitively connected) job done” is the obvious choice.

But we’re _defining_ standards here, and for something completely new that doesn’t exist yet. It would be irresponsible for us to embed poor design decisions that impact our users just because doing something better might require tool developers to change things. So having rejected that constraint, I argued that a simple boolean “warn-as-error” flag best balances the complexity for everyone, and tooling developers may have to figure out a way to say “do a debug build” that isn’t permanently on by default.

* * *

1. In the case of `Py_OMIT_LEGACY_API` 

2. In the case of `Py_COMPAT_API_VERSION`

---

<div class="post-metadata">

**Author:** ![thomas](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/thomas/32/5492_2.png) [@thomas](https://discuss.python.org/u/thomas)\
**Post date:** [February 20, 2026, 10:49am UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/20 "2026-02-20T10:49:31Z")

</div>

The Steering Council has read and considered [PEP 743 (Add Py\_OMIT\_LEGACY\_API to the Python C API)](https://peps.python.org/pep-0743/), 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_API` in 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.

---

<div class="post-metadata">

**Author:** ![vstinner](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/vstinner/32/15130_2.png) [@vstinner](https://discuss.python.org/u/vstinner)\
**Post date:** [February 20, 2026, 12:29pm UTC](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323/21 "2026-02-20T12:29:19Z")

</div>

Ok, understood. Thanks for reviewing our PEP! Sure, there are other approaches to this problem such as a linter.

[Next page](https://discuss.python.org/t/pep-743-add-py-compat-api-version-to-the-python-c-api-take-2/59323.md?page=2)
