1. 项目概述：为什么我们需要inspect模块？

如果你写过一段时间的 Python，尤其是涉及到框架开发、代码调试或者动态分析，你大概率会遇到一个场景：你手里有一个函数对象，但你想知道它叫什么名字、有哪些参数、源代码在哪儿。或者，你拿到一个类，想动态地遍历它的所有方法。这时候，你可能会去翻dir()或者__dict__，但得到的信息往往杂乱无章，难以直接使用。inspect模块就是 Python 标准库中专门为解决这类“内省”（Introspection）问题而生的利器。所谓内省，就是在运行时检查对象（如模块、类、方法、函数、帧对象、代码对象）的内部信息的能力。

inspect模块封装了访问这些内部属性的底层细节，提供了高层、稳定且易用的 API。它让你能像外科医生一样，精准地“解剖”你的代码对象，获取签名、源代码、文档字符串、类继承关系等关键信息。这对于编写调试工具、实现依赖注入、构建 Web 框架的路由系统、生成 API 文档、或者进行元编程来说，都是不可或缺的。很多人初学 Python 时可能觉得这个模块很“高级”用不上，但一旦你的项目复杂度上来了，或者需要写一些更“聪明”的代码时，inspect往往能成为你工具箱里最趁手的那把“手术刀”。接下来，我们就来系统地拆解这把“手术刀”的每一个部件。

2.inspect模块核心函数全解析

inspect模块的函数很多，但我们可以根据其功能划分为几个核心类别：类型检查、成员获取、源代码处理、签名与参数解析、栈与帧信息。我们将逐一深入，并附上实际场景中的用法和避坑指南。

2.1 类型检查与对象识别

在动态处理对象前，我们首先得知道它是什么。inspect提供了一系列is*函数来进行精确的类型判断。

2.1.1isfunction,ismethod,isroutine

这三个函数最容易混淆，但理解它们对动态调用至关重要。

• inspect.isfunction(obj): 判断obj是否是一个用户定义的函数（function）。注意，内置函数（如len,print）或 C 语言实现的函数返回False。Lambda 表达式也是函数。

  import inspect def my_func(): pass print(inspect.isfunction(my_func)) # True print(inspect.isfunction(lambda x: x)) # True print(inspect.isfunction(print)) # False，因为 print 是内置函数

• inspect.ismethod(obj): 判断obj是否是一个绑定方法（bound method）。即它是一个与类实例关联的方法。

  class MyClass: def method(self): pass obj = MyClass() print(inspect.ismethod(obj.method)) # True，绑定到实例 obj 的方法 print(inspect.ismethod(MyClass.method)) # False，MyClass.method 是一个函数

• inspect.isroutine(obj): 判断obj是否是一个可调用例程（callable routine）。这是一个更宽泛的概念，包括了用户函数、内置函数、绑定方法、未绑定方法（在 Python 3 中也是函数）、类方法（@classmethod）、静态方法（@staticmethod）等。当你只关心对象能否被调用，并且它是一个函数或方法时，用这个。

  print(inspect.isroutine(my_func)) # True print(inspect.isroutine(print)) # True print(inspect.isroutine(obj.method)) # True print(inspect.isroutine(MyClass.method)) # True

实操心得：在编写通用装饰器或拦截器时，我通常先用inspect.isroutine()判断对象是否可调用且为函数/方法，然后再用isfunction或ismethod进行更精细的处理。直接使用callable()虽然能判断可调用性，但无法区分函数、方法和实现了__call__的类实例，isroutine在这方面更精确。

2.1.2isclass,ismodule,iscode,isbuiltin

这些函数顾名思义，用于判断对象是否为类、模块、代码对象或内置函数。

• inspect.isclass(obj): 判断是否为类。
• inspect.ismodule(obj): 判断是否为模块。
• inspect.iscode(obj): 判断是否为代码对象（code object），这是函数编译后的底层表示，包含了字节码等信息。
• inspect.isbuiltin(obj): 判断是否为内置函数或方法。

import inspect import os print(inspect.isclass(list)) # True print(inspect.ismodule(os)) # True print(inspect.iscode(my_func.__code__)) # True print(inspect.isbuiltin(len)) # True

2.2 获取对象成员信息

比dir()更强大的成员获取函数，能过滤和排序。

2.2.1getmembers(obj [, predicate])

这是最常用的成员获取函数。它返回一个列表，包含对象的所有(name, value)对。可选的predicate参数是一个函数，用于过滤成员（只保留使predicate(value)为True的成员）。

