使用inspect模块动态查看Python函数源码与字节码

一、使用 inspect 动态获取函数源代码

在进行框架开发、自动化测试、插件热加载或调试排查时，动态获取某个函数在磁盘上的原始 Python 语法定义是一项常见需求。inspect 模块提供了统一的内省接口，其底层通过读取模块的物理文件并配合行缓存进行文本抽取。

1. 基础用法：inspect.getsource()

获取一个自定义函数源代码的最直接方法是调用 inspect.getsource(object)。该函数接收函数、方法、模块、类或代码对象作为参数，返回包含完整缩进与注释的原始 Python 源码字符串。

import inspect

def calculate_discount(price: float, rate: float = 0.9) -> float:
    """计算商品折后价格并保留两位小数"""
    if price <= 0:
        raise ValueError("价格必须大于 0")
    final_price = price * rate
    return round(final_price, 2)

# 动态读取函数的源代码字符串
source_text = inspect.getsource(calculate_discount)
print(source_text)

def calculate_discount(price: float, rate: float = 0.9) -> float:
    """计算商品折后价格并保留两位小数"""
    if price <= 0:
        raise ValueError("价格必须大于 0")
    final_price = price * rate
    return round(final_price, 2)

2. 精确定位行号与分行列表：inspect.getsourcelines()

当我们需要将源码与行号对齐显示，或者做局部高亮标记时，inspect.getsourcelines(object) 比 getsource 更具实用性。它返回一个二元元组：第一项是由源码每一行文本组成的列表，第二项是该函数在其所属源文件中的起始物理行号（从 1 开始计）。

lines, start_lineno = inspect.getsourcelines(calculate_discount)
print(f"函数起始物理行号: {start_lineno}")
for offset, line in enumerate(lines):
    current_no = start_lineno + offset
    print(f"{current_no:4d} | {line.rstrip()}")

3. 检索源文件物理路径：inspect.getsourcefile()

如果希望明确该函数究竟是在哪一个物理文件或虚拟环境中被加载的，可以使用 inspect.getsourcefile(object) 或 inspect.getfile(object)。两者的核心区别在于：getsourcefile() 只返回能够找到 Python 源码的文件路径（如果是被编译的二进制模块则返回 None），而 getfile() 可能会返回编译后的 .pyc 文件或共享库扩展路径。

file_path = inspect.getsourcefile(calculate_discount)
print(f"源文件所在绝对路径: {file_path}")

二、穿透装饰器与处理源码缺失的边界条件

在真实的生产代码中，函数往往被多层装饰器（如身份鉴权、日志追踪、缓存等）包裹，或者由 C 语言扩展直接导出。如果在这些复杂场景下直接调用 inspect.getsource()，极易获取到非预期的包装器代码或直接触发异常。

1. 穿透装饰器：使用 inspect.unwrap() 脱壳

如果函数被标准库 functools.wraps 修饰，装饰器会在外层闭包上挂载 __wrapped__ 属性指回原函数。若直接对该函数调用 inspect.getsource()，得到的是最外层的 wrapper 定义，而非核心业务逻辑。inspect.unwrap() 能够沿着 __wrapped__ 链递归解包，直到获取底层真正的原始函数对象。

import functools
import inspect

