Chapter 52: Context Managers and Resource Cleanup Architecture

资源清理架构要回答的问题是：一个资源在什么位置被获取，谁拥有它，失败时由谁释放它，多个资源交叠时按什么顺序退出，清理动作自身出错时异常状态如何继续传播。读完本章，读者应能追踪一个 with 或 async with 代码块背后的资源生命周期，判断普通 context manager、ExitStack、AsyncExitStack、try/finally 和 finalizer 各自适合承担哪一层责任。

本章贯穿一个报表导出场景：程序要拿锁、创建临时目录、打开若干输入文件、打开输出文件、可选进入事务，还可能在异步版本中建立连接并注册取消回调。这个场景的难点不在语法，而在资源数量运行时才确定，任意一步获取失败都要释放已经获取的资源，异常路径还要保留原始错误信息。

Python 的 with 语句把这类问题收束成 __enter__ 与 __exit__ 两个协议点。Python 3.14 language reference 规定：只要 __enter__() 成功返回，后续目标绑定、语句体执行或异常退出都会进入 __exit__()。这个保证是 context manager 能成为资源边界的基础。

contextlib 是标准库在这个协议之上提供的工具层。contextlib 文档 把生成器式 context manager、同步退出栈、异步退出栈、可选上下文、关闭包装和异常抑制工具放在同一组接口下。本章关注它们在架构中的分工：用协议描述单个资源，用栈描述多个资源，用显式所有权描述 lifetime，用异常规则描述 cleanup 的可信边界。

52.1 contextlib

contextlib 的核心价值是把“进入、产出绑定值、退出、异常处理”这组动作包装成可组合对象。普通 class context manager 直接实现 __enter__ 和 __exit__；生成器式 context manager 使用 @contextmanager 把 yield 前的代码作为获取阶段，把 yield 后的 finally 作为释放阶段。两种写法进入同一个 with 协议，因此调用方看到的是同一种资源边界。

下面的代码把一个临时工作目录包装成 context manager。示例要证明的点是：调用方只接收一个路径对象，释放责任留在 manager 内部；异常是否发生不会改变释放入口。

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory

@contextmanager
def report_workspace(prefix: str):
    with TemporaryDirectory(prefix=prefix) as directory:
        workspace = Path(directory)
        yield workspace

def export_report():
    with report_workspace("report-") as workspace:
        output = workspace / "result.csv"
        output.write_text("id,total\n", encoding="utf-8")
        return output.name

这段代码里有两层 context manager。外层 report_workspace() 是业务语义，内层 TemporaryDirectory() 是标准库资源。yield workspace 把目录路径交给语句体使用；语句体返回、抛异常或目标绑定失败后，生成器会继续执行到内层 TemporaryDirectory() 的退出逻辑。调用方没有拿到目录对象的关闭权，只拿到借用期内可用的路径。

@contextmanager 生成的对象要求生成器恰好产出一次。yield 前抛出的异常属于获取失败，语句体还没有开始；yield 后的 finally 属于释放阶段，会看到语句体异常重新注入到生成器的结果。这里的关键判断是：生成器式写法适合短小、线性、单次使用的资源边界；当进入过程存在多个阶段、多个失败点或复杂状态迁移时，class 或 ExitStack 更容易把所有权写清楚。

contextlib 还提供若干小工具。closing(obj) 把只有 close() 方法的对象转成 context manager；aclosing(obj) 对应异步 aclose()，尤其适合提前结束的异步生成器；nullcontext(value) 用同一个 with 结构表达“有时自己创建资源，有时借用调用方传入资源”；suppress(*exceptions) 把明确可忽略的异常收束到局部范围。redirect_stdout()、redirect_stderr() 和 chdir() 修改进程级状态，适合脚本和局部工具，放进库代码、线程或异步任务时要先确认全局状态是否会影响并发调用方。

contextlib 的工具层只改变资源边界的表达方式。它不会自动判断谁拥有资源，也不会替代业务协议。例如一个函数接收已经打开的文件对象时，函数通常只是 borrower；函数自己调用 open() 时，函数就是 owner。nullcontext() 能把这两种调用形态放进同一个缩进块，但 ownership 仍要由函数签名、文档和代码路径明确表达。

52.2 ExitStack

