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，含全部实测数据与被否决方案的决策记录。

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

zdog_template-0.1.1-py3-none-manylinux_2_28_x86_64.whl (2.2 MB view details)

Uploaded Aug 12, 2026 Python 3manylinux: glibc 2.28+ x86-64

zdog_template-0.1.1-py3-none-macosx_26_0_arm64.whl (1.1 MB view details)

Uploaded Aug 12, 2026 Python 3macOS 26.0+ ARM64

File details

Details for the file zdog_template-0.1.1-py3-none-manylinux_2_28_x86_64.whl.

File metadata

Download URL: zdog_template-0.1.1-py3-none-manylinux_2_28_x86_64.whl
Upload date: Aug 12, 2026
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

Hashes for zdog_template-0.1.1-py3-none-manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`84f75d7ebec44e492b734fd0d647fc36c7ded14699b2ab01e8410d5daa79708b`
MD5	`c7d0e2583cceb24fb8ffe1edee1bcb38`
BLAKE2b-256	`040a2700dc9fd400a45dc4a1c491b30f27fbc6812eae16b09a40f1793ccde8e2`

See more details on using hashes here.

Provenance

The following attestation bundles were made for zdog_template-0.1.1-py3-none-manylinux_2_28_x86_64.whl:

Publisher: release.yml on litterzhang/zdog-template

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: zdog_template-0.1.1-py3-none-manylinux_2_28_x86_64.whl
- Subject digest: 84f75d7ebec44e492b734fd0d647fc36c7ded14699b2ab01e8410d5daa79708b
- Sigstore transparency entry: 2434202237
- Sigstore integration time: Aug 12, 2026
Source repository:
- Permalink: litterzhang/zdog-template@63b126e69a03dfc5e70bc0067b22a695db8ac66c
- Branch / Tag: refs/tags/v0.1.1
- Owner: https://github.com/litterzhang
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@63b126e69a03dfc5e70bc0067b22a695db8ac66c
- Trigger Event: push

File details

Details for the file zdog_template-0.1.1-py3-none-macosx_26_0_arm64.whl.

File metadata

Download URL: zdog_template-0.1.1-py3-none-macosx_26_0_arm64.whl
Upload date: Aug 12, 2026
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

Hashes for zdog_template-0.1.1-py3-none-macosx_26_0_arm64.whl
Algorithm	Hash digest
SHA256	`93248329fbc481ea6df72addf96b6e33f58e14741a632fc3afff00c8a8b2d52a`
MD5	`ad356f75d230e89acf68af64a90559d8`
BLAKE2b-256	`bf60b5b0be8b1fc176a5e86d18bc3e1dc5083eded439acf1dfdc552811e020a7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for zdog_template-0.1.1-py3-none-macosx_26_0_arm64.whl:

Publisher: release.yml on litterzhang/zdog-template

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: zdog_template-0.1.1-py3-none-macosx_26_0_arm64.whl
- Subject digest: 93248329fbc481ea6df72addf96b6e33f58e14741a632fc3afff00c8a8b2d52a
- Sigstore transparency entry: 2434202278
- Sigstore integration time: Aug 12, 2026
Source repository:
- Permalink: litterzhang/zdog-template@63b126e69a03dfc5e70bc0067b22a695db8ac66c
- Branch / Tag: refs/tags/v0.1.1
- Owner: https://github.com/litterzhang
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@63b126e69a03dfc5e70bc0067b22a695db8ac66c
- Trigger Event: push

Release history Release notifications | RSS feed

This release

0.1.1

Aug 12, 2026

0.1.0

Aug 12, 2026

zdog-template 0.1.1

ztpl —— Z-Template Python SDK

安装

用法

四个批量操作

模板语法

映射表达式（JMESPath 子集）

性能

命令行

设计

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Tags

Classifiers

Download files

Source Distributions

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed