small-toolkit 0.1.1__py3-none-any.whl

small_toolkit/__init__.py

@@ -0,0 +1,62 @@
+"""small_toolkit：纯标准库的通用小工具（产物目录 / 日志 / 命令行 / 终端表格）。
+
+分区：:mod:`small_toolkit.outputs` 路径与落盘、:mod:`small_toolkit.logs` 日志初始化、
+:mod:`small_toolkit.cli` 命令行参数、:mod:`small_toolkit.table` 终端表格。全部零第三方依赖、
+不读凭据、不含内网地址。
+"""
+
+from .cli import (
+    add_grouped_subparsers,
+    add_parameter,
+    resolve_env_var,
+    resolve_parameters,
+)
+from .logs import (
+    DEBUG_HELP,
+    add_debug_argument,
+    enable_debug_logging,
+    set_log_env,
+    setup_job,
+)
+from .outputs import (
+    WORKSPACE_MARKERS,
+    display_path,
+    env_suffix,
+    get_output_dir,
+    output_dir,
+    output_root,
+    save_bytes,
+    save_json,
+    save_response,
+    tool_dir_name,
+    tool_output_dir,
+    write_json,
+)
+from .table import print_grouped_table, print_table, print_tree
+
+__all__ = [
+    "DEBUG_HELP",
+    "WORKSPACE_MARKERS",
+    "add_debug_argument",
+    "add_grouped_subparsers",
+    "add_parameter",
+    "display_path",
+    "enable_debug_logging",
+    "env_suffix",
+    "get_output_dir",
+    "output_dir",
+    "output_root",
+    "print_grouped_table",
+    "print_table",
+    "print_tree",
+    "resolve_env_var",
+    "resolve_parameters",
+    "save_bytes",
+    "save_json",
+    "save_response",
+    "set_log_env",
+    "setup_job",
+    "tool_dir_name",
+    "tool_output_dir",
+    "write_json",
+]

small_toolkit/cli.py

