Python warnings.deprecated怎样标记即将移除的API

维护公共 Python 模块时，最怕的不是删除旧函数，而是调用方完全不知道它什么时候该迁移。Python 的 warnings.deprecated 把这件事拆成两个可消费的信号：运行时可以发出 DeprecationWarning，静态类型检查器也可以在调用旧 API 时给出诊断。

官方文档：https://docs.python.org/3.14/library/warnings.html#warnings.deprecated

本文只讲标准库装饰器的声明方式、运行时参数、重载边界和兼容判断，不把它当成全项目迁移扫描器。

先把弃用信息写在旧 API 旁边

deprecated() 的第一个参数是必填的字符串消息，最好同时写出替代 API 和计划移除版本。这样类型检查器展示提示时，调用方不用再翻项目文档。

from warnings import deprecated

@deprecated("Use fetch_user_v2 instead; remove after 3.0")
def fetch_user(user_id: int) -> dict[str, object]:
    # 旧入口暂时保留，把迁移方向写进弃用消息。
    return fetch_user_v2(user_id)

def fetch_user_v2(user_id: int) -> dict[str, object]:
    # 新入口承接后续参数和返回值设计。
    return {"id": user_id}

这个装饰器可以用于函数、类或方法。它不会替你改写调用方，也不会自动删除旧实现；它做的是给旧对象加上统一的弃用契约。消息内容应保持稳定，避免把临时排障信息写进去。

category 和 stacklevel 只控制运行时警告

默认情况下，使用被标记的函数会发出 DeprecationWarning；类则在实例化或创建子类时触发。category=None 可以关闭运行时警告，但不会关闭静态类型检查器的弃用诊断。stacklevel 决定警告指向调用栈的哪一层，公共库通常希望调用方看到自己的代码位置。

from warnings import deprecated

@deprecated(
    "Use read_config_v2 instead",
    category=DeprecationWarning,
    stacklevel=2,
)
def read_config(path: str) -> dict[str, str]:
    # stacklevel=2 让警告位置更接近直接调用方。
    return read_config_v2(path)

@deprecated("仅保留给旧类型检查配置", category=None)
def legacy_type_hook() -> None:
    # category=None 不发运行时警告，但仍保留静态弃用标记。
    pass

要注意，运行时警告还会受到 Python 的 warning filter 影响。生产进程可能默认忽略某些 DeprecationWarning，所以不能把“没有看到 stderr 输出”当成“没有弃用契约”。如果要在测试中主动暴露这类问题，应在测试入口配置合适的 warning filter。

overload 应该标记哪一层

如果只有某一种参数签名要被移除，应只标记对应的 overload；如果整个函数都要移除，才标记实现对应的整体 API。官方规则要求在单个重载上把 @deprecated 放在 @overload 下面，也就是先写 @overload，再写 @deprecated。

from typing import overload
from warnings import deprecated

@overload
@deprecated("int 参数将在 3.0 移除，请改用 str")
def parse_id(value: int) -> str: ...

@overload
def parse_id(value: str) -> str: ...

def parse_id(value: int | str) -> str:
    # 实现函数保留两种签名，迁移提示只针对 int overload。
    return str(value)

这样，类型检查器可以只对 parse_id(10) 给出弃用诊断，而 parse_id("10") 继续保持正常。category 和 stacklevel 影响运行时行为，不会改变静态诊断本身。

用 __deprecated__ 给文档或适配层读取消息

装饰器传入的消息会保存到被装饰对象的 __deprecated__ 属性。它适合让内部文档生成器或适配层读取人类可读的迁移提示，但不要把这个属性当作完整的版本策略数据库：移除版本、替代 API 和兼容期限仍应由项目自己的发布说明维护。

from warnings import deprecated

@deprecated("Use export_json instead")
def export_dict(data: dict[str, object]) -> str:
    # 旧函数仍然可以调用，元数据用于展示迁移提示。
    return export_json(data)

message = getattr(export_dict, "__deprecated__", None)
if message is not None:
    # 读取属性前先判断，避免普通函数没有该属性时抛出异常。
    print(f"迁移提示：{message}")

对重载来说，如果要从 typing.get_overloads() 取得对应的弃用消息，装饰器顺序尤其重要；顺序写反可能导致重载对象上没有预期的元数据。

Python 版本兼容时先确认导入边界

warnings.deprecated 是 Python 3.13 引入的标准库能力。项目仍支持更早版本时，不能无条件导入它，否则旧解释器会在模块加载阶段失败。兼容策略可以是提高最低 Python 版本、把弃用标记放进仅供新版本加载的模块，或者为旧版本保留不依赖该装饰器的实现；不要把一个只会发运行时 warning 的自定义装饰器误称为等价替代，因为静态类型检查能力并不会自动出现。

import sys

if sys.version_info >= (3, 13):
    from warnings import deprecated
else:
    def deprecated(message: str, /, **_options):
        # 旧版本兜底只保持装饰器可导入，不伪造静态检查器能力。
        def decorate(obj):
            # 保留消息属性，便于文档层读取迁移提示。
            obj.__deprecated__ = message
            return obj
        return decorate

如果项目需要真正的跨版本静态诊断，应把类型检查器、stub 或兼容依赖的选择单独写入开发工具配置，并在发布说明里明确支持范围。标准库文档只保证 Python 3.13 及之后提供 warnings.deprecated。

把弃用标记接入发布流程

一条实用的维护规则是：新 API 合并时给旧入口加上稳定消息；测试环境把弃用警告设为可见；类型检查阶段关注调用方诊断；真正移除前再检查替代 API 是否覆盖旧用法。四个环节分别消费运行时信号、静态信号和项目自己的迁移记录，不能用其中一个代替全部流程。

常见问题

warnings.deprecated 会自动抛异常吗？

默认是发出弃用警告，不是直接抛出异常；如果 warning filter 把对应类别设置为 error，才会按过滤规则转成异常。

category=None 会让类型检查器忽略 API 吗？

不会。它只关闭运行时警告，静态类型检查器仍可根据弃用标记给出诊断。

普通函数和 overload 都要标记吗？

只淘汰一个参数形态时标记对应 overload；整个公共函数都要迁移时，再考虑标记整体 API。

把 warnings.deprecated 当成“迁移契约声明”最容易用对：消息负责告诉调用方往哪里走，运行时参数负责控制警告落点，类型检查器负责尽早暴露调用位置，而版本兼容和最终移除仍然属于项目发布流程。