使用Mypy为调用super()方法的Django Mixin类正确添加类型注解

问题背景 #

Django 默认不会在模型写入数据库前自动执行验证逻辑，开发者通常会编写 Mixin 类让模型继承，实现保存时自动调用 full_clean() 做验证。但给这类 Mixin 添加类型注解时，调用 super().save() 会触发 Mypy 错误：error: Unsupported argument 2 for 'super' [misc]，核心原因是 self 参数的类型标注未匹配 Django Model 的类型约束。

正确的类型注解实现 #

1. 导入依赖模块 #

from typing import TypeVar, Generic, Any
from django.db import models

2. 定义绑定模型的类型变量 #

通过 TypeVar 约束 Mixin 适配的对象必须是 Django Model 或其子类：

ModelType = TypeVar("ModelType", bound=models.Model)

3. 编写带类型注解的验证 Mixin #

让 Mixin 继承泛型类 Generic[ModelType]，并明确 self 的类型为绑定的模型类型：

class ValidateOnSaveMixin(Generic[ModelType]):
    def save(
        self: ModelType,
        force_insert: bool = False,
        force_update: bool = False,
        using: str | None = None,
        update_fields: list[str] | None = None,
    ) -> None:
        # 保存前执行全量验证
        self.full_clean()
        # 调用父类 save 方法，无需给 super() 额外传参
        super().save(
            force_insert=force_insert,
            force_update=force_update,
            using=using,
            update_fields=update_fields,
        )

方案说明 #

• 泛型约束确保 Mypy 能识别 self 是 Django Model 实例，正确解析父类 save 方法的签名。
• Python 3 的 super() 会自动处理类与实例的绑定，无需手动传递 self 参数，避免触发 Mypy 的参数错误提示。
• 类型注解完全匹配 Django 官方 models.Model.save() 的参数定义，保证代码兼容性。

使用示例 #

class User(ValidateOnSaveMixin, models.Model):
    username = models.CharField(max_length=50, unique=True)
    age = models.IntegerField()

# 实例保存时自动触发验证
user = User(username="john_doe", age=25)
user.save()  # 先执行 full_clean()，验证通过后写入数据库

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