import inspect class Demo: attr = 1 def method(self): pass def _private(self): pass # 获取所有成员 all_members = inspect.getmembers(Demo) print(all_members[:3]) # 输出很多，包括从 object 继承的 # 只获取方法 methods = inspect.getmembers(Demo, predicate=inspect.isfunction) print(methods) # [('_private', <function...>), ('method', <function...>)] # 只获取不以 '_' 开头的公共方法 public_methods = inspect.getmembers(Demo, predicate=lambda m: inspect.isfunction(m) and not m.__name__.startswith('_')) print(public_methods) # [('method', <function...>)]

注意事项：getmembers()返回的列表包含了从所有父类继承来的成员。如果你只想获取当前类定义的成员，需要结合__dict__进行过滤，或者使用inspect.getattr_static()来避免触发描述符协议（如@property）的执行。

2.2.2signature(func)与Parameter对象

这是inspect模块的“王牌”功能之一，用于获取可调用对象的签名信息，在 Python 3.3+ 中引入。它返回一个Signature对象，其中包含了丰富的参数信息。

import inspect def example(a, b=10, *args, c=20, d, **kwargs): pass sig = inspect.signature(example) print(sig) # (a, b=10, *args, c=20, d, **kwargs) # 遍历参数 for param_name, param in sig.parameters.items(): print(f"参数名: {param_name}") print(f" 类型: {param.kind}") # POSITIONAL_ONLY, POSITIONAL_OR_KEYWORD, VAR_POSITIONAL, KEYWORD_ONLY, VAR_KEYWORD print(f" 默认值: {param.default}") # 如果没有默认值，是 inspect.Parameter.empty print(f" 注解: {param.annotation}") # 类型注解

Parameter.kind的几种类型非常重要：

1. POSITIONAL_OR_KEYWORD: 可以通过位置或关键字传入的参数（最常见）。
2. VAR_POSITIONAL:*args形式的可变位置参数。
3. KEYWORD_ONLY: 仅关键字参数，出现在*或*args之后，例如上面的c,d。
4. VAR_KEYWORD:**kwargs形式的可变关键字参数。
5. POSITIONAL_ONLY: 仅限位置参数（Python 语法不支持直接定义，但某些内置函数如pow有）。

实际应用场景：Web 框架的路由映射。一个请求处理器（视图函数）可能有各种参数。框架可以通过inspect.signature分析这个函数需要哪些参数（如request,user_id,name），然后自动从请求（URL 路径、查询字符串、POST 数据）中提取对应的值并传入，实现依赖注入。

# 模拟一个简单的依赖注入 def handle_request(request, user_id: int, name: str = "Guest"): return f"Hello {name}, your ID is {user_id}" def invoke_with_context(func, context_dict): """根据函数签名，从上下文字典中提取参数并调用函数""" sig = inspect.signature(func) bound_args = sig.bind(**context_dict) # 将字典绑定到签名 bound_args.apply_defaults() # 应用默认值 return func(*bound_args.args, **bound_args.kwargs) # 模拟请求上下文 context = {'request': 'req_obj', 'user_id': 123, 'name': 'Alice'} result = invoke_with_context(handle_request, context) print(result) # Hello Alice, your ID is 123

踩坑记录：使用signature()时，如果对象是 C 扩展模块中实现的（如很多内置函数或第三方库的底层函数），可能会抛出ValueError。在实际代码中，一定要用try...except包裹，或者先用inspect.isbuiltin()判断一下。另外，Signature.bind()方法非常强大，它能帮你验证传入的参数是否符合函数签名，但要注意它不会执行函数体。

2.3 源代码与文档处理

2.3.1getsource(object)与getsourcelines(object)

这两个函数用于获取对象的源代码。

• getsource(object): 返回一个字符串，包含对象的完整源代码。
• getsourcelines(object): 返回一个元组(source_lines, starting_line_number)，其中source_lines是源代码行的列表。

import inspect def test_func(x): """A test function.""" return x * 2 print(inspect.getsource(test_func)) # 输出： # def test_func(x): # """A test function.""" # return x * 2 lines, lineno = inspect.getsourcelines(test_func) print(f"起始行号: {lineno}") print(f"源代码: {''.join(lines)}")

重要限制：这两个函数只能获取到定义在.py文件中的对象的源代码。对于在交互式环境（如 REPL）、动态执行（exec）或编译后的模块（.pyc）中定义的对象，它们会抛出OSError。在编写调试工具或代码生成器时，这是一个必须处理的边界情况。

2.3.2getdoc(object)与getcomments(object)

• getdoc(object): 返回对象的文档字符串（__doc__），经过清理（去除首尾空白）。
• getcomments(object): 返回对象定义之前出现的第一个注释块（通常用于模块、类、函数顶部的版权或说明注释）。

print(inspect.getdoc(test_func)) # A test function. # 假设在 mymodule.py 中 """ Module-level docstring. """ # This is a module comment. def foo(): pass # 在另一个文件中 import mymodule print(inspect.getcomments(mymodule)) # 可能输出 '# This is a module comment.\n'

