跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://ahvn.top/llms.txt

Use this file to discover all available pages before exploring further.

序列化 helper 为本地数据读写提供统一的小契约。

​
1. JSON 和 YAML

JSON 适合机器可读 artifact、配置和 benchmark 输出。非 strict 模式下，缺失 JSON 文件会返回 {}。 文本编码默认读取 heavenbase.serialize.encoding（默认 utf-8），JSON/YAML 缩进默认读取 heavenbase.serialize.indent（默认 4）。单个文件需要特殊行为时传入 encoding=... 或 indent=... 覆盖即可。 
from heavenbase.utils.serialize import dump_json, load_json

dump_json({"backend": "sqlite", "rows": 1000}, "demos/.temp/run.json", sort_keys=True)
data = load_json("demos/.temp/run.json")
缺文件应该报错时使用 strict 模式： 
data = load_json("required.json", strict=True)
YAML 使用同样的形状：load_yaml, dump_yaml, loads_yaml, dumps_yaml。

​
2. 文本和 JSONL 流

save_txt 写入文本并保留结尾换行，适合生成 Markdown 和日志片段。 
from heavenbase.utils.serialize import append_jsonl, save_txt

save_txt("# Benchmark notes", "demos/.temp/notes.md")
append_jsonl({"stage": "build", "seconds": 0.12}, "demos/.temp/events.jsonl")
append_txt, iter_txt, append_jsonl, iter_jsonl 适合一条条追加和读取的文件。 
from heavenbase.utils.serialize import append_txt, iter_jsonl

append_txt("ready", "demos/.temp/events.log")
events = list(iter_jsonl("demos/.temp/events.jsonl"))

​
3. 二进制、Base64、hex 和 pickle

dump_bin 和 load_bin 处理原始 bytes。load_b64 与 load_hex 会把已有二进制文件编码成字符串；dump_b64 与 dump_hex 会把字符串解码后写成 bytes。 
from heavenbase.utils.serialize import dump_b64, dump_hex, load_b64, load_hex

dump_b64("aGVsbG8=", "demos/.temp/hello.bin")
assert load_b64("demos/.temp/hello.bin") == "aGVsbG8="

dump_hex("00ff10", "demos/.temp/payload.bin")
assert load_hex("demos/.temp/payload.bin") == "00ff10"
pickle 只适合可信本地 artifact。 
from heavenbase.utils.serialize import load_pkl, save_pkl

save_pkl({"rows": ["p1", "p2"]}, "demos/.temp/snapshot.pkl")
rows = load_pkl("demos/.temp/snapshot.pkl")
load_pkl 会执行 Python pickle 加载。只读取你自己可信环境生成的 pickle 文件。

​
4. Round-trip 行为

JSON helper 会保留 tuple、set、date、Decimal 和大整数等常见 Python 值，用户不需要手写 encoder。 
from decimal import Decimal
from heavenbase.utils.serialize import dump_json, load_json

payload = {"coords": (1, 2), "tags": {"blue", "green"}, "amount": Decimal("12.3400")}
dump_json(payload, "demos/.temp/payload.json")
assert load_json("demos/.temp/payload.json")["coords"] == (1, 2)
assert load_json("demos/.temp/payload.json")["amount"] == Decimal("12.3400")
需要单行 JSON 时，给 dumps_json 或 dump_json 传 compact=True。JSONL helper 已经默认使用每行 compact JSON。 Callable JSON 序列化是保守的。不要把 callable 当成可移植 JSON 数据；长期 callable 元数据属于 Capsule 和 prompt 能力，而不是通用文件 helper。

​
Further Exploration

相关资源：
  • 文件和路径工具 - 写文件前创建目录和路径。
  • 函数工具 - 为测试夹具生成可复现数据。