def audit_logger(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"执行审计日志: {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

@audit_logger
def transfer_funds(account_id: str, amount: float):
    """核心转账业务逻辑"""
    return {"status": "success", "balance": amount}

# 错误做法：直接读取将获取到 wrapper 闭包代码
raw_wrapper_source = inspect.getsource(transfer_funds)

# 正确做法：先使用 inspect.unwrap 解开所有包装层
original_func = inspect.unwrap(transfer_funds)
real_source = inspect.getsource(original_func)
print(real_source)

2. 源码获取不可用的三类典型场景

inspect.getsource() 的工作原理依赖于底层模块 linecache。当发生以下情况时，由于缺乏对应的物理源码文件，该调用将抛出 OSError 或 TypeError：

• 内置函数与 C 扩展模块：例如 math.sin、len 或使用 Cython/C-API 编译的二进制模块，其函数体由原生机器码实现，内存中不存在 Python 语法文本，调用时抛出 TypeError: is not a module, class, method, function, traceback, frame, or code object 或 OSError。
• 交互式环境 (REPL) 与 exec/eval 动态代码：在 Python 命令行终端、早期交互式 Shell 或通过 exec("def temp(): pass") 动态编译的函数，其代码对象文件名通常标记为 <string> 或 <stdin>，磁盘上并无对应文件，调用将抛出 OSError: could not get source code。
• 剥离源码的生产环境（仅包含 .pyc）：出于合规或代码保护目的，部分生产 Docker 镜像在构建时仅编译并保留字节码文件（.pyc），删除了所有 .py 源文件。在此类环境下读取源码必定失败。

三、深入代码对象：从 inspect 到底层字节码

当源码因环境原因不可见，或者我们需要探查解释器执行的真实物理逻辑时，就必须下潜至字节码层级。在 Python 中，函数是代码对象（types.CodeType）的外层包装，所有的可执行指令、符号表与常量池均常驻于内存中的代码对象内。

1. 代码对象的获取与校验

每个纯 Python 函数都有一个 __code__ 属性，指向其底层的代码对象。我们可以使用 inspect.iscode(obj) 进行类型断言，确保所操作的目标具备执行体语义：

code_obj = transfer_funds.__code__
if inspect.iscode(code_obj):
    print(f"对象名称: {code_obj.co_name}, 参数个数: {code_obj.co_argcount}")

2. 代码对象的核心属性解析

代码对象是只读的，包含了 Python 虚拟机执行该函数所需的全部符号信息与指令序列。理解以下核心字段是分析字节码的基础：

# 查看原始字节码与元数据元组
raw_bytes = calculate_discount.__code__.co_code
print("原始字节码 (16进制):", raw_bytes.hex())
print("常量表 co_consts:", calculate_discount.__code__.co_consts)
print("局部变量表 co_varnames:", calculate_discount.__code__.co_varnames)

原始字节码 (16进制): 7c0064016b01721674006402830182007c007c0114007d0274017c02640383025300
常量表 co_consts: ('计算商品折后价格并保留两位小数', 0, '价格必须大于 0', 2)
局部变量表 co_varnames: ('price', 'rate', 'final_price')

四、字节码指令反汇编与源码行精准映射

直接阅读十六进制的 co_code 原始字节极为晦涩。为了便于分析，Python 提供了标准库模块 dis（Disassembler）。它不仅能将字节指令转换为人类可读的助记符（Mnemonic），还支持直接与代码对象的行号映射表关联。

1. 结构化反汇编：使用 dis.Bytecode

dis.Bytecode(func) 返回一个可迭代的指令生成器。每条指令都被解析为一个结构化的 Instruction 对象，包含操作码名称、数字参数、实际参数值以及该指令所对应的物理源码行。

import dis

bytecode_seq = dis.Bytecode(calculate_discount)
for instr in bytecode_seq:
    # starts_line 标记该指令是否为某一行源码生成的第一条指令
    line_indicator = f"[行 {instr.starts_line:2d}]" if instr.starts_line else "        "
    print(f"{line_indicator} 偏移: {instr.offset:3d} | {instr.opname:18s} 参数: {instr.argval!r}")

[行  5] 偏移:   0 | LOAD_FAST          参数: 'price'
        偏移:   2 | LOAD_CONST         参数: 0
        偏移:   4 | COMPARE_OP         参数: '<='
        偏移:   6 | POP_JUMP_FORWARD_IF_FALSE 参数: 22
[行  6] 偏移:   8 | LOAD_GLOBAL        参数: 'ValueError'
        偏移:  10 | LOAD_CONST         参数: '价格必须大于 0'
        偏移:  12 | CALL               参数: 1
        偏移:  14 | RAISE_VARARGS      参数: 1
[行  7] 偏移:  16 | LOAD_FAST          参数: 'price'
        偏移:  18 | LOAD_FAST          参数: 'rate'
        偏移:  20 | BINARY_OP          参数: 5
        偏移:  22 | STORE_FAST         参数: 'final_price'
[行  8] 偏移:  24 | LOAD_GLOBAL        参数: 'round'
        偏移:  26 | LOAD_FAST          参数: 'final_price'
        偏移:  28 | LOAD_CONST         参数: 2
        偏移:  30 | CALL               参数: 2
        偏移:  32 | RETURN_VALUE       参数: None

2. 字节码指令与源码行的精准对齐：co_lines()

在 Python 3.11+ 中，代码对象引入了更精准的源码映射机制 code.co_lines()，替代了旧版本的行号位移表（co_lnotab）。该方法返回一个包含 (start_offset, end_offset, lineno) 的迭代器，明确标定某字节码区间所属于的源码行号。结合该机制，开发者可以构建精确到具体指令偏移量的源码反查定位器。

五、实战演练：编写一体化函数内省诊断工具

为了将源码与字节码探查能力整合为一个具备生产容灾特性的工具，我们编写一个名为 inspect_function() 的诊断函数。该工具具备以下功能：

1. 自动通过 inspect.unwrap() 穿透全部装饰器。
2. 尝试读取完整源码；若遇到 OSError（如 REPL 或纯 .pyc 容器），平滑降级并输出原因。
3. 提取代码对象并打印其参数签名、常量表与局部符号表。
4. 反汇编输出带有行号标记的虚拟机指令序列。

import inspect
import dis
from typing import Any, Callable

def inspect_function(fn: Callable[..., Any]) -> None:
    """
    一体化函数诊断器：结合 inspect 与 dis 模块提取源码与字节码
    """
    if not callable(fn):
        raise TypeError(f"目标对象不是可调用函数: {fn!r}")

    # 步骤 1：解包装饰器
    target = inspect.unwrap(fn)
    func_name = getattr(target, "__name__", "<anonymous>")

    print("=" * 64)
    print(f"【函数内省诊断报告】: {func_name}")
    print("=" * 64)

    # 步骤 2：探测物理文件与源码
    source_available = False
    try:
        source_file = inspect.getsourcefile(target) or "<未知物理文件>"
        source_lines, start_no = inspect.getsourcelines(target)
        source_available = True
        print(f"[*] 源文件: {source_file} (起始物理行: {start_no})")
        print("[*] 源代码内容:")
        for idx, l in enumerate(source_lines[:8]):  # 预览前8行
            print(f"    {start_no + idx:3d} | {l.rstrip()}")
        if len(source_lines) > 8:
            print(f"    ... (共 {len(source_lines)} 行代码)")
    except (OSError, TypeError) as err:
        print(f"[!] 无法提取源代码文本 (原因: {err})，已降级至纯字节码模式。")

    # 步骤 3：提取代码对象元数据
    code_obj = getattr(target, "__code__", None)
    if not inspect.iscode(code_obj):
        print("[!] 目标不包含 Python 代码对象 (可能是 C 内置扩展函数)")
        return

    print("
[*] 代码对象 (Code Object) 元数据:")
    print(f"    形参个数: {code_obj.co_argcount}, 局部变量: {code_obj.co_varnames}")
    print(f"    常量表:   {code_obj.co_consts}")
    print(f"    指令大小: {len(code_obj.co_code)} bytes")

    # 步骤 4：反汇编字节码指令
    print("
[*] 结构化字节码反汇编序列:")
    for instr in dis.Bytecode(target):
        line_str = f"L.{instr.starts_line:2d}" if instr.starts_line else "    "
        print(f"    {line_str} [偏移 {instr.offset:3d}] {instr.opname:18s} {instr.argval!r}")

    print("=" * 64 + "
")

使用示例与执行验证

我们可以使用该诊断工具对带装饰器的函数和通过 exec 动态编译的函数分别进行内省测试：

# 测试 1：常规修饰函数
inspect_function(transfer_funds)

# 测试 2：动态字符串编译函数（模拟 REPL 或无源文件场景）
scope = {}
exec("def dynamic_add(x, y): return x + y", scope)
inspect_function(scope["dynamic_add"])

================================================================
【函数内省诊断报告】: dynamic_add
================================================================
[!] 无法提取源代码文本 (原因: could not get source code)，已降级至纯字节码模式。

[*] 代码对象 (Code Object) 元数据:
    形参个数: 2, 局部变量: ('x', 'y')
    常量表:   (None,)
    指令大小: 6 bytes

[*] 结构化字节码反汇编序列:
    L. 1 [偏移   0] LOAD_FAST          'x'
         [偏移   2] LOAD_FAST          'y'
         [偏移   4] BINARY_OP          0
         [偏移   6] RETURN_VALUE       None
================================================================

从测试 2 的输出可以看到，尽管由于函数通过动态代码块编译导致 inspect.getsource 捕获异常，但工具成功通过底层的 __code__ 抽取出参数元数据并完整打印出了虚拟机操作码序列，验证了容灾机制的有效性。

六、总结与工程选型建议

动态探查 Python 函数的内部实现，需要在“高级语义表达”与“底层执行指令”之间做出正确的路径选择：

• 优先使用 inspect 模块获取语义上下文：在有完整源码的项目调试、静态代码生成与接口文档抽取中，inspect.getsource() 和 inspect.getsourcelines() 是首选工具。记得在面对高阶函数时，先使用 inspect.unwrap() 剥离装饰器切面。
• 借助 __code__ 与 dis 模块构筑底层兜底能力：在无源码发布镜像、混淆环境或动态生成的业务场景下，不可单纯假设源码一定存在。func.__code__ 提供了零外部依赖的纯内存内省途径，结合 dis.Bytecode 能够准确呈现解释器的真实指令逻辑。
• 警惕 linecache 的运行时缓存脏读：如果应用程序在运行过程中通过热补丁、热替换或者文件覆写修改了磁盘上的 .py 文件，inspect.getsource() 仍可能读取到内存旧缓存。此时需主动调用 linecache.checkcache(filename) 强制刷新文件系统映射。