2.4 类与继承关系探查

2.4.1getclasstree(classes, unique=False)

以嵌套列表的形式返回给定类的继承关系树。这在分析复杂类体系时非常直观。

import inspect class A: pass class B(A): pass class C(A): pass class D(B, C): pass tree = inspect.getclasstree([A, B, C, D]) print(tree) # 输出类似：[（<class 'object'>, ()）， ...]，展示了继承链。

2.4.2getmro(cls)

返回一个元组，包含类的方法解析顺序（Method Resolution Order, MRO），即cls.__mro__。对于理解多继承至关重要。

print(inspect.getmro(D)) # (<class '__main__.D'>, <class '__main__.B'>, <class '__main__.C'>, <class '__main__.A'>, <class 'object'>)

2.5 栈与帧信息（调试利器）

这是inspect模块在调试和日志记录中最强大的功能之一。它允许你访问当前调用栈的帧对象。

• currentframe(): 返回当前执行帧的帧对象。
• stack(context=1): 返回一个FrameInfo列表，表示调用栈。每个FrameInfo是一个命名元组，包含frame,filename,lineno,function,code_context,index。
• getouterframes(frame, context=1): 获取从给定帧到最外层帧的列表。
• getinnerframes(tb, context=1): 获取从给定追溯（traceback）到最内层帧的列表。

import inspect def func_a(): func_b() def func_b(): # 获取当前栈信息 current_stack = inspect.stack() for frame_info in current_stack: print(f"在文件 {frame_info.filename} 的第 {frame_info.lineno} 行，" f"函数 {frame_info.function} 中") # 获取当前帧的局部变量 current_frame = inspect.currentframe() print(f"局部变量: {current_frame.f_locals}") func_a()

典型应用场景：

1. 增强日志：在日志记录中自动添加上下文信息（文件名、行号、函数名），而无需手动传入__file__和__name__。
2. 调试器：实现自定义的调试工具，查看任意时刻的变量状态。
3. 性能分析：采样调用栈以分析热点函数。

严重警告：帧对象包含大量引用，持有它们会阻止垃圾回收器释放相关对象，可能导致内存泄漏。绝对不要在生产环境的常驻逻辑中长时间持有或存储帧对象（比如在全局变量或缓存中）。仅在调试、错误处理等短期场景下使用，并且在使用后尽快将帧对象引用设为None。

3. 实战演练：构建一个简易的依赖注入容器

让我们综合运用以上知识，构建一个超简易的依赖注入（DI）容器原型。这个容器能自动分析被装饰函数的参数，并从注册的依赖中提供相应的值。

import inspect class SimpleContainer: def __init__(self): self._dependencies = {} def register(self, name, dependency): """注册一个依赖项""" self._dependencies[name] = dependency def inject(self, func): """装饰器：自动注入依赖""" def wrapper(*args, **kwargs): # 1. 获取函数签名 sig = inspect.signature(func) # 2. 创建一个参数字典的副本用于绑定 bound_args = sig.bind_partial(*args, **kwargs) bound_args.apply_defaults() # 3. 遍历参数，查找需要注入的依赖 for param_name, param in sig.parameters.items(): # 如果该参数未由调用者提供，且其名称在已注册的依赖中 if param_name not in bound_args.arguments and param_name in self._dependencies: bound_args.arguments[param_name] = self._dependencies[param_name] # 4. 使用注入后的参数调用原函数 return func(*bound_args.args, **bound_args.kwargs) return wrapper # 使用示例 container = SimpleContainer() container.register('db_connection', 'mysql://localhost') container.register('config', {'debug': True}) @container.inject def process_data(db_connection, config, query): print(f"使用连接: {db_connection}") print(f"配置: {config}") print(f"执行查询: {query}") return "success" # 调用时，只需要提供未被注册为依赖的参数 result = process_data(query="SELECT * FROM users") # 输出： # 使用连接: mysql://localhost # 配置: {'debug': True} # 执行查询: SELECT * FROM users print(result) # success

这个例子展示了如何利用inspect.signature和参数绑定，实现一种声明式的依赖管理。在实际的框架（如 FastAPI）中，依赖注入系统要复杂得多，会处理类型注解、子依赖、作用域等，但核心原理与此类似。

4. 常见问题与排查技巧实录

即使熟悉了 API，在实际使用inspect时还是会遇到一些坑。这里记录了几个我踩过的雷和解决方法。

4.1 问题：signature()在装饰器上失效

场景：你写了一个装饰器，用它装饰函数后，再用inspect.signature()查看被装饰函数的签名，发现看到的还是原函数的签名，而不是装饰器内部包装函数的签名。

