第二章 C API稳定性

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。)

• Py_LIMITED_API
  在选择仅使用受限 API 并选择受限 API 版本之前，请先定义此宏。Python.h
  定义为与扩展支持的最低 Python 版本相对应的 PY_VERSION_HEX的值。从指定版本开始，该扩展无需重新编译所有Python 3版本即可工作，并且可以使用该版本之前引入的有限API。Py_LIMITED_API
  与其直接使用宏，不如对最小次要版本进行硬编码（例如 对于 Python 3.10），以便在编译未来的 Python 版本时保持稳定。PY_VERSION_HEX0x030A0000
  也可以将 定义为 。这与（Python 3.2，引入Limited API的版本）的工作方式相同。Py_LIMITED_API30x03020000

在 Windows 上，应链接使用稳定 ABI 的扩展，而不是特定于版本的库，例如 .python3.dllpython39.dll

在某些平台上，Python会查找并加载以标记命名的共享库文件（例如）。它不会检查此类扩展是否符合稳定 ABI。用户（或其打包工具）需要确保，例如，使用3.10 +Limited API构建的扩展不会为较低版本的Python安装。abi3mymodule.abi3.so

Stable ABI中的所有函数都作为Python共享库中的函数存在，而不仅仅是宏。这使得它们可用于不使用 C 预处理器的语言。

有限的API范围和性能

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警告

请注意，编译并不能完全保证代码符合受限 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包括以下项目:【腾讯文档】有限API的内容
https://docs.qq.com/doc/DSUVIbmxrVVprZmhD