DeepDiff 导入需用 from deepdiff import DeepDiff；ignore_order=True 仅对嵌套 list 有效，比较顶层 dict 列表需加 report_repetition=True；NaN、datetime、numpy 类型需特殊处理。
DeepDiff 安装后 DeepDiff 报 NameError
常见现象是刚 pip install deepdiff 后直接写 from deepdiff import DeepDiff，运行却提示 NameError: name 'DeepDiff' is not defined。这不是安装问题，而是导入方式记混了——DeepDiff 是类，不是函数，必须显式导入类本身。
- 正确写法：
from deepdiff import DeepDiff（推荐）或import deepdiff; diff = deepdiff.DeepDiff(...) - 别写成
import DeepDiff或from deepdiff import deepdiff，后者会导入模块对象，不是类 - 注意大小写：
DeepDiff首字母大写，deepdiff包名全小写；写错大小写在 Linux/macOS 下直接报错
对比两个字典时 ignore_order=True 不生效
这是最常踩的坑：以为加了 ignore_order=True 就能无视 list 里元素顺序，结果仍报差异。根本原因是该参数默认只对「嵌套在 dict 中的 list」起作用，对顶层 list 或 list 中的 dict 无效。
- 场景举例：比较
{"items": [1, 2]}和{"items": [2, 1]}→ignore_order=True有效 - 但比较
[{"id": 1}, {"id": 2}]和[{"id": 2}, {"id": 1}]→ 默认不生效，需额外加report_repetition=True并配合ignore_order=True - 更稳妥的做法是明确指定
ignore_order=True+report_repetition=True，尤其当 list 元素是 dict 时 - 性能影响：开启
ignore_order会让 DeepDiff 内部做排列组合比对，大数据量 list 会明显变慢
pytest 中断言失败时输出太长，看不到关键差异
直接用 assert not DeepDiff(...) 在 pytest 里失败时，只会打印一整段 diff 字符串，密密麻麻全是路径和值，根本没法快速定位哪一层错了。
- 实操建议：用
DeepDiff(..., verbose_level=2)限制输出粒度，避免嵌套过深的细节刷屏 - 更推荐封装成自定义断言函数，例如：
def assert_deep_equal(a, b):<br> diff = DeepDiff(a, b, ignore_order=True, report_repetition=True)<br> if diff:<br> raise AssertionError(f"Deep diff found:\n{diff}") - 配合 pytest 的
-v参数 + 自定义 message，能精准看到values_changed、iterable_item_added等分类项 - 注意：
verbose_level=0会隐藏所有路径信息，调试时慎用
DeepDiff 对 NaN、datetime、numpy 类型处理出错
测试数据里一旦含 float('nan')、datetime.now() 或 numpy 数组，DeepDiff 默认会抛 TypeError 或返回意外结果，因为它内部用 json.dumps 做序列化预处理，而这三者都不被原生 JSON 支持。
立即学习“Python免费学习笔记（深入）”；
- NaN：Python 的
float('nan')与 numpy 的np.nan行为不同，前者在 DeepDiff 中可能被转成None，后者需注册自定义 type_comparator - datetime：必须传
ignore_type_in_groups=(datetime.datetime,)或提前转成字符串（如.isoformat()） - numpy：加
ignore_type_in_groups=(np.ndarray, np.number)，否则数组会被展开成嵌套 list，diff 结果失真 - 兼容性提醒：DeepDiff 6.x 开始对 numpy 支持更好，但旧项目若用 5.x，建议统一转成 Python 原生类型再比
