Python inspect.get_annotations 怎样安全读取函数注解

读取可信函数的注解时，可以先用 inspect.get_annotations(func, eval_str=False) 获取字典，避免额外把字符串注解交给 eval。需要真实类型对象时，再单独选择解析策略。这里的“安全”必须有前提：它不是运行不可信 Python 代码的沙箱，Python 3.14 及以后的延迟注解在读取时仍可能执行代码。

eval_str=False 控制的是字符串注解是否额外求值，不承诺读取任意对象都没有副作用。把可信来源、返回格式、异常状态分开设计，比只设置一个开关可靠。

我在设计文档生成器或函数注册器时，会先问“只展示声明，还是需要能参与运算的类型对象”。两种需求混在同一个读取步骤里，往往让一个未定义的前向引用拖垮整批处理。以下代码是原创说明示例，没有作为本机运行记录。

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

先确定注解来自哪里

inspect.get_annotations 从 Python 3.10 起提供；从 3.14 起成为 annotationlib.get_annotations 的别名。处理自己的模块、固定依赖和已允许加载的插件时，可以围绕这个入口建立读取约定。对于用户提交的 Python 文件，导入本身就能运行代码，不应为了读取一个函数签名而在主服务中直接导入。

如果外部输入只是表单中的类型名称，最好用自己的名称映射或数据格式处理。不要先把它写入函数的 __annotations__，再期待反射接口替你完成可信度判断。权限边界在输入接纳和代码加载阶段，不能等到拿到函数对象之后才补上。

只读取声明时显式关闭字符串求值

下面的 quote 函数用引号声明未定义的 Price 类型。对于只想展示参数说明的工具，可以保留这段字符串，不必为了生成文档提前导入全部业务类型。

import inspect

def quote(amount: "Price") -> "str":
    # 这是业务函数占位，读取注解不会调用这个函数体。
    raise NotImplementedError

# 不额外解析字符串注解，便于显示未解析的声明。
annotations = inspect.get_annotations(quote, eval_str=False)
parameter_annotation = annotations.get("amount")
return_annotation = annotations.get("return")

amount 对应参数注解，return 对应返回值注解；没有注解的参数不会自动被补齐。返回的是新的字典，修改其顶层键不会直接改写函数原来的注解字典，但这不意味着内部对象被深拷贝。

关闭 eval_str 也不会把已经是类型对象的值变成字符串。在旧版默认的即时求值语义下，未加引号的注解表达式可能早在定义函数时就已求值；在新版延迟语义下，默认 VALUE 格式的读取可能触发求值。所以这个参数不能逆转定义或导入阶段已经发生的行为，也不能屏蔽新版的全部注解执行。

需要类型对象时单独开启解析

如果注册器确实要拿到 Price 类，而不是文本名称，我会把解析放进明确命名的另一阶段，只处理可信函数，并由业务方提供需要的命名空间。下面的例子与上一段可以放在同一个模块中理解。

class Price:
    pass

# 使用函数原有全局名称，加上当前需要解析的业务类型。
namespace = dict(quote.__globals__)
namespace["Price"] = Price

resolved = inspect.get_annotations(
    quote,
    globals=namespace,
    locals=namespace,
    eval_str=True,  # 仅对可信注解启用字符串表达式求值。
)

这段代码的目的，是显式表达 Price 从哪里解析，而不是声称传一个小字典就能安全执行未知表达式。开启 eval_str 允许对字符串内容调用 eval，缺失名称或表达式内部异常都会影响读取。不要通过不断补全环境变量、导入无关模块的方式“试到成功”，那会让解析依赖变得难以解释。

从 3.14 起，format 与 eval_str 也要配套选择：非 VALUE 格式不能同时设置 eval_str=True。普通跨版本示例不传 format；专门针对新版的文档工具则可以选择 STRING 格式。

记录缺失、成功与读取失败

批量处理时最容易丢失的信息，是把读取异常转换成空字典。空字典可能表示对象没有自己的注解；读取失败则意味着这一项没有完成，不能让注册器将它视为一个不需要约束的函数。

import inspect

def annotation_record(func):
    try:
        values = inspect.get_annotations(func, eval_str=False)
    except Exception as exc:
        # 批量任务保留失败类型，不把失败伪装成没有注解。
        return {"status": "error", "error_type": type(exc).__name__}
    return {
        "status": "ok",
        "has_annotations": bool(values),
        "annotations": values,
    }

这是可信代码批处理的状态包装，不是限制执行时间或副作用的隔离器。它没有捕获 BaseException，也不能阻止一个注解求值过程长时间不返回。日志里记录对象标识和失败类型通常已足够定位；面向公开用户的报错无需直接展开全部异常文本和内部模块路径。

给文档工具选择合适的输出契约

Python 3.14 及以上可以请求 STRING，让文档任务取得面向显示的字符串表示。它不保证逐字符保留源文件的空格和写法，也不能被宣传成绝对无执行风险的源代码读取器。

import inspect
from annotationlib import Format

# 仅用于 Python 3.14 及以上，仍以可信函数为输入。
display_annotations = inspect.get_annotations(
    quote,
    eval_str=False,
    format=Format.STRING,
)

类的处理还要注意范围：get_annotations 不会把父类注解自动合并成子类的完整字段表。做数据模型文档时，是否继承、如何覆盖，应是你自己的明确规则。另一个工具 typing.get_type_hints 面向类型提示解析，不能作为一个“更安全”的无条件替换入口。

eval_str=False 能保证注解不执行代码吗？

不能。它只关闭字符串值的额外 eval。对象访问、新版延迟注解和导入阶段都有自己的执行语义。对不可信代码应在接纳和加载方式上另行设计隔离。

返回空字典能证明函数没有类型要求吗？

不能。它只说明这次读取没有得到注解条目；业务约束可能在其他地方。读取异常更不能用空字典代替。

只做文档时必须把前向引用变成类型对象吗？

通常不必。我会优先保留声明表示，让展示任务不依赖业务类型全部加载；真正需要类型对象的注册过程再显式解析，并保留失败状态。

官方资料：inspect 入口及版本变化、annotationlib 返回格式与安全说明、Python 3.13 的注解读取接口。