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.

File helpers keep local paths predictable. Use them when code needs to build paths, create folders, list files, or clean temporary artifacts.

​
1. Build paths with pj

pj joins path parts, expands ~ and environment variables, and normalizes separators for the current platform. 
from heavenbase.utils.files import pj

db_path = pj("demos", ".temp", "workspace.db", abs=True)
cache_path = pj("~/heavenbase-cache", "index.json", abs=True)
Aliases are explicit. Pass them at the call site so readers can see where a shortcut points: 
from heavenbase.utils.files import pj

path = pj("%/runs/latest.json", aliases={"%": "demos/.temp"}, abs=True)

​
2. Create and check files

Use touch_dir and touch_file before writing local artifacts. They create missing parents and return the resolved path as a string. 
from heavenbase.utils.files import exists_file, touch_dir, touch_file

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

assert exists_file(report)
Use clear=True when a folder or file should start empty: 
from heavenbase.utils.files import touch_dir

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

​
3. List and clean folders

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

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

for path in enum_files("demos/.temp", ext="json", abs=True):
    delete_path(path)
delete_dir and delete_path remove local data. Keep demo and benchmark artifacts under demos/.temp/ so cleanup never touches project files or user data.

​
4. Copy and inspect paths

Use copy_file, copy_dir, or copy_path when a workflow needs explicit conflict behavior. File copies support mode="replace", mode="skip", and mode="strict"; directory copies also support mode="merge". 
from heavenbase.utils.files import copy_path

copy_path("demos/.temp/source", "demos/.temp/archive", mode="merge")
copy_path("demos/.temp/report.md", "demos/.temp/latest.md", mode="replace")
Use folder_diagram for a compact file tree. The current implementation is intentionally simple: it supports single files, root names, basic annotations, limits, and depth caps. Future docs or LLM-oriented rendering can extend the same signature. 
from heavenbase.utils.files import folder_diagram

print(folder_diagram("demos/.temp", annotations={"latest.md": "current report"}, limit=12))

​
Further Exploration

Related resources:
  • Serialization utilities - read and write file contents.
  • Utilities overview - how utilities are grouped.