> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Miscs

> Support helpers, development-time utilities, and a compact module menu.

<Note>
  *Not everything fits a chapter. Some things fit a labeled junk drawer.*
</Note>

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.

<br />

## 1. Support Helper Menu

| 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                     |

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

<br />

## 2. Run a Command

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils import cmd

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

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

<br />

## 3. Map Bounded Work

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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(...)`.

<br />

## 4. Format Errors and Mismatches

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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()`.

<br />

## 5. Use Scoped Proxy Settings

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<br />

## 6. Log and Color Diagnostics

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [Overview](/features/utilities/overview) - the guided entry point for this section.
  * [File System](/features/utilities/file-system) - local paths and files used by command workflows.
  * [Configuration](/features/configuration) - config defaults for parallel worker limits and logging.
  * [Catalog](/features/catalog) - public naming and object discovery.
</Tip>

<br />