本文介绍一种标准库兼容的方案，通过封装 contextlib._GeneratorContextManager 并禁用 __call__ 方法，构建出仅可作为上下文管理器（with）、不可用作装饰器（@）的函数，从而在 API 层面杜绝误用。
本文介绍一种标准库兼容的方案，通过封装 `contextlib._generatorcontextmanager` 并禁用 `__call__` 方法，构建出仅可作为上下文管理器（`with`）、不可用作装饰器（`@`）的函数，从而在 api 层面杜绝误用。
Python 的 @contextlib.contextmanager 虽然简洁易用，但其返回对象继承自 contextlib.ContextDecorator，天然支持双重用途：既可作为 with 上下文管理器，也可作为函数装饰器。然而在许多场景中（如资源独占初始化、状态临时切换等），将其用于装饰器会导致逻辑错误或难以调试的副作用——例如意外地将整个函数体包裹进上下文生命周期中，而开发者本意仅是临时进入某环境执行一段代码。
为严格区分语义、强化 API 约束，我们可以构造一个轻量级替代工具 contextmanager_without_decorator。它复用 contextlib 内部已验证的 _GeneratorContextManager（负责核心 __enter__/__exit__ 行为），但通过类型与运行时双重手段移除装饰器能力：
- 关键技巧：将 __call__ 属性显式设为 None，使实例不可调用；
- 安全封装：使用 functools.wraps 保留原函数元信息；
- 类型友好：支持 Python 3.12+ 的 ParamSpec 和协变泛型，确保 IDE 和类型检查器（如 mypy）能正确推导签名。
以下是完整实现（兼容 Python 3.9+，含类型提示）：
from __future__ import annotations
import contextlib
import functools
import typing as t
if t.TYPE_CHECKING:
import collections.abc as cx
import typing_extensions as tx
_P = tx.ParamSpec("_P")
_T_co = t.TypeVar("_T_co", covariant=True)
_ContextManagerDecoratee: tx.TypeAlias = cx.Callable[
_P, cx.Generator[_T_co, None, None]
]
class _GeneratorContextManager(contextlib._GeneratorContextManager[t.Any]):
__call__: t.ClassVar[None] = None # type: ignore[assignment]
def contextmanager_without_decorator(
func: _ContextManagerDecoratee[_P, _T_co],
) -> t.Callable[_P, _GeneratorContextManager[_T_co]]:
@functools.wraps(func)
def helper(*args: _P.args, **kwds: _P.kwargs) -> _GeneratorContextManager[_T_co]:
return _GeneratorContextManager(func, args, kwds)
return helper
使用方式与 @contextlib.contextmanager 完全一致，但行为更严格：
@contextmanager_without_decorator
def db_transaction():
print("BEGIN")
try:
yield "transaction_id"
finally:
print("COMMIT")
# ✅ 正确：作为上下文管理器使用
with db_transaction() as tx_id:
print(f"Inside: {tx_id}")
# ❌ 运行时报错：TypeError: 'NoneType' object is not callable
# @db_transaction()
# def risky_function():
# ...
注意事项：
- 该方案依赖 contextlib._GeneratorContextManager（虽为“私有”但自 Python 3.7 起稳定且被广泛使用，CPython 源码中明确标注为“供内部和 contextlib.contextmanager 使用”，实际可视为受支持的底层构件）；
- 若需完全避免私有 API，可手动实现 __enter__/__exit__（但会失去 yield 的简洁性与异常传播逻辑）；
- 在单元测试中建议显式验证装饰器调用是否抛出 TypeError，以保障约束有效性。
综上，contextmanager_without_decorator 是一个精准、轻量、类型安全的解决方案：它在零侵入原有开发习惯的前提下，通过最小化修改（仅禁用一个方法），将潜在的误用转化为清晰的运行时错误，显著提升 API 的健壮性与可维护性。
