直接调用 warnings.warn() 并指定 DeprecationWarning 类型是最常用方式，需设 stacklevel=2 使警告指向调用处，且 Python 默认忽略该警告，调试时可用 -W default::DeprecationWarning 临时启用。
怎么用 warnings.warn() 发出弃用警告
直接调用 warnings.warn()，并指定 DeprecationWarning 类型，是最常用也最明确的方式。Python 默认会忽略 DeprecationWarning（除非在测试或开发模式下），所以别指望它总在终端里自动弹出来——这是设计行为，不是 bug。
实操建议：
- 把警告放在即将被移除的函数或方法开头，比如：
def old_function(): warnings.warn("old_function is deprecated, use new_function instead", DeprecationWarning, stacklevel=2) # 原逻辑 -
stacklevel=2很关键：它让警告指向调用该函数的位置，而不是warn()这一行，否则调试时你会困惑“谁在用我？” - 不要省略
category参数（即DeprecationWarning），否则默认是UserWarning，语义不对，且可能被不同过滤规则处理
为什么 DeprecationWarning 默认不显示
因为 Python 认为这类警告主要面向开发者而非终端用户，所以从 2.7 起就默认过滤掉 DeprecationWarning（包括其子类）。你运行脚本时没看到警告，大概率不是代码错了，而是 Python 压根没让它出来。
临时启用方式（仅用于调试）：
立即学习“Python免费学习笔记（深入）”；
- 命令行加
-W default::DeprecationWarning：python -W default::DeprecationWarning script.py
- 代码里提前调用：
warnings.simplefilter("default", DeprecationWarning)，但注意这要放在所有warn()调用之前，且只影响当前解释器会话 - 测试时更推荐用
pytest的--filterwarnings=default::DeprecationWarning，避免污染生产逻辑
如何给类或模块加弃用提示
类和模块本身没法直接“调用”，所以得在实例化或导入时触发警告。常见做法是封装一层代理或用模块级代码拦截。
实操建议：
- 对类：重写
__init__或定义一个替代类，原类里发警告class OldClass: def __init__(self): warnings.warn("OldClass is deprecated, use NewClass instead", DeprecationWarning, stacklevel=2) # 初始化逻辑 - 对模块：在
__init__.py顶部加警告（但需谨慎——每次导入都触发）# mypackage/__init__.py import warnings warnings.warn("mypackage is deprecated, see newpackage", DeprecationWarning, stacklevel=2) - 更稳妥的做法是导出一个“懒警告”函数，在首次使用关键功能时才提醒，避免导入即警告打扰用户
容易踩的坑：过滤规则冲突和误用 PendingDeprecationWarning
PendingDeprecationWarning 是给“将来几个版本后才弃用”的功能用的，不是 DeprecationWarning 的温和版。绝大多数情况应该用后者——错用会导致警告被完全忽略（因为默认过滤规则不包含前者）。
另一个高频问题：自定义过滤器写错位置。比如在 main() 里调用 simplefilter，但警告发生在导入阶段（模块顶层代码），那它已经错过了。
真正需要全局生效时，过滤器必须在任何可能触发警告的代码执行前设置，典型位置是脚本最开头、或 sitecustomize.py 中。
还有个细节：如果你用的是打包工具（如 PyInstaller），某些警告可能因冻结环境被静默吞掉，这时得靠日志或显式检查 warnings.showwarning 是否被重定向。
