• 第二章 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

  • 相关阅读:
    react 安装教程
    4.cuBLAS开发指南中文版--CUDA 数据类型引用
    【计算机视觉】哈里斯角点检测 Harris Corner Detection
    python使用numpy中的equal函数比较两个numpy数组中每个位置的元素是否相同、并计算相同元素的比例
    216. 组合总和 III
    IOS工程:如何在apple后台为app添加沙盒测试账户
    异步编程概览
    PPT录屏怎么录?PPT录屏,3种方法简单操作
    flink sql 毫秒转date ms转date
    基于java的滑雪场学具租赁管理系统计算机毕业设计源码+系统+lw文档+mysql数据库+调试部署
  • 原文地址:https://blog.csdn.net/ekcchina/article/details/125619313