Docling 的 Dignified Python：生产级 Python 编码规范与 Agent Skill 应用实践

本篇基于 docling 仓库中内置的 dignified-python 技能参考文档（.agents/skills/dignified-python/references/README.md）展开，系统讲解一套面向 Python 3.10–3.13 的"有主见"（opinionated）生产编码标准：现代类型语法、LBYL 条件检查、pathlib 路径操作、绝对导入与 CLI 错误边界。读完后，你将掌握这套规范的完整模式、按版本选择特性的检测流程，以及如何把它作为 AI Agent 技能在 docling 这类真实项目中落地。

1. Dignified Python 是什么：文档定位与整体结构

Dignified Python 参考文档定义了一组"用于编写整洁、可维护、现代 Python 代码"的有主见标准（Opinionated Python standards）。它不追求普适中立，而是明确偏向某些约定（例如偏向 LBYL 而非 EAFP），并声明"项目自身的约定在必要时可以覆盖它"。

该技能在仓库中的组织结构如下，各文档均为自包含（self-contained）的完整指南：

文件	职责
.agents/skills/dignified-python/references/README.md	总入口：目录导航、核心原则、快速参考、版本检测流程
.agents/skills/dignified-python/SKILL.md	技能定义：触发条件、自动加载与按需加载规则
.agents/skills/dignified-python/dignified-python-core.md	核心标准（覆盖 80%+ 的 Python 代码模式，每次调用必载）
.agents/skills/dignified-python/cli-patterns.md	CLI 模式（click、argparse、错误处理、配置管理）
.agents/skills/dignified-python/versions/python-3.10.md 至 python-3.13.md	按 Python 版本划分的特性指南（PEP 604/585、异常组、PEP 695、free-threading 等）
.agents/skills/dignified-python/references/advanced/	进阶主题：exception-handling.md、interfaces.md、typing-advanced.md、api-design.md
.agents/skills/dignified-python/references/checklists.md / module-design.md	提交前检查清单、模块设计（模块级代码、内联导入的合法场景）

从 SKILL.md 的 front matter 与加载规则可以看出其"分层加载"设计：

1. 核心知识永远加载（@dignified-python-core.md）：默认值、pathlib、导入组织、反模式；
2. 版本检测只执行一次：确定项目最低 Python 版本后，只加载对应的版本文件（3.10–3.13）；
3. 参考文档按需加载：仅在检测到特定模式时加载，例如任务提到 "click" 或 "CLI" 时加载 cli-patterns.md，提到 "subprocess" 时加载 subprocess.md；
4. 每个文件自包含，无需跨文件即可在其领域内得到完整指引。

2. 五大核心原则

README 的 "Core Principles" 一节给出了五条核心原则，每一条都配有 Good/Avoid 对比示例。

2.1 现代类型语法：Python 3.10+ 写法

在所有位置使用 Python 3.10+ 类型语法，弃用 typing 模块的旧式别名：

# Good (modern)
def process(items: list[str]) -> str | None:
    pass

# Avoid (legacy)
from typing import List, Optional
def process(items: List[str]) -> Optional[str]:
    pass

这与 python-3.10.md 中的说明一致：PEP 585（内置泛型 list[T]、dict[K, V]）和 PEP 604（联合类型 X | Y）消除了对 List、Dict、Union、Optional 等导入的需要。仍需从 typing 导入的只有少数符号：TypeVar（3.10 下的泛型）、Protocol（结构性类型，文档建议少用、优先 ABC）、TYPE_CHECKING（条件导入）以及谨慎使用的 Any。

2.2 优先 LBYL（先检查再行动），但保持务实

该技能偏向 LBYL（Look Before You Leap）：当预检查"廉价且精确"时，优先显式条件检查；而当"操作本身就是权威测试"（如解析、API 调用）时，仍然使用定向的 try/except：

# Good (LBYL)
if path.exists():
    content = path.read_text()

# Avoid (EAFP)
try:
    content = path.read_text()
except FileNotFoundError:
    pass

exception-handling.md 进一步给出了判断准则——"是否可以用廉价且精确的检查在调用前先验证条件？如果可以就优先 LBYL；如果操作本身才是权威校验器，一个小范围的 try/except 往往更清晰"。它还特别提醒：不要用 str.isdigit() 或手写的 ISO 日期启发式去替代真正的解析器；当"尝试解析、失败取默认值"的模式反复出现时，抽一个泛型助手：

from typing import TypeVar, Callable

T = TypeVar("T")

def try_parse(parse: Callable[[str], T], value: str, default: T) -> T:
    """Parse *value* with *parse*, returning *default* on ValueError."""
    try:
        return parse(value)
    except ValueError:
        return default

2.3 pathlib 优先于 os.path

所有文件操作统一使用 pathlib：

# Good
from pathlib import Path
config_path = Path("config.yaml")
if config_path.exists():
    content = config_path.read_text()

# Avoid
import os
if os.path.exists("config.yaml"):
    with open("config.yaml") as f:
        content = f.read()

