Inspect API

本页提供 tarsio.inspect 的参考文档。 可用于理解类型解析结果、字段布局和递归引用结构。

示例代码

from tarsio import Struct, inspect as tinspect, field

class User(Struct):
    id: int = field(tag=0)
    name: str = field(tag=1)

info = tinspect.struct_info(User)
assert info is not None
assert info.fields[0].name == "id"

核心概念

• type_info(tp): 解析任意支持类型，返回带 kind 的 TypeInfo。
• struct_info(cls): 返回 StructInfo，描述字段、tag 与默认值语义。
• FieldInfo 是 Field 的兼容别名，适合渐进迁移。

注意事项

• 内省 API 面向开发与诊断，不替代业务解码逻辑。
• 不支持的标注会抛 TypeError，建议在启动阶段完成类型预检。
• 递归结构会出现 RefType 分支，需要在工具层显式处理。

API 参考

tarsio.inspect

Tarsio 类型内省.

主要用途：

• 在开发阶段对 typing.Annotated 字段标注进行静态建模
• 提供 type_info() / struct_info() 的返回对象结构（kind 分支 + 关联字段）

type_info

type_info(tp: Any) -> TypeInfo

将类型标注解析为 Tarsio 的类型内省结果.

参数	描述
tp	需要解析的类型标注，支持内置类型（如 int/str/bytes）、容器类型 （如 list[T]、tuple[T]、dict[K, V]）、Optional/Union 形式， 以及 typing.Annotated[T, ...]（会解析其中的 Meta 约束信息）。 类型： Any

返回	描述
TypeInfo	解析后的 TypeInfo 实例，可通过其 kind 字段区分具体分支，并读取对应属性。

引发	描述
TypeError	当类型标注不受支持或包含未支持的前向引用时抛出。

源代码位于： python/tarsio/inspect.pyi

def type_info(tp: Any) -> TypeInfo:
    """将类型标注解析为 Tarsio 的类型内省结果.

    Args:
        tp: 需要解析的类型标注，支持内置类型（如 `int/str/bytes`）、容器类型
            （如 `list[T]`、`tuple[T]`、`dict[K, V]`）、Optional/Union 形式，
            以及 `typing.Annotated[T, ...]`（会解析其中的 `Meta` 约束信息）。

    Returns:
        解析后的 `TypeInfo` 实例，可通过其 `kind` 字段区分具体分支，并读取对应属性。

    Raises:
        TypeError: 当类型标注不受支持或包含未支持的前向引用时抛出。
    """

struct_info

struct_info(cls: type) -> StructInfo | None

解析 Struct 类并返回字段定义信息.

参数	描述
cls	需要解析的 tarsio.Struct 子类。 类型： type

返回	描述
StructInfo | None	StructInfo 对象，包含字段列表（按 tag 升序）；如果该类没有可用字段，
StructInfo | None	或该类是未具体化的泛型模板，则返回 None。

引发	描述
TypeError	当字段缺少 tag、tag 重复、混用整数 tag 与 Meta，或字段类型不受支持时抛出。

源代码位于： python/tarsio/inspect.pyi

def struct_info(cls: type) -> StructInfo | None:
    """解析 Struct 类并返回字段定义信息.

    Args:
        cls: 需要解析的 `tarsio.Struct` 子类。

    Returns:
        `StructInfo` 对象，包含字段列表（按 tag 升序）；如果该类没有可用字段，
        或该类是未具体化的泛型模板，则返回 `None`。

    Raises:
        TypeError: 当字段缺少 tag、tag 重复、混用整数 tag 与 `Meta`，或字段类型不受支持时抛出。
    """

TypeInfo module-attribute

TypeInfo: TypeAlias = (
    IntType
    | StrType
    | FloatType
    | BoolType
    | BytesType
    | AnyType
    | NoneType
    | TypedDictType
    | NamedTupleType
    | DataclassType
    | EnumType
    | UnionType
    | ListType
    | TupleType
    | VarTupleType
    | MapType
    | SetType
    | OptionalType
    | StructType
    | RefType
    | TarsDictType
)

