Python contextlib.nullcontext 统一同步异步入口

我第一次用 contextlib.nullcontext，是在重构一个“既接受文件路径，也接受已打开文件对象”的函数。原代码有两条几乎一样的分支：路径分支负责 open 和关闭文件，对象分支直接读取且不能关闭调用方的文件。真正不同的只有资源怎么进入和退出，中间处理逻辑却复制了两遍。

nullcontext(enter_result) 正是给这种可选上下文管理器准备的无操作替身：进入上下文时原样返回 enter_result，退出时不做清理。这样，函数自己创建的资源使用真正的上下文管理器，调用方提供的资源使用 nullcontext，两条路径最终汇合到一个 with 或 async with 主体。

先检查：问题是不是资源所有权分叉

看到下面这些现象时，nullcontext 往往比继续写 if/else 更清楚：

• 参数可以是路径，也可以是已经打开的文件对象；
• HTTP 客户端可以临时创建，也可以复用调用方传入的会话；
• 事务、锁、追踪 span 或性能计时器可以按配置启用；
• 两条分支的业务主体完全相同，只是进入和退出动作不同。

关键判断不是“能不能少写几行”，而是谁拥有资源。函数创建的资源通常由函数关闭；调用方传入的资源通常由调用方关闭。nullcontext 的价值是保留这条所有权边界，同时统一业务入口。

同步入口：文件路径和文件对象共用一个 with

下面的函数接受路径或二进制文件对象。路径由函数打开，因此离开 with 时必须关闭；文件对象由调用方传入，函数只借用，不应擅自关闭。

from os import PathLike
from typing import BinaryIO
from contextlib import nullcontext


def read_prefix(source: str | PathLike[str] | BinaryIO, size: int = 64) -> bytes:
    if isinstance(source, (str, PathLike)):
        # 本函数创建文件，因此由 open 的上下文管理器负责关闭
        cm = open(source, "rb")
    else:
        # 调用方拥有文件对象，退出 with 时保持对象可用
        cm = nullcontext(source)

    with cm as file:
        # 两种输入只保留一份读取与长度校验逻辑
        data = file.read(size)
        if len(data) == 0:
            raise ValueError("文件内容为空")
        return data

nullcontext(source) 的参数叫 enter_result。进入上下文时，with cm as file 得到的就是原来的 source；退出时既不调用它的 close，也不吞掉异常。因此文件对象在函数返回后仍保持调用方原来的生命周期。

用测试确认“借用但不关闭”

from io import BytesIO


def test_external_file_remains_open() -> None:
    external = BytesIO(b"abcdef")

    # 函数只借用 external，读取完成后不应关闭它
    assert read_prefix(external, 3) == b"abc"
    assert not external.closed

    # 调用方仍可继续使用，并在自己的生命周期结束时关闭
    assert external.read() == b"def"
    external.close()

如果这个断言失败，问题通常不是 nullcontext，而是你仍把外部对象放进了它自己的 with external 中。多数文件对象的 __exit__ 会关闭自身，nullcontext 才是“只把对象带进代码块，不替它做退出动作”的包装器。

异步入口：可选会话共用一个 async with

从 Python 3.10 开始，nullcontext 同时支持异步上下文管理器协议。典型场景是异步请求函数：没有传会话时临时创建并关闭；传入已有会话时复用，但关闭责任仍属于调用方。

from contextlib import nullcontext
from aiohttp import ClientSession


async def fetch_json(url: str, session: ClientSession | None = None) -> dict:
    if session is None:
        # 本函数创建临时会话，async with 退出时会自动关闭
        cm = ClientSession()
    else:
        # 外部会话只被借用，nullcontext 不会关闭它
        cm = nullcontext(session)

    async with cm as active_session:
        # 创建或复用会话后，请求与状态检查只保留一份
        async with active_session.get(url) as response:
            response.raise_for_status()
            return await response.json()

条件判断应写成 session is None，不要写 if not session。后者把“没有提供会话”和“对象的布尔值为假”混成一件事；可选依赖的语义通常只由 None 表示。

Python 3.9 报异步协议错误怎么办

如果在 Python 3.9 或更早版本执行 async with nullcontext(...)，会遇到对象不支持异步上下文管理器协议的错误。nullcontext 自 Python 3.7 加入，但异步支持是 Python 3.10 才补上的。解决方式有三个：

1. 把项目最低版本提升到 Python 3.10；
2. 同步代码继续使用标准库 nullcontext，异步代码写一个很小的兼容包装器；
3. 若可选异步资源不止一个，直接使用 AsyncExitStack 统一登记。

from contextlib import asynccontextmanager
from typing import AsyncIterator, TypeVar

T = TypeVar("T")


@asynccontextmanager
async def async_nullcontext(value: T) -> AsyncIterator[T]:
    # 兼容 Python 3.9：返回对象，但不接管任何清理责任
    yield value

这个兼容器只适合“无退出动作”的场景。若资源需要异步清理，应使用它原生的异步上下文管理器，或用 asynccontextmanager 在 finally 中执行真实的 await close()，不能拿无操作包装器代替。

分层排查：为什么统一后仍然报错

检查一：同步协议和异步协议是否混用

with 查找 __enter__/__exit__，async with 查找 __aenter__/__aexit__。Python 3.10+ 的 nullcontext 两套协议都支持，但被替代的真实资源未必支持。同步文件对象不能直接放进 async with；异步会话也不能直接放进普通 with。

检查二：传入的是资源还是创建资源的函数

nullcontext(factory) 返回的是函数对象，不会自动调用它。要么把已经创建的资源作为 enter_result，要么在真正需要管理生命周期的分支调用工厂。

def use_optional_lock(lock=None) -> None:
    # 传入现成锁就进入它；没有锁时使用无操作上下文
    cm = lock if lock is not None else nullcontext()
    with cm:
        # 临界区主体不再复制到两个条件分支
        update_shared_state()

这个例子没有给 nullcontext 传 enter_result，因此 with cm as value 中的 value 会是 None。当代码块不需要引用资源本身时，这正合适。

检查三：外部资源是否被意外关闭

若函数接受外部会话，就要让 nullcontext 包住它，而不是无条件执行 async with session。后者会触发会话自己的退出逻辑，导致调用方后续复用时出现“会话已关闭”。测试应分别覆盖临时资源被关闭和外部资源仍可用。

检查四：无操作真的是正确语义吗

nullcontext 不会调用 close 或 aclose。如果对象本身不是上下文管理器，但当前函数确实拥有它并应在结束时调用 close，同步场景应该使用 contextlib.closing；异步对象需要 aclosing。无操作包装器只用于“不需要退出动作”或“退出责任在外部”的分支。

什么时候该换成 ExitStack

只有一个可选资源时，nullcontext 最直接。可选文件、锁、事务和临时目录开始组合后，继续嵌套条件表达式会变得难读。这时使用 ExitStack 或 AsyncExitStack，按条件把真正需要管理的上下文逐个登记。

from contextlib import ExitStack, nullcontext


def export_report(output, lock=None) -> None:
    with ExitStack() as stack:
        # 路径由函数打开；外部流只借用，不关闭
        stream_cm = open(output, "w", encoding="utf-8") if isinstance(output, str) else nullcontext(output)
        stream = stack.enter_context(stream_cm)

        # 有锁时登记锁，没有锁时无需再制造嵌套分支
        if lock is not None:
            stack.enter_context(lock)

        stream.write(build_report())

这里 nullcontext 仍然负责“外部流不关闭”，ExitStack 负责动态数量的退出动作。两者不是竞争关系，而是粒度不同：前者给单个可选上下文补一个空分支，后者组合多个上下文和回调。

最终检查清单

• 真正不同的是否只有资源获取和释放，业务主体是否可以共用？
• 函数创建的资源是否由函数退出，调用方资源是否保持开放？
• 需要 enter_result，还是仅需要一个无操作代码块？
• 当前入口是 with 还是 async with，真实资源支持哪套协议？
• 异步 nullcontext 的运行环境是否为 Python 3.10 及以上？
• 对象需要真实关闭时，是否误用了无操作包装器？
• 可选上下文超过一个时，是否该改用 ExitStack 或 AsyncExitStack？

我现在把 nullcontext 看成一个“保持所有权不变的适配器”。它不会让同步资源自动变成异步资源，也不会替代真实清理；它只是让“需要管理”和“只需借用”两条资源路径在同一种上下文语法里汇合。只要先把谁创建、谁关闭说清楚，统一入口就会自然很多。

参考资料

• Python 官方文档：contextlib.nullcontext
• Python 官方文档：ExitStack
• Python 官方文档：AsyncExitStack
• Python 3.10 版本说明：contextlib