如何配置mypy实现Django模型字段到对应类型的转换？

问题描述 #

我已经在项目中集成了Mypy，现在想给Django模型添加类型提示，需要实现以下类型转换：

• ForeignKey 映射为关联的实际模型类型
• CharField、TextField 映射为 str 类型
• DecimalField 映射为 Decimal 类型

示例模型代码：

class mymodel(models.Model):
       address: str = models.CharField(max_length=100)
       description: str = models.TextField()
       organisation: Organisation = models.ForeignKey(
        "organisations.Organisation",
        on_delete=models.CASCADE,
        related_name="properties",
        editable=False,
    )

当前的setup.cfg配置：

[mypy]
plugins = mypy_drf_plugin.main,  mypy_django_plugin.main, pydantic.mypy
exclude = /migrations/|template
python_version = 3.11
no_implicit_optional = True
strict_optional = True


[mypy.plugins.django-stubs]
django_settings_module = "backend.settings"

解决方案 #

你已经启用了mypy_django_plugin，这个插件专门用来处理Django模型字段与Python类型的映射，只需调整模型写法和插件配置就能实现需求：

1. 规范模型类型提示写法 #

• CharField/TextField：直接标注为str即可，你示例中的写法是正确的，建议模型类名遵循PEP8规范（比如改为MyModel）
• ForeignKey：
  • 若关联模型在同一文件，直接标注为对应类型；
  • 若为跨app模型，可通过from __future__ import annotations启用延迟类型解析（避免循环导入），或提前导入关联模型（确保无循环依赖）。示例调整后：

    from __future__ import annotations
    from django.db import models
    
    class MyModel(models.Model):
        address: str = models.CharField(max_length=100)
        description: str = models.TextField()
        # 用字符串注解或提前导入Organisation后标注类型
        organisation: Organisation = models.ForeignKey(
            "organisations.Organisation",
            on_delete=models.CASCADE,
            related_name="properties",
            editable=False,
        )
    

• DecimalField：需先导入Decimal，再标注类型：

  from decimal import Decimal
  
  class MyModel(models.Model):
      amount: Decimal = models.DecimalField(max_digits=10, decimal_places=2)
  

2. 优化Mypy插件配置 #

你的配置已经指定了django_settings_module，这是插件正确解析Django模型的关键——它需要通过这个配置加载项目环境，识别模型关系和字段类型。

若遇到ForeignKey类型提示报错（如无法识别Organisation），请检查：

• organisations应用已添加到项目INSTALLED_APPS中
• 跨app模型是否通过延迟注解或正确导入避免了循环依赖

3. 处理可选字段的类型提示 #

如果字段设置了null=True或blank=True（对应可选值），需要在类型中标注None：

class MyModel(models.Model):
    # 可选的CharField
    nickname: str | None = models.CharField(max_length=50, null=True, blank=True)
    # 可选的ForeignKey
    parent_org: Organisation | None = models.ForeignKey(
        "organisations.Organisation",
        on_delete=models.SET_NULL,
        null=True,
        blank=True
    )

4. 验证配置 #

运行mypy命令扫描项目，插件会自动完成以下映射：

• models.CharField/models.TextField → str
• models.ForeignKey[ModelType] → ModelType（或ModelType | None，若字段可选）
• models.DecimalField → Decimal

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