small-toolkit 0.1.1__tar.gz

small_toolkit-0.1.1/.github/workflows/publish-test.yml

@@ -0,0 +1,34 @@
+name: publish-test
+
+on:
+  workflow_dispatch: # 手动触发：先发 TestPyPI 验证，不占正式版本号
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

small_toolkit-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 校验 tag 与 pyproject 版本一致
+        # PyPI 同版本不可覆盖，tag/版本不一致会在上传时才报错，这里提前拦
+        run: |
+          version=$(python3 -c "import pathlib,tomllib;print(tomllib.loads(pathlib.Path('pyproject.toml').read_text(encoding='utf-8'))['project']['version'])")
+          test "v${version}" = "${GITHUB_REF_NAME}"
+
+      - uses: astral-sh/setup-uv@v5
+
+      - run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # Trusted Publishing（OIDC），无需 API token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

small_toolkit-0.1.1/.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+
+# 环境与缓存
+.venv/
+.pytest_cache/
+
+# 构建
+build/
+dist/
+*.egg-info/
+
+# 运行时产物（本地）
+output/
+_tmp_*

small_toolkit-0.1.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,82 @@
+# 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/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "small_toolkit"
+version = "0.1.1"
+description = "纯标准库的通用小工具：产物目录、日志初始化、命令行参数与终端表格"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["small_toolkit"]
+
+[tool.uv]
+package = true
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

small_toolkit-0.1.1/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-0.1.1/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