PEP 743 – 向 Python C API 添加Py_COMPAT_API_VERSION

猫勺猫勺 04-19 129 阅读 0 评论

抽象

添加和宏 选择加入 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()

向后兼容性

对向后兼容性没有影响。

添加 和 宏对向后兼容性没有影响。仅开发人员设置 他们项目中的宏将受到以下因素的影响 此宏的影响,这是预期行为。Py_COMPAT_API_VERSIONPy_COMPAT_API_VERSION_MAXPy_COMPAT_API_VERSION

现有技术

Py_LIMITED_APIPEP 384“定义稳定的 ABI”的宏。

版权

文档位于公共领域或 CC0-1.0-通用许可证,以更宽松者为准。

The End 微信扫一扫

文章声明:以上内容(如有图片或视频在内)除非注明,否则均为腾龙猫勺儿原创文章,转载或复制请以超链接形式并注明出处。

本文作者:猫勺本文链接:https://www.jo6.cn/post/84.html

上一篇 下一篇

相关阅读

发表评论

访客 访客
快捷回复: 表情:
评论列表 (暂无评论,129人围观)

还没有评论,来说两句吧...

取消
微信二维码
微信二维码
支付宝二维码