ExitStack 解决的是运行时动态组合资源的问题。普通多项 with A() as a, B() as b: 在语义上等价于嵌套 with，适合资源数量固定的情况；报表导出的输入文件列表、可选事务、可选锁和额外 cleanup callback 都来自运行时条件，手写嵌套会把主逻辑淹没在层层缩进和重复 try/finally 中。ExitStack 用一个后进先出的退出栈记录已经注册的释放动作，让获取代码保持线性。

下面的示例展示一个同步报表导出路径。示例要证明的点是：每次获取成功后立即注册退出动作，后续任意一步失败时，已经注册的动作都会按反向顺序执行。

from contextlib import ExitStack, nullcontext

class ReportLock:
    def __enter__(self):
        acquire_report_lock()
        return self

    def __exit__(self, exc_type, exc, tb):
        release_report_lock()
        return False

def build_report(input_paths, output_path, transaction=None):
    with ExitStack() as stack:
        stack.enter_context(ReportLock())
        tx = stack.enter_context(transaction or nullcontext())
        inputs = [
            stack.enter_context(open(path, encoding="utf-8"))
            for path in input_paths
        ]
        output = stack.enter_context(open(output_path, "w", encoding="utf-8"))
        stack.callback(write_audit_log, output_path)
        write_report(inputs, output, tx)

stack.enter_context(cm) 会调用 cm.__enter__()，并在成功后把 cm.__exit__ 放入栈中。输入文件列表中第 3 个文件打开失败时，前两个文件、事务和锁已经进入栈，它们会按 file2 → file1 → transaction → lock 的顺序退出。输出文件打开成功后，write_report() 抛异常时，退出顺序还会包含输出文件和审计回调。这个顺序和多层嵌套 with 的退出顺序一致，只是资源数量由循环和条件决定。

ExitStack.callback(func, *args, **kwargs) 注册普通回调，适合没有 __exit__ 协议的释放函数。普通回调不会收到异常三元组，因此它无法抑制异常。ExitStack.push(exit) 注册带 __exit__ 签名的退出函数，适合把“是否抑制异常”交给退出逻辑判断。二者的区别会影响异常路径：普通回调只负责清理，push() 注册的退出函数还参与异常状态变更。

ExitStack.pop_all() 用于所有权转移。一个常见模式是先把一组资源按“全部获取成功才交付”的方式放入临时栈；全部成功后调用 pop_all()，把退出责任转交给新的栈或返回给调用方。这样可以表达 all-or-nothing 语义：任一步失败时临时栈自动释放；全部成功时释放责任离开当前 with 块，进入新的 owner。

还有一个工程边界要明确：ExitStack 实例被垃圾回收时不会隐式调用栈内 callback。这个设计迫使代码把 with ExitStack() 或显式 stack.close() 写成可见 release point。对于文件、锁、事务和临时目录，清理动作应绑定到明确控制流，而非依赖对象何时被回收。

52.3 AsyncExitStack

AsyncExitStack 把同一套退出栈模型扩展到 async with。异步资源的释放动作可能要 await，例如关闭连接、归还连接池对象、取消订阅、等待远端确认或执行异步回滚。同步 ExitStack.close() 无法表达这些 awaitable cleanup；AsyncExitStack 使用 aclose() 和 async with 保证退出栈中的异步清理按顺序等待完成。

下面的示例展示异步报表任务。示例要证明的点是：同一个 AsyncExitStack 可以同时管理异步 context manager、同步 context manager 和异步 callback；退出时同步资源和异步资源仍按反向注册顺序释放。

from contextlib import AsyncExitStack

async def export_remote_report(client_factory, log_path):
    async with AsyncExitStack() as stack:
        client = await stack.enter_async_context(client_factory())
        log_file = stack.enter_context(open(log_path, "a", encoding="utf-8"))

        subscription = await client.subscribe("report-events")
        stack.push_async_callback(client.unsubscribe, subscription)

        token = await client.acquire_token()
        stack.push_async_callback(client.release_token, token)

        await client.write_report(log_file)

enter_async_context(cm) 期望对象实现 __aenter__ 和 __aexit__，并在进入成功后把异步退出动作压栈。enter_context(cm) 仍可管理同步 context manager，因此异步任务中打开本地日志文件不需要额外包装。push_async_callback() 注册 coroutine function，退出时会等待它完成。上例如果 client.acquire_token() 之后的写入失败，退出顺序是 release_token → unsubscribe → close log_file → client.__aexit__。

