Python contextlib 资源清理配方：把 try/finally 收进上下文管理器

Python 里最常见的资源清理问题，不是不会写 try/finally，而是同一套打开、使用、关闭逻辑散落在多个函数里。文件、临时目录、锁、连接对象一多，代码会越来越像“先做一堆准备，最后再小心收尾”。

contextlib 是标准库里专门帮助我们整理上下文管理器的模块。它适合把重复的清理逻辑收进 with 语句，让业务代码只关注“资源已经准备好，可以使用”。这篇文章用配方卡片的方式，整理三个实用写法：自定义上下文管理器、忽略可接受的小错误、动态管理多个资源。

问题：清理逻辑散在业务代码里

先看一个很常见的片段：函数里创建临时目录，处理文件，最后要删除临时目录。代码能跑，但清理逻辑和业务逻辑绑在一起，后续一改就容易漏。

import shutil
from pathlib import Path


def build_report(source: Path, workdir: Path) -> Path:
    temp_dir = workdir / "tmp-report"
    temp_dir.mkdir(parents=True, exist_ok=True)
    try:
        output = temp_dir / "result.txt"
        output.write_text(source.read_text(encoding="utf-8"), encoding="utf-8")
        return output
    finally:
        shutil.rmtree(temp_dir, ignore_errors=True)

这个例子有三个不舒服的地方：函数核心目的是生成报告，但开头和结尾都在处理临时目录；清理策略以后如果要改，每个类似函数都要改；如果中途又加了文件句柄或锁，finally 会继续变长。

更稳的思路是把“准备资源”和“清理资源”做成一个上下文管理器。调用方只写 with，资源的生命周期由上下文管理器负责。

最小配方：用 contextmanager 包住打开和关闭

contextlib.contextmanager 可以把一个生成器函数变成上下文管理器。函数里 yield 前面的代码负责准备资源，yield 后面的代码负责退出时清理。

from contextlib import contextmanager
from pathlib import Path
import shutil


@contextmanager
def temporary_dir(path: Path):
    path.mkdir(parents=True, exist_ok=True)
    try:
        yield path
    finally:
        shutil.rmtree(path, ignore_errors=True)

使用时就会干净很多：

def build_report(source: Path, workdir: Path) -> str:
    with temporary_dir(workdir / "tmp-report") as temp_dir:
        output = temp_dir / "result.txt"
        output.write_text(source.read_text(encoding="utf-8"), encoding="utf-8")
        return output.read_text(encoding="utf-8")

这里故意返回字符串，而不是返回临时目录里的文件路径。因为 with 退出后临时目录会被删除，返回一个已经失效的路径没有意义。这个边界要在设计时想清楚。

关键代码：把临时工作目录做成 with 块

如果临时目录里还有多个步骤，可以继续把业务代码拆小，让上下文管理器只负责生命周期。

def normalize_text(text: str) -> str:
    lines = [line.strip() for line in text.splitlines()]
    return "\n".join(line for line in lines if line)


def save_normalized_report(source: Path, workdir: Path, target: Path) -> None:
    with temporary_dir(workdir / "tmp-report") as temp_dir:
        draft = temp_dir / "draft.txt"
        draft.write_text(normalize_text(source.read_text(encoding="utf-8")), encoding="utf-8")
        target.write_text(draft.read_text(encoding="utf-8"), encoding="utf-8")

这段代码的关键点是：业务函数不用关心临时目录何时删除，只关心拿到一个可用目录并完成处理。上下文管理器把资源边界固定住，后续加日志、加统计、换清理策略，都能集中改。

变体：用 suppress 处理可接受的小错误

有些错误是可以接受的。例如清理缓存文件时，文件已经不存在并不算故障。以前可能会写一个很短的 try 块：

try:
    cache_file.unlink()
except FileNotFoundError:
    pass

用 contextlib.suppress 可以把意图写得更直接：

from contextlib import suppress


def remove_cache(cache_file: Path) -> None:
    with suppress(FileNotFoundError):
        cache_file.unlink()

注意不要为了“让代码不报错”而扩大忽略范围。只忽略你能解释清楚、并且业务上允许发生的异常。比如删除缓存文件可以忽略不存在，但写入目标文件失败通常不应该被吞掉。

变体：用 ExitStack 管理动态数量资源

当资源数量固定时，嵌套 with 还可以接受；当文件数量来自参数列表时，ExitStack 更合适。它可以把多个上下文管理器登记到一个栈里，退出时按相反顺序清理。

from contextlib import ExitStack


def read_many(paths: list[Path]) -> list[str]:
    with ExitStack() as stack:
        files = [
            stack.enter_context(path.open("r", encoding="utf-8"))
            for path in paths
        ]
        return [file.read() for file in files]

这段代码的好处是资源数量可以变化，但关闭动作仍然集中、可靠。只要进入了 ExitStack，后续任何一步出错，已经打开的文件都会被关闭。

兼容坑：哪些场景不要硬套

第一，contextmanager 函数只能正常产出一次。 它适合描述“进入一次、退出一次”的生命周期，不适合写成循环产出多个结果的普通生成器。

第二，不要在清理阶段隐藏重要错误。 清理失败可能说明文件权限、磁盘状态或对象状态异常。如果业务需要强一致结果，清理阶段也应该记录日志或继续抛出。

第三，不要返回已经被清理的资源。 临时目录、临时文件、打开的连接对象都应该在 with 块内使用。退出后再访问，通常就是设计边界不清。

第四，suppress 只用于明确可接受的异常。 如果你写成 with suppress(Exception)，排查问题会变得很困难。建议只列具体异常类型。

完整片段：批量读取文件并保证关闭

最后把配方组合成一个完整小工具：读取多个文本文件，跳过不存在的可选文件，把内容合并到目标文件。这里使用 ExitStack 管理已打开文件，用 suppress 删除旧输出。

from contextlib import ExitStack, suppress
from pathlib import Path


def merge_text_files(inputs: list[Path], output: Path) -> None:
    output.parent.mkdir(parents=True, exist_ok=True)

    with suppress(FileNotFoundError):
        output.unlink()

    with ExitStack() as stack:
        handles = []
        for path in inputs:
            if not path.exists():
                continue
            handles.append(stack.enter_context(path.open("r", encoding="utf-8")))

        parts = []
        for handle in handles:
            text = handle.read().strip()
            if text:
                parts.append(text)

    output.write_text("\n\n".join(parts) + "\n", encoding="utf-8")

这个片段适合改造成配置合并、Markdown 片段拼接、测试数据准备等小工具。核心原则不变：资源进入和退出写在同一个上下文结构里，业务代码只处理已经准备好的对象。

总结一下，contextlib 的价值不是少写几行代码，而是把资源生命周期写清楚。一个资源用 contextmanager 封装，一类可接受的小错误用 suppress 表达，动态数量资源交给 ExitStack。这样写出来的小工具更容易读，也更容易在出错时保持资源状态可控。