docling 中的 Python 异常处理模式：EAFP 边界、B904 异常链与反模式

本文基于 docling 仓库内 dignified-python 技能集的高级参考文档 exception-handling.md 展开，系统讲解 Python 中"何时该用异常、何时该用显式前置检查（LBYL）"的判定标准、Ruff 规则 B904 要求的异常链（from e / from None）、第三方 API 兼容写法与静默吞异常等反模式。读完本文后，你既能掌握一套可直接落地的 try/except 编写规范，也能在 docling/exceptions.py 与各后端源码中看到这套规范在真实文档转换框架中的印证。

一、文档定位：dignified-python 技能集中的异常处理参考

SKILL.md 是 docling 仓库内"有主见"（opinionated）的生产级 Python 编码规范技能，适用于 Python 3.10–3.13。它采用"核心知识常驻 + 参考文档按需加载"的组织方式：

• 核心文件 dignified-python-core.md 每次调用自动加载，确立了总基调——默认偏向 LBYL（Look Before You Leap），即当前置条件廉价且精确时，优先写显式检查而非 try/except；
• 高级参考 exception-handling.md 在以下场景被触发加载：编写 try/except 块、包装可能抛异常的第三方 API、见到 from e 或 from None、不确定是否存在 LBYL 替代方案时。

核心文件给出了 LBYL 的默认写法示例，例如字典访问应使用成员测试或 .get()，而不是把 KeyError 当作控制流：

# CORRECT: 先检查再访问
if key in mapping:
    value = mapping[key]
    process(value)

# WRONG: 用异常做控制流
try:
    value = mapping[key]
    process(value)
except KeyError:
    pass

而 exception-handling.md 正是回答另一个问题的：既然默认不鼓励 try/except，那么哪些场景例外？ 这正是本文的主体。

二、异常的三种正当使用场景

参考文档开宗明义列出了异常是"正确工具"的三类常见情境：错误边界（CLI/API 层）、调用本身即为权威判定的操作、以及在重新抛出前补充上下文。

2.1 场景一：错误边界（Error Boundaries）

错误边界是系统的最外层，负责把内部异常翻译为用户可读的退出信息。文档给出的可接受示例是一个 CLI 命令的收尾处：

# ACCEPTABLE: CLI command error boundary
@click.command("create")
@click.pass_obj
def create(ctx: AppContext, name: str) -> None:
    """Create a resource."""
    try:
        create_resource(ctx, name)
    except subprocess.CalledProcessError as e:
        click.echo(f"Error: Git command failed: {e.stderr}", err=True)
        raise SystemExit(1) from e

要点有二：一是 except 精确捕获 subprocess.CalledProcessError 而非裸 Exception；二是 raise SystemExit(1) from e 显式保留了原始异常的 traceback。这个"边界翻译"思想在 docling 中同样可见：docling/pipeline/base_pipeline.py 第 97 行在管道执行失败时包装抛出 RuntimeError 并用 from e 保持链条完整：

raise RuntimeError(f"Pipeline {self.__class__.__name__} failed") from e

2.2 场景二：第三方 API 兼容性（调用即权威判定）

有些第三方 API 只能通过"试着调用、看是否失败"来探测其行为。文档给出的 BigQuery 示例很典型：TABLESAMPLE 对视图不生效，且无法在调用前可靠判断某张表是否支持它：

# ACCEPTABLE: Third-party API forces exception handling
def _get_bigquery_sample(sql_client, table_name):
    """
    BigQuery's TABLESAMPLE doesn't work on views.
    There's no reliable way to determine a priori whether
    a table supports TABLESAMPLE.
    """
    try:
        return sql_client.run_query(f"SELECT * FROM {table_name} TABLESAMPLE...")
    except Exception:
        return sql_client.run_query(f"SELECT * FROM {table_name} ORDER BY RAND()...")

文档为此给出了一条判别准则——"先用 LBYL 吗"的测试：能否在调用 API 之前，用一个廉价、精确的检查验证该条件？如果能，优先做显式检查；如果操作本身就是权威验证器（authoritative validator），那么一小段 try/except 往往更清晰。

docling 的后端实现中有大量与之同构的写法：各格式后端在 load()/解析路径上捕获底层解析库的异常，并统一转译为 docling/exceptions.py 中的项目异常。例如：

• docling/backend/epub_backend.py 第 214 行：raise RuntimeError(f"Failed to extract EPUB archive: {e}") from e——异常在边界处被补充上下文后重新抛出；
• docling/backend/utils/image_resource_loader.py 第 61 行：raise ValueError(f"Cannot resolve hostname: {hostname}") from e。

docling/exceptions.py 本身也展示了异常层级的设计意图：DocumentLoadError 继承自 ConversionError 再继承 BaseError(RuntimeError)，其 docstring 明确说明这样设计是为了"与内部缺陷（缺依赖、bug）区分开，且既有 except RuntimeError 的调用方继续有效"——这正是"在边界处转译异常"思想的类型系统落地。

2.3 场景三：重新抛出前补充上下文

# ACCEPTABLE: Adding context before re-raising
try:
    process_file(config_file)
except yaml.YAMLError as e:
    raise ValueError(f"Failed to parse config file {config_file}: {e}") from e

这种"窄异常进、宽语义出"的转译，让上层调用者无需了解底层解析库的细节，只面向业务异常处理。

2.4 附注：优先使用真正的解析器，而非脆弱的预检查

