如何修复Django模型管理器方法的返回类型不兼容问题？

问题背景 #

使用环境：Django 4.1.7、django-stubs 1.16.0、mypy 1.1.1

现有代码：

class ProductQuerySet(QuerySet):
    ...

class ProductManager(Manager):
    def create_red_product(self, **kwargs) -> "Product":
        return self.model(color=Product.Color.RED, **kwargs)

_product_manager = ProductManager.from_queryset(ProductQuerySet)

class Product(Model):
    ...
    objects = _product_manager()

运行mypy检查时出现报错：

models/product.py:46: error: Incompatible return value type (got "_T", expected "Product")  [return-value]

已知self.model的类型是绑定到模型的泛型_T，理应对应Product，但mypy无法识别，询问原因及修复方法。

原因分析 #

mypy无法将self.model关联到Product，核心原因是：

• Manager和QuerySet都是泛型类，你定义ProductManager和ProductQuerySet时没有显式指定泛型参数为Product；
• from_queryset生成的管理器子类也没能自动完成泛型类型的绑定，导致mypy只能把self.model识别为泛型占位符_T，而非具体的Product类。

修复方案 #

有两种可行的解决办法：

方案一：显式指定泛型参数（推荐） #

修改ProductQuerySet和ProductManager的定义，明确将泛型绑定到Product（使用字符串转发引用是因为Product类定义在后面）：

from django.db.models import Manager, Model, QuerySet

class ProductQuerySet(QuerySet["Product"]):
    ...

class ProductManager(Manager["Product"]):
    def create_red_product(self, **kwargs) -> "Product":
        return self.model(color=Product.Color.RED, **kwargs)

_product_manager = ProductManager.from_queryset(ProductQuerySet)

class Product(Model):
    class Color:
        RED = "red"
    ...
    objects = _product_manager()

这样mypy就能明确self.model对应的具体类型是Product，错误会自动消失。

方案二：使用cast强制类型断言 #

如果不想修改类的泛型定义，可以通过typing.cast直接告诉mypy返回值的具体类型：

from typing import cast
from django.db.models import Manager, Model, QuerySet

class ProductQuerySet(QuerySet):
    ...

class ProductManager(Manager):
    def create_red_product(self, **kwargs) -> "Product":
        return cast("Product", self.model(color=Product.Color.RED, **kwargs))

_product_manager = ProductManager.from_queryset(ProductQuerySet)

class Product(Model):
    class Color:
        RED = "red"
    ...
    objects = _product_manager()

这种方式属于临时类型断言，适合快速修复，但不如方案一规范，无法让类型系统完整推断关联关系。

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