PEP 387 – Backwards Compatibility Policy

Table of Contents

摘要

这个 PEP 概述了 Python 的向后兼容政策。

作为当今使用最多的编程语言之一 [1]，Python 核心语言及其标准库在数以百万计的应用程序和库中发挥了关键作用。然而，这意味着开发团队必须非常小心，不要用新版本破坏这些现有的第三方代码。

这个 PEP 采取的观点是：“向后不兼容” 是指预先存在的代码在改变后不再具有相对的功能。我们承认这不是一个具体的定义，但我们希望人们能够普遍理解 “向后不兼容” 的含义，如果他们不确定，可以向 Python 开发团队和/或指导委员会寻求指导。

该政策适用于所有公共 API。这些包括：

其他的是明确地不属于公共 API 的一部分。它们可以在任何时候以任何方式改变或被删除。这些包括：

函数、类、模块、属性、方法和 C-API 的名称和类型，其前缀为 “_”。（特殊名称除外）。
任何公开记录的东西都是私人的。
导入的模块（除非明确记录为公共 API 的一部分；例如，在 spam 中导入 bacon 模块并不自动意味着 spam.bacon 是公共 API 的一部分，除非它被记录下来）。
内部类的继承模式。
测试套件。（任何在 Lib/test 目录下或软件包的测试包的子目录。）
Backward compatibility rules do not apply to any module or API that is explicitly documented as Provisional per PEP 411.

一般来说，不兼容应该有一个很大的利益与破坏的比率，而且不兼容应该在受影响的代码中容易解决。例如，添加一个与第三方软件包同名的stdlib模块通常是不被接受的。然而，添加一个通过继承与第三方代码相冲突的方法或属性，可能是合理的。
除非它正在经历下面的废弃过程，否则一个 API 的行为必须在任何两个连续的版本之间不以不兼容的方式改变。Python 的年度发布过程（PEP 602）意味着废弃期必须至少持续两年。
同样，在任何两个连续的版本之间，不能在没有通知的情况下删除一项功能。
For changes that are unable to raise a deprecation warning, consult with the steering council.
指导委员会可以批准这一政策的例外情况。特别是，他们可以缩短一个功能所需的废弃期。只有在极端的情况下才会批准例外，如危险的破损或不安全的功能或没有人可以合理地依赖的功能（例如，对完全过时的平台的支持）。

做一个不兼容的改变是一个渐进的过程，在几个版本中执行：

讨论一下这个变化。根据不兼容的程度，这可以在 bug 追踪器、python-dev、python-list 或适当的 SIG 上进行。希望受影响的 API 的用户能够发表意见。
增加一个警告。如果行为正在改变，API 可能会获得一个新的函数或方法来执行新的行为；旧的用法应该引起警告。如果一个 API 正在被删除，只要在它被输入时发出警告即可。DeprecationWarning 是通常使用的警告类别，但 PendingDeprecationWarning 可用于特殊情况，即 API 的新旧版本将共存于许多版本 [2]。编译器警告也是可以接受的。警告信息应该包括不兼容的版本预计将成为默认的版本，以及一个用户可以发布反馈的问题链接。
等待警告出现在同一大版本的至少两个 Python 小版本中，或者在更早的大版本中的一个小版本中（例如，对于 Python 3.10 中的警告，你要么等到至少 Python 3.12，要么等到 Python 4.0 来做改变）。等待两个以上的版本也是可以的。
看看是否有任何反馈。没有参与原始讨论的用户在看到警告后现在可以发表评论。也许会重新考虑。
行为改变或功能删除现在可以成为默认的或永久的，已经达到声明的版本。删除旧版本和警告。
If a warning cannot be provided to users, consult with the steering council.

本文件已被置于公共领域。