文档还强调，不要用 str.isdigit() 或手写的 ISO 日期启发式这类"字符串形状检查"替代真正的解析器调用——这类检查经常拒绝合法输入、放行非法输入。当"try 解析 + 返回默认值"的模式反复出现时，应抽出一个泛型助手函数：

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

用法：

from datetime import datetime

port = try_parse(int, user_input, 80)
ts = try_parse(datetime.fromisoformat, timestamp_str, None)

只有在你有意接受比解析器更窄的格式且能精确陈述该规则时，才使用独立的前置检查。

三、异常链与 Ruff B904 合规

Ruff 规则 B904 要求：在 except 块内抛出异常时，必须显式声明异常链，否则原始 traceback 会丢失。文档给出四组对照示例：

# CORRECT: Chain to preserve context
try:
    parse_config(path)
except ValueError as e:
    click.echo(json.dumps({"success": False, "error": str(e)}))
    raise SystemExit(1) from e  # Preserves traceback

# CORRECT: Explicitly break chain when intentional
try:
    fetch_from_cache(key)
except KeyError:
    # Original exception is not relevant to caller
    raise ValueError(f"Unknown key: {key}") from None

# WRONG: Missing exception chain (B904 violation)
try:
    parse_config(path)
except ValueError:
    raise SystemExit(1)  # Lint error: missing 'from e' or 'from None'

# CORRECT: CLI error boundary with JSON output
try:
    result = some_operation()
except RuntimeError as e:
    click.echo(json.dumps({"success": False, "error": str(e)}))
    raise SystemExit(0) from None  # Exception is in JSON, traceback irrelevant to CLI user

选择准则很简单：

• from e —— 保留原始异常供调试（默认选择）；
• from None —— 有意切断链条：典型场景是异常类型转译（原异常对调用方无意义）或 CLI 的 JSON 输出（错误信息已进入 JSON，traceback 对终端用户没有价值）。

docling 仓库源码中两种写法均有真实用例，可以互相印证：

• from e 用于保留排查线索，如 docling/backend/asciidoc_backend.py、docling/backend/csv_backend.py、docling/backend/html_backend.py 等十余个后端在解析失败时携带原始异常上抛；
• from None 用于主动截断，如 docling/models/stages/ocr/easyocr_model.py 第 70 行 raise ValueError(f"Unsupported EasyOCR language code: {language}") from None——语言代码不合法属于参数错误，底层异常（若有）对调用方没有诊断价值。

需要说明的是，从 pyproject.toml 的 [tool.ruff.lint] select 列表看，当前仓库启用的规则族是 C、C9、E、F、I、PD、PIE、Q、RUF、S307、W、ASYNC、UP，并未显式勾选 B（flake8-bugbear），因此 B904 在本仓库并非强制 lint 规则，而是作为 dignified-python 技能集的约定性规范存在。这一点在应用该文档时值得注意：它是团队编码守则，而非仓库 CI 的硬性门槛。

四、异常反模式

文档最后两条反模式都围绕一个词：静默。

4.1 绝不静默吞掉异常

即使在错误边界，也至少要留下日志，否则问题无从诊断：

# WRONG: Silent exception swallowing
try:
    risky_operation()
except:
    pass

# WRONG: Silent swallowing even at error boundary
try:
    optional_feature()
except Exception:
    pass  # Silent - impossible to diagnose issues

# CORRECT: Let exceptions bubble up (default)
risky_operation()

# CORRECT: At error boundaries, log the exception
try:
    optional_feature()
except Exception as e:
    logging.warning("Optional feature failed: %s", e)  # Diagnosable

与核心文件的默认立场呼应：让异常自然冒泡是默认行为，捕获是例外，而捕获则必须"有产出"（重新抛出、转译或记日志）。

4.2 绝不使用静默回退（silent fallback）

# WRONG: Silent fallback masks failure
def process_text(text: str) -> dict:
    try:
        return llm_client.process(text)
    except Exception:
        return regex_parse_fallback(text)

# CORRECT: Let error bubble to boundary
def process_text(text: str) -> dict:
    return llm_client.process(text)

这条反模式对 docling 这类文档转换管线尤其重要：如果某个后端解析失败被静默替换成降级结果，用户拿到的是"看似成功、实则错误"的输出，且无任何诊断线索。仓库中的做法正相反——DocumentLoadError 被明确定义为"后端无法把输入字节解析为文档"的显式信号（见 docling/exceptions.py 第 13–19 行），并在 docling/backend/iwork/pages_backend.py 等处以 except DocumentLoadError 精确捕获后走显式的失败分支，而非吞掉。

五、小结：一套可执行的判定清单

综合 exception-handling.md 与 dignified-python-core.md，编写 try/except 前可以按以下顺序自问：

1. 能否用廉价、精确的前置检查替代？ 能 → 写 LBYL（成员测试、.get()、exists() 等）；
2. 不能时，是否属于三类正当场景之一？ 错误边界 / 调用即权威判定 / 补充上下文后重抛；
3. 在 except 内抛出异常了吗？ 是 → 必须 from e 或 from None（B904），并想清楚原异常对调用方是否有价值；
4. 捕获后是否"有产出"？ 重抛、转译、或至少 logging.warning——裸 pass 与静默回退一律禁止；
5. 解析类逻辑是否用了真正的解析器？ 避免 isdigit() 式预检查，重复模式抽成 try_parse 助手。

这套规范以 docling 的多后端文档转换架构为真实注脚：从统一异常基类（BaseError → ConversionError → DocumentLoadError）到各后端的 raise ... from e 链式抛出，再到边界处的转译与失败分支处理，恰好覆盖了文档中每一条正例与反例的落点。