@@ -0,0 +1,146 @@
+"""命令行辅助：分组子命令帮助、CLI / 占位符 / 环境变量 / 默认值的参数回退。"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import os
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+#: 平台代码参数占位符（形如 ``${name}``）：解析时视为未设置
+_PLACEHOLDER = re.compile(r"^\$\{[^{}]+\}$")
+
+CommandGroups = Mapping[str, Sequence[tuple[str, str]]]
+
+
+def add_grouped_subparsers(
+    parser: argparse.ArgumentParser,
+    groups: CommandGroups,
+    *,
+    dest: str = "command",
+    footer: str | None = None,
+) -> dict[str, argparse.ArgumentParser]:
+    """注册按领域分组的子命令，并将统一命令清单加入帮助描述。"""
+    commands = [(name, help_text) for items in groups.values() for name, help_text in items]
+    if not commands:
+        raise ValueError("命令分组不能为空")
+
+    width = max(len(name) for name, _ in commands)
+    lines = []
+    for title, items in groups.items():
+        if lines:
+            lines.append("")
+        lines.append(f"{title}:")
+        lines.extend(f"  {name:<{width}}  {help_text}" for name, help_text in items)
+    if footer:
+        lines.extend(("", footer))
+
+    description = parser.description or ""
+    parser.description = "\n\n".join(part for part in (description, "\n".join(lines)) if part)
+    parser.formatter_class = argparse.RawDescriptionHelpFormatter
+
+    subparsers = parser.add_subparsers(dest=dest, metavar="命令")
+    result = {}
+    for name, _ in commands:
+        sub = subparsers.add_parser(name)
+        # 缺必选参数时显示帮助而非 argparse 默认的 usage+error
+        sub.error = lambda msg, self=sub: (self.print_help(), self.exit(2))
+        result[name] = sub
+    return result
+
+
+def add_parameter(
+    parser: argparse.ArgumentParser,
+    option: str,
+    *aliases: str,
+    default: Any = None,
+    parameter: Any = None,
+    env: str | None = None,
+    **kwargs: Any,
+) -> None:
+    """添加本地 CLI 参数，并登记平台代码参数占位符与环境变量回退。
+
+    ``parameter`` 为平台注入的代码参数值，``env`` 为环境变量名；取值优先级由
+    :func:`resolve_parameters` 统一处理（CLI → ``parameter`` → 环境变量 → ``default``）。
+    """
+    if not option.startswith("--"):
+        raise ValueError("参数必须使用长选项，例如 --database")
+
+    name = option[2:].replace("-", "_")
+    # 属性名沿用既有工具链（UI 扫描器按此名读取参数规格），勿改名
+    specs = getattr(parser, "_dataphin_parameter_specs", {})
+    if name in specs:
+        raise ValueError(f"重复的参数配置: {option}")
+
+    parser.add_argument(option, *aliases, default=None, **kwargs)
+    specs[name] = {"default": default, "parameter": parameter, "env": env, "type": kwargs.get("type")}
+    parser._dataphin_parameter_specs = specs
+    parser.set_defaults(_dataphin_parameter_specs=specs)
+
+
+def resolve_parameters(args: argparse.Namespace) -> argparse.Namespace:
+    """按 CLI、平台代码参数、环境变量、默认值的顺序填充参数。"""
+    for name, spec in getattr(args, "_dataphin_parameter_specs", {}).items():
+        value = getattr(args, name)
+        if _is_unset(value):
+            value = _parameter_value(spec["parameter"])
+        if _is_unset(value) and spec["env"]:
+            value = os.getenv(spec["env"])
+        if _is_unset(value):
+            value = spec["default"]
+        elif spec["type"] and isinstance(value, str):
+            value = spec["type"](value)
+        setattr(args, name, value)
+    return args
+
+
+def _is_unset(value: Any) -> bool:
+    return value is None or value == "" or (isinstance(value, str) and _PLACEHOLDER.fullmatch(value))
+
+
+def _parameter_value(value: Any) -> Any:
+    if not isinstance(value, str) or _is_unset(value):
+        return value
+    if len(value) >= 2 and value[0] in "'\"" and value[-1] == value[0]:
+        try:
+            return ast.literal_eval(value)
+        except (SyntaxError, ValueError):
+            pass
+    return value
+
+
+def resolve_env_var(env: str, base_name: str) -> str | None:
+    """按优先级解析多环境变量：
+
+    1. ``{base_name}_LIST`` — 分号分隔的 ``env=value`` 格式（最高优先级）
+    2. ``{base_name}_{ENV}`` — 单环境变量
+    3. ``{base_name}`` — 仅 ``env=prod`` 时回退到原生变量名
+
+    任一来源有值（含空字符串）即返回，全缺失返回 ``None``。非 prod 环境不会读原生变量，
+    避免旧单环境凭据被误当作测试/开发环境配置。
+
+    例（值由外部注入，本库不读写凭据）::
+
+        # _LIST = "tst=doris-tst:8030;prod=doris-prod:8030"
+        resolve_env_var("tst", "DW_doris_RW_url")  # -> "doris-tst:8030"
+    """
+    # 1. LIST 格式
+    list_raw = os.environ.get(f"{base_name}_LIST", "").strip()
+    if list_raw:
+        for part in list_raw.split(";"):
+            part = part.strip()
+            if "=" in part:
+                k, v = part.split("=", 1)
+                if k.strip() == env:
+                    return v.strip()
+    # 2. 单环境变量 {KEY}_{ENV}
+    env_val = os.environ.get(f"{base_name}_{env.upper()}", "").strip()
+    if env_val:
+        return env_val
+    # 3. 回退原生变量（仅 prod 环境）
+    if env.lower() == "prod":
+        fallback = os.environ.get(base_name, "").strip()
+        return fallback or None
+    return None

small_toolkit/logs.py

@@ -0,0 +1,223 @@
+"""日志初始化：控制台着色、按环境隔离的文件日志与 ``--debug`` 开关。
+
+默认只输出到控制台；``setup_job(..., log_file=True)`` 额外落盘到
+``<产物根>/output/logs/``。控制台着色只在真终端生效——管道、重定向、子进程捕获
+都不是真终端，一律纯文本；落盘日志始终纯文本。
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import re
+from datetime import datetime
+from pathlib import Path
+
+from .outputs import env_suffix, get_output_dir
+
+#: ``--debug`` 的统一帮助文案（口径：输出调用摘要、不输出完整请求/响应正文）
+DEBUG_HELP = "启用 DEBUG 诊断日志（输出调用摘要，不输出完整请求/响应正文）"
+
+#: ANSI 控制序列：消息正文按级别 / 角色着色（时间戳与级别名前缀保持终端默认色）
+_RESET = "\033[0m"
+
+#: 日志级别 -> 消息正文颜色（INFO 留空 = 终端默认色，不加控制序列）
+_LEVEL_COLORS = {
+    "DEBUG": "\033[36m",
+    "INFO": "",
+    "WARNING": "\033[33m",
+    "ERROR": "\033[31m",
+    "CRITICAL": "\033[31m",
+}
+
+#: INFO 行首角色标记 -> 整行颜色（允许缩进，判定前先 lstrip）。
+#: ``▸`` 任务行保持默认色，故不登记。
+_ROLE_COLORS = {
+    "━━": "\033[1m\033[36m",  # 阶段标题：粗体青
+    "≠": "\033[33m",  # 差异：黄
+    "⚠": "\033[1m\033[33m",  # 告警：粗体黄
+    "✗": "\033[1m\033[31m",  # 失败：粗体红
+    "·": "\033[2m",  # 次级信息：暗淡
+}
+
+#: 行首「两空格 + 块内标签」只给标签着青色
+_FIELD_LABELS = ("输入", "查询", "映射", "分组", "产物", "任务名模板", "管道目标", "结果")
+_FIELD_LINE_RE = re.compile(
+    "(  )(" + "|".join(sorted(_FIELD_LABELS, key=len, reverse=True)) + r")(\s)"
+)
+
+
+def _role_color(message: str) -> str:
+    """消息行首角色标记对应的整行颜色；无标记返回空串（保持终端默认色）。"""
+    stripped = message.lstrip()
+    for marker, color in _ROLE_COLORS.items():
+        if stripped.startswith(marker):
+            return color
+    return ""
+
+
+def _message_offset(text: str, message: str) -> int | None:
+    """消息在整行渲染结果里的起始位置（默认格式 = 前缀 + 消息后缀）。"""
+    if not message or not text.endswith(message):
+        return None
+    return len(text) - len(message)
+
+
+def _color_enabled(stream) -> bool:
+    """控制台是否着色：真终端，且未被 ``NO_COLOR`` / ``TERM=dumb`` 关闭。
+
+    管道、重定向、子进程捕获、平台调度都不是真终端 → 一律纯文本。
+    ``NO_COLOR`` 按 no-color.org 约定：设了非空值即关闭。
+    """
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM", "").lower() == "dumb":
+        return False
+    isatty = getattr(stream, "isatty", None)
+    return bool(isatty and isatty())
+
+
+class _ColorFormatter(logging.Formatter):
+    """给控制台的**消息正文**着色的 Formatter（时间戳 / 级别名前缀保持终端默认色）。
+
+    角色标记（``━━`` / ``≠`` / ``⚠`` / ``✗`` / ``·``）优先于级别色——``⚠`` / ``✗``
+    用角色表里的粗体色，其余按级别（WARNING 黄 / ERROR 红 / DEBUG 青）；INFO 无角色
+    标记时再看「两空格 + 块内标签」（如 ``输入`` / ``任务名模板``），只给标签着青色。
+
+    落盘日志不挂本 Formatter（文件 handler 用默认 Formatter），文件里始终是纯文本。
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        message = record.getMessage()
+        text = super().format(record)
+        offset = _message_offset(text, message)
+        if offset is None:
+            return text
+        color = _role_color(message) or _LEVEL_COLORS.get(record.levelname, "")
+        if color:
+            return f"{text[:offset]}{color}{text[offset:]}{_RESET}"
+        match = _FIELD_LINE_RE.match(message)
+        if match:
+            return (
+                f"{text[: offset + match.start(2)]}\033[36m{match.group(2)}\033[0m"
+                f"{text[offset + match.end(2):]}"
+            )
+        return text
+
+
+class _LazyDirFileHandler(logging.FileHandler):
+    """延迟建目录的 FileHandler：首次 emit 才 ``mkdir``，import 期不产生空目录。"""
+
+    def __init__(self, filename: str | Path, encoding: str = "utf-8") -> None:
+        super().__init__(filename, encoding=encoding, delay=True)
+        self._dir_ready = False
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if not self._dir_ready:
+            Path(self.baseFilename).parent.mkdir(parents=True, exist_ok=True)
+            self._dir_ready = True
+        super().emit(record)
+
+
+def setup_job(
+    script_path: str | Path,
+    *,
+    log_file: bool | str | Path = False,
+    level: int = logging.INFO,
+    format: str = "%(asctime)s - %(levelname)s - %(message)s",
+    datefmt: str = "%m-%d %H:%M:%S",
+) -> logging.Logger:
+    """初始化脚本运行环境：配置 logging。
+
+    - 默认配置 StreamHandler（控制台输出）。
+    - 控制台是真终端时按级别 / 角色着色（只给消息正文上色）；管道、重定向、子进程
+      捕获下自动关闭，落盘文件始终是纯文本。
+    - ``log_file=True`` 时自动在 ``<产物根>/output/logs/`` 下创建 ``<脚本名>_<YYYYMMDD>.log``
+      文件处理器（非 tst 环境由主流程解析参数后调 :func:`set_log_env` 改名）。
+    - ``log_file`` 为自定义字符串或 Path 时，创建对应文件处理器（相对路径基于 ``output/logs/``）。
+    - 目录在**首次落日志时**才创建（import 期调用不产生空目录）。
+    - 返回对应模块的 Logger。
+    """
+    console = logging.StreamHandler()
+    handlers: list[logging.Handler] = [console]
+    if log_file:
+        if isinstance(log_file, bool):
+            filename = f"{Path(script_path).stem}_{datetime.now():%Y%m%d}.log"
+            log_path = get_output_dir(script_path, "logs", create=False) / filename
+        else:
+            log_path = Path(log_file)
+            if not log_path.is_absolute():
+                log_path = get_output_dir(script_path, "logs", create=False) / log_path
+        handlers.append(_LazyDirFileHandler(log_path))
+
+    logging.basicConfig(level=level, format=format, datefmt=datefmt, handlers=handlers, force=True)
+
+    # 颜色只给控制台：文件日志保持 basicConfig 挂的默认 Formatter（纯文本）
+    if _color_enabled(console.stream):
+        console.setFormatter(_ColorFormatter(format, datefmt))
+    return logging.getLogger(Path(script_path).stem)
+
+
+#: setup_job 自动日志文件名（``<脚本名>_<YYYYMMDD>.log``）的识别模式
+_AUTO_LOG_NAME_RE = re.compile(r"(.+)_(\d{8})\.log$")
+
+
+def set_log_env(env: str | None) -> Path | None:
+    """把 ``setup_job(log_file=True)`` 自动创建的文件日志按环境改名：非 tst 重写为
+    ``<脚本名>@<env 小写>_<YYYYMMDD>.log``（如 ``intake_tool@prod_20261031.log``）。
+
+    在脚本 ``main()`` 解析出 ``-e/--env`` 后调用一次；tst（含未传，大小写不敏感）不动，
+    保持 ``<脚本名>_<YYYYMMDD>.log``。只处理自动命名的 FileHandler；自定义
+    ``log_file=...`` 的不动。env 归一与产物目录同一套（:func:`env_suffix`）。
+    调用前已写出的行留在原名文件里（handler 是 ``delay=True``，通常调用时文件尚未创建）。
+    返回新日志路径；无需改名或没有自动命名 FileHandler 时返回 ``None``。
+    """
+    suffix = env_suffix(env)
+    if not suffix:
+        return None
+    root = logging.getLogger()
+    new_path: Path | None = None
+    for handler in root.handlers[:]:
+        if not isinstance(handler, logging.FileHandler):
+            continue
+        old_path = Path(handler.baseFilename)
+        match = _AUTO_LOG_NAME_RE.fullmatch(old_path.name)
+        if not match:
+            continue
+        # 先剥离可能已有的 @env 后缀，保证连续调用幂等（不叠成 @prod@uat@prod）
+        base = match.group(1).split("@", 1)[0]
+        candidate = old_path.with_name(f"{base}{suffix}_{match.group(2)}.log")
+        if candidate == old_path:
+            continue
+        replacement = _LazyDirFileHandler(candidate)
+        replacement.setFormatter(handler.formatter)
+        replacement.setLevel(handler.level)
+        root.removeHandler(handler)
+        handler.close()
+        root.addHandler(replacement)
+        new_path = candidate
+    return new_path
+
+
+def add_debug_argument(parser: argparse.ArgumentParser, *, help: str = DEBUG_HELP) -> None:
+    """注册 ``--debug``：输出诊断日志与调用摘要（完整请求/响应正文仍不落日志）。
+
+    默认 ``argparse.SUPPRESS``，因此带子命令的入口可在顶层与子命令各注册一次，
+    使 ``--debug`` 放在子命令前或后都能生效；判断统一交给 :func:`enable_debug_logging`。
+    """
+    parser.add_argument("--debug", action="store_true", default=argparse.SUPPRESS, help=help)
+
+
+def enable_debug_logging(args: argparse.Namespace, *, level: int = logging.DEBUG) -> None:
+    """``--debug`` 生效：root 与既有 handler 一并切到 ``level``；未开启时不动任何级别。
+
+    :func:`setup_job` 用 ``basicConfig(handlers=[...], force=True)`` 建好 handler，
+    只改 root 级别不足以放行 DEBUG，故两层都改。
+    """
+    if not getattr(args, "debug", False):
+        return
+    root = logging.getLogger()
+    root.setLevel(level)
+    for handler in root.handlers:
+        handler.setLevel(level)

small_toolkit/outputs.py

@@ -0,0 +1,185 @@
+"""产物目录与落盘：路径拼装、环境后缀、JSON 与原始字节写入。
+
+产物根默认是运行目录；从运行目录向上命中便携工作区标记（:data:`WORKSPACE_MARKERS`）
+时归到该目录，便于在工作区任意子目录启动脚本。所有落盘路径都经 :func:`output_dir`
+拼装，不在各脚本里手写 ``Path("output")``。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime
+from pathlib import Path
+
+#: 便携工作区标记：从运行目录向上命中任一个即把产物根切到该目录所在层级。
+#: ``.workspace-root`` 为通用标记；``.dataphin.jsonc`` 保留以兼容既有工作区。
+WORKSPACE_MARKERS = (".workspace-root", ".dataphin.jsonc")
+
+
+def output_root(start: str | Path | None = None) -> Path:
+    """产物根：默认运行目录（cwd）；cwd 起向上命中便携标记时用它所在目录。
+
+    便携工作区（根目录放 ``.workspace-root`` / ``.dataphin.jsonc``）里无论从哪一层
+    子目录启动，产物都归到工作区根；普通目录仍是 cwd 本身（产物归到运行位置）。
+    """
+    base = Path(start) if start is not None else Path.cwd()
+    base = base.resolve()
+    for candidate in (base, *base.parents):
+        if any((candidate / marker).is_file() for marker in WORKSPACE_MARKERS):
+            return candidate
+    return base
+
+
+def output_dir(*segments: str | Path, create: bool = False) -> Path:
+    """产物根下的 ``output/<segments...>``；``create=True`` 时确保目录存在。
+
+    所有落盘路径的唯一拼装入点：分类、工具名、产物类型都作为片段传入。
+    """
+    directory = output_root() / "output"
+    for segment in segments:
+        if segment:
+            directory = directory / segment
+    if create:
+        directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def get_output_dir(
+    script_path: str | Path | None, *subdirs: str | Path, create: bool = True
+) -> Path:
+    """获取工具产物目录：``<产物根>/output/<subdirs...>``，默认确保目录存在。
+
+    ``script_path`` 仅作调用方自述（日志定位用），不参与路径计算；产物根见
+    :func:`output_root`，与脚本所在路径无关。
+
+    - get_output_dir(__file__) -> <root>/output
+    - get_output_dir(__file__, "intake_tool", tag) -> <root>/output/intake_tool/<tag>
+    - get_output_dir(__file__, create=False) -> 只算路径、不建目录（import 期用）
+
+    带分类层与环境后缀的调用优先用 :func:`tool_output_dir`；本函数保留给仓库级
+    构建/辅助产物（``output/_build/...``）。
+    """
+    return output_dir(*subdirs, create=create)
+
+
+def tool_output_dir(
+    group: str, tool_name: str, *subdirs: str | Path, env: str | None = None, create: bool = False
+) -> Path:
+    """业务工具产物目录：``<产物根>/output/<group>/<tool>[@env]/<subdirs...>``。
+
+    ``group`` 是业务分类英文 slug，与调用方仓库的分类目录一一对应；
+    ``env`` 按 :func:`tool_dir_name` 规则加后缀。
+    """
+    return get_output_dir(None, group, tool_dir_name(tool_name, env), *subdirs, create=create)
+
+
+def display_path(path: str | Path) -> str:
+    """日志里的文件路径展示：优先相对产物根，其次相对运行目录，都不在则用绝对路径。
+
+    不产生 ``..``；输出保留本机分隔符（Windows 为 ``\\``）。所有落盘日志共用这一份规则。
+    """
+    absolute = Path(path).resolve()
+    for base in (output_root(), Path.cwd().resolve()):
+        try:
+            return str(absolute.relative_to(base))
+        except ValueError:
+            continue
+    return str(absolute)
+
+
+def env_suffix(env: str | None = None) -> str:
+    """环境归一后缀：tst（含未传，大小写不敏感）为空串，其余环境 ``@<env 小写>``。
+
+    产物目录（:func:`tool_dir_name`）与日志文件名（:func:`set_log_env`）共用这一套归一，
+    避免出现两种写法；归一**只作用于本地目录/文件命名**，不改动传给外部系统的 env 原值。
+    """
+    return "" if not env or env.lower() == "tst" else f"@{env.lower()}"
+
+
+def tool_dir_name(tool_name: str, env: str | None = None) -> str:
+    """产物工具目录名：默认环境 tst（含未传，大小写不敏感）不带后缀，其余环境
+    ``{tool_name}@<env 小写>``。
+
+    默认环境存量路径零变化，其它环境在工具目录名后加 ``@<env 小写>`` 后缀，如
+    ``task_tool@prod``、``-e UAT`` → ``task_tool@uat``；显式传给 ``--output-dir``
+    等的完整目录不套用本规则。
+    """
+    return tool_name + env_suffix(env)
+
+
+def _dump_json(
+    path: str | Path,
+    data,
+    *,
+    indent: int,
+    newline: bool,
+    stringify: bool,
+) -> Path:
+    """JSON 落盘内核：自动建父目录，UTF-8 写出，可选末尾换行 / 非序列化对象转字符串。"""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    text = json.dumps(
+        data, ensure_ascii=False, indent=indent, default=str if stringify else None
+    )
+    if newline:
+        text += "\n"
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+def save_json(path: str | Path, data, *, indent: int = 2) -> Path:
+    """把数据按 UTF-8 JSON 写到 ``path``（自动建父目录），返回落盘路径。
+
+    非序列化对象按 ``str()`` 落盘（如 datetime）；不追加末尾换行。
+    """
+    return _dump_json(path, data, indent=indent, newline=False, stringify=True)
+
+
+def write_json(path: str | Path, data, *, indent: int = 2) -> Path:
+    """把对象写成 UTF-8 JSON 文件（``ensure_ascii=False``、末尾换行），返回写入路径。
+
+    目录不存在时自动创建。与 :func:`save_json` 的区别仅在末尾换行与是否容错非序列化对象。
+    """
+    return _dump_json(path, data, indent=indent, newline=True, stringify=False)
+
+
+def save_bytes(path: str | Path, content: bytes) -> Path:
+    """把原始字节写到 ``path``（自动建父目录），返回落盘路径。"""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(content)
+    return path
+
+
+def save_response(
+    script_path: str,
+    category: str,
+    name: str,
+    data,
+    *,
+    output_dir: str | Path | None = None,
+    tool_name: str | None = None,
+    env: str | None = None,
+    group: str | None = None,
+    timestamp_fmt: str = "%Y%m%d",
+) -> Path | None:
+    """保存原始响应，默认路径为 ``<产物根>/output/[<分类>/]<tool名称[@{env}]/<子类别>``。
+
+    ``group`` 为业务分类 slug（见 :func:`tool_output_dir`）；不传时保持扁平路径
+    ``output/<tool>/<子类别>``（仅兼容仓库级/未分类调用）。``data`` 为空时不落盘。
+    """
+    if not data:
+        return None
+    script = Path(script_path).resolve()
+    if output_dir is not None:
+        directory = Path(output_dir)
+        directory.mkdir(parents=True, exist_ok=True)
+    elif group:
+        directory = tool_output_dir(group, tool_name or script.stem, category, env=env, create=True)
+    else:
+        directory = get_output_dir(script, tool_dir_name(tool_name or script.stem, env), category)
+    path = directory / f"{name}_{datetime.now().strftime(timestamp_fmt)}.json"
+    save_json(path, data)
+    logging.getLogger(__name__).info("  响应：%s", display_path(path))
+    return path

small_toolkit/table.py

@@ -0,0 +1,149 @@
+"""终端输出工具：按显示宽度对齐的表格与目录树。"""
+
+import unicodedata
+
+
+def _display_width(s: str) -> int:
+    """字符串显示宽度（中日韩 = 2，ASCII/box-drawing/emoji = 1）。"""
+    return sum(2 if unicodedata.east_asian_width(c) in "WF" else 1 for c in s)
+
+
+def _widths(headers: list[str], values: list[list[str]]) -> list[int]:
+    """各列显示宽度：取表头与全部数据行的最大值。"""
+    widths = [_display_width(h) for h in headers]
+    for row in values:
+        for i, v in enumerate(row):
+            widths[i] = max(widths[i], _display_width(v))
+    return widths
+
+
+def _fmt_row(row: list[str], widths: list[int]) -> str:
+    """按列宽补齐一行（中文算 2 宽，右侧补空格）。"""
+    return " | ".join(v + " " * (widths[i] - _display_width(v)) for i, v in enumerate(row))
+
+
+def print_table(headers: list[str], rows: list[list[object]], *, border: bool = False) -> None:
+    """按显示宽度对齐输出表格（中文算2宽，ASCII算1宽）。
+
+    版式：标题行下边一条 ``---+---`` 分隔线；``border=True`` 时表格最上与最下各加一条
+    与行等宽的 ``--`` 线（默认不加，调用方按需开启）；``==`` 线留给调用方做汇总级分隔。
+
+    Parameters
+    ----------
+    headers : list[str]
+        表头。
+    rows : list[list[object]]
+        数据行；``None`` 显示为空串。
+    border : bool, keyword-only
+        是否加表格最上 / 最下的等宽边线，默认 ``False``（不加）。
+    """
+    values = [["" if v is None else str(v) for v in row] for row in rows]
+    widths = _widths(headers, values)
+
+    # 边线与 _fmt_row 行等宽：各列宽之和 + 列间 " | "（3 字符 × (列数-1)）
+    edge = "-" * (sum(widths) + 3 * (len(widths) - 1))
+    if border:
+        print(edge)
+    print(_fmt_row(headers, widths))
+    print("-+-".join("-" * w for w in widths))
+    for row in values:
+        print(_fmt_row(row, widths))
+    if border:
+        print(edge)
+
+
+def print_grouped_table(headers: list[str], groups: list[tuple[str, list[list[object]]]]) -> None:
+    """多组数据合成**一张表**：单一表头 + 每组一行 ``▸ 组名`` 标记行。
+
+    ``groups`` 为 ``[(组名, 行列表), ...]``，按传入顺序输出；组名行不占列宽，故表宽与
+    :func:`print_table` 同口径（不新增列）。各组数据参与同一次列宽计算，跨组同名列对齐；
+   计划表按目录分组时用它替代「每组一张表」，避免表头重复和组间错位。
+    """
+    blocks = [[["" if v is None else str(v) for v in row] for row in rows] for _, rows in groups]
+    widths = _widths(headers, [row for block in blocks for row in block])
+    print(_fmt_row(headers, widths))
+    print("-+-".join("-" * w for w in widths))
+    for (label, _), block in zip(groups, blocks):
+        print(f"▸ {label}")
+        for row in block:
+            print(_fmt_row(row, widths))
+
+
+def print_tree(
+    items: list[dict],
+    headers: list[str],
+    *,
+    parent_key: str = "Directory",
+    name_key: str = "Name",
+    container_type: str = "directory",
+    type_key: str = "FileType",
+    cols: list[str] | None = None,
+):
+    """按父子关系打印目录树，首列带树形缩进，其余列表格对齐。
+
+    Parameters
+    ----------
+    items : list[dict]
+        扁平条目列表。
+    headers : list[str]
+        表头（首列为名称列）。
+    parent_key : str
+        父路径字段名。
+    name_key : str
+        名称字段名。
+    container_type : str
+        容器类型标记值。
+    type_key : str
+        类型字段名。
+    cols : list[str] | None
+        各列对应的字段名；不传时取 headers 小写。
+    """
+    cols = cols or [h.lower() for h in headers]
+
+    # 构建树（统一去掉尾斜杠，防止 API 返回的 "/视图登记/" 与拼接的 "/视图登记" 不匹配）
+    tree: dict[str, list[dict]] = {}
+    for f in items:
+        parent = f.get(parent_key, "/").rstrip("/") or "/"
+        tree.setdefault(parent, []).append(f)
+    for parent in tree:
+        tree[parent].sort(
+            key=lambda f: (
+                0 if f.get(type_key) == container_type else 1,
+                (f.get(name_key) or "").lower(),
+            )
+        )
+
+    # 收集展平行（首列带缩进）
+    flat_rows: list[list[str]] = []
+
+    def _collect(parent: str, indent: str = ""):
+        children = tree.get(parent, [])
+        for i, f in enumerate(children):
+            is_last = i == len(children) - 1
+            name = f.get(name_key, "")
+            is_container = f.get(type_key) == container_type
+            tag = "📁 " if is_container else "📄 "
+            stem = "└── " if is_last else "├── "
+            ext = "    " if is_last else "│   "
+            row = [indent + stem + tag + name]
+            for c in cols[1:]:
+                row.append(str(f.get(c, "")) if f.get(c) is not None else "")
+            flat_rows.append(row)
+            if is_container:
+                child_path = (parent.rstrip("/") + "/" + name).replace("//", "/")
+                _collect(child_path, indent + ext)
+
+    _collect("/")
+
+    widths = [_display_width(h) for h in headers]
+    for row in flat_rows:
+        for i, v in enumerate(row):
+            widths[i] = max(widths[i], _display_width(v))
+
+    def _fmt(row: list[str]) -> str:
+        return " | ".join(v + " " * (widths[i] - _display_width(v)) for i, v in enumerate(row))
+
+    print(_fmt(headers))
+    print("-+-".join("-" * w for w in widths))
+    for row in flat_rows:
+        print(_fmt(row))

small_toolkit-0.1.1.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: small_toolkit
+Version: 0.1.1
+Summary: 纯标准库的通用小工具：产物目录、日志初始化、命令行参数与终端表格
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# small_toolkit
+
+纯标准库的通用 Python 小工具集合：产物目录、日志初始化、命令行参数、终端表格。
+
+## 边界
+
+- **零第三方依赖**：只用标准库（`pathlib` / `logging` / `argparse` / `unicodedata`）。
+- **无凭据、无内网地址**：不读环境里的密钥，不内置任何内网域名；环境变量只做**名字**层面的回退。
+- 只抽跨项目复用的通用能力，业务逻辑（平台 SDK、数据源客户端、领域规则）留在各自仓库。
+
+## 安装
+
+从 tag 安装（跨仓依赖固定到 tag，不跟浮动分支）：
+
+```bash
+uv add "small_toolkit @ git+https://github.com/jalousiex/py-toolkit.git@v0.1.1"
+```
+
+本地开发：
+
+```bash
+uv sync
+uv run pytest -q
+```
+
+## 分区
+
+| 模块 | 内容 |
+| --- | --- |
+| `small_toolkit.outputs` | `output_root` / `output_dir` / `get_output_dir` / `tool_output_dir` / `display_path` / `env_suffix` / `tool_dir_name` / `save_json` / `write_json` / `save_bytes` / `save_response` |
+| `small_toolkit.logs` | `setup_job`（控制台着色 + 延迟建目录的文件日志）/ `set_log_env` / `add_debug_argument` / `enable_debug_logging` |
+| `small_toolkit.cli` | `add_grouped_subparsers` / `add_parameter` / `resolve_parameters` / `resolve_env_var` |
+| `small_toolkit.table` | `print_table` / `print_grouped_table` / `print_tree` |
+
+顶层 `small_toolkit` 已重导出全部公开 API，`from small_toolkit import setup_job, tool_output_dir` 即可。
+
+## 产物目录约定
+
+```text
+<产物根>/output/<分类 slug>/<工具名>[@<env 小写>]/<产物类型>/
+```
+
+- 产物根：默认运行目录；从运行目录向上命中便携标记（`WORKSPACE_MARKERS`，默认
+  `.workspace-root` / `.dataphin.jsonc`）时归到该目录，工作区任意子目录启动都落到工作区根。
+- 环境后缀：`tst`（含未传，大小写不敏感）无后缀；其它环境 `@<env 小写>`，同一套归一
+  同时作用于产物目录与日志文件名。
+- 落盘统一走 `save_json` / `write_json` / `save_bytes`：自动建父目录；`save_json` 不补末尾
+  换行、非序列化对象按 `str()` 落盘，`write_json` 末尾补换行。
+
+```python
+from small_toolkit import setup_job, tool_output_dir
+
+setup_job(__file__, log_file=True)
+out = tool_output_dir("data_dev", "intake_tool", env="prod", create=True)
+```
+
+## 日志与 `--debug`
+
+`setup_job()` 只在**真终端**给消息正文着色；管道、重定向、子进程捕获、`NO_COLOR`
+下一律纯文本，落盘日志始终纯文本。`add_debug_argument()` 默认 `argparse.SUPPRESS`，
+顶层与子命令各注册一次也不会互相覆盖，判断统一交给 `enable_debug_logging()`。
+
+## 命令行回退顺序
+
+`add_parameter()` 登记后，`resolve_parameters()` 按
+**CLI → 平台代码参数（`parameter`）→ 环境变量（`env`）→ 默认值** 填充；
+平台占位符（`${name}`）按未设置处理。`resolve_env_var(env, base)` 依次读
+`{base}_LIST`（`env=value;...`）、`{base}_{ENV}`，仅 `prod` 时回退原生 `{base}`。
+
+## 版本
+
+`pyproject.toml` 的 `version` 为唯一来源；发版打 tag（`v0.1.1`），引用方按 tag 固定。
+
+## 发布
+
+PyPI 走 GitHub Actions + Trusted Publishing（OIDC，不用 API token）：
+
+- 先手动跑 `publish-test`（`workflow_dispatch`）发 TestPyPI 验证，不占正式版本号；
+- 正式发布：`pyproject.toml` 升版本 → 打 tag `v*` → push tag，`publish` 工作流构建并上传。
+- 工作流会先校验 tag 与 `pyproject.toml` 的 `version` 一致，不一致直接失败（PyPI 同版本不可覆盖）。
+- GitHub 仓库需要预先配置 PyPI 的 pending publisher（Owner / Repository / Workflow / Environment 四项与工作流一致）。
+

small_toolkit-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+small_toolkit/__init__.py,sha256=InEs1gU2F84i48iHqDz4ljQjo4YymtVRjtmaaVCFfmw,1429
+small_toolkit/cli.py,sha256=08Z2HHQgsEBQudDbbQGwcPE6IxJyl3CJhceUVVZej28,5452
+small_toolkit/logs.py,sha256=UrRfYupVpSQQ2Uw-TvKiYyaWw_cpb-kTysNvfAwLSOM,9626
+small_toolkit/outputs.py,sha256=l9h9Tmy_R1oMS5KDLhCD-fNJWLG7jqCdjsUXTRw-8P8,7460
+small_toolkit/table.py,sha256=wJ2SZHagdnvUKKBtscSCfq1PT9cATn81JAQyMlst6xI,5620
+small_toolkit-0.1.1.dist-info/METADATA,sha256=sl3WgqP6ayC1wNlsq2SPj4PZgdYAnBXnQ9G7s7r_W_I,3964
+small_toolkit-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+small_toolkit-0.1.1.dist-info/RECORD,,

small_toolkit-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any