函数与异常 API

本页汇总模块级函数与调试能力。 包括序列化入口、追踪工具以及异常类型。

示例代码

from tarsio import Struct, decode_trace, encode, field

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

payload = encode(User(1))
obj = User.decode(payload)
trace = decode_trace(payload)
assert obj.id == 1
assert trace.jce_type == "ROOT"

核心概念

• encode/decode 是统一入口，按输入决定 schema 或 Raw 路径。
• decode_trace 适合协议调试，可输出树状追踪信息。
• probe_struct 可快速判断 bytes 是否像完整 Struct。
• ValidationError 表示约束校验失败，不等同于二进制损坏。

注意事项

• 调试函数返回的是诊断视图，不保证和业务模型一一对应。
• 面向外部输入时应限制包体大小并做好异常分类处理。
• decode 的目标类型应明确，避免运行时分派歧义。

API 参考

tarsio.encode

encode(obj: Any) -> bytes

将对象序列化为 Tars 二进制格式.

该函数会自动根据输入对象的类型选择合适的编码模式： 1. Schema 模式：如果对象是 Struct、dataclass、NamedTuple 或 TypedDict 实例， 将按照其定义的 Schema 进行编码。 2. Raw 模式：如果对象是 TarsDict、 dict、list 或基本类型， 将进行原始编码（无 Schema）。

参数	描述
obj	要编码的对象。 类型： Any

返回	描述
bytes	包含序列化数据的 bytes 对象。

引发	描述
TypeError	如果对象既不是有效的 Struct 也不是支持的 Raw 类型。
ValueError	如果数据校验失败。

源代码位于： python/tarsio/api.py

def encode(obj: Any) -> bytes:
    """将对象序列化为 Tars 二进制格式.

    该函数会自动根据输入对象的类型选择合适的编码模式：
    1. **Schema 模式**：如果对象是 `Struct`、`dataclass`、`NamedTuple` 或 `TypedDict` 实例，
       将按照其定义的 Schema 进行编码。
    2. **Raw 模式**：如果对象是 `TarsDict`、 `dict`、`list` 或基本类型，
       将进行原始编码（无 Schema）。

    Args:
        obj: 要编码的对象。

    Returns:
        包含序列化数据的 bytes 对象。

    Raises:
        TypeError: 如果对象既不是有效的 Struct 也不是支持的 Raw 类型。
        ValueError: 如果数据校验失败。
    """
    # 优先处理显式的 Raw 容器和基本类型
    if isinstance(
        obj, (TarsDict, dict, list, tuple, set, int, float, str, bytes, bool)
    ):
        return _core_encode_raw(obj)

    # 尝试作为 Struct 处理 (Struct)
    # 优化：通过检查特征属性避免 try-except 开销
    if isinstance(obj, Struct):
        return _core_encode(obj)

    # 如果不是 Struct，最后尝试 Raw 兜底
    return _core_encode_raw(obj)

tarsio.decode

decode(data: _BytesLike, cls: type[TarsDict]) -> TarsDict

decode(data: _BytesLike, cls: type[_StructT]) -> _StructT

decode(data: _BytesLike, cls: type = TarsDict) -> Any

从 Tars 二进制数据反序列化.

参数	描述
cls	目标类 类型： type 默认： TarsDict
data	二进制数据 类型： _BytesLike

返回	描述
Any	反序列化的类实例或 TarsDict。

引发	描述
TypeError	参数类型错误或目标类未注册 Schema。
ValueError	数据格式不正确。

源代码位于： python/tarsio/api.py

def decode(
    data: _BytesLike,
    cls: type = TarsDict,
) -> Any:
    """从 Tars 二进制数据反序列化.

    Args:
        cls: 目标类
        data: 二进制数据

    Returns:
        反序列化的类实例或 TarsDict。

    Raises:
        TypeError: 参数类型错误或目标类未注册 Schema。
        ValueError: 数据格式不正确。
    """
    if issubclass(cls, (Struct)):
        return _core_decode(cls, data)
    else:
        return _core_decode_raw(data)

tarsio.probe_struct builtin

probe_struct(data: bytes) -> TarsDict | None

启发式探测字节数据是否为一个有效的 Tars Struct.

参数	描述
data	可能包含 Tars Struct 的 bytes. 类型： bytes

返回	描述
TarsDict | None	若解析成功且完全消费输入,返回 TarsDict;否则返回 None.

tarsio.decode_trace builtin

decode_trace(
    data: bytes, cls: type[Any] | None = None
) -> TraceNode

解析二进制数据并生成追踪树.

tarsio.TraceNode

decode_trace 返回的调试树节点.

属性	描述
tag	当前节点对应的 Tag。 类型： int
jce_type	JCE 类型名。 类型： str
value	当前节点值（容器节点通常为 None）。 类型： Any | None
children	子节点列表。 类型： list[TraceNode]
name	字段名（有 Schema 时可用）。 类型： str | None
type_name	类型名（有 Schema 时可用）。 类型： str | None
path	从根开始的可读路径。 类型： str

__module__ class-attribute

__module__ = 'tarsio._core'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__repr__ method descriptor

__repr__()

Return repr(self).

children property

children: list[TraceNode]

jce_type property

jce_type: str

name property

name: str | None

path property

path: str

tag property

tag: int

type_name property

type_name: str | None

value property

value: Any | None

tarsio.ValidationError

Bases: builtins.ValueError

解码阶段的校验错误.

由 Meta 约束或 Schema 校验失败触发。

错误消息包含路径与原因，典型格式： Error at <root>.<field>.<tag:N>: <reason>。

Notes

当前版本不提供结构化字段访问器（如 field_name、tag 属性）。 建议在业务侧解析异常消息中的路径片段。

__module__ class-attribute

__module__ = 'tarsio._core'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__weakref__ property

__weakref__

list of weak references to the object