ddlkit 0.1.0__tar.gz

ddlkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yangyang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ddlkit-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: ddlkit
+Version: 0.1.0
+Summary: 多方言 DDL 文本解析器：无损保真地提取表、列、约束、索引与方言特性
+Project-URL: Homepage, https://github.com/YOUR-ORG/ddl-kit
+Project-URL: Repository, https://github.com/YOUR-ORG/ddl-kit
+Project-URL: Issues, https://github.com/YOUR-ORG/ddl-kit/issues
+Project-URL: Changelog, https://github.com/YOUR-ORG/ddl-kit/blob/main/CHANGELOG.md
+Author: yangyang
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit,clickhouse,dameng,ddl,governance,hive,oceanbase,parser,sql
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: sqlglot<31,>=30.18
+Description-Content-Type: text/markdown
+
+# ddlkit
+
+多方言 DDL 文本解析器。只做一件事：**DDL 文本 → 结构化数据**，不含规则引擎。
+
+面向的场景是**建表规范审计**：校验表名/列名/索引名的书写形态、长度、注释是否齐全、
+类型是否符合规范。这类审计对"保真"的要求极高——解析器**改写**或**丢弃**任何一处，
+规则就会判错，而判错是静默的，比报错更危险。
+
+## 核心特征
+
+| 特征 | 说明 |
+|---|---|
+| **不丢原文** | 每个字段双轨：`*_raw` 保留原文（含引号、原始类型名），归一化字段供比较 |
+| **不丢方言** | 方言特性（达梦 `STORAGE`、CK `ENGINE`/`ORDER BY`、Hive `TBLPROPERTIES`、OB `REPLICA_NUM`…）全部结构化进 `extras`，**不做摘除** |
+| **不挂死** | 只走 sqlglot 的 tokenizer，不碰 parser。达梦 `NOT CLUSTER PRIMARY KEY` 曾导致 parser 无限回溯 OOM |
+| **不改写** | 绕过 parser + generator，因此 `TINYINT` 不会变成 `SMALLINT` |
+| **格式自适应** | 自动识别 5 种导出格式（beeline / 双引号包裹逐行 / `\n` 转义逐行 / 无分号锚点 / 常规脚本） |
+| **编码自适应** | 逐文件探测 UTF-8 / UTF-8-BOM / GB18030（同一批导出文件里可能混存） |
+| **零额外依赖** | 只依赖纯 Python 版 `sqlglot` |
+
+## 安装
+
+```bash
+pip install ddlkit
+# 或
+uv add ddlkit
+```
+
+> 依赖声明为 `sqlglot`（纯 Python 版）。**不要同时安装 `sqlglot[c]`**——它会把
+> 编译产物覆盖到 `sqlglot/tokenizer_core`，本包未在该形态下验证。
+
+## 快速开始
+
+```python
+from ddlkit import parse_file
+
+res = parse_file("ddl/ANMS_ALARM.sql", dialect="dm")
+
+for t in res.tables:
+    print(t.qualified_name, len(t.columns), t.comment)
+    for c in t.columns:
+        # 用 type_raw 判断类型，不要用归一化后的值——那会丢原始写法
+        print("   ", c.name_raw, c.type_raw, c.comment)
+    for k in t.constraints:
+        print("   PK?", k.kind, k.columns, k.clustered)
+    print("   方言特性:", t.extras)
+```
+
+解析一段文本：
+
+```python
+from ddlkit import parse_ddl
+
+res = parse_ddl(
+    '''CREATE TABLE `t` (
+         `ID` varchar(512) NOT NULL COMMENT '主键',
+         PRIMARY KEY (`ID`)
+       ) REPLICA_NUM = 3 COMMENT = '示例表';''',
+    dialect="ob_mysql",
+)
+t = res.tables[0]
+assert t.constraints[0].kind == "PRIMARY KEY"
+assert t.extras["REPLICA_NUM"] == "REPLICA_NUM = 3"
+```
+
+## 支持的方言别名
+
+| 业务库 | 可传的 `dialect` | 映射到 sqlglot 方言 |
+|---|---|---|
+| 达梦 | `dm` / `dameng` / `达梦` | `oracle` |
+| ClickHouse | `ck` / `clickhouse` | `clickhouse` |
+| OceanBase(MySQL 模式) | `ob` / `ob_mysql` / `oceanbase` | `mysql` |
+| Hive | `hive` / `hive2` | `hive` |
+
+其余任意 sqlglot 方言名也可直接传入（如 `postgres`、`snowflake`）。
+
+## 数据模型
+
+```
+ParseResult
+├── tables: list[Table]
+│   ├── name / name_raw / quoted / schema / catalog / temporary
+│   ├── columns: list[Column]
+│   │   ├── name / name_raw / quoted
+│   │   ├── type_name / type_raw / type_args_raw
+│   │   ├── nullable / default_raw / comment
+│   │   ├── extras      # identity / collate / codec / primary_key …
+│   │   └── line / col
+│   ├── constraints: list[Constraint]   # PRIMARY KEY / UNIQUE / FOREIGN KEY / CHECK / INDEX
+│   ├── indexes: list[Index]            # 独立 CREATE INDEX 语句，已按表名挂接
+│   ├── comment
+│   ├── extras          # 方言特性，原样保存
+│   ├── source          # 文件 / 行号 / 编码 / 格式，供报告定位
+│   └── warnings
+├── warnings
+└── unsupported         # 无法当作建表语句处理的语句（如 CTAS）
+```
+
+完整字段语义见 `docs/详细设计.md`。
+
+## 已知限制
+
+* 只解析 DDL，不解析 DML / 存储过程 / PL-SQL 块。
+* 只解析 `CREATE TABLE` / `CREATE INDEX` / `COMMENT ON`；其余语句进 `unsupported`/忽略。
+* 全角字符长度、`CASE_SENSITIVE` 语义等**库侧语义**不在解析层处理，交由规则层。
+* 单条语句内部的极端嵌套（Oracle `q'[...]'` 引号、`$$` 块）未覆盖。
+
+## 开发
+
+```bash
+uv sync
+uv run pytest -q
+uv run ruff check src tests
+uv run mypy
+```
+
+## 许可
+
+MIT

