基于Basedpyright项目分析Python协程返回类型在1.28+版本的类型检查变更

在Python类型检查器Basedpyright的1.28版本更新中，对协程返回类型的处理逻辑进行了重要调整。这一变更影响了异步生成器方法的类型检查行为，特别是在抽象方法定义和协议实现场景下。

问题现象

开发者在使用基于泛型的抽象处理器模式时发现，当抽象方法声明为返回AsyncGenerator并标记为async时，类型检查器会报错提示协程类型不可迭代。典型示例如下：

class Handler[T: Event](ABC):
    @abstractmethod
    async def handle(self, event: T) -> AsyncGenerator[Event | None, None]: ...

在1.27.1版本能正常通过的类型检查，在1.28.1版本会抛出"CoroutineType不可迭代"的错误。类似问题也出现在协议实现场景中，当尝试将具体实现赋值给协议类型时会出现类型不匹配的错误。

技术背景

这一变更源于类型检查器对async关键字使用场景的严格化处理。在Python中：

1. async关键字用于定义协程函数，但并非所有返回协程或异步生成器的方法都需要标记为async
2. 只有函数体内包含await表达式或异步上下文时才需要async修饰
3. 异步生成器函数即使没有await表达式，使用yield语句也会隐式创建异步上下文

解决方案

对于抽象方法和协议定义，正确的做法是：

1. 移除不必要的async修饰符，因为抽象方法本身不包含实现
2. 保持返回类型为AsyncGenerator的明确声明
3. 在具体实现中根据需要添加async修饰符

修正后的抽象方法定义应为：

class Handler[T: Event](ABC):
    @abstractmethod
    def handle(self, event: T) -> AsyncGenerator[Event | None, None]: ...

而在具体实现类中，可以根据实际需要决定是否添加async：

class FooHandler(Handler[Event]):
    async def handle(self, event: Event):  # 实现中有await时需要async
        await some_async_op()
        yield event

最佳实践建议

1. 在抽象定义中避免过度使用async修饰符
2. 明确区分协程函数(Coroutine)和异步生成器(AsyncGenerator)的返回类型
3. 对于协议定义，确保方法签名与实际实现的返回类型精确匹配
4. 升级到1.28+版本后，检查现有代码中的抽象异步方法定义

这一变更体现了类型检查器对Python异步编程模型理解的深化，有助于开发者编写更精确的类型注解，避免潜在的运行时错误。理解这一变化对于构建健壮的异步Python代码库具有重要意义。