warnings.warn() 更合适，因其专为弃用提示设计：默认首次触发显示、支持警告过滤机制（-W参数/ warnings.filterwarnings()）、能被 pytest --error-on-warning 捕获，而 print() 无法静默或过滤，logging.warning() 缺乏内置集成。
为什么 warnings.warn() 比 print() 或 logging.warning() 更合适？
因为弃用提示的目标不是“让用户看到”，而是“让调用栈里真正写代码的人意识到问题，并在开发/测试阶段就发现”。warnings.warn() 默认只在首次触发时显示，且能被 Python 的警告过滤机制（-W 参数、warnings.filterwarnings()）统一控制——这正是它和 print() 的本质区别：后者无法被静默、无法按模块/类别过滤，而 logging.warning() 缺少与 Python 内置警告系统的集成，比如不会被 pytest 的 --error-on-warning 捕获。
常见错误现象：warnings.warn("xxx") 在 Jupyter 或某些 IDE 中不显示？那是因为默认过滤器把 DeprecationWarning 压制了（仅对 __main__ 模块以外的代码生效）。别急着加 print()，先确认警告是否真的被过滤了。
如何正确发出弃用警告（含类别和堆栈定位）？
必须指定 category=DeprecationWarning（或 PendingDeprecationWarning），否则不会被标准工具链识别；同时建议传入 stacklevel=2，让警告指向调用你封装函数的位置，而不是警告语句本身。
使用场景：给一个旧函数打上弃用标记，同时提供新替代方案：
立即学习“Python免费学习笔记（深入）”；
import warnings <p>def old_calc(x, y): warnings.warn( "old_calc() is deprecated, use new_calculate(x, y) instead", category=DeprecationWarning, stacklevel=2 ) return x + y * 2
关键点：
-
category必须是DeprecationWarning类型，不能是字符串 -
stacklevel=2让警告行号指向调用old_calc()的地方，而非该函数内部 - 消息中明确写出替代函数名，避免模糊表述如“请使用新版本”
怎样让弃用警告在 CI/测试中变成硬性失败？
Pytest 和 Python 自身都支持将警告升级为异常。这是防止弃用功能被忽略的关键防线。
常见错误现象：本地运行没报错，CI 却挂了？大概率是本地没启用警告转异常，而 CI 配了 --error-on-warning。
实操方式：
- 运行时加参数：
python -W error::DeprecationWarning script.py - pytest 中加：
pytest --error-on-warning（等价于-W error::DeprecationWarning） - 代码内临时启用：
warnings.simplefilter("error", DeprecationWarning)（慎用，会影响全局）
注意：DeprecationWarning 默认只对 __main__ 模块可见，所以直接运行脚本时可能看不到，但导入后被调用就会触发——这也是为什么测试里必须显式开启。
如何按模块/函数精细控制警告行为？
全局开关太粗暴，实际项目常需“对旧模块宽容，对新模块严格”。这时要用 warnings.filterwarnings() 配合模块路径。
例如，在测试入口处屏蔽某个已知旧模块的弃用警告，但保留其他所有警告：
import warnings
warnings.filterwarnings("ignore", category=DeprecationWarning, module="legacy_module")
参数差异：
-
module支持正则（如r"myproject\.old.*"），但注意转义 -
message可匹配警告文本，适合临时压制特定提示 -
action="once"表示每个（文件+行号）组合只警告一次，比默认"default"更安静
容易踩的坑：在 __init__.py 里调用 filterwarnings() 可能过早，导致后续导入的模块警告被误杀；建议只在测试启动逻辑或 CLI 入口处设置。
复杂点在于警告过滤器是全局状态，多个库可能互相覆盖；最稳妥的做法是不在库代码里调用 filterwarnings()，只由最终应用或测试框架来配置。