ddlkit-0.1.0/README.md

@@ -0,0 +1,119 @@
+# ddlkit
+
+多方言 DDL 文本解析器。只做一件事：**DDL 文本 → 结构化数据**，不含规则引擎。
+
+面向的场景是**建表规范审计**：校验表名/列名/索引名的书写形态、长度、注释是否齐全、
+类型是否符合规范。这类审计对"保真"的要求极高——解析器**改写**或**丢弃**任何一处，
+规则就会判错，而判错是静默的，比报错更危险。
+
+## 核心特征
+
+| 特征 | 说明 |
+|---|---|
+| **不丢原文** | 每个字段双轨：`*_raw` 保留原文（含引号、原始类型名），归一化字段供比较 |
+| **不丢方言** | 方言特性（达梦 `STORAGE`、CK `ENGINE`/`ORDER BY`、Hive `TBLPROPERTIES`、OB `REPLICA_NUM`…）全部结构化进 `extras`，**不做摘除** |
+| **不挂死** | 只走 sqlglot 的 tokenizer，不碰 parser。达梦 `NOT CLUSTER PRIMARY KEY` 曾导致 parser 无限回溯 OOM |
+| **不改写** | 绕过 parser + generator，因此 `TINYINT` 不会变成 `SMALLINT` |
+| **格式自适应** | 自动识别 5 种导出格式（beeline / 双引号包裹逐行 / `\n` 转义逐行 / 无分号锚点 / 常规脚本） |
+| **编码自适应** | 逐文件探测 UTF-8 / UTF-8-BOM / GB18030（同一批导出文件里可能混存） |
+| **零额外依赖** | 只依赖纯 Python 版 `sqlglot` |
+
+## 安装
+
+```bash
+pip install ddlkit
+# 或
+uv add ddlkit
+```
+
+> 依赖声明为 `sqlglot`（纯 Python 版）。**不要同时安装 `sqlglot[c]`**——它会把
+> 编译产物覆盖到 `sqlglot/tokenizer_core`，本包未在该形态下验证。
+
+## 快速开始
+
+```python
+from ddlkit import parse_file
+
+res = parse_file("ddl/ANMS_ALARM.sql", dialect="dm")
+
+for t in res.tables:
+    print(t.qualified_name, len(t.columns), t.comment)
+    for c in t.columns:
+        # 用 type_raw 判断类型，不要用归一化后的值——那会丢原始写法
+        print("   ", c.name_raw, c.type_raw, c.comment)
+    for k in t.constraints:
+        print("   PK?", k.kind, k.columns, k.clustered)
+    print("   方言特性:", t.extras)
+```
+
+解析一段文本：
+
+```python
+from ddlkit import parse_ddl
+
+res = parse_ddl(
+    '''CREATE TABLE `t` (
+         `ID` varchar(512) NOT NULL COMMENT '主键',
+         PRIMARY KEY (`ID`)
+       ) REPLICA_NUM = 3 COMMENT = '示例表';''',
+    dialect="ob_mysql",
+)
+t = res.tables[0]
+assert t.constraints[0].kind == "PRIMARY KEY"
+assert t.extras["REPLICA_NUM"] == "REPLICA_NUM = 3"
+```
+
+## 支持的方言别名
+
+| 业务库 | 可传的 `dialect` | 映射到 sqlglot 方言 |
+|---|---|---|
+| 达梦 | `dm` / `dameng` / `达梦` | `oracle` |
+| ClickHouse | `ck` / `clickhouse` | `clickhouse` |
+| OceanBase(MySQL 模式) | `ob` / `ob_mysql` / `oceanbase` | `mysql` |
+| Hive | `hive` / `hive2` | `hive` |
+
+其余任意 sqlglot 方言名也可直接传入（如 `postgres`、`snowflake`）。
+
+## 数据模型
+
+```
+ParseResult
+├── tables: list[Table]
+│   ├── name / name_raw / quoted / schema / catalog / temporary
+│   ├── columns: list[Column]
+│   │   ├── name / name_raw / quoted
+│   │   ├── type_name / type_raw / type_args_raw
+│   │   ├── nullable / default_raw / comment
+│   │   ├── extras      # identity / collate / codec / primary_key …
+│   │   └── line / col
+│   ├── constraints: list[Constraint]   # PRIMARY KEY / UNIQUE / FOREIGN KEY / CHECK / INDEX
+│   ├── indexes: list[Index]            # 独立 CREATE INDEX 语句，已按表名挂接
+│   ├── comment
+│   ├── extras          # 方言特性，原样保存
+│   ├── source          # 文件 / 行号 / 编码 / 格式，供报告定位
+│   └── warnings
+├── warnings
+└── unsupported         # 无法当作建表语句处理的语句（如 CTAS）
+```
+
+完整字段语义见 `docs/详细设计.md`。
+
+## 已知限制
+
+* 只解析 DDL，不解析 DML / 存储过程 / PL-SQL 块。
+* 只解析 `CREATE TABLE` / `CREATE INDEX` / `COMMENT ON`；其余语句进 `unsupported`/忽略。
+* 全角字符长度、`CASE_SENSITIVE` 语义等**库侧语义**不在解析层处理，交由规则层。
+* 单条语句内部的极端嵌套（Oracle `q'[...]'` 引号、`$$` 块）未覆盖。
+
+## 开发
+
+```bash
+uv sync
+uv run pytest -q
+uv run ruff check src tests
+uv run mypy
+```
+
+## 许可
+
+MIT

