Python warnings 模块用于非致命性提示，区别于异常和日志。核心在于过滤器机制，支持 ignore、default、error 等行为。警告类别、过滤器原理及上下文管理器用法，并通过构建企业级 SDK 示例，演示如何自定义警告类、设置 stacklevel 实现优雅废弃机制，帮助开发者规范代码演进并提升 API 专业度。
在日常的 Python 开发中，除了红色的 Traceback 报错，控制台偶尔会闪过几行黄色的 Warning（警告）。在企业级开发和开源项目维护中，。本文将深度解析 Python 标准库中 模块。
warnings所有警告继承自内置 Warning 类。常用类别包括：
Python 内部维护一个过滤器列表。触发警告时，按顺序匹配规则 (action, message, category, module, lineno)。
关键 Action 行为：
使用 warnings.warn() 是最基础的操作。
import warnings
def calculate_salary(base, bonus):
if bonus > base * 2:
# 发出 UserWarning 警告
warnings.warn("奖金居然超过了底薪的两倍，这在企业里很不正常！", UserWarning)
return base + bonus
print("第一次计算：", calculate_salary(5000, 12000))
print("第二次计算：", calculate_salary(5000, 12000))
# 预期输出：
# demo.py:6: UserWarning: 奖金居然超过了底薪的两倍，这在企业里很不正常！
# warnings.warn("奖金居然超过了底薪的两倍，这在企业里很不正常！", UserWarning)
# 第一次计算：17000
# 第二次计算：17000
# (注意：因为默认 action 是 'default'，同一行的警告第二次没有打印！)
在单元测试或调用第三方陈旧库时，可用 catch_warnings 隔离并记录警告。
import warnings
def use_old_api():
warnings.warn("这个 API 又老又慢，别用了", DeprecationWarning)
# 使用上下文管理器
with warnings.catch_warnings(record=True) as w:
# 改变当前上下文的过滤规则，使其记录所有警告
warnings.simplefilter("always")
use_old_api()
# 离开 with 块后，全局警告规则恢复原样
if len(w) > 0:
print(f"成功在后台捕获到 {len(w)} 个警告！")
print(f"警告内容是：{w[-1].message}")
从 Python 2.7 开始，默认将 DeprecationWarning 的 action 设置为 ignore。
改正方法：显式开启或在命令行使用 -W default 参数。
import warnings
# 显式开启废弃警告的打印
warnings.simplefilter('default', DeprecationWarning)
将警告升级为异常，利用 Traceback 查看完整的调用栈。
import warnings
# 将所有警告升级为异常
warnings.simplefilter("error")
try:
warnings.warn("内存占用偏高", RuntimeWarning)
except RuntimeWarning as e:
print(f"抓到你了！由于转成了异常，我现在可以拿到堆栈信息。错误：{e}")
模拟维护核心 Python SDK 场景。旧版本 Client.get_data() 有缺陷，开发了新版 Client.fetch_data_v2()。需在不阻断运行的前提下给出升级指引。
新建 sdk_client.py 文件：
import warnings
import time
# ==========================================
# 1. 定义企业专属的警告类
# ==========================================
class SDKDeprecationWarning(DeprecationWarning):
"""SDK 专属的废弃警告，方便后续统一拦截处理"""
pass
class SDKPerformanceWarning(UserWarning):
"""SDK 性能风险警告"""
pass
# 配置：默认情况下，Python 会忽略 DeprecationWarning
# 作为 SDK 开发者，我们可以在模块级别强制使其对于我们的自定义类生效
warnings.simplefilter('always', SDKDeprecationWarning)
# ==========================================
# 2. 编写带有容错和版本控制的 SDK
# ==========================================
class EnterpriseDataClient:
def __init__(self, timeout: int = 3):
self.timeout = timeout
# 校验不合理的配置，但不报错退出
if self.timeout > 30:
warnings.warn(
f"设置的 timeout={self.timeout}s 过长，可能会导致线程阻塞。建议小于 10s。",
category=SDKPerformanceWarning,
stacklevel=2 # stacklevel=2 让警告指向调用 __init__ 的那行代码，而不是 warn 这行
)
def get_data(self, query: str):
"""【已废弃】旧版获取数据的方法"""
# 抛出专属的废弃警告
warnings.warn(
"get_data() 方法将在 v2.0 版本中移除，请尽快迁移至 fetch_data_v2()！",
category=SDKDeprecationWarning,
stacklevel=2
)
print(f"[Old API] 正在努力查询：{query} ...")
time.sleep(1)
return {"data": "old_data", "status": "ok"}
def fetch_data_v2(self, query: str):
"""【推荐】新版高性能获取数据方法"""
print(f"[New API V2] 高速检索：{query} ...")
return {"data": "new_data", "status": "success", "speed": "fast"}
# ==========================================
# 3. 模拟业务方调用 (测试用例)
# ==========================================
def main():
print("--- 业务线 A 启动 ---")
# 业务线 A 传入了极其离谱的超时时间
client_a = EnterpriseDataClient(timeout=100)
# 业务线 A 依然在使用老接口
result1 = client_a.get_data("SELECT * FROM users")
# 第二次调用，验证 always 规则（每次都会打印警告）
result2 = client_a.get_data("SELECT * FROM orders")
print("\n--- 业务线 B 启动 ---")
# 业务线 B 进行了代码升级
client_b = EnterpriseDataClient(timeout=5)
result3 = client_b.fetch_data_v2("SELECT * FROM users")
if __name__ == "__main__":
main()
在命令行执行 python sdk_client.py，你将看到专业的控制台输出：
--- 业务线 A 启动 ---
sdk_client.py:44: SDKPerformanceWarning: 设置的 timeout=100s 过长，可能会导致线程阻塞。建议小于 10s。
client_a = EnterpriseDataClient(timeout=100)
sdk_client.py:47: SDKDeprecationWarning: get_data() 方法将在 v2.0 版本中移除，请尽快迁移至 fetch_data_v2()！
result1 = client_a.get_data("SELECT * FROM users")
[Old API] 正在努力查询：SELECT * FROM users ...
sdk_client.py:49: SDKDeprecationWarning: get_data() 方法将在 v2.0 版本中移除，请尽快迁移至 fetch_data_v2()！
result2 = client_a.get_data("SELECT * FROM orders")
[Old API] 正在努力查询：SELECT * FROM orders ...
--- 业务线 B 启动 ---
[New API V2] 高速检索：SELECT * FROM users ...
注意代码中的 stacklevel=2 参数。如果不加这个参数，警告输出的行号会指向 SDK 内部的 warn 所在行。对于 SDK 用户来说，他们想知道的是自己写的哪行代码触发了警告。将 stacklevel 设为 2，就可以向上追溯一层调用栈，精准指向用户实例化 Client 或调用老方法的那行代码。这是架构师写底层库必备的素养！
总结，warnings 库不仅能帮助规范团队内部的代码演进，更能极大提升对外提供 API 的专业度。在你的项目中试着把 print("TODO: 这个方法以后要改") 替换为正规的 warnings.warn 吧！
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online