PEP 387 – 向后兼容性策略

抽象

此 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 版本终止支持后才会删除。

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

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

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