一个可复用的 Python 工程化工具库，覆盖：文件读写、日志、配置、计时器。
设计目标：函数式写法优先 + 类式封装补充 + 完整异常层 + typing + 性能基础实践。

flowchart TD
    A["业务代码 / CLI / Script"] --> B["统一 API: utils_lib.__init__"]
    B --> C["file_io 模块"]
    B --> D["logging_utils 模块"]
    B --> E["config 模块"]
    B --> F["timer 模块"]

    C --> C1["read or write text and json"]
    C --> C2["iter_lines and read_jsonl generators"]
    C --> C3["FileClient and atomic_write_text"]

    D --> D1["build_logger function"]
    D --> D2["LoggerFactory class"]
    D --> D3["RotatingFileHandler"]

    E --> E1["JSON or TOML loading"]
    E --> E2["APP_ env override"]
    E --> E3["AppConfig dataclass"]

    F --> F1["Timer context manager"]
    F --> F2["timeit decorator"]
    F --> F3["benchmark and iter_benchmark"]

    C --> G["exceptions.py"]
    D --> G
    E --> G
    F --> G

• utils_lib/file_io.py

  • 函数式：read_text write_text read_json write_json iter_lines read_jsonl atomic_write_text
  • 类式：FileClient(base_dir)
  • 性能与可靠性：iter_lines、read_jsonl 使用生成器；write_json 走原子写，减少中断导致半写入文件风险

• utils_lib/logging_utils.py

  • 函数式：build_logger
  • 类式：LoggerFactory
  • 支持控制台 + 文件滚动日志（RotatingFileHandler）

• utils_lib/config.py

  • 函数式：load_config(path, env_prefix="APP_")
  • 类式：ConfigManager
  • 数据模型：AppConfig(dataclass, slots=True)
  • 合并策略：文件配置 + 环境变量覆盖

• utils_lib/timer.py

  • 类式：Timer（上下文管理器）
  • 函数式：@timeit、benchmark
  • 生成器：iter_benchmark

• utils_lib/exceptions.py

  • UtilsError 基类 + 各模块细分异常，保证错误语义清晰

• 函数式 + 面向对象双 API，满足脚本与中大型项目两类使用场景
• 全模块 typing 注解（TypeAlias、ParamSpec、TypeVar、返回值类型）
• 异常分层：文件、配置、日志、计时错误可精准捕获
• 性能基础：
  • 列表推导：non_empty_lines、示例中的 word_count
  • 字典推导：环境变量筛选 _from_env
  • 生成器：iter_lines / read_jsonl / iter_benchmark

cd utils-codebase
pip install -e .

python -m examples.quickstart
pytest -q

from pathlib import Path
from utils_lib import write_json, load_config, build_logger, Timer, timeit

write_json("tmp/app.json", {
    "app_name": "resume-utils",
    "debug": True,
    "retries": 3,
    "timeout_sec": 1.2,
})

cfg = load_config("tmp/app.json", env_prefix="APP_")
logger = build_logger("app", log_file=Path("tmp/app.log"))

with Timer("task") as t:
    values = [i * i for i in range(10000)]
logger.info("values=%d cost=%.3fms", len(values), t.elapsed_ms or 0.0)

@timeit
def calc(n: int) -> int:
    return sum(x for x in range(n))

result, ms = calc(100000)
logger.info("result=%d cost=%.3fms", result, ms)

• 设计并实现 Python 工程化 utils 代码库（文件读写、日志、配置、计时器），采用函数式 + 类式双 API 架构，提升脚本与服务端项目复用性。
• 建立统一异常体系（UtilsError + 模块级异常）与完整类型注解，降低运行时故障定位成本并提升代码可维护性。
• 引入生成器/推导式等性能基础优化（流式读取 JSONL、环境变量字典推导、基准测试迭代器），在大文件与高频调用场景下减少内存占用。

utils-codebase/
├── pyproject.toml
├── README.md
├── examples/
│   └── quickstart.py
└── utils_lib/
    ├── __init__.py
    ├── config.py
    ├── exceptions.py
    ├── file_io.py
    ├── logging_utils.py
    ├── timer.py
    └── types.py