摘要

本 PEP 增加了一个 @warnings.deprecated() 装饰器，用于将类或函数标记为已弃用，使静态检查器能够在其被使用时发出警告。默认情况下，此装饰器还将在运行时引发 DeprecationWarning。

动机

随着软件的发展，新的功能被添加，旧的功能变得过时。库开发人员希望致力于移除过时的代码，同时给用户时间迁移到新的 API。Python 提供了一种实现这些目标的机制：DeprecationWarning 警告类，用于在使用已弃用功能时显示警告。此机制被广泛使用：截至本 PEP 编写时，CPython 主分支包含大约 150 条不同的代码路径会引发 DeprecationWarning。许多第三方库也使用 DeprecationWarning 来标记弃用。在PyPI 排名前 5000 的软件包中，有

• 1911 个匹配正则表达式 warnings\.warn.*\bDeprecationWarning\b，表示使用了 DeprecationWarning（不包括警告拆分为多行的情况）；
• 1661 个匹配正则表达式 ^\s*@deprecated，表示使用了某种弃用装饰器。

然而，目前的机制通常不足以确保已弃用功能的用户及时更新其代码。例如，移除各种长期弃用的 unittest 功能不得不回滚到 Python 3.11，以给用户更多时间更新代码。用户可能出于实际原因禁用警告来运行其测试套件，或者弃用可能在未被测试覆盖的代码路径中触发。

提供更多方法让用户了解已弃用功能可以加快迁移过程。本 PEP 建议利用静态类型检查器向用户传达弃用信息。此类检查器对用户代码有透彻的语义理解，使它们能够检测并报告单个 grep 调用无法找到的许多弃用。此外，许多类型检查器与 IDE 集成，使用户可以直接在编辑器中看到弃用警告。

基本原理

乍一看，弃用似乎不是类型检查器应该触及的话题。毕竟，类型检查器关注的是检查代码是否按原样工作，而不是潜在的未来更改。然而，类型检查器对代码执行的分析以查找类型错误与检测许多弃用所需的分析非常相似。因此，类型检查器非常适合查找和报告弃用。

其他语言已经有类似的功能

• GCC 支持在函数声明上使用 deprecated 属性。这驱动了 CPython 的 Py_DEPRECATED 宏。
• GraphQL 支持将字段标记为 @deprecated。
• Kotlin 支持 Deprecated 注解。
• Scala 支持 @deprecated 注解。
• Swift 支持使用 @available 属性将 API 标记为已弃用。
• TypeScript 使用 @deprecated JSDoc 标签来发出提示，标记已弃用功能的使用。

几位用户已请求支持此类功能

• typing-sig 讨论串
• Pyright 功能请求
• mypy 功能请求

存在类似的现有第三方工具

• Deprecated 提供了一个装饰器，用于将类、函数或方法标记为已弃用。访问已装饰对象会引发运行时警告，但不会被类型检查器检测到。
• flake8-deprecated 是一个 linter 插件，用于警告已弃用功能的使用。然而，它仅限于一个简短、硬编码的弃用列表。

规范

warnings 模块中添加了一个新的装饰器 @deprecated()。此装饰器可用于类、函数或方法，以将其标记为已弃用。这包括 typing.TypedDict 和 typing.NamedTuple 定义。对于重载函数，装饰器可以应用于单个重载，表示特定的重载已弃用。装饰器也可以应用于重载实现函数，表示整个函数已弃用。

装饰器接受以下参数

• 一个必需的仅限位置参数，表示弃用消息。
• 两个仅限关键字参数 category 和 stacklevel，用于控制运行时行为（参见下面的“运行时行为”）。

仅限位置参数的类型是 str，它包含在类型检查器遇到已装饰对象的用法时应显示的消。工具可以清理弃用消息以进行显示，例如使用 inspect.cleandoc() 或等效逻辑。消息必须是字符串文字。弃用消息的内容由用户决定，但可以包括已弃用对象将被移除的版本，以及有关建议的替换 API 的信息。

类型检查器在遇到标记为已弃用的对象的用法时应生成诊断。对于已弃用的重载，这包括所有解析为已弃用重载的调用。对于已弃用的类和函数，这包括

• 通过模块、类或实例属性的引用（module.deprecated_object、module.SomeClass.deprecated_method、module.SomeClass().deprecated_method）
• 在其定义模块中对已弃用对象的任何使用（module.py 中的 x = deprecated_object()）
• 如果使用 import *，则使用模块中的已弃用对象（from module import *; x = deprecated_object()）
• from 导入（from module import deprecated_object）
• 任何间接触发函数调用的语法。例如，如果类 C 的 __add__ 方法已弃用，则代码 C() + C() 应触发诊断。类似地，如果属性的 setter 被标记为已弃用，则尝试设置属性应触发诊断。

如果方法使用来自 PEP 698 的 typing.override() 装饰器标记，并且它覆盖的基类方法已弃用，则类型检查器应生成诊断。

还有其他场景中可能涉及弃用。例如，一个对象可能实现一个 typing.Protocol，但协议合规性所需的方法之一已弃用。由于此类场景看起来复杂且在实践中相对不太可能出现，因此本 PEP 不强制类型检查器检测它们。

from warnings import deprecated

@deprecated("Use Spam instead")
class Ham: ...

@deprecated("It is pining for the fiords")
def norwegian_blue(x: int) -> int: ...

@overload
@deprecated("Only str will be allowed")
def foo(x: int) -> str: ...
@overload
def foo(x: str) -> str: ...

class Spam:
    @deprecated("There is enough spam in the world")
    def __add__(self, other: object) -> object: ...

    @property
    @deprecated("All spam will be equally greasy")
    def greasy(self) -> float: ...

    @property
    def shape(self) -> str: ...
    @shape.setter
    @deprecated("Shapes are becoming immutable")
    def shape(self, value: str) -> None: ...

from library import Ham  # error: Use of deprecated class Ham. Use Spam instead.

import library

library.norwegian_blue(1)  # error: Use of deprecated function norwegian_blue. It is pining for the fiords.
map(library.norwegian_blue, [1, 2, 3])  # error: Use of deprecated function norwegian_blue. It is pining for the fiords.

library.foo(1)  # error: Use of deprecated overload for foo. Only str will be allowed.
library.foo("x")  # no error

ham = Ham()  # no error (already reported above)

spam = library.Spam()
spam + 1  # error: Use of deprecated method Spam.__add__. There is enough spam in the world.
spam.greasy  # error: Use of deprecated property Spam.greasy. All spam will be equally greasy.
spam.shape  # no error
spam.shape = "cube"  # error: Use of deprecated property setter Spam.shape. Shapes are becoming immutable.

向后兼容性

创建新的装饰器不会带来向后兼容性问题。与所有新的类型功能一样，@deprecated 装饰器将添加到 typing_extensions 模块中，使其能够在旧版本的 Python 中使用。

如何教授

对于在 IDE 或类型检查器输出中遇到弃用警告的用户，他们收到的消息应该清晰明了。使用 @deprecated 装饰器将是一个高级功能，主要与库作者相关。装饰器应在相关文档中提及（例如，PEP 387 和 DeprecationWarning 文档），作为标记已弃用功能的额外方式。

参考实现

typing-extensions 库自 4.5.0 版本起提供了 @deprecated 装饰器的运行时实现。pyanalyze 类型检查器提供了发出弃用错误的原型支持，Pyright 也提供类似支持。

被拒绝的想法

致谢

与 typing-sig 聚会小组的通话为该提案提供了有用的反馈。

版权

本文档置于公共领域或 CC0-1.0-Universal 许可证下，以更宽松者为准。