Python inspect.getclosurevars怎样查看函数依赖的外部变量

排查闭包、装饰器或动态生成的函数时，单看 __code__.co_freevars 往往不够：它只能告诉你部分自由变量名，不能直接把名称对应的当前值分组。Python 的 inspect.getclosurevars(func) 会返回一个 ClosureVars，把依赖拆成 nonlocals、globals、builtins 和 unbound 四部分。

官方地址：https://docs.python.org/3/library/inspect.html#inspect.getclosurevars

记住一个判断顺序：先看 unbound 是否为空，再看依赖来自闭包还是模块全局；这比直接打印整个函数对象更容易定位名称解析问题。

ClosureVars 四个字段分别表示什么

getclosurevars 接收 Python 函数或方法，返回的对象像一个带四个属性的命名元组。nonlocals 是外层函数捕获的局部变量，globals 是函数所在模块的全局名称，builtins 是函数能看到的内置名称，unbound 则是当前模块全局和内置名称都无法解析的引用。

用一个闭包读出当前依赖

下面的例子故意同时放入闭包变量、模块全局变量和一个未定义名称。代码不调用业务函数，只检查函数对象本身，因此可以把“名称是否能解析”和“函数执行后得到什么结果”分开。

import inspect

SERVICE_PREFIX = "billing"  # 模块级配置会进入 globals

def make_label(suffix: str):
    local_prefix = f"{SERVICE_PREFIX}-"  # 外层局部变量会进入 nonlocals

    def label(order_id: str) -> str:
        # 这个分支用于演示未解析名称，不需要真正执行到这里。
        if order_id == "debug":
            return debug_marker
        # 参数来自当前调用，不会被 getclosurevars 当作外部依赖。
        return f"{local_prefix}{order_id}{suffix}"

    return label

formatter = make_label("-paid")
closure_vars = inspect.getclosurevars(formatter)

# 读取四组结果，先看 unbound 再决定是否执行函数。
print(closure_vars.nonlocals)
print(closure_vars.globals)
print(closure_vars.builtins)
print(closure_vars.unbound)

这个函数的 local_prefix 和 suffix 会出现在 nonlocals，SERVICE_PREFIX 会出现在 globals，而未定义的 debug_marker 会进入 unbound。order_id 是调用参数，不能从这个 API 的四个映射里找到。

发现 unbound 后怎样定位真正的问题

unbound 非空并不等于函数一定会立刻失败：如果缺失名称藏在不会走到的分支里，普通输入可能暂时正常。但它说明函数体包含当前无法解析的外部引用，适合在插件加载、装饰器注册或配置热更新时提前暴露。

import inspect

def explain_dependencies(func):
    # 先限制输入类型，避免把实例、字符串等对象误当成函数检查。
    if not inspect.isfunction(func) and not inspect.ismethod(func):
        raise TypeError("func 必须是 Python 函数或方法")

    values = inspect.getclosurevars(func)
    # 把名称集合排序，日志结果稳定，便于比较两次配置加载。
    return {
        "nonlocals": sorted(values.nonlocals),
        "globals": sorted(values.globals),
        "builtins": sorted(values.builtins),
        "unbound": sorted(values.unbound),
    }

report = explain_dependencies(formatter)
if report["unbound"]:
    # 缺失名称先作为配置或代码问题记录，不要用空值静默补齐。
    raise RuntimeError(f"函数存在未解析名称: {report['unbound']}")

print(report)

工程上可以把这段检查放在注册阶段，但不要把它当成完整的静态分析器。它只回答“函数当前引用了哪些可解析或不可解析名称”，不会告诉你分支覆盖率，也不会代替类型检查、测试和实际调用。

装饰器、方法与兼容边界

对实例方法调用 getclosurevars 时，检查的是这个方法函数体可见的外部名称；实例属性和调用时传入的参数不属于四个外部映射。对装饰器则要先明确想看哪一层：传入包装函数就得到包装器的依赖，使用 functools.wraps 只会改善元数据，不会把包装器的闭包自动变成原函数的闭包。

该 API 从 Python 3.3 起提供，当前版本仍属于 inspect 模块的标准能力。为了兼容更老的运行环境，可以集中做一次能力判断；但不要用读取 __closure__ 的私有细节完全替代它，因为那样拿不到全局名称和未解析名称的分组结果。

常见问题

getclosurevars 会执行函数吗？

不会。它检查函数对象能解析到的外部名称和当前值，不会替你调用函数；因此适合放在注册或调试阶段，但不能据此证明函数的所有分支都能成功运行。

为什么参数不在 nonlocals 里？

参数属于调用帧，不是函数创建时捕获的外部名称。getclosurevars 关注的是函数体从外部作用域解析到的名称，所以应把参数边界单独记录。

总结

• inspect.getclosurevars 把外部依赖分成 nonlocals、globals、builtins 和 unbound。
• 排查闭包或装饰器时先看 unbound，再按来源检查当前值。
• 它是运行时依赖观察工具，不代替测试、类型检查或分支行为验证。