Mypy无法推断第三方库函数返回类型问题排查

Mypy严格遵循PEP 561类型分发规范，默认仅信任两类第三方库的类型注解：一是发布包内自带py.typed标记的内嵌类型库，二是独立发布的types-*前缀官方存根包。django-queryset-csv的发布包中没有携带py.typed标记，因此无论将follow_imports调整为silent还是normal，Mypy都不会读取该包源码内编写的类型注解，会直接将包导出的所有对象标记为Any类型，最终触发no-any-return错误。
Pyright没有强制要求第三方包携带py.typed标记，会直接扫描源码中的类型注解做推断，因此可以正常识别render_to_csv_response的返回类型。

按推荐优先级从高到低排列：

• 编写本地存根文件（一劳永逸，类型检查完全生效）

  1. 在项目根目录新建stubs文件夹用于存放本地类型存根，在pyproject.toml的[tool.mypy]配置段添加路径声明：

     mypy_path = "stubs"
     

  2. 在stubs目录下创建对应包的存根路径stubs/django_queryset_csv/__init__.pyi，写入用到的方法的类型签名：

     from typing import Any, Iterable
     from django.http import HttpResponse, StreamingHttpResponse
     from django.db.models import QuerySet
     
     def render_to_csv_response(
         queryset: QuerySet | Iterable[Any],
         *args: Any,
         **kwargs: Any
     ) -> HttpResponse | StreamingHttpResponse: ...
     

  配置完成后重启Mypy即可正确识别该方法的返回类型，后续用到包内其他方法时，直接在.pyi存根文件中补充对应签名即可。

• 行级忽略报错（最快修复，适合临时场景）
  直接在报错的返回行添加类型忽略注释，指定跳过对应错误码即可，不需要修改全局配置：

  def export_csv(self) -> HttpResponse | StreamingHttpResponse:
      fields = getattr(self.model_admin, "csv_export_fields", [])
      return render_to_csv_response(self.queryset.all().values(*fields))  # type: ignore[no-any-return]
  

• 针对单包关闭严格检查（适合不想维护存根的场景）
  在pyproject.toml中添加针对该包的单独Mypy配置，关闭对应检查规则：

  [tool.mypy-django_queryset_csv]
  warn_return_any = false
  

  该配置会让Mypy不对django_queryset_csv包的返回值触发return Any相关报错，不需要修改其他全局严格配置。

注意：不要尝试通过全局关闭warn_return_any解决问题，会大幅降低整个项目的类型检查严格度；调整follow_imports参数对未携带py.typed标记的包本身不生效，无法解决该问题。

内容的提问来源于stack exchange，提问作者Adrien Lemaire