import inspect def my_decorator(func): def wrapper(*args, **kwargs): print("装饰器逻辑") return func(*args, **kwargs) return wrapper @my_decorator def original(a, b): return a + b print(inspect.signature(original)) # 输出 (a, b)，而不是 (*args, **kwargs)

原因：inspect.signature()默认会尝试绕过装饰器，查找被装饰的原始对象。这是通过检查对象的__wrapped__属性实现的。

解决方案：在装饰器内部，使用functools.wraps或functools.update_wrapper来更新包装函数的元数据。同时，为了保留正确的签名，可以使用functools.wraps并结合inspect.signature手动更新__signature__属性（Python 3.3+）。

import inspect import functools def my_decorator_correct(func): @functools.wraps(func) # 关键步骤1：复制元数据 def wrapper(*args, **kwargs): print("装饰器逻辑") return func(*args, **kwargs) # 关键步骤2：更新签名（如果需要包装函数有不同的签名，可以在这里自定义） # wrapper.__signature__ = inspect.signature(wrapper) # 如果需要显示包装器的签名 # 但通常我们希望显示原函数的签名，所以 wraps 已经帮我们处理了。 return wrapper @my_decorator_correct def original(a, b): return a + b print(inspect.signature(original)) # 正确输出 (a, b) print(original.__name__) # 正确输出 'original'

4.2 问题：处理内置函数和 C 扩展函数时抛出异常

场景：你写了一个通用函数，用来记录所有被调用函数的签名，但当它遇到len、numpy的某些函数或pandas的方法时，程序崩溃了。

import inspect def log_call(func): sig = inspect.signature(func) # 这里对内置函数会抛出 ValueError def wrapper(*args, **kwargs): print(f"调用 {func.__name__}，签名: {sig}") return func(*args, **kwargs) return wrapper # 尝试装饰内置函数会失败 # logged_len = log_call(len)

排查与解决：inspect.signature()无法为许多内置函数和用 C 编写的扩展函数生成签名。必须进行防御性编程。

def get_signature_safe(func): """ 安全地获取可调用对象的签名。 对于无法获取签名的对象，返回一个占位符字符串。 """ try: sig = inspect.signature(func) return str(sig) except (ValueError, TypeError): # 可能是内置函数、C扩展函数或其他无法内省的对象 # 可以进一步用 isbuiltin, ismethod 等判断 if inspect.isbuiltin(func): return "<built-in function>" elif inspect.ismethoddescriptor(func): # 一些C扩展方法 return "<method descriptor>" else: return "<signature not available>"

4.3 问题：getsource()在特定环境下返回空或报错

场景：你的工具在开发环境运行良好，但部署到服务器或打包成可执行文件后，getsource()无法获取源代码。

原因：

1. 源代码文件（.py）不存在（只有.pyc或打包在 zip 里）。
2. 函数是在运行时动态生成的（例如通过exec,eval,type()动态创建类）。

应对策略：

1. 明确需求：你的功能是否必须依赖源代码？如果只是为了记录或显示，或许文档字符串getdoc()就足够了。
2. 提供降级方案：在try...except OSError块中调用getsource()，失败时返回一个友好的错误信息或备用内容（如函数名和所在模块名）。
3. 环境判断：如果是打包环境，直接禁用依赖源代码的功能。

def get_source_or_fallback(obj): """尝试获取源代码，失败时返回备用信息""" try: return inspect.getsource(obj) except OSError: # 无法读取源代码 module_name = getattr(obj, '__module__', '<unknown module>') name = getattr(obj, '__name__', str(obj)) return f"[源代码不可用] 对象: {name}, 模块: {module_name}" except TypeError: # 对象类型不支持，如内置函数 return f"[对象类型不支持获取源代码] {type(obj)}"

4.4 性能考量：不要过度使用inspect

inspect模块的功能强大，但很多操作（特别是涉及源代码读取、栈帧遍历）是有开销的。在性能敏感的代码路径（如被频繁调用的函数、循环内部）中，应避免使用。

• 缓存签名：如果你需要反复查询同一个函数的签名，应该在外部计算一次并缓存起来。
• 避免在热路径中使用stack()：获取整个调用栈是相对昂贵的操作。
• 使用getattr_static替代getattr：当你想获取一个类的属性但又不想触发属性描述符（如@property）的__get__方法时，inspect.getattr_static(cls, name)是更安全且有时更高效的选择。

inspect模块是 Python 元编程能力的一个集中体现。从简单的类型检查到复杂的运行时代码分析，它为我们打开了一扇深入了解和操控程序自身结构的大门。掌握它，意味着你能编写出更灵活、更智能、也更强大的代码。不过，正如我们最后讨论的，能力越大责任越大，在使用这些内省功能时，务必注意其边界条件、异常处理和性能影响，确保你的“手术刀”用在正确的地方，写出既强大又稳健的程序。