核心文档 dignified-python-core.md 对这条原则补充了两个容易踩坑的细节，值得重点掌握：

• .exists() 只用于"文件系统存在性确实在需求中"的场景，而不是给 .resolve() 或 .is_relative_to() 做无差别的前置保护。因为 Python 3.11 起 Path.resolve() 对不存在的路径也能解析成功（除非传 strict=True），而 Path.is_relative_to() 返回 bool 而非抛 ValueError。用宽泛的异常包裹这些 API 通常是"隐藏意图"而非"澄清意图"：

# 正确：只有需要真实文件系统条目时才检查存在性
for wt_path in worktree_paths:
    wt_path_resolved = wt_path.resolve()
    if not wt_path_resolved.exists():
        continue
    if current_dir.is_relative_to(wt_path_resolved):
        current_worktree = wt_path_resolved
        break

# 正确：当"不存在"就是错误时，让 resolve() 自己失败
config_dir = config_path.resolve(strict=True)

• 读写文本永远显式指定编码：path.read_text(encoding="utf-8")，避免依赖平台默认编码。

2.4 绝对导入，禁用相对导入

# Good
from myproject.utils import helper

# Avoid
from .utils import helper
from ..shared import helper

配套规则（来自核心文档的 "Import Organization"）：导入默认放在模块级；内联导入只允许在少数例外场景使用（循环依赖、TYPE_CHECKING、可选特性条件导入），其合法边界详见 module-design.md。

2.5 错误边界放在 CLI 层

异常不应该在调用栈深处被静默吞掉，而应在 CLI 入口点集中处理，给最终用户干净的错误消息。配套的 CLI 规范见 cli-patterns.md：只用 click.echo()（绝不用 print()）、错误输出走 err=True（stderr）、CLI 错误用 raise SystemExit(1) 退出。docling 仓库自身的 docling/cli/main.py 就体现了同样的"入口层错误边界"思想：从源码结构看，它在文件头部用 try/except ImportError 检测 typer/rich 是否缺失，把安装指引写入 sys.stderr 后 sys.exit(1)，而不是让缺失依赖的异常一路冒泡。

3. 快速参考：日常编码模式速查

README 的 "Quick Reference" 一节汇总了四类最高频的写法，这里完整保留并加以组织。

3.1 类型注解速查

# Basic types
def greet(name: str) -> str:
    return f"Hello, {name}"

# Collections (modern syntax)
def process(items: list[str], mapping: dict[str, int]) -> tuple[str, int]:
    pass

# Optional/Union (modern syntax)
def find(query: str) -> str | None:
    pass

# Multiple types
def parse(value: str | int | float) -> float:
    pass

3.2 LBYL 条件检查模式

# 文件操作
if path.exists():
    content = path.read_text()

# 字典访问
if "key" in data:
    value = data["key"]

# 属性访问
if hasattr(obj, "method"):
    obj.method()

# 类型检查
if isinstance(value, str):
    result = value.upper()

字典访问还有两个被核心文档明确认可的替代形式：mapping.get(key, default)，以及嵌套键的先检后取（if "config" in data and "timeout" in data["config"]）。

3.3 pathlib 操作速查

from pathlib import Path

# Create path
config = Path("config.yaml")
data_dir = Path("/data")

# Check existence
if config.exists():
    pass

# Read/write
content = config.read_text()
config.write_text("data")

# Directory operations
for file in data_dir.glob("*.txt"):
    print(file.name)

# Path manipulation
full_path = data_dir / "subdir" / "file.txt"
parent = full_path.parent
name = full_path.name

3.4 Click CLI 模式

import click

@click.command()
@click.option("--name", required=True, help="User name")
@click.option("--count", default=1, help="Number of times")
def greet(name: str, count: int) -> None:
    """Greet a user multiple times."""
    for _ in range(count):
        click.echo(f"Hello, {name}!")

if __name__ == "__main__":
    greet()

cli-patterns.md 在此之上给出了完整的命令结构范式：用 click.group() 建立主入口、ctx.ensure_object(dict) 注入配置对象、click.Path(exists=True) 给路径参数加类型约束，以及一个实操细节——在 click.confirm() 之前 sys.stderr.flush()，避免 stderr 输出与 stdin 提示混用时出现缓冲区挂起。

4. 版本检测：自动选择适用的 Python 特性集

README 定义了四步"自动版本检测"流程，用于决定推荐哪些版本特性：

1. 检查 pyproject.toml 的 requires-python 字段；
2. 检查 setup.py/setup.cfg 的 python_requires；
3. 检查 .python-version 文件；
4. 均未指定时，默认按 Python 3.12 处理。

以 docling 仓库本身为例，pyproject.toml 中声明了 requires-python = '>=3.10,<4.0'，因此按这套流程检测出的基线是 Python 3.10，即应以 python-3.10.md 为类型语法基线（| 联合类型、内置泛型），再按项目实际上限叠加更高版本的特性：

