Skip to main content

Documentation Index

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

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

Serialization helpers give HeavenBase one small contract for reading and writing local data files.

​
1. JSON and YAML

Use JSON for machine-readable artifacts, configs, and benchmark output. Missing non-strict files return {} so optional local files are easy to read. Text encodings default to heavenbase.serialize.encoding (utf-8 by default), and JSON/YAML indentation defaults to heavenbase.serialize.indent (4 by default). Pass encoding=... or indent=... when a file needs a local override. 
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")
Use strict mode when a missing file is a real error: 
from heavenbase.utils.serialize import load_json

data = load_json("required.json", strict=True)
YAML follows the same shape with load_yaml, dump_yaml, loads_yaml, and dumps_yaml.

​
2. Text and JSONL streams

Use save_txt for human-readable output. It writes a trailing newline, which keeps generated Markdown and logs tidy. 
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")
Use append_txt, iter_txt, append_jsonl, and iter_jsonl for streaming-style files that grow one record at a time. 
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. Binary, Base64, hex, and pickle

Use dump_bin and load_bin for raw bytes. load_b64 and load_hex encode an existing binary file to a string; dump_b64 and dump_hex decode a string and write the resulting 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"
Use pickle only for trusted local artifacts. It is useful for internal snapshots, not for data from untrusted users. 
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")
The longer aliases dump_pickle, load_pickle, save_pickle, dumps_pickle, and loads_pickle are also exposed for readability.
load_pkl executes Python pickle loading. Only open pickle files produced by your own trusted environment.

​
4. Round-trip behavior

JSON helpers preserve common Python values such as tuples, sets, dates, Decimal, and large integers through small type markers. That keeps HeavenBase-generated metadata stable without asking users to manage custom encoders. 
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")
Use compact=True with dumps_json or dump_json when a one-line JSON representation is required. JSONL helpers already use compact per-line JSON. Callable JSON serialization is intentionally conservative. Do not treat callable objects as portable JSON data; durable callable metadata belongs in the Capsule and prompt surfaces rather than generic file helpers.

​
Further Exploration

Related resources:
  • File and path utilities - create folders and build paths before writing files.
  • Function utilities - deterministic data generation for test fixtures.