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.

heavenbase.utils is the small local toolbox HeavenBase uses for everyday runtime work: files, serialization, deterministic data generation, command execution, logs, color, and common Python typing helpers.

​
1. What belongs here

Use heavenbase.utils when you need a basic helper that should behave the same across HeavenBase code, demos, scripts, and tests. These helpers are intentionally short and boring. They keep repeated tasks out of feature code without asking you to learn a second framework. The public surface is grouped by job:
  • File and path helpers: pj, touch_dir, touch_file, list_files, enum_files, delete_path
  • Serialization helpers: load_json, dump_json, load_yaml, save_pkl, save_txt, iter_jsonl, load_b64, dump_hex
  • Reproducible data helpers: StableRNG, md5hash, hash_id
  • Runtime helpers: cmd, batch, abatch, pmap, NetworkProxy, safe_error, cstr
  • Common imports: Any, Dict, List, Optional, Sequence, dataclass, field

​
2. Public surface map

The top-level heavenbase.utils export mirrors the focused modules below. Import from the module when you want a narrower dependency boundary; import from heavenbase.utils in demos and small extensions.
  • utils.files: pj, touch_dir, touch_file, exists_*, list_*, enum_*, copy_*, delete_*, empty_dir, nonempty_dir, get_file_*, has_file_ext, folder_diagram
  • utils.serialize: load_*, dump_*, save_*, loads_*, dumps_*, iter_txt, append_txt, iter_jsonl, append_jsonl, HbJsonEncoder, HbJsonDecoder
  • utils.parallel: TaskResult, batch, batch_stream, abatch, abatch_stream, pmap, pforeach
  • utils.rng: StableRNG, interpret_seed, evolve_seed
  • utils.cmd: CmdResult, cmd, browse, clipboard, is_linux, is_macos, is_windows
  • utils.config: CM_HVNB, ConfigManager, ConfigStore, ConfigSnapshot, InterpolationPolicy, dget, dset, dsetdef, dunset, dmerge, dflat, dunflat
  • utils.log and utils.debug: get_logger, configure_logs, redirect_logs, suppress_logs, restore_logs, safe_error, ErrorRecord, capture_error, error_str, raise_mismatch, value_match, print_exception
  • utils.ids, utils.naming, and utils.ops: identifier validation, backend-safe table/index names, operation token constants, and operation-family lookup helpers
  • utils.strings and utils.color: Markdown builders, compact display helpers, text normalization, terminal color helpers, and strip_color
Every exposed utility function has a Google-style docstring with Args: and Returns: sections. Helpers with no parameters omit Args:, and side-effect helpers still document Returns: None.

​
3. Import pattern

Most users can import from the top-level utility surface: 
from heavenbase.utils import StableRNG, dump_json, pj, touch_dir

root = touch_dir(pj("demos", ".temp", "trial"))
dump_json({"seed": StableRNG(seed=42).rnd_int()}, pj(root, "meta.json"))
When you are writing implementation code and want a clearer dependency boundary, import from the focused module: 
from heavenbase.utils.files import pj, touch_dir
from heavenbase.utils.serialize import load_json

​
4. How to choose a helper

Start from the thing you are trying to do, not from the module name:
  • Building paths or touching local artifacts: see File and path utilities.
  • Reading and writing JSON, YAML, pickle, text, binary, or JSONL: see Serialization utilities.
  • Formatting names or display text: see String utilities.
  • Formatting errors, applying temporary proxy settings, running commands, mapping work in parallel, or generating deterministic mock data: see Common utilities and Function utilities.
For tests and benchmarks, prefer StableRNG(seed=...) over ad-hoc random data. Reusing a seed makes failures easier to reproduce and benchmark results easier to compare.

​
Further Exploration

Related resources:
  • Configuration - runtime defaults and scoped overrides.
  • File and path utilities - local file workflows.
  • Function utilities - deterministic RNG, command execution, and parallel helpers.