PEP 743 – 向 Python C API 添加Py_COMPAT_API_VERSION

抽象

添加和宏选择加入 C 扩展中计划中的不兼容 C API 更改。维护者可以决定何时使他们的 C 扩展兼容并决定他们希望兼容哪个未来的 Python 版本跟。Py_COMPAT_API_VERSIONPy_COMPAT_API_VERSION_MAX

理由

Python 版本强制执行 C API 更改

每个 Python 3.x 版本都有一长串 C API 更改，包括不兼容的更改。C 扩展必须更新才能在新发布的 Python。

一些不兼容的更改是由新功能驱动的：它们不能避免，除非我们决定不添加这些功能。其他原因：

删除已弃用的 API（请参阅 PEP 387）。
简化另一项更改的实施。
更改或删除容易出错的 API。

目前，在“不更改 C API”和 “不兼容的 C API 更改会影响每个人”。C 扩展是更新或无法使用新的 Python 版本。这样的全有或全无 deal 既不能满足 C 扩展维护者，也不能满足 C 扩展用户。

有限的 C API

受限的 C API 是版本控制的：可以设置宏更改为 Python 版本以选择可用的 API。在 Python 上另一方面，它允许在特定版本中引入不兼容的更改。例如，if 设置为 Python 3.11 或更高版本，不再包含在中，而面向 Python 3.10 的 C 扩展则不包含影响。Py_LIMITED_APIPy_LIMITED_APIPy_LIMITED_API<stdio.h>Python.h

这里的区别在于，升级 Python 不会改变是否包含，但更新会改变。更新是 C 故意采取的行动扩展维护者。它提供了更多的自由来决定何时维护者已准备好处理最新一批不兼容的变化。<stdio.h>Py_LIMITED_APIPy_LIMITED_API

类似的版本可以与常规（非限制）C API 一起使用。

弃用和编译器警告

已弃用的函数标有。使用已弃用的函数发出编译器警告。Py_DEPRECATED()

问题是，工具隐藏编译器日志默认值，除非生成失败。此外，很容易错过一个在数百行日志中间发出警告。pipbuild

计划变更

目前，无法安排 C API 更改：宣布它，但还为维护者提供了一种使用改变。要么不进行更改，要么每个人都必须更新他们的代码如果他们想更新 Python。

规范

新宏

添加新宏和宏。可以将它们设置为测试是否为将来准备了 C 扩展 C API 更改：与未来的 Python 版本兼容。Py_COMPAT_API_VERSIONPy_COMPAT_API_VERSION_MAX

该宏可以设置为特定的 Python 版本。例如，测试 C API 在 Python 3.14 中计划更改。Py_COMPAT_API_VERSIONPy_COMPAT_API_VERSION=0x030e0000

如果宏设置为，则在下测试所有计划的 C API 更改一次。Py_COMPAT_API_VERSIONPy_COMPAT_API_VERSION_MAX

如果未设置宏，则默认为。Py_COMPAT_API_VERSIONPY_VERSION_HEX

该宏可以在单个 C 文件中设置，也可以用于编译器标志中的整个项目。宏不影响其他项目或 Python 本身。Py_COMPAT_API_VERSION

Python 中的示例

例如，函数是在 Python 3.13 中已弃用，并计划在 Python 3.15 中移除。这函数可以在 Python C API 中使用以下内容声明声明：PyImport_ImportModuleNoBlock()

#if Py_COMPAT_API_VERSION < 0x030f0000
Py_DEPRECATED(3.13) PyAPI_FUNC(PyObject *) PyImport_ImportModuleNoBlock( 
   const char *name            /* UTF-8 encoded string */    
   );
#endif

如果等于或大于 Python 3.15 （），函数不是声明，因此使用它失败并出现生成错误。if Py_COMPAT_API_VERSION0x030f0000PyImport_ImportModuleNoBlock()

目标

减少影响 C 扩展的 C API 更改次数更新 Python。
测试 C 扩展（例如，可选的 CI 测试）时，可以设置为检测将来的不兼容性。对于强制性测试，它是建议设置为特定的 Python 版本。Py_COMPAT_API_VERSIONPy_COMPAT_API_VERSION_MAXPy_COMPAT_API_VERSION
对于核心开发人员，请确保 C API 仍然可以发展而不用担心破坏未知数量的 C 扩展。

非目标

永久冻结 API：这不是稳定的 ABI。例如已弃用的函数将继续定期删除。
C 扩展维护者不使用 will 更新 Python 时仍会受到 C API 更改的影响。Py_COMPAT_API_VERSION
提供稳定的 ABI：宏只影响常规（非限制）应用程序接口。
解决所有 C API 问题的灵丹妙药。

用法示例

删除已弃用的函数。
删除已弃用的结构成员，例如 .PyBytesObject.ob_shash
删除标准，例如，从。#include#include <string.h><Python.h>
更改函数或宏的行为。例如，调用可能会失败，以强制使用的函数，以删除属性。PyObject_SetAttr(obj, name, NULL)PyObject_DelAttr()