ztpl —— Z-Template Python SDK
一份模板，两个方向：同一份模板既能把文本解析成结构化数据，也能把数据格式化回文本； 再加一层字段映射，"文本 A → 文本 B" 就成了声明式的。
核心引擎是 Go，本包是一层 ~200 行的 ctypes 薄壳，运行期零依赖。
安装
uv sync # 装开发依赖
make -C ../.. build # 构建 libztpl.so
uv run pytest # 跑测试 + 一致性用例
用法
from ztemplate import Template
# 只做解析时不需要目标模板
with Template("[${ts}] ${lv} ${msg} payload=${json|name=p}") as t:
t.parse_records("[T1] ERROR disk full payload={\"host\":\"web-1\"}")
# [{"ts":"T1","lv":"ERROR","msg":"disk full","p":{"host":"web-1"}}]
# JSON 岛被解码成真正的对象 ↑
t.verify_text(log) # 校验 round-trip 定律 A 与歧义
t.inspect() # 执行层级、是否回溯、字段与重复块
# 完整流水线
with Template(
"[${ts}] ${lv} ${msg}",
target="${level}|${text}",
mapping={"level": "upper(lv)", "text": "msg"},
) as t:
t.transform_text("[T1] error disk full") # -> "ERROR|disk full\n"
四个批量操作
| 方法 | 输入 → 输出 |
|---|---|
transform |
源文本 → 目标文本（完整流水线） |
parse |
源文本 → NDJSON 绑定 |
format |
NDJSON 绑定 → 目标文本 |
verify |
源文本 → 定律 A 与歧义报告 |
批量是架构要求而非优化：整条流水线都在 Go 侧完成，Python 只拿最终结果。 实测把字段逐个跨界回 Python 会让加速比从 12x 掉到 1.09x。
res = t.transform(data) # data: bytes，按 \n 分行
res.output # bytes
res.matched, res.total # 匹配/总行数，不匹配的行被跳过
res.records() # parse/verify 的 NDJSON 输出解析成对象列表
模板语法
| 写法 | 含义 |
|---|---|
${name} |
洞，由后继字面量定界（最快，走 SIMD 字面量搜索） |
${re|name=n,expr=\d+} |
正则洞，默认最短匹配 |
${json|name=p} |
JSON 结构化岛，自定界，惰性解码 |
${each|name=xs,sep=';'}...${end} |
重复块 |
映射表达式（JMESPath 子集）
mapping={
"time": "ts", # 裸字段名 —— 零拷贝快路径
"level": "upper(lv)", # 函数
"host": "p.host || 'unknown'", # 路径 + 回退
}
裸字段名与表达式的性能差一倍以上（99 vs 245 ns/行），能用裸字段名就别写表达式。
属性值含 , 时用单引号：sep=','；或反斜杠转义：sep=\,。
性能
| ns/行 | 吞吐 | |
|---|---|---|
| 本 SDK | 90 | 11 M行/秒 |
纯 Python（re.finditer + f-string） |
940 | 1.1 M行/秒 |
宿主绑定层相对纯 C 只损耗 ~9%。
命令行
见 zdog-template-cli —— 建立在本 SDK 之上，ztpl demo 可快速上手。
设计
见 docs/DESIGN.md，含全部实测数据与被否决方案的决策记录。
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file zdog_template-0.1.0-py3-none-manylinux_2_28_x86_64.whl.
File metadata
- Download URL: zdog_template-0.1.0-py3-none-manylinux_2_28_x86_64.whl
- Upload date:
- Size: 2.2 MB
- Tags: Python 3, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2ab5dd2460c97faafedbffa9bb7ff808c8035a7e7c7d9661bf235b0e38f73ac8
|
|
| MD5 |
d15cf7d125596992af51cc54cb0327f9
|
|
| BLAKE2b-256 |
f2fd6709fb25343b9c0ea46529cf476e72ef520d87f123e2a863825f65d2d741
|
Provenance
The following attestation bundles were made for zdog_template-0.1.0-py3-none-manylinux_2_28_x86_64.whl:
Publisher:
release.yml on litterzhang/zdog-template
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
zdog_template-0.1.0-py3-none-manylinux_2_28_x86_64.whl -
Subject digest:
2ab5dd2460c97faafedbffa9bb7ff808c8035a7e7c7d9661bf235b0e38f73ac8 - Sigstore transparency entry: 2434022040
- Sigstore integration time:
-
Permalink:
litterzhang/zdog-template@6702f1f150a3c6702ddc8aba5159182ed7109c40 -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/litterzhang
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@6702f1f150a3c6702ddc8aba5159182ed7109c40 -
Trigger Event:
push
-
Statement type:
File details
Details for the file zdog_template-0.1.0-py3-none-macosx_26_0_arm64.whl.
File metadata
- Download URL: zdog_template-0.1.0-py3-none-macosx_26_0_arm64.whl
- Upload date:
- Size: 1.1 MB
- Tags: Python 3, macOS 26.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1e1e24e2840e3fa7bafde32c6844a830c24d66d5618e7188a1d4017021061bcd
|
|
| MD5 |
0d8d7fcaa98f1e2a913fe17864b01172
|
|
| BLAKE2b-256 |
8f1b33a0dfe36eccb118a63a428db340dc3c08f951b414fcfbe97899a49bbb44
|
Provenance
The following attestation bundles were made for zdog_template-0.1.0-py3-none-macosx_26_0_arm64.whl:
Publisher:
release.yml on litterzhang/zdog-template
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
zdog_template-0.1.0-py3-none-macosx_26_0_arm64.whl -
Subject digest:
1e1e24e2840e3fa7bafde32c6844a830c24d66d5618e7188a1d4017021061bcd - Sigstore transparency entry: 2434022225
- Sigstore integration time:
-
Permalink:
litterzhang/zdog-template@6702f1f150a3c6702ddc8aba5159182ed7109c40 -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/litterzhang
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@6702f1f150a3c6702ddc8aba5159182ed7109c40 -
Trigger Event:
push
-
Statement type:
