Python 的 C 语言 API 包含于向下兼容政策 PEP 387 中。C API 会跟随小版本的发布而发生变化(比如 3.9 到3.10 的时候),不过大多数变化都是源代码级兼容的,通常只会增加新的 API。已有 API 的修改或删除,只有在废止期过后或修复严重问题时才会进行。
CPython 的应用二进制接口(ABI)可以跨小版本实现前后兼容(只要以同样方式编译;参见下面的PlatformConsiderations )。因此,用 Python 3.10.0 编译的代码可以在 3.10.8 上运行,反之亦然,但针对 3.9.x 和 3.10.x则需分别进行编译。
带下划线前缀的是私有 API,如 _Py_InternalState,即便是补丁发布版本中也可能不加通知地进行改动。
Python3.2引入了有限的API,这是Python的CAPI的一个子集。只使用有限的API的扩展可以编译一次,并与多个版本的Python一起工作。有限的API的内容如下。
为了实现这一点,Python提供了一个稳定的ABI:一组将与Python3保持兼容的符号。x版本。稳定的ABI包含在有限的API中公开的符号,但也包含其他符号——例如,支持有限的API的旧版本所必需的函数。
(为了简单起见,本文档讨论了扩展,但是有限的API和稳定的ABI对于API的所有使用都是相同的——例如,嵌入Python。)
Python.h
Py_LIMITED_API
PY_VERSION_HEX0x030A0000
Py_LIMITED_API30x03020000
在 Windows 上,应链接使用稳定 ABI 的扩展,而不是特定于版本的库,例如 .python3.dllpython39.dll
在某些平台上,Python会查找并加载以标记命名的共享库文件(例如)。它不会检查此类扩展是否符合稳定 ABI。用户(或其打包工具)需要确保,例如,使用3.10 +Limited API构建的扩展不会为较低版本的Python安装。abi3mymodule.abi3.so
Stable ABI中的所有函数都作为Python共享库中的函数存在,而不仅仅是宏。这使得它们可用于不使用 C 预处理器的语言。
Limited API 的目标是允许使用完整的 C API 实现所有可能的功能,但可能会降低性能。
例如,虽然PyList_GetItem()
可用,但其“不安全”的宏变体 PyList_GET_ITEM()
不可用。宏可以更快,因为它可以依赖于列表对象的特定于版本的实现详细信息。
如果没有定义,某些 C API 函数将内联或由宏替换。定义会禁用此内联,从而在改进Python的数据结构时允许稳定性,但可能会降低性能。Py_LIMITED_APIPy_LIMITED_API
通过省略定义,可以使用特定于版本的 ABI 编译受限 API 扩展。这可以提高该Python版本的性能,但会限制兼容性。然后,编译将产生一个扩展,该扩展可以在没有特定于版本的扩展可用的情况下分发 - 例如,用于即将推出的Python版本的预发布。Py_LIMITED_APIPy_LIMITED_API
请注意,编译并不能完全保证代码符合受限 API 或稳定 ABI。 仅涵盖定义,但 API 还包括其他问题,例如预期语义。Py_LIMITED_APIPy_LIMITED_API
一个不能防范的问题是调用具有在较低Python版本中无效的参数的函数。例如,考虑一个开始接受参数的函数。在 Python 3.9 中,现在选择默认行为,但在 Python 3.8 中,参数将直接使用,从而导致取消引用和崩溃。类似的参数适用于结构字段。Py_LIMITED_APINULLNULLNULL
另一个问题是,某些结构字段在定义时当前未隐藏,即使它们是受限 API 的一部分。Py_LIMITED_API
出于这些原因,我们建议使用它支持的所有次要Python版本测试扩展,并且最好使用最低的此类版本进行构建。
我们还建议查看所有已用 API 的文档,以检查它是否明确属于受限 API 的一部分。即使定义了,一些私有声明也会由于技术原因(甚至无意中作为错误)而公开。Py_LIMITED_API
另请注意,Limited API不一定稳定:使用Python 3.8编译意味着扩展将使用Python 3.12运行,但不一定使用Python 3.12编译。特别是,如果稳定 ABI 保持稳定,则可能会弃用和删除受限 API 的某些部分。Py_LIMITED_API
ABI的稳定性不仅取决于Python,还取决于所使用的编译器,低级库和编译器选项。出于稳定 ABI 的目的,这些细节定义了一个“平台”。它们通常取决于操作系统类型和处理器体系结构
每个特定的Python分发者都有责任确保特定平台上的所有Python版本都是以不破坏稳定ABI的方式构建的。来自Windows和macOS版本以及许多第三方分销商就是这种情况。python.org
目前,有限的API包括以下项目:【腾讯文档】有限API的内容
https://docs.qq.com/doc/DSUVIbmxrVVprZmhD