最直接办法是运行时开启 deprecationwarning：python -w default::deprecationwarning 或代码开头加 warnings.filterwarnings("default", category=deprecationwarning)，且须在所有导入前执行。
怎么识别代码里还在用已废弃的 Python 接口
Python 的 DeprecationWarning 默认不显示，所以很多人根本不知道自己调用了废弃接口。最直接的办法是运行时主动开启警告捕获：
python -W default::DeprecationWarning your_script.py或在代码开头加
warnings.filterwarnings("default", category=DeprecationWarning)。注意：只加这行不够，得确保它在所有导入之前执行，否则模块内部的废弃调用可能已被跳过。
常见错误现象：CI 流水线没报错，但本地跑 pytest 加了 -W error::DeprecationWarning 就挂；或者升级 Python 小版本后突然抛 PendingDeprecationWarning（比如 3.12 对 collections.MutableMapping 的处理更激进）。
- 别依赖 IDE 的静态扫描——很多废弃提示（如
asyncio.async()→asyncio.create_task()）需要运行时上下文才能判断 -
pip install pyflakes+pyflakes .能发现部分硬编码废弃函数名，但对动态调用（getattr(obj, "old_method")）完全无效 - 检查
setup.py或pyproject.toml中的python_requires，如果还写着>=3.7，那typing.Text、collections.abc.Mapping这类过渡接口大概率还没清理干净
替换 urllib.parse.urlencode() 等老式编码逻辑时要注意什么
这类接口本身没删，但行为在 Python 3.9+ 有隐性变化：比如 urllib.parse.urlencode() 对 None 值的处理从静默忽略变成抛 TypeError。不是所有“能跑”都等于“正确”，尤其当参数来自用户输入或外部 API。
使用场景集中在表单提交、API 请求拼接、日志上下文序列化。容易踩的坑是只改函数名，不校验参数类型：
立即学习“Python免费学习笔记（深入）”；
- 旧写法：
urlencode({"a": None, "b": "ok"})→"b=ok"（3.8 及以前） - 新写法必须先过滤：
urlencode({k: v for k, v in data.items() if v is not None}) - 若用
requests，直接传params=字典更安全——它内部做了兼容处理，但自定义 HTTP 客户端（如httpx）未必 - 性能影响很小，但
urlencode()在 3.11 后对 bytes 输入不再自动 decode，传b"key=val"会报错，得显式转 str
如何让团队平滑过渡，而不是等上线才爆雷
废弃接口下线最怕“改完本地能跑，一上生产就崩”。核心思路是分阶段：先监控、再告警、最后拦截。关键动作不是写新代码，而是控制旧代码的可见范围。
推荐在项目根目录放一个 deprecated.py，把所有待下线接口封装一层：
def old_helper(*args, **kwargs):
warnings.warn("old_helper() is deprecated, use new_helper() instead",
DeprecationWarning, stacklevel=2)
return _real_old_impl(*args, **kwargs)
然后用 grep -r "old_helper" --include="*.py" . 快速定位调用点。比全局搜函数名靠谱，因为能避开字符串匹配误伤（比如注释里写“不要用 old_helper”）。
- CI 阶段加检查：用
ast-grep扫描未被封装的废弃调用，失败则阻断合并 - 线上埋点：在封装层里加
logging.info("deprecated.old_helper called by %s", inspect.stack()[1].filename)，聚合到日志平台看调用频次和来源模块 - 别在
__init__.py里 re-export 废弃接口——看似方便，实则延长了死亡周期
为什么 collections.MutableMapping 替换后测试会漏掉边界 case
这个废弃项特别典型：Python 3.10 开始发警告，3.13 正式移除。但很多人只改了继承声明，没动 __setitem__ 和 __delitem__ 的实现逻辑，导致子类在 isinstance(obj, collections.abc.MutableMapping) 下返回 False，而旧版检查用的是 collections.MutableMapping。
问题本质是 ABC 层级变了：collections.abc.MutableMapping 是抽象基类，而 collections.MutableMapping 是具体类（且已空壳）。替换后，如果测试只 mock 了旧类，没更新 isinstance 断言目标，就会漏掉兼容性断裂。
- 查漏方法：在测试 setup 里加
assert isinstance(your_obj, collections.abc.MutableMapping)，别信文档说的“只要实现方法就行” - 第三方库（如
ruamel.yaml）可能仍依赖旧路径，得看它源码里 import 了哪个，不能只靠自己代码 clean - 如果用
mypy，记得更新typeshed版本，否则类型检查会误报“找不到 MutableMapping”
废弃接口下线最难的不是改代码，是确认“谁还在调用它”以及“调用时的上下文是否可控”。日志埋点和 CI 卡点比一次性 grep 更有用，尤其当项目有 C 扩展或 Cython 模块时，Python 层的警告根本捕获不到底层调用。
