最直接重构时用 warnings.warn() 发出弃用警告需指定 category=deprecationwarning 和 stacklevel=2，并在函数体内而非模块顶层触发，确保警告指向调用处、可见且推动整改。
用 warnings.warn() 发出弃用警告最直接
重构时想让调用方知道某个函数或类即将下线，warnings.warn() 是标准做法。它不会中断执行，但能在控制台、日志或测试中清晰暴露问题。
关键不是“要不要发”，而是“怎么发才不被忽略”。默认的 DeprecationWarning 在命令行和脚本里常被静默过滤——这是最常踩的坑。
- 必须显式指定
category=DeprecationWarning，否则可能被当成UserWarning降级处理 - 加上
stacklevel=2，让警告指向调用位置，而不是封装警告的内部函数 - 消息里写明替代方案，比如 “Use
new_function()instead”
import warnings <p>def old_api(x): warnings.warn( "old_api() is deprecated, use new_api() instead", category=DeprecationWarning, stacklevel=2 ) return x * 2</p>
让弃用警告在终端/IDE里真正可见
Python 默认屏蔽 DeprecationWarning，除非你是在交互式环境（如 IPython）或用 -W default 启动解释器。用户跑脚本时根本看不到。
有三个实际可行的解法：
- 开发阶段加启动参数：
python -W default script.py—— 适合 CI 或本地调试 - 在代码开头临时启用：
warnings.simplefilter("default", DeprecationWarning)—— 注意别提交到生产代码 - 配合 pytest：加
--error=DeprecationWarning让测试直接失败，倒逼清理
区分 DeprecationWarning 和 PendingDeprecationWarning
这两个不是随意选的：DeprecationWarning 表示“现在就该改”，而 PendingDeprecationWarning 是“下个大版本才删”，语义差很多。
重构期间多数情况属于前者。如果提前半年预告，又不想立刻打扰用户，才考虑后者；但要注意它的默认行为更隐蔽——连 -W default 都不一定触发，得用 -W once::PendingDeprecationWarning 才行。
-
DeprecationWarning：当前版本已不推荐，后续版本大概率移除 -
PendingDeprecationWarning：尚未移除，但已有明确移除计划（如 Python 自身对某些内置函数的标记） - 不要混用：把
PendingDeprecationWarning当成“软提醒”用，容易让用户拖到最后一刻才改
避免在模块顶层触发警告导致导入失败
有人把 warnings.warn() 放在模块最外层，结果一 import 就报警——这会让依赖该模块的其他项目在导入时就被打断，尤其在自动化构建或类型检查（如 mypy）场景下很恼人。
- 警告必须放在实际执行路径里，比如函数体、方法内、或
if分支中 - 如果要标记整个类弃用，可在
__init__或常用方法里 warn，而不是在 class 定义后立刻 warn - 切忌在
__all__或__getattr__里动态 warn——那会污染属性访问逻辑，引发不可预期的重复警告
真正难的不是加一行 warnings.warn()，而是让警告出现在正确的时间、正确的上下文、并推动人去行动。没人看的警告，和没写一样。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
