跳转到主要内容

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 是 HeavenBase 的小型本地工具箱，覆盖文件、序列化、可复现数据、命令执行、日志脱敏、终端颜色和常用 Python 类型导入。

​
1. 这里放什么

当你需要一个在代码、脚本、demo 和测试里都保持一致的基础 helper 时，优先看 heavenbase.utils。这些 API 刻意保持短小，避免每个模块各自写一套路径、JSON、随机数或错误脱敏逻辑。 常用分组：
  • 文件和路径：pj, touch_dir, touch_file, list_files, enum_files, delete_path
  • 序列化：load_json, dump_json, load_yaml, save_pkl, save_txt, iter_jsonl, load_b64, dump_hex
  • 可复现数据：StableRNG, md5hash, hash_id
  • 运行时辅助：cmd, batch, abatch, pmap, NetworkProxy, safe_error, cstr
  • 常用导入：Any, Dict, List, Optional, Sequence, dataclass, field

​
2. 公开工具面

顶层 heavenbase.utils 导出与各聚焦模块保持同步。demo 和小扩展可以从顶层导入；底层实现代码如果想让依赖边界更清楚，可以从具体模块导入。
  • 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 与 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, utils.ops：标识符校验、后端安全表名/索引名、操作 token 常量和操作族查询
  • utils.strings 与 utils.color：Markdown 构建、紧凑展示、文本归一化、终端颜色和 strip_color
每个公开 utility 函数都有 Google 风格 docstring，并包含 Args: 和 Returns:。没有参数的函数会省略 Args:；只做副作用的函数也会明确写 Returns: None。

​
3. 导入方式

大多数情况下可以直接从顶层导入： 
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"))
如果你在实现底层模块，想让依赖边界更清楚，也可以从具体模块导入： 
from heavenbase.utils.files import pj, touch_dir
from heavenbase.utils.serialize import load_json

​
4. 如何选择 helper

按任务选择，而不是先记模块名：
  • 要创建路径、目录或清理本地 artifact，看文件和路径工具。
  • 要读写 JSON、YAML、pickle、文本、二进制或 JSONL，看序列化工具。
  • 要格式化名称或展示文本，看字符串工具。
  • 要格式化错误、临时设置网络代理、运行命令、并行处理或生成可复现 mock data，看通用工具和函数工具。
测试和 benchmark 里优先用 StableRNG(seed=...)，不要临时使用全局随机数。固定 seed 会让失败和性能结果更容易复现。

​
Further Exploration

相关资源：
  • 配置 - 运行时默认值和作用域覆盖。
  • 文件和路径工具 - 本地文件工作流。
  • 函数工具 - StableRNG、命令执行和并行 helper。