PEP 387 – 向后兼容性策略
- 作者:
- Benjamin Peterson <benjamin at python.org>
- PEP 代表:
- Brett Cannon <brett at python.org>
- 状态:
- 活跃
- 类型:
- 流程
- 创建:
- 2009-06-18
- 更新历史:
- 2009-06-19, 2020-06-12, 2022-12-19, 2023-06-16
摘要
本 PEP 概述了 Python 的向后兼容性策略。
基本原理
作为当今使用最广泛的编程语言之一 [1]，Python 核心语言及其标准库在数百万个应用程序和库中发挥着至关重要的作用。这非常棒。但是，这意味着开发团队必须非常小心，不要在新版本中破坏现有的第三方代码。
本 PEP 认为“向后不兼容”意味着在更改后，预先存在的代码无法继续正常运行。我们承认这不是一个具体的定义，但人们普遍理解“向后不兼容”的含义，如果他们不确定，可以咨询 Python 开发团队和/或指导委员会以获得指导。
向后兼容性规则
此策略适用于所有公共 API。这些包括
- 参考手册中定义的这些构造的语法和行为。
- C-API。
- 函数、类、模块、属性和方法的名称和类型。
- 给定一组参数，函数的返回值、副作用和引发的异常。这并不排除来自合理错误修复的更改。
- 参数和返回值的位置和预期类型。
- 类关于子类的行为：覆盖方法被调用的条件。
- 已记录的异常以及导致其引发的语义。
- 在 EAFP 场景中通常引发的异常。
其他内容明确不属于公共 API 的一部分。它们可以随时以任何方式更改或删除。这些包括
- 以“_”为前缀的函数、类、模块、属性、方法和 C-API 名称和类型（特殊名称除外）。
- 任何公开记录为私有的内容。请注意，如果某件事根本没有记录，则不自动将其视为私有。
- 导入的模块（除非明确记录为公共 API 的一部分；例如，在
spam中导入bacon模块并不自动意味着spam.bacon是公共 API 的一部分，除非它被记录为这样）。 - 内部类的继承模式。
- 测试套件。（
Lib/test目录或包的测试子目录中的任何内容。） - 向后兼容性规则不适用于根据 PEP 411 明确记录为临时的任何模块或 API。
向后兼容性的基本策略
- 通常，不兼容性应该具有较高的收益与破坏比，并且不兼容性应该易于在受影响的代码中解决。例如，添加与第三方包同名的标准库模块通常是不可接受的。但是，添加通过继承与第三方代码冲突的方法或属性可能是合理的。
- 除非正在经历以下弃用流程，否则 API 的行为在任何两个连续版本之间不得以不兼容的方式更改。Python 的年度发布流程 (PEP 602) 意味着弃用期必须至少持续两年。
- 类似地，在任何两个连续版本之间，都不能在未经通知的情况下删除功能。
- 对于无法发出弃用警告的更改，请咨询指导委员会。
- 指导委员会可以对此策略授予例外。特别是，他们可以缩短功能所需的弃用期限。仅在极端情况下才会授予例外，例如危险的损坏或不安全的特性，或没有人可能依赖的特性（例如，对完全过时的平台的支持）。
软弃用
当使用不再应该用于编写新代码的 API 时，可以使用软弃用，但继续在现有代码中使用它仍然是安全的。API 仍然有文档和测试，但不会进一步开发（没有增强）。
“软”弃用和（常规的）“硬”弃用之间的主要区别在于，软弃用并不意味着要安排删除弃用的 API。
另一个区别是软弃用不会发出警告：它仅在文档中提及，而通常“硬”弃用在运行时会发出 DeprecationWarning 警告。软弃用的文档应解释为什么应避免使用该 API，如果可能，建议替换方案。
如果决定弃用（按常规方式）当前已软弃用的功能，则弃用必须遵循 向后兼容性规则（即，由于该功能已软弃用，因此没有例外）。
进行不兼容的更改
进行不兼容的更改是一个分阶段的过程，需要跨多个版本进行
- 讨论更改。根据不兼容程度，这可能在错误跟踪器、python-dev、python-list 或相应的 SIG 上进行。可以编写 PEP 或类似文档。希望受影响 API 的用户会发表评论。
- 在当前的
main分支中添加警告。如果行为正在更改，则 API 可能会获得一个新的函数或方法来执行新行为；旧用法应该引发警告。如果 API 即将被删除，则在每次进入时发出警告即可。DeprecationWarning是通常使用的警告类别，但在特殊情况下可以使用PendingDeprecationWarning，在这些情况下，API 的旧版本和新版本将在多个版本中共存 [2]。警告消息应包含不兼容性预计成为默认值的发行版本以及用户可以发布反馈的问题的链接。在可行的情况下，还应更改 typeshed 以添加@deprecated装饰器（请参阅 PEP 702）到弃用的 API，以便静态类型检查器的用户有另一种方法来了解弃用。对于 C API，由
Py_DEPRECATED宏生成的编译器警告也可以接受。 - 等待警告出现在至少两个相同主版本的 Python 次要版本中，或在较旧的主版本中的一个次要版本中（例如，对于 Python 3.10.0 中的警告，您要么等到至少 Python 3.12 或 Python 4.0 才能进行更改）。
等待超过两个版本是可以的，例如
- 如果弃用行为的预期维护开销和安全风险很小（例如，旧函数是用新的、更通用的函数重新实现的），它可以无限期地保留（或直到情况发生变化）。
- 如果弃用的功能被新功能取代，则通常应在最后一个没有新功能的 Python 版本达到支持结束时才将其删除。
- 查看是否有任何反馈。在看到警告后，最初未参与讨论的用户现在可能会发表评论。也许可以重新考虑。
- 在达到声明的版本后，可以将行为更改或功能删除设置为默认值或永久值。删除旧版本和警告。
- 如果无法向用户提供警告，请咨询指导委员会。
变更日志
- 2023-11-14：根据 PEP 702 添加了
@deprecated装饰器。 - 2023-07-03：添加了软弃用部分，如 https://discuss.python.org/t/27957 中所讨论的那样。
- 2023-06-26：多个较小的更新和澄清，如 https://discuss.python.org/t/22042 中所讨论的那样。
- 2022-04-04：添加了在几个例外情况下要求咨询指导委员会的明确说明。
- 2021-04-16：阐明了在进行更改之前必须发出警告多长时间。
- 2020-07-20：初始接受版本。
参考文献
版权声明
此文档已置于公共领域。
来源：https://github.com/python/peps/blob/main/peps/pep-0387.rst