异步释放有一个额外约束：cleanup 所依赖的 task、context variables 和 event loop 必须仍然存在。contextlib.aclosing() 对提前结束的异步生成器有实际意义，因为它让生成器的异步退出代码在同一个 async with 生命周期中执行。若把异步生成器留给稍后的垃圾回收路径，退出代码可能运行在错误的任务上下文中，也可能失去原本的 context variable 状态。

AsyncExitStack 的判断顺序可以固定为三步。先区分资源的进入动作是否需要 await，需要则使用 enter_async_context() 或显式 await 后注册异步 callback。再区分释放动作是否需要 await，需要则使用 push_async_callback() 或 push_async_exit()。最后确认退出栈本身通过 async with 或 await stack.aclose() 收束，异步资源的释放入口应保持可等待。

52.4 deterministic cleanup

deterministic cleanup 指资源有可预测、可定位、可复查的释放点。它的关注重点通常落在 Python 托管内存之外，包括文件描述符、锁、事务、临时目录、网络连接、订阅、进程级状态和远端租约。这些资源的约束来自操作系统、数据库、服务端或业务协议；释放时间拖延会表现为文件句柄耗尽、锁长期占用、事务悬挂、临时文件残留或连接池枯竭。

with 语句提供的确定性来自控制流。只要 __enter__() 成功返回，__exit__() 就成为释放点；语句体正常结束、抛异常、目标绑定失败都会进入退出逻辑。CPython 的引用计数常让某些对象在引用归零时很快被销毁，但语言层面的资源设计不应依赖这种实现策略。PyPy、MicroPython、循环引用、全局缓存和 traceback 持有关系都会改变对象销毁时机。

下面的图把报表导出的确定性释放路径压缩成一个可复查模型。图中的重点是“注册成功的释放动作”与“实际获取成功的资源”一一对应，退出栈只释放已经进入栈的资源。

这个模型能解释三个常见边界。第一，获取失败发生在注册之前，该资源没有进入栈，退出栈也不会尝试释放它。第二，获取成功后立刻注册，后续任意失败都会覆盖到它。第三，退出阶段的返回值和异常会影响外层看到的异常状态，因此 cleanup 代码本身也属于错误处理路径的一部分。

确定性清理也要求 release point 和 owner 对齐。函数自己获取的文件对象由函数释放；调用方传入的文件对象由调用方释放；函数从资源池借出的连接通常要归还给池，而非关闭底层 socket。with 和 ExitStack 只能表达“何时退出”，无法替代码自动推断“退出动作应该是 close、release、rollback、cancel 还是 restore”。

52.5 context composition

context composition 指把多个资源边界组合成一个更大的资源边界。组合的核心问题是部分成功：如果第 1 个资源成功、第 2 个资源成功、第 3 个资源失败，组合体的 __enter__() 整体失败，但前两个资源已经进入生命周期。健壮组合的规则是：每个子资源获取成功后立即把释放动作注册到局部退出栈；组合整体成功后再决定是否把 ownership 转移给组合对象。

下面的 class 把锁、临时目录和输出文件组合成一个业务级 context manager。示例要证明的点是：__enter__() 自己内部也可以使用 ExitStack，从而让组合体的获取阶段具备异常安全。

from contextlib import ExitStack
from tempfile import TemporaryDirectory
from pathlib import Path

class ReportBundle:
    def __init__(self, lock, output_name):
        self._lock = lock
        self._output_name = output_name
        self._stack = None

    def __enter__(self):
        stack = ExitStack()
        try:
            stack.enter_context(self._lock)
            temp = stack.enter_context(TemporaryDirectory(prefix="report-"))
            output = stack.enter_context(
                open(Path(temp) / self._output_name, "w", encoding="utf-8")
            )
            self.workspace = Path(temp)
            self.output = output
            self._stack = stack.pop_all()
            return self
        finally:
            stack.close()

    def __exit__(self, exc_type, exc, tb):
        return self._stack.__exit__(exc_type, exc, tb)

__enter__() 先创建临时 ExitStack。锁、临时目录和输出文件任何一步失败时，finally: stack.close() 会释放已经获取的资源。全部成功后，pop_all() 把 callback 栈转移到 self._stack，随后临时栈变空，finally 执行时不会释放已经交付给对象的资源。外层 with ReportBundle(...) 退出时，self._stack.__exit__() 再统一释放组合体持有的资源。

这个模式把 partial acquisition 的责任放在组合体内部，调用方只看到一个稳定的业务对象。它适合封装“必须一起成立”的资源组，例如事务加锁、临时目录加文件、连接加订阅、配置替换加恢复回调。组合体的 __exit__() 返回值应保持保守，通常返回 False，让原始异常继续传播；只有明确设计为异常抑制器的 manager 才返回真值。

