重定义AbstractUser子类User的email字段致mypy类型不兼容如何解决？

问题背景 #

我们的Django项目基于AbstractUser实现了自定义User模型，因业务需要将email字段重定义为：

class User(AbstractUser):
    ...
    email = models.EmailField(db_index=True, blank=True, null=True, unique=True)
    ...

启用mypy类型检查后，触发了类型不兼容错误：

error: Incompatible types in assignment (expression has type
"EmailField[str | int | Combinable | None, str | None]", base class
"AbstractUser" defined the type as "EmailField[str | int | Combinable,
str]" [assignment]

如果用# type: ignore忽略该错误，又会导致大量Cannot determine type of "email"的报错，无法保留mypy的类型保护能力。

环境信息：

• Python：3.10.5
• Django：3.2.19
• mypy：1.6.1
• django-stubs[compatible-mypy]：4.2.6
• django-stubs-ext：4.2.5
• typing-extensions：4.8.0

解决方案 #

1. 显式声明字段类型注解 #

直接给重定义的email字段添加精确的类型注解，明确告知mypy字段的合法类型：

from django.db import models
from django.contrib.auth.models import AbstractUser
from typing import Optional, Union
from django.db.models.expressions import Combinable

class User(AbstractUser):
    email: models.EmailField[Union[str, int, Combinable, None], Optional[str]] = models.EmailField(
        db_index=True, blank=True, null=True, unique=True
    )

2. 自定义类型别名简化注解 #

如果多个地方需要用到可空的EmailField，可以定义类型别名来复用：

from django.db import models
from django.contrib.auth.models import AbstractUser
from typing import TypeAlias, Optional, Union

# 定义可空EmailField的类型别名
NullableEmailField: TypeAlias = models.EmailField[Union[str, int, models.Combinable, None], Optional[str]]

class User(AbstractUser):
    email: NullableEmailField = models.EmailField(
        db_index=True, blank=True, null=True, unique=True
    )

3. 升级django-stubs版本（备选） #

虽然当前django-stubs4.2.6与Django3.2兼容，但可以检查是否有更高版本对可空字段的类型推导做了优化，不过这个方法优先级低于前两种，因为前两种更直接可控。

原理说明 #

AbstractUser中原生的email字段类型是EmailField[str | int | Combinable, str]，不允许None值；而我们重定义的字段因为设置了null=True和blank=True，类型变为EmailField[str | int | Combinable | None, str | None]，两者类型不匹配导致mypy报错。通过显式类型注解，我们直接指定字段的预期类型，消除了类型冲突。

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