PEP 387 – 向后兼容性策略

猫勺猫勺 02-22 189 阅读 0 评论

抽象

PEP 概述了 Python 的向后兼容策略

理由

作为当今最常用的编程语言之一 , Python 核心语言及其标准库在 数以百万计的应用程序和库。这太棒了。然而,它 意味着开发团队必须非常小心,不要破坏这一点 具有新版本的现有第三方代码

该 PEP 认为“向后不兼容”意味着 预先存在的代码在更改后相对停止运行。是的 承认这不是一个具体的定义,而是期望 人们一般都明白是什么意思吗 “向后不兼容”,如果他们不确定,他们可能会问 Python 开发团队和/或指导委员会提供指导。

向后兼容规则

此策略适用于所有公共 API。这些包括:

引用定义的这些构造的语法和行为 手动。

The C-API.

函数、类、模块、属性和方法名称和类型。

给定一组参数,返回值、副作用和 函数的异常。这并不排除从 合理的错误修复。

参数和返回值的位置和预期类型。

类相对于子类的行为:下 调用了哪些重写的方法。

记录在案的异常和导致其引发的语义。

EAFP 方案中通常引发的异常。

其他的则明确不是公共 API 的一部分。他们可以更改或 随时以任何方式删除。这些包括:

函数、类、模块、属性、方法和 C-API 名称和 以“_”为前缀的类型(特殊名称除外)。

任何公开记录为私密的东西。 请注意,如果某些内容根本没有记录,则不会自动将其视为私有。

导入的模块(除非明确记录为公共的一部分 应用程序接口;例如,将模块导入 doesn't automatically mean 是公共 API 的一部分,除非 它被记录在案)。baconspamspam.bacon

内部类的继承模式。

测试套件。(目录或测试中的任何内容 软件包的子目录。Lib/test

向后兼容性规则不适用于以下任何模块或 API 根据 PEP 411 明确记录为临时。

向后兼容性的基本策略

一般来说,不相容性应该对 破损率,不相容性应易于解决 受影响的代码。例如,添加一个 stdlib 模块,具有相同的 名称作为第三方软件包通常是不可接受的。添加 与第三方代码冲突的方法或属性 然而,继承可能是合理的。

除非它正在经历下面的弃用过程,否则 API 的行为不得以不兼容的方式更改 在任意两个连续版本之间。Python 的年度发布 process (PEP 602) 表示弃用期必须持续到 至少两年。

同样,任何两个要素之间不能在没有通知的情况下删除要素 连续发布。

对于无法引发弃用警告的更改,请参阅 与指导委员会合作。

指导委员会可以批准此政策的例外情况。在 特别是,它们可能会缩短 特征。例外情况仅适用于极端情况,例如 危险损坏或不安全的功能或没有人可以的功能 合理地依赖于(例如,支持完全过时 平台)。

软弃用

当使用不应再使用的 API 时,可以使用软弃用 用于编写新代码,但继续使用它仍然是安全的 现有代码。API 仍会记录和测试,但不会 进一步发展(无增强)。

“软”和(常规)“硬”弃用之间的主要区别 是软弃用并不意味着计划删除 已弃用的 API。

另一个区别是软弃用不会发出警告: 它仅在文档中提到,而通常为“硬” 弃用在运行时发出警告。这 软弃用的文档应解释为什么 API 应该 避免,如果可能的话,建议更换。DeprecationWarning

如果决定弃用(在常规意义上)某个功能 当前是软弃用的,弃用必须遵循向后兼容性规则(即,没有例外,因为 该功能已被软弃用)。

进行不兼容的更改

进行不兼容的更改是一个渐进的过程,需要 多个版本:

讨论更改。根据不相容的程度, 这可以在 bug tracker、python-dev、python-list 或 适当的 SIG。可以编写 PEP 或类似文件。 希望受影响 API 的用户能够发表评论。

向当前分支添加警告。 如果行为发生变化,则 API 可能会获得新的 执行新行为的功能或方法;旧用法应 发出警告。如果要删除 API,只需发出警告 每当它被输入时。 是平常的 警告类别,但可能是 用于 API 的新旧版本将 共存于多个版本 。警告消息应 包括不兼容的版本,预计会成为 默认值和指向用户可以发布反馈的问题的链接。 如果可行,还可以更改 typeshed 以将装饰器(参见 PEP 702)添加到已弃用的 API 中, 这样静态类型检查器的用户就有了另一种学习方式 关于弃用。mainDeprecationWarningPendingDeprecationWarning@deprecated

对于 C API,宏生成的编译器警告 也是可以接受的。Py_DEPRECATED

等待警告出现在至少两个次要 Python 中 同一主要版本的版本,或旧版本中的一个次要版本 主要版本(例如,对于 Python 3.10.0 中的警告,您要么等待 直到至少 Python 3.12 或 Python 4.0 进行更改)。

等待两个以上的版本是可以的,例如:

如果预期的维护开销和安全风险 不推荐使用的行为很小(例如,旧函数被重新实现 就新的、更通用的而言),它可以无限期地保持 (或直到情况发生变化)。

如果已弃用的功能被新功能替换,则应 通常只有在没有新功能的最后一个 Python 版本终止支持后才会删除。

看看是否有任何反馈。未参与原件的用户 讨论可以在看到警告后立即发表评论。也许 考虑。

行为更改或功能删除现在可能成为默认行为,或者 达到声明版本的永久版本。删除旧的 版本和警告。

如果无法向用户提供警告,请咨询转向 理事会。


版权

本文档已置于公有领域。

The End 微信扫一扫

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

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

上一篇 下一篇

相关阅读

发表评论

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

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

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