组合顺序要反映依赖关系。后获取的资源通常依赖先获取的资源，释放时应先释放后获取者。例如订阅依赖连接，退出时先取消订阅，再关闭连接；输出文件依赖临时目录，退出时先关闭文件，再删除目录；事务依赖锁时，是否先提交事务再释放锁要由业务一致性决定。ExitStack 提供的是反向顺序执行能力，正确注册顺序仍由设计者负责。

52.6 resource lifetime

resource lifetime 是资源从获取到释放之间的有效区间。分析 lifetime 时应把角色和动作拆开：owner 负责释放，borrower 只在借用期内使用，transfer 表示所有权迁移，release 表示归还或解除占用，close 表示关闭底层资源，cancel 表示撤销尚未完成的异步或远端工作，finalizer 表示对象销毁时可能执行的兜底清理。

角色或动作	在资源生命周期中的含义	典型代码信号
owner	创建、获取或接收所有权的一方，负责在边界处释放	open()、TemporaryDirectory()、acquire()
borrower	临时使用资源的一方，使用期结束后不关闭底层资源	函数参数 file_obj、传入的 session
transfer	释放责任从一个对象转移到另一个对象	ExitStack.pop_all()、返回带 close() 的句柄
release	把资源归还给池、锁管理器或外部服务	release()、rollback()、restore()
close	关闭文件、socket、stream 或进程句柄	close()、aclose()
cancel	撤销异步任务、订阅、租约或未完成操作	cancel()、unsubscribe()
finalizer	对象销毁时执行的清理入口，适合作为兜底信号	__del__()、weakref.finalize()

owner 与 borrower 的区别会直接改变 API 设计。下面的函数同时支持路径和已打开文件对象。路径输入意味着函数自己打开文件并成为 owner；文件对象输入意味着调用方保留所有权，函数只借用。nullcontext() 让两个分支在同一个读取逻辑中汇合。

from contextlib import nullcontext
from os import PathLike

PathValue = str | bytes | PathLike[str] | PathLike[bytes]

def load_header(source):
    if isinstance(source, (str, bytes, PathLike)):
        manager = open(source, encoding="utf-8")
    else:
        manager = nullcontext(source)

    with manager as file_obj:
        return file_obj.readline().strip()

这段代码的结论是：load_header("report.csv") 会在函数内部关闭文件；load_header(file_obj) 会在函数返回后保持 file_obj 的生命周期由调用方控制。这个区别应在函数文档和测试中固定下来，因为调用方会据此决定是否还能继续读同一个文件对象。

finalizer 的位置也要放准。__del__() 或 weakref.finalize() 可以作为泄漏时的兜底提示或资源释放补线，但它们不提供业务上可预测的释放时刻。资源清理架构应把 with、ExitStack、AsyncExitStack、显式 close() 和 aclose() 放在主路径，把 finalizer 放在诊断与防御层。这样可以同时获得可读控制流和运行时兜底。

52.7 exception-safe cleanup

exception-safe cleanup 要保证三件事可分析：原始异常如何交给退出逻辑，清理异常如何改变传播结果，异常抑制是否被局部限定。__exit__(exc_type, exc, tb) 的三个参数记录语句体异常；没有异常时三个参数都是 None。__exit__() 返回假值时原始异常继续传播，返回真值时异常被抑制。ExitStack 会把这个规则扩展到多个退出函数，并把内层退出函数造成的抑制或替换传递给外层退出函数。

事务 context manager 是观察异常安全的典型材料。示例要证明的点是：事务根据 exc_type 选择 commit 或 rollback，随后返回 False，让业务异常仍由调用方处理。

class Transaction:
    def __init__(self, connection):
        self.connection = connection

    def __enter__(self):
        self.connection.begin()
        return self

    def __exit__(self, exc_type, exc, tb):
        if exc_type is None:
            self.connection.commit()
        else:
            self.connection.rollback()
        return False

如果语句体正常结束，commit() 运行。若语句体抛出 ValueError，rollback() 运行，然后 ValueError 继续传播。若 rollback() 自身抛出 RuntimeError，外层最终看到的新异常会变成 cleanup 异常，原始 ValueError 会通过异常上下文链保留。这个结果符合 Python 异常传播规则：清理阶段也是普通 Python 代码，它的失败会改变外层可见错误。

