Python ContextDecorator 同时支持 with 与函数装饰器的实现边界

如果一段逻辑既想包住一小段 with 代码，又想包住整个函数，contextlib.ContextDecorator 可以让同一个上下文管理器承担两种入口。它把被装饰函数的调用体放进一次新的上下文生命周期里，但不会把 __enter__() 的返回值交给函数参数。实际使用时，先确认上下文每次都能重新进入，再决定是否采用装饰器写法。

官方文档：https://docs.python.org/3/library/contextlib.html#contextlib.ContextDecorator

ContextDecorator 把两种用法统一到同一生命周期

它不是另一套上下文协议，而是一个可以混入自定义类的基类。类仍然实现普通的 __enter__() 和 __exit__()；作为装饰器使用时，Python 会把函数体等价地包进一次 with。因此进入日志、退出清理和异常参数仍然沿用熟悉的规则。

from contextlib import ContextDecorator


class trace_scope(ContextDecorator):
    def __init__(self, name: str) -> None:
        self.name = name

    def __enter__(self):
        # 进入阶段建立本次调用需要的上下文状态。
        print(f"enter: {self.name}")
        return self

    def __exit__(self, exc_type, exc, traceback) -> bool:
        # 返回 False，让函数中的异常继续传给调用者。
        print(f"exit: {self.name}")
        return False


scope = trace_scope("load-config")
with scope:
    print("with body")

@scope
def load_config() -> None:
    # 装饰器调用等价于在函数体外包一层 with scope。
    print("function body")

load_config()

上面的两个入口都会先打印 enter，执行主体，再打印 exit。注意装饰器本身不改变函数返回值；它只负责把调用包进上下文。如果 __exit__() 返回真值，异常会被视为已处理，这个行为也与普通 with 一致。

让上下文管理器可重复装饰函数

最容易踩的坑是把“只能进入一次”的对象当成装饰器长期复用。函数每调用一次，装饰器都要重新进入上下文；如果类在第一次退出后留下了已关闭的连接、已消费的迭代器或不可复位的标记，第二次调用就会出现隐藏状态错误。

from contextlib import ContextDecorator


class request_scope(ContextDecorator):
    def __init__(self) -> None:
        self.request_id = None

    def __enter__(self):
        # 每次进入都重新分配本次函数调用的状态。
        self.request_id = "new-request"
        return self.request_id

    def __exit__(self, exc_type, exc, traceback) -> bool:
        # 退出时清理状态，避免下一次调用误用旧值。
        self.request_id = None
        return False


scope = request_scope()

@scope
def handle() -> str:
    # 函数可以被连续调用，生命周期由装饰器包住每次调用。
    return "handled"

handle()
handle()

工程上要把可重复性当作硬条件：资源获取放进 __enter__()，释放放进 __exit__()，不要把一次调用的资源对象永久放在实例字段里并假定它下次仍然可用。若上下文对象本身是一次性生成器，直接写显式 with 通常比强行套成装饰器更清楚。

__enter__ 返回值与异常传播的边界

显式 with manager as value 可以把 __enter__() 的返回值绑定到 value；使用 @manager 时没有对应的参数位置，函数也无法自动拿到它。这是两种写法最关键的语义差异。需要连接、事务或临时目录对象时，不要为了少一层缩进而丢掉这个返回值。

异常处理同样不要靠猜。下面的 __exit__ 返回 False，表示只做清理，不吞掉异常；调用方仍然能捕获 ValueError。如果返回 True，异常会在上下文边界被压下去，装饰器和显式 with 都会有同样的结果。

from contextlib import ContextDecorator


class keep_error(ContextDecorator):
    def __enter__(self):
        # 这里只做进入标记，不负责修改异常对象。
        print("start")
        return "context-value"

    def __exit__(self, exc_type, exc, traceback) -> bool:
        # False 表示清理完成后仍把原异常交还给调用者。
        print("finish")
        return False


try:
    with keep_error() as value:
        # 显式 with 可以使用 __enter__ 返回的字符串。
        print(value)
        raise ValueError("bad input")
except ValueError:
    print("caller handles the error")

什么时候坚持显式 with

如果函数主体必须拿到上下文对象，或者上下文每次都要根据参数新建，显式 with 更直白。装饰器适合横切型动作，例如统一记录耗时、设置临时标志、进入和退出一段可重复的观测范围；它不适合隐藏关键资源依赖。

• 只包住函数整体、且不需要 as 返回值：可以使用 ContextDecorator。
• 需要在函数内部操作连接、锁或事务对象：使用 with manager() as resource。
• 函数是协程或异步生成器：选择 AsyncContextDecorator，或显式使用 async with。
• 上下文持有一次性资源：让每次调用创建新实例，不要共享已经退出的实例。

常见问题

ContextDecorator 和普通装饰器有什么区别？

普通装饰器直接包装函数调用；ContextDecorator 额外复用了上下文的进入、退出和异常处理协议，所以同一个类还能用于 with。

为什么被装饰函数拿不到 __enter__ 的返回值？

装饰器语法没有 as 绑定位置。需要这个对象时，用显式 with，或者把依赖改成函数参数并在调用前明确传入。

__exit__ 返回 True 可以吗？

可以，但它表示当前异常已被处理。除非这是明确的业务策略，否则返回 False 或 None，避免装饰器悄悄改变调用方的错误处理。

判断标准很简单：横切逻辑且生命周期可重复时，ContextDecorator 能减少重复代码；需要资源返回值、一次性状态或异步清理时，保留显式上下文边界更安全。