Miscs

Not everything fits a chapter. Some things fit a labeled junk drawer.

Use this page when you are reading HeavenBase internals and need to recognize a helper. For new application code, prefer the focused pages in this section and the feature docs.

Need	Module	Status
Typing and dataclass bridge	`heavenbase.utils.typing`	Migration bridge
One-level list flattening	`heavenbase.utils.containers`	Small public helper
Small value coercion	`heavenbase.utils.coerce`	Small public helper
Public ID validation	`heavenbase.utils.ids`	Useful public support
Config CLI parsing and operations	`heavenbase.utils.config_api`	CLI/support helper
Config engine specs	`heavenbase.utils.spec`	Support helper
Command execution	`heavenbase.utils.cmd`	Small public helper
Parallel and async batch work	`heavenbase.utils.parallel`	Small public helper
Error formatting and capture	`heavenbase.utils.debug`	Small public helper
Scoped proxy settings	`heavenbase.utils.network`	Small public helper
Logging and log routing	`heavenbase.utils.log`	Small public helper
Terminal color diagnostics	`heavenbase.utils.color`	Small public helper
Backend-safe names	`heavenbase.utils.ids`, `heavenbase.utils.naming`	System-facing, avoid new app dependencies
Operation tokens	`heavenbase.utils.ops`	System-facing, expected to move
Registry key resolution	`heavenbase.utils.registry_identity`	System-facing, expected to move
Database URL tokens	`heavenbase.utils.db_path`	System-facing support

Current heavenbase.utils.typing is a migration bridge for common imports. It intentionally does not provide legacy autotype, jsonschema_type, or parse_func_sig.

2. Run a Command

Use cmd(...) when you need stdout, stderr, and the exit code as data.

from heavenbase.utils import cmd

result = cmd(["python", "--version"])

if not result.ok:
    raise RuntimeError(result.err)

print(result.out)

Ask for one field when the caller only needs that field:

from heavenbase.utils import cmd

version = cmd(["python", "--version"], include="out")
handle = cmd(["python", "-m", "http.server", "8000"], wait=False, include="handle")

Sequence commands do not invoke a shell unless you pass shell=True. Prefer sequence commands for user-provided values.

3. Map Bounded Work

Use pmap(...) when work can run concurrently and the returned values must stay in input order.

from heavenbase.utils import pmap

items = [{"score": 3}, {"score": 1}, {"score": 2}]
scores = pmap(lambda score: score * 2, items, max_workers=4)

Each item is passed as keyword arguments, so batch items must be mappings. Use batch(...) when you need per-item status, captured exceptions, elapsed time, or progress callbacks.

from heavenbase.utils import batch

results = batch(lambda x: 10 / x, [{"x": 2}, {"x": 0}, {"x": 5}], max_workers=2)

failed = [result for result in results if not result.ok]

Async code uses the same contract through abatch(...) and abatch_stream(...).

4. Format Errors and Mismatches

Use raise_mismatch(...) when validation should suggest the closest supported value.

from heavenbase.utils import capture_error, error_str, raise_mismatch

try:
    raise_mismatch(["json", "yaml"], "jsno", name="format")
except ValueError as exc:
    message = error_str(exc, tb=False)
    record = capture_error(exc)

capture_error(...) returns an ErrorRecord that can preserve the original exception through record.reraise().

5. Use Scoped Proxy Settings

Use NetworkProxy when one operation needs temporary HTTP_PROXY, HTTPS_PROXY, or NO_PROXY environment variables.

from heavenbase.utils import NetworkProxy

with NetworkProxy(http_proxy="http://localhost:7890", no_proxy="localhost,127.0.0.1"):
    ...

Existing environment values are restored when the context exits. Passing an empty string disables that proxy variable inside the context.

6. Log and Color Diagnostics

Use get_logger(...) for HeavenBase log output, and redirect_logs(...) or suppress_logs(...) for temporary diagnostic routing.

from heavenbase.utils import get_logger, redirect_logs, restore_logs, suppress_logs

logger = get_logger("heavenbase.docs")
logger.success("ready")

redirect_logs("demos/.temp/heavenbase.log")
try:
    logger.warning("written to the log file")
finally:
    restore_logs()

suppress_logs()
restore_logs()

Color helpers such as cstr(...), color_success(...), and strip_color(...) are for terminal diagnostics. Do not store colored strings in JSON, rows, or benchmark artifacts.

Further Exploration

Related resources:

Overview - the guided entry point for this section.
File System - local paths and files used by command workflows.
Configuration - config defaults for parallel worker limits and logging.
Catalog - public naming and object discovery.

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Support Helper Menu

2. Run a Command

3. Map Bounded Work

4. Format Errors and Mismatches

5. Use Scoped Proxy Settings

6. Log and Color Diagnostics

Further Exploration

​1. Support Helper Menu

​2. Run a Command

​3. Map Bounded Work

​4. Format Errors and Mismatches

​5. Use Scoped Proxy Settings

​6. Log and Color Diagnostics

​Further Exploration

1. Support Helper Menu

2. Run a Command

3. Map Bounded Work

4. Format Errors and Mismatches

5. Use Scoped Proxy Settings

6. Log and Color Diagnostics

Further Exploration