Skip to main content
File System utilities make local artifacts predictable: normalize the path, resolve aliases, use configured encodings, then read or write through one small contract.
Use this page when a demo, test, script, or extension needs predictable local files without hand-rolling path handling and serialization details.

​
1. Core Idea

pj(...) is the canonical path join helper. It joins path parts, expands ~ and environment variables, normalizes separators, optionally returns an absolute path, and can resolve caller-provided aliases. Think of it as a small path vocabulary. . means the current working location, ~ expands to the user home, environment variables expand through the operating system, and aliases such as % or & can point to a runtime folder or resource folder when the caller or config manager provides that alias map. File and serialization helpers wrap common I/O for the same reason configuration wraps hyperparameters: callers should not pass encoding, indentation, and platform path details through every function. Defaults such as heavenbase.serialize.encoding and heavenbase.serialize.indent live in CM_HVNB.
Utility pj(...) handles normal paths and caller aliases. CM_HVNB.pj(...) handles HeavenBase package aliases: %/ for package-local runtime data and &/ for package resources.

​
2. Build a Path

Use pj(...) for ordinary local paths: 
from heavenbase.utils import pj

project_root = pj(".", abs=True)
cache_file = pj("~/heavenbase-cache", "index.json", abs=True)
Pass aliases when the first path segment is a project-specific shortcut: 
from heavenbase.utils import pj

run_path = pj("%/runs/latest.json", aliases={"%": "demos/.temp"}, abs=True)
asset_path = pj("&/sample.txt", aliases={"&": "demos/assets"}, abs=True)
Use package aliases through the config manager: 
from heavenbase.utils import CM_HVNB

config_db = CM_HVNB.pj("%/config.db", abs=True)
default_yaml = CM_HVNB.pj("&/configs/default.yaml", abs=True)

​
3. Prepare Files and Folders

Use touch_dir(...) and touch_file(...) before writing artifacts. Both create missing parents and return an absolute path. 
from heavenbase.utils import exists_file, touch_dir, touch_file

root = touch_dir("demos/.temp/report")
summary = touch_file(f"{root}/summary.md", content="# Summary")

assert exists_file(summary)
Use clear=True only when the folder or file should start empty: 
from heavenbase.utils import touch_dir

run_dir = touch_dir("demos/.temp/run", clear=True)

​
4. Read and Write Data

Use JSON and YAML for machine-readable artifacts, text for human-readable output, and JSONL when a workflow appends one event at a time. 
from heavenbase.utils import append_jsonl, dump_json, load_json, pj, save_txt, touch_dir

root = touch_dir(pj("demos", ".temp", "docs-run"))
meta_path = pj(root, "meta.json")

dump_json({"workspace": "docs-demo", "rows": 3}, meta_path, sort_keys=True)
save_txt("# Run Notes", pj(root, "notes.md"))
append_jsonl({"event": "created", "path": meta_path}, pj(root, "events.jsonl"))

meta = load_json(meta_path)
Text encodings default to heavenbase.serialize.encoding, which is utf-8 in the default config. JSON and YAML indentation default to heavenbase.serialize.indent, which is 4.
load_pkl(...) reads Python pickle data. Use pickle only for trusted local artifacts produced by your own environment.

​
5. List, Copy, and Delete Artifacts

list_files(...) reads direct children. enum_files(...) walks recursively. Both return stable, case-insensitive order. 
from heavenbase.utils import copy_path, delete_path, enum_files, list_files

for name in list_files("demos/.temp/docs-run", ext="json"):
    print(name)

for path in enum_files("demos/.temp/docs-run", ext=["json", "jsonl"], abs=True):
    print(path)

copy_path("demos/.temp/docs-run", "demos/.temp/docs-run-copy", mode="merge")
delete_path("demos/.temp/docs-run-copy")
Copy helpers use explicit conflict modes. Files support replace, skip, and strict; directories also support merge.

​
6. Show a Folder Diagram

Use folder_diagram(...) for compact diagnostics in logs, reports, and docs snippets. 
from heavenbase.utils import folder_diagram

print(folder_diagram("demos/.temp/docs-run", annotations={"meta.json": "run metadata"}, limit=12))
delete_dir(...) and delete_path(...) remove local data. Keep demo cleanup targets under known temporary folders such as demos/.temp/.

​
Further Exploration

Related resources:
  • Configuration - config-driven defaults used by serialization helpers.
  • Hash - deterministic file-safe identifiers and fingerprints.
  • Development - command execution around local artifacts.