ddlkit-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ddlkit"
+version = "0.1.0"
+description = "多方言 DDL 文本解析器：无损保真地提取表、列、约束、索引与方言特性"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "yangyang" }]
+keywords = ["ddl", "sql", "parser", "audit", "governance", "clickhouse", "hive", "oceanbase", "dameng"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Database",
+  "Topic :: Software Development :: Quality Assurance",
+  "Typing :: Typed",
+]
+dependencies = [
+  # 必须显式声明为纯 Python 版 sqlglot。
+  # sqlglot[c]（即 sqlglotc 发行包）会用编译产物覆盖 sqlglot/tokenizer_core，
+  # 本包依赖纯 Python 的词法实现，未在该形态下验证，因此不要引入 sqlglot[c]。
+  "sqlglot>=30.18,<31",
+]
+
+[project.urls]
+Homepage = "https://github.com/YOUR-ORG/ddl-kit"
+Repository = "https://github.com/YOUR-ORG/ddl-kit"
+Issues = "https://github.com/YOUR-ORG/ddl-kit/issues"
+Changelog = "https://github.com/YOUR-ORG/ddl-kit/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=6.0",
+  "ruff>=0.9",
+  "mypy>=1.13",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ddlkit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/ddlkit", "tests", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/ddlkit"]
+
+# 私有索引（内网）示例：把下面这段放进仓库根的 pyproject.toml 或用户级配置，
+# 然后用 `uv publish --index nexus` 发布。
+#
+# [[tool.uv.index]]
+# name = "nexus"
+# url = "https://nexus.internal/repository/pypi-hosted/simple/"
+# publish-url = "https://nexus.internal/repository/pypi-hosted/"
+# explicit = true

ddlkit-0.1.0/src/ddlkit/__init__.py

@@ -0,0 +1,24 @@
+"""ddlkit —— 多方言 DDL 文本解析器（无损保真）。
+
+只做一件事：**DDL 文本 -> 结构化数据**。不含规则引擎。
+"""
+from __future__ import annotations
+
+from .api import DIALECT_ALIASES, parse_ddl, parse_file, resolve_dialect
+from .model import Column, Constraint, Index, ParseResult, SourceRef, Table
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Column",
+    "Constraint",
+    "DIALECT_ALIASES",
+    "Index",
+    "ParseResult",
+    "SourceRef",
+    "Table",
+    "__version__",
+    "parse_ddl",
+    "parse_file",
+    "resolve_dialect",
+]

ddlkit-0.1.0/src/ddlkit/api.py

@@ -0,0 +1,110 @@
+"""对外入口。
+
+调用方只需要知道两件事：**文本从哪来** 和 **它是哪个方言**。
+包内部负责：编码探测 -> 导出格式识别 -> 语句切分 -> 词法 -> 结构提取 -> 注释回填。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import comments as _comments
+from . import encoding as _encoding
+from . import source as _source
+from .extract import extract_index, extract_table
+from .lexer import lex
+from .model import ParseResult, SourceRef, Table
+
+#: 业务库名 -> sqlglot 方言名。新增库只需在这里加一行。
+DIALECT_ALIASES: dict[str, str] = {
+    "dm": "oracle",
+    "dameng": "oracle",
+    "达梦": "oracle",
+    "ck": "clickhouse",
+    "clickhouse": "clickhouse",
+    "ob": "mysql",
+    "ob_mysql": "mysql",
+    "oceanbase": "mysql",
+    "oceanbase_mysql": "mysql",
+    "hive": "hive",
+    "hive2": "hive",
+}
+
+
+def resolve_dialect(name: str) -> str:
+    """把业务库名映射成 sqlglot 方言名；已是方言名则原样返回。"""
+    key = name.strip().lower()
+    return DIALECT_ALIASES.get(key, key)
+
+
+def parse_ddl(
+    text: str | bytes,
+    dialect: str,
+    *,
+    filename: str | None = None,
+    encoding: str | None = None,
+    fmt: str | None = None,
+) -> ParseResult:
+    """解析一段 DDL 文本（可含多库/多语句）。"""
+    if isinstance(text, bytes):
+        text, used_encoding = _encoding.decode(text, encoding)
+    else:
+        used_encoding = encoding or "utf-8"
+
+    resolved = resolve_dialect(dialect)
+    fmt = fmt or _source.detect(text)
+
+    result = ParseResult()
+    statements = _source.split(text, fmt)
+
+    tables: list[Table] = []
+    by_name: dict[str, Table] = {}
+    pending_indexes: list[tuple[str, object, int]] = []
+    comment_on_texts: list[str] = []
+
+    for stmt in statements:
+        if stmt.kind == "other":
+            continue
+        lexed = lex(stmt.sql, resolved)
+        src = SourceRef(path=filename, line=stmt.line, encoding=used_encoding, fmt=fmt)
+
+        if stmt.kind == "create_table":
+            table = extract_table(lexed, resolved, src)
+            if table is None:
+                result.unsupported.append(f"line {stmt.line}: {stmt.sql[:80]}")
+                continue
+            tables.append(table)
+            if table.schema:
+                by_name[f"{table.schema}.{table.name}".upper()] = table
+            by_name.setdefault(table.name.upper(), table)
+        elif stmt.kind == "create_index":
+            parsed = extract_index(lexed, src)
+            if parsed is not None:
+                pending_indexes.append((parsed[0], parsed[1], stmt.line))
+        elif stmt.kind == "comment_on":
+            comment_on_texts.append(stmt.sql)
+
+    for target, index, line in pending_indexes:
+        table = by_name.get(target.upper())
+        if table is None:
+            result.warnings.append(f"line {line}: 索引 {index.name!r} 找不到目标表 {target!r}")
+            continue
+        table.indexes.append(index)
+
+    if comment_on_texts:
+        _comments.backfill(comment_on_texts, tables)
+
+    result.tables = tables
+    return result
+
+
+def parse_file(
+    path: str | Path,
+    dialect: str,
+    *,
+    encoding: str | None = None,
+    fmt: str | None = None,
+) -> ParseResult:
+    """解析一个 DDL 导出文件。"""
+    p = Path(path)
+    text, used = _encoding.decode(p.read_bytes(), encoding)
+    return parse_ddl(text, dialect, filename=p.name, encoding=used, fmt=fmt)

ddlkit-0.1.0/src/ddlkit/comments.py

@@ -0,0 +1,72 @@
+"""``COMMENT ON`` 语句回填。
+
+Oracle 系的库（达梦）把注释写成**独立语句**：
+
+    COMMENT ON TABLE  "S"."T"   IS '表注释'
+    COMMENT ON COLUMN "S"."T"."C" IS '列注释'
+
+只解析单条 CREATE TABLE 会漏掉全部注释，导致"注释必填"类规则大面积误报。
+该语法极规整，正则可 100% 覆盖，比赌解析器对 COMMENT 语句的支持更稳。
+"""
+from __future__ import annotations
+
+import re
+
+from .model import Table
+
+COMMENT_ON = re.compile(
+    r"""COMMENT\s+ON\s+(?P<kind>TABLE|COLUMN)\s+
+        (?P<target>
+            "[^"]+"(?:\s*\.\s*"[^"]+")*
+          | `[^`]+`(?:\s*\.\s*`[^`]+`)*
+          | [A-Za-z_][\w$#]*(?:\s*\.\s*[A-Za-z_][\w$#]*)*
+        )
+        \s+IS\s+'(?P<text>(?:[^']|'')*)'""",
+    re.IGNORECASE | re.VERBOSE,
+)
+
+_NAME_SPLIT = re.compile(r"\s*\.\s*")
+
+
+def _parts(target: str) -> list[str]:
+    return [p.strip('"`').upper() for p in _NAME_SPLIT.split(target.strip())]
+
+
+def _build_index(tables: list[Table]) -> dict[tuple[str, ...], Table]:
+    index: dict[tuple[str, ...], Table] = {}
+    for t in tables:
+        if t.schema:
+            index[(t.schema.upper(), t.name.upper())] = t
+        index[(t.name.upper(),)] = t
+    return index
+
+
+def backfill(statements: list[str], tables: list[Table]) -> int:
+    """把 COMMENT ON 回填到表/列上，返回成功回填的条数。"""
+    index = _build_index(tables)
+    hits = 0
+    for stmt in statements:
+        for m in COMMENT_ON.finditer(stmt):
+            kind = m.group("kind").upper()
+            segs = _parts(m.group("target"))
+            text = m.group("text").replace("''", "'")
+            if not segs:
+                continue
+
+            if kind == "TABLE":
+                table = index.get(tuple(segs[-2:])) or index.get((segs[-1],))
+                if table is not None:
+                    table.comment = text
+                    hits += 1
+            else:
+                if len(segs) < 2:
+                    continue
+                table = index.get(tuple(segs[-3:-1])) or index.get((segs[-2],))
+                if table is None:
+                    continue
+                for col in table.columns:
+                    if col.name.upper() == segs[-1]:
+                        col.comment = text
+                        hits += 1
+                        break
+    return hits

ddlkit-0.1.0/src/ddlkit/encoding.py

@@ -0,0 +1,34 @@
+"""编码探测。
+
+实测：同一批导出文件里 UTF-8 与 GB18030 混存（OB 的 test.sql 是 GB18030，
+其余 88 个文件是 UTF-8）。按单一编码读取会让中文注释整体乱码，
+而"注释必填"类规则会因此大面积误报。
+"""
+from __future__ import annotations
+
+BOM_UTF8 = b"\xef\xbb\xbf"
+CANDIDATES: tuple[str, ...] = ("utf-8", "gb18030")
+
+
+def sniff(raw: bytes) -> str:
+    """返回最可能的编码名。
+
+    顺序敏感：UTF-8 先试，失败再试 GB18030。
+    局限：字节序列恰好同时合法于两种编码时会误判（中文文本极少见）。
+    需要更高准确率时可换 charset-normalizer，本包默认零依赖。
+    """
+    if raw.startswith(BOM_UTF8):
+        return "utf-8-sig"
+    for enc in CANDIDATES:
+        try:
+            raw.decode(enc)
+            return enc
+        except UnicodeDecodeError:
+            continue
+    return "utf-8"  # 兜底，配合 errors="replace"
+
+
+def decode(raw: bytes, encoding: str | None = None) -> tuple[str, str]:
+    """返回 (文本, 实际使用的编码名)。"""
+    enc = encoding or sniff(raw)
+    return raw.decode(enc, errors="strict" if encoding else "replace"), enc