版本文件	关键特性
versions/python-3.10.md	结构化模式匹配（match/case）、X | Y 联合类型、括号上下文管理器、更友好的错误信息
versions/python-3.11.md	异常组（ExceptionGroup）、except* 语法、Self 类型、变长泛型
versions/python-3.12.md	PEP 695 类型参数语法（def fT）、@override 装饰器、f-string 改进
versions/python-3.13.md	实验性 free-threading（无 GIL 构建）、JIT 编译、错误信息改进

各版本文件均遵循统一结构：Overview（该版本引入了什么）、完整语法示例（PREFERRED/WRONG 对照）、最佳实践与反模式。

5. 参考文档选型指南："When to Read Each Reference"

README 提供了一张按场景选文档的对照表，SKILL.md 中还有更细粒度的触发条件（例如"定义 5 个以上参数的函数 → 读 api-design.md"、"写 try/except 或看到 from e / from None → 读 exception-handling.md"）：

场景	应读的参考文档
写任何 Python 代码	dignified-python-core.md
构建 CLI 工具	cli-patterns.md
使用 Python 3.10 / 3.11 / 3.12 / 3.13 特性	versions/ 下对应文件
处理异常	references/advanced/exception-handling.md
设计接口（ABC/Protocol）	references/advanced/interfaces.md
复杂类型标注（Literal、类型收窄、TypedDict）	references/advanced/typing-advanced.md
API 设计决策（默认参数、关键字参数）	references/advanced/api-design.md
提交前最终检查	references/checklists.md

6. 核心文档中的进阶规则（源码级细节）

dignified-python-core.md 是"每次技能调用都会加载"的规范，其中还有若干 README 未展开的硬性规则：

• 性能约束：@property 和魔法方法（如 __len__）必须是 O(1)。需要 I/O 或遍历的操作应命名为显式方法（如 fetch_size_from_db），而不是伪装成属性。
• 不保留向后兼容（默认立场）：不默认保留 legacy_format: bool = False 这类兼容分支；只有当代码明确属于公开 API、用户显式要求或迁移成本极高时才保留。
• 禁止再导出：每个符号只有一条规范导入路径，__init__.py 中不做 from x import y 式再导出；插件入口点确需再导出时使用显式语法 from myapp.core.feature import my_function as my_function。
• 变量就近声明：result_path = compute_result_path(ctx) 不应在函数开头声明、20 行后才使用，而应内联到使用点。
• 不拆对象到一次性局部变量：user.name、user.email 只用一次就直接访问字段，不要先解包成局部变量。
• 缩进深度上限 4 层：超过就抽辅助函数。
• 上下文管理器保持内联在 with 语句中：with (lock if thread_safe else nullcontext()):，不要抽到中间变量，以免模糊 __enter__/__exit__ 生命周期。
• 异常处理的三种合法场景：错误边界（CLI/API 层）、"操作本身是权威测试"的场景、补上下文后 raise ... from e 再抛出（对应 ruff B904 链式要求）；其余情况默认让异常继续冒泡。

7. 定位与边界：通用 Python 风格，而非框架专属

README 最后两节划清了该技能的适用边界，这也是把它接入 docling 这类仓库时的关键前提：

• 它是"通用 Python 质量标准"技能，用户在任何 Python 项目（不限于某个编排框架）中都可以在需要代码评审、类型标注、异常处理或 CLI 实现指导时调用它；
• 它是刻意有主见的，而非普适真理：/dignified-python 捕获的是一组明确的、偏向 LBYL 的约定；项目自身约定在必要时可以覆盖它；
• 自选择（Self-Selecting）设计：技能描述明确说明自己只处理通用 Python 质量，框架专属模式交给其他技能（文档中列举了对应框架专属的三个技能），用户会自然地在正确的场景选择它；
• 文档结构一致性：每个参考文档都遵循六段式结构——Overview（高层概念）、Patterns（常见代码模式）、Best Practices（推荐做法）、Anti-Patterns（应避免的做法）、Real-World Examples（生产代码样例）、Related Topics（交叉引用）。

8. 生产模式小结

README 的 "Production Patterns" 一节把五条标准与它们的工程收益对应起来：

标准	生产收益
现代类型语法	改善 IDE 支持与类型检查
LBYL 模式	比 EAFP 更明确、更易调试
pathlib	比 os.path 更可读、更跨平台
绝对导入	避免导入混乱与相对导入问题
CLI 层错误边界	面向最终用户的干净错误消息

结合 docling 仓库实际（pyproject.toml 的 requires-python = '>=3.10,<4.0'、docling/cli/main.py 入口层的依赖检查与 stderr 错误输出、模块级的绝对导入组织），可以看到这套"Dignified Python"规范并非纸上谈兵：它正是作为 AI 辅助开发的参考知识库，直接约束和校准 docling 代码演进中的风格决策。如果你在维护或评审一个 Python 3.10+ 项目，可以直接按"第 4 节版本检测 → 第 5 节选型表 → 核心文档 + 对应版本文件"的路径，把这套标准落到自己的代码库里。