Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python Enhancement Proposals

PEP 387 – Backwards Compatibility Policy

Author:
Benjamin Peterson <benjamin at python.org>
PEP-Delegate:
Brett Cannon <brett at python.org>
Discussions-To:
Discourse thread
Status:
Active
Type:
Process
Created:
18-Jun-2009
Post-History:
19-Jun-2009, 12-Jun-2020

Table of Contents

摘要

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

理论依据

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

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

向后兼容规则

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

  • 参考手册中定义的这些结构的语法和行为。
  • C API。
  • 函数、类、模块、属性和方法的名称和类型。
  • 给定一组参数,一个函数的返回值、副作用和引发的异常。这并不排除合理的错误修复带来的变化。
  • 参数和返回值的位置和预期类型。
  • 类对子类的行为:重载方法被调用的条件。
  • 被记录的异常和导致其产生的语义。
  • 在 EAFP 方案中经常提出的例外情况。

其他的是明确地不属于公共 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.
  • 指导委员会可以批准这一政策的例外情况。特别是,他们可以缩短一个功能所需的废弃期。只有在极端的情况下才会批准例外,如危险的破损或不安全的功能或没有人可以合理地依赖的功能(例如,对完全过时的平台的支持)。

进行不兼容的修改

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

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

参考


Source: https://github.com/python/peps/blob/main/pep-0387.txt

Last modified: 2022-04-20 09:53:08 GMT