Type

类型内省基类.

属性	描述
kind	类型分支标识。 类型： str

BasicType

Bases: Type

基础标量类型基类.

CompoundType

Bases: Type

复合容器类型基类.

IntType

Bases: BasicType

整数类型（JCE int 家族的抽象视图）.

编码：ZeroTag 或 Int1/Int2/Int4/Int8。

StrType

Bases: BasicType

字符串类型.

编码：String1 或 String4。

FloatType

Bases: BasicType

浮点类型（运行时对应 double 语义）.

编码：ZeroTag 或 Double。

BoolType

Bases: BasicType

布尔类型（在 JCE 编码层面通常以 int 表达）.

编码：ZeroTag 或 Int1/Int2/Int4/Int8。

BytesType

Bases: BasicType

二进制类型（运行时会被视为 byte-list 的特殊形式）.

编码：SimpleList。

AnyType

Bases: BasicType

动态类型（运行时根据值推断编码）.

编码：运行时按值类型选择具体 TarsType。

NoneType

Bases: BasicType

None 类型（通常仅出现在 Union/Optional 中）.

编码：不能直接编码，仅用于 Optional/Union 的语义分支。

EnumType

Bases: CompoundType

Enum 类型.

编码：取 value 的内层类型映射。

属性	描述
cls	枚举类型。 类型： type
value_type	枚举值的类型内省结果。 类型： TypeInfo

UnionType

Bases: CompoundType

Union 类型（非 Optional 形式）.

编码：按变体顺序匹配实际值，直接按匹配类型编码。

属性	描述
variants	变体类型列表。 类型： tuple[TypeInfo, ...]

ListType

Bases: CompoundType

列表类型：list[T].

编码：List（若元素类型为 int 且值为 bytes，则使用 SimpleList）。

属性	描述
item_type	元素类型。 类型： TypeInfo

TupleType

Bases: CompoundType

元组类型：固定长度、固定类型 tuple[T1, T2, ...].

编码：List。

属性	描述
items	元素类型列表。 类型： tuple[TypeInfo, ...]

VarTupleType

Bases: CompoundType

元组类型：可变长度、元素类型相同 tuple[T, ...].

编码：List（若元素类型为 int 且值为 bytes，则使用 SimpleList）。

属性	描述
item_type	元素类型。 类型： TypeInfo

MapType

Bases: CompoundType

映射类型：dict[K, V].

编码：Map。

属性	描述
key_type	键类型。 类型： TypeInfo
value_type	值类型。 类型： TypeInfo

SetType

Bases: CompoundType

集合类型：set[T] / frozenset[T].

编码：List，解码为 set。

属性	描述
item_type	元素类型。 类型： TypeInfo

OptionalType

Bases: CompoundType

可选类型：T | None 或 typing.Optional[T].

编码：None 时不写 tag，有值时按内层类型映射。

属性	描述
inner_type	内层类型。 类型： TypeInfo

StructType

Bases: CompoundType

Struct 类型：字段类型为另一个 tarsio.Struct 子类.

编码：StructBegin ... StructEnd。

属性	描述
cls	Struct 类型。 类型： type
fields	字段列表，按 tag 升序。 类型： tuple[Field, ...]

RefType

Bases: CompoundType

引用类型：用于递归结构中的循环引用节点.

属性	描述
cls	被引用的 Struct 类型。 类型： type

Field

结构体字段信息.

属性	描述
name	字段名。 类型： str
tag	字段 tag。 类型： int
type	字段类型内省结果。 类型： TypeInfo
default	字段默认值。 类型： Any
default_factory	字段默认值工厂；无工厂时为 tarsio.NODEFAULT。 类型： Any
has_default	是否显式有默认值。 类型： bool
optional	是否可选。 类型： bool
required	是否必填。 类型： bool

FieldInfo module-attribute

FieldInfo: TypeAlias = Field

StructInfo

结构体信息（类级 Schema 视图）.

属性	描述
cls	结构体类型。 类型： type
fields	字段列表，按 tag 升序。 类型： tuple[Field, ...]