Pyright类型检查器中异步上下文管理器装饰器的正确使用方式

在Python类型检查器Pyright中，使用@asynccontextmanager装饰器定义异步上下文管理器时，开发者可能会遇到类型检查错误。本文将深入分析这一现象的原因，并提供正确的解决方案。

问题现象

当开发者尝试在类型存根(stub)文件中使用@asynccontextmanager装饰器定义异步上下文管理器时，Pyright会报告类型不匹配错误。错误信息表明返回类型Coroutine[Any, Any, AsyncIterator[int]]与期望的AsyncIterator[_T_co]不兼容。

根本原因

这一现象并非Pyright的bug，而是有意为之的设计。主要原因有两点：

1. yield语句的语义转换：Python中yield语句的存在会改变函数的返回类型语义。虽然Python类型规范尚未明确描述这一转换，但主流类型检查器(Pyright、mypy等)都采用了一致的处理方式。

2. 存根文件装饰器限制：Python类型规范明确定义了存根文件中支持的装饰器列表，而@contextlib.asynccontextmanager并不在其中。对于不在支持列表中的装饰器，开发者需要手动应用装饰器效果并在存根文件中正确反映。

解决方案

方法一：使用内部类型定义

对于私有存根文件，可以直接使用contextlib模块中的内部类型定义：

from contextlib import _AsyncGeneratorContextManager

def async_simple_stub() -> _AsyncGeneratorContextManager[int, None]: ...

需要注意的是，这种方法使用了私有类，不适合用于公开发布的存根库。

方法二：复制类型定义

对于公开的存根库，更规范的做法是从typeshed存根中复制相关类型定义：

from typing import AsyncIterator, Generic, TypeVar

T = TypeVar('T')

class _AsyncGeneratorContextManager(Generic[T]):
    async def __aenter__(self) -> T: ...
    async def __aexit__(self, *args: object) -> None: ...

def async_simple_stub() -> _AsyncGeneratorContextManager[int]: ...

同步上下文管理器的情况

值得注意的是，同步上下文管理器(@contextmanager)在存根文件中不会出现类似问题，因为其行为已被类型系统更好地捕获。

最佳实践建议

1. 在存根文件中尽量避免使用复杂装饰器
2. 对于必须使用的装饰器效果，直接在类型注解中体现
3. 保持与typeshed存根的一致性
4. 对于公开库，优先使用方法二确保类型安全

通过理解类型系统的这些特性，开发者可以更准确地定义异步上下文管理器的类型注解，避免类型检查错误。