异常抑制要收束在精确场景中。contextlib.suppress(FileNotFoundError) 适合删除临时文件这类幂等清理，因为文件已经消失时继续执行符合语义。它不适合包住大段业务逻辑，因为大范围抑制会让调用方失去失败信号。Python 3.12 起，suppress() 对 BaseExceptionGroup 中匹配的异常成员也会执行抑制处理；版本敏感代码应按目标 Python 版本确认行为。

finally 与 context manager 的关系也要分层。try/finally 是语言级清理工具，适合极短、局部、单资源释放；context manager 把这段模式封装成可复用对象；ExitStack 把多个 context manager 和 callback 组成动态退出栈。工程判断顺序是：单个资源先写成 context manager；固定数量资源用嵌套或多项 with；动态数量资源用 ExitStack；异步释放用 AsyncExitStack；兜底泄漏诊断再考虑 finalizer。

本章最终建立的判断模型是：资源清理先看 ownership，再看 release point，再看组合顺序，最后看异常状态。contextlib 提供工具，with 提供语义保证，ExitStack 和 AsyncExitStack 提供动态组合能力；可靠设计来自这三者和清晰 lifetime 标注之间的配合。

最小自检任务

阅读下面的代码，判断 run() 抛出 ValueError("body") 时，退出动作的执行顺序是什么；再判断如果 Trace("b").__exit__() 返回 True，外层还能否看到 ValueError("body")。

from contextlib import ExitStack

class Trace:
    def __init__(self, name, suppress=False):
        self.name = name
        self.suppress = suppress

    def __enter__(self):
        print(f"enter {self.name}")
        return self

    def __exit__(self, exc_type, exc, tb):
        print(f"exit {self.name}", exc_type.__name__ if exc_type else None)
        return self.suppress

def run():
    with ExitStack() as stack:
        stack.enter_context(Trace("a"))
        stack.callback(lambda: print("callback"))
        stack.enter_context(Trace("b"))
        raise ValueError("body")

答案要点

ExitStack 按注册的反向顺序退出。Trace("b") 最后进入，所以最先执行 b.__exit__()，它收到 ValueError。随后普通 callback 执行，它没有异常三元组，也没有抑制能力。最后 a.__exit__() 执行；在 b.__exit__() 返回假值且 callback 没有抛出新异常时，a.__exit__() 仍会看到 ValueError，外层也会继续看到这个异常。

如果 Trace("b").__exit__() 返回 True，ValueError("body") 被内层退出函数抑制，后续 callback 继续执行，a.__exit__() 收到的异常三元组变成 None, None, None。外层不会再看到原始 ValueError。这个判断来自 with 语义和 ExitStack 的栈式异常状态更新：内层退出函数可以改变外层退出函数接收到的异常状态。

本章知识点总结

• 协议入口：with 通过 __enter__ 和 __exit__ 建立资源边界，进入成功后退出逻辑会在正常路径和异常路径上执行。
• 工具分层：contextlib 把生成器函数、关闭包装、可选上下文、异常抑制和 decorator 统一包装成 context manager 工具。
• 生成器边界：@contextmanager 适合短小线性资源，yield 前是获取阶段，yield 后的 finally 是释放阶段。
• 动态组合：ExitStack 用后进先出的退出栈表达运行时数量变化的资源组合，获取成功后应立即注册释放动作。
• 回调差异：callback() 注册普通清理函数，只执行清理；push() 注册带 __exit__ 形态的退出函数，可以参与异常状态处理。
• 异步释放：AsyncExitStack 支持异步 context manager、同步 context manager 和异步 callback，退出时通过 aclose() 等待 cleanup 完成。
• 确定释放：deterministic cleanup 的核心是可见 release point，文件、锁、事务和连接的释放时刻应由控制流明确决定。
• 组合安全：context composition 要覆盖 partial acquisition，已获取资源必须在组合体 __enter__() 失败时按正确顺序释放。
• 生命周期角色：owner 负责释放，borrower 只在借用期内使用，transfer 会移动释放责任，finalizer 只适合作为兜底层。
• 异常状态：__exit__() 的返回值决定原始异常是否继续传播，cleanup 自身抛出的新异常会改变外层可见错误。
• 抑制边界：异常抑制应限定在语义明确的小范围，例如幂等清理中的 FileNotFoundError。
• 判断顺序：资源清理先定位 ownership，再确认 release point，再检查组合顺序，最后分析异常传播和抑制规则。