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

# 杂项

> 支持类 helper、开发期工具，以及紧凑的模块菜单。

<Note>
  *并非一切都能成章。有些东西适合放进贴了标签的杂物抽屉。*
</Note>

当你阅读 HeavenBase 内部实现并需要识别某个 helper 时，请使用本页。编写新应用代码时，请优先使用本节中的专题页与功能文档。

<br />

## 1. 支持 Helper 菜单

| 需求                    | 模块                                               | 状态            |
| --------------------- | ------------------------------------------------ | ------------- |
| Typing 与 dataclass 桥接 | `heavenbase.utils.typing`                        | 迁移桥接          |
| 单层列表扁平化               | `heavenbase.utils.containers`                    | 小型公开 helper   |
| 小型值强制转换               | `heavenbase.utils.coerce`                        | 小型公开 helper   |
| 公开 ID 校验              | `heavenbase.utils.ids`                           | 有用的公开支持       |
| 配置 CLI 解析与操作          | `heavenbase.utils.config_api`                    | CLI/支持 helper |
| 配置引擎规范                | `heavenbase.utils.spec`                          | 支持 helper     |
| 命令执行                  | `heavenbase.utils.cmd`                           | 小型公开 helper   |
| 并行与异步批量工作             | `heavenbase.utils.parallel`                      | 小型公开 helper   |
| 错误格式化与捕获              | `heavenbase.utils.debug`                         | 小型公开 helper   |
| 作用域代理设置               | `heavenbase.utils.network`                       | 小型公开 helper   |
| 日志与日志路由               | `heavenbase.utils.log`                           | 小型公开 helper   |
| 终端颜色诊断                | `heavenbase.utils.color`                         | 小型公开 helper   |
| Backend 安全命名          | `heavenbase.utils.ids`、`heavenbase.utils.naming` | 系统面向，避免新应用依赖  |
| Operation token       | `heavenbase.utils.ops`                           | 系统面向，预计迁移     |
| Registry 键解析          | `heavenbase.utils.registry_identity`             | 系统面向，预计迁移     |
| 数据库 URL token         | `heavenbase.utils.db_path`                       | 系统面向支持        |

<Info>
  当前的 `heavenbase.utils.typing` 是常见导入的迁移桥接，有意不提供 legacy `autotype`、`jsonschema_type` 或 `parse_func_sig`。
</Info>

<br />

## 2. 运行命令

当你需要以数据形式获取 stdout、stderr 与退出码时，使用 `cmd(...)`。

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

调用方只需其中一个字段时，可单独请求：

```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>
  序列命令不会调用 shell，除非你传入 `shell=True`。对用户提供的值请优先使用序列命令。
</Note>

<br />

## 3. 映射有界工作

当工作可并发执行且返回值必须保持输入顺序时，使用 `pmap(...)`。

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

每个项作为关键字参数传入，因此 batch 项必须是 mapping。

当你需要每项状态、捕获异常、耗时或进度回调时，使用 `batch(...)`。

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

异步代码通过 `abatch(...)` 与 `abatch_stream(...)` 遵循相同契约。

<br />

## 4. 格式化错误与不匹配

当校验应建议最接近的支持值时，使用 `raise_mismatch(...)`。

```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(...)` 返回 `ErrorRecord`，可通过 `record.reraise()` 保留原始异常。

<br />

## 5. 使用作用域代理设置

当某次操作需要临时设置 `HTTP_PROXY`、`HTTPS_PROXY` 或 `NO_PROXY` 环境变量时，使用 `NetworkProxy`。

```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"):
    ...
```

上下文退出时会恢复原有环境值。传入空字符串会在上下文内禁用对应代理变量。

<br />

## 6. 日志与颜色诊断

使用 `get_logger(...)` 输出 HeavenBase 日志，使用 `redirect_logs(...)` 或 `suppress_logs(...)` 做临时诊断路由。

```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()
```

`cstr(...)`、`color_success(...)` 与 `strip_color(...)` 等颜色 helper 用于终端诊断。不要在 JSON、行或基准测试产物中存储带颜色的字符串。

<br />

## 进一步探索

<Tip>
  **相关资源：**

  * [概述](/features/utilities/overview) - 本节导览入口。
  * [文件系统](/features/utilities/file-system) - 命令工作流使用的本地路径与文件。
  * [配置](/features/configuration) - 并行 worker 限制与日志的配置默认值。
  * [目录](/features/catalog) - 公开命名与对象发现。
</Tip>

<br />