如何使用django-stubs正确标注Django模型字段类型适配PyLance

首先明确前提：你需要先安装django-stubs包并完成对应配置，大部分常规Django模型字段可以被自动推断类型，无需手动标注；如果出现字段显示为Field[Unknown, Unknown]、Meta类重写告警的问题，按以下规则处理即可。

字段泛型参数规则 #

django-stubs为所有模型字段定义的泛型固定接收两个类型参数：

• 第一个参数：从数据库查询出模型实例后，该字段返回的Python值类型
• 第二个参数：创建模型实例、做ORM查询过滤时，允许传入该字段的Python值类型

Meta类告警处理 #

你遇到的Meta overrides symbol of same name in class "HasStatus"告警，是因为PyLance按普通Python类继承规则做检查，而子类重写父类Meta是Django框架的标准写法，不需要为Meta类编写额外类型标注，只需要在Meta类定义行添加忽略注释即可：

class Meta: # type: ignore[override]
    verbose_name = "Machine"

常用字段标注示例 #

先修正你给出的Machine模型代码：

from django.db import models

class Machine(HasStatus):
    # Manager标注写法正确，保留即可
    machines: "models.Manager[Machine]" = models.Manager()
    # IntegerField读写都是int类型，两个泛型参数都传int
    number: models.IntegerField[int, int] = models.IntegerField(verbose_name="Číslo stroje", unique=True)

    class Meta: # type: ignore[override]
        verbose_name = "Machine"

其他常用字段的标注参考如下：

• 字符串类字段（CharField/TextField）
  读写类型均为str，泛型参数统一传str即可，字段的max_length、blank、default等参数不影响类型定义：

  name: models.CharField[str, str] = models.CharField(max_length=100, verbose_name="设备名称")
  description: models.TextField[str, str] = models.TextField(verbose_name="设备描述", blank=True, default="")
  

• 允许为null的字段
  两个泛型参数都需要补充None类型，匹配字段可空的特性：

  import datetime
  # 可空整数字段
  last_run_duration: models.IntegerField[int | None, int | None] = models.IntegerField(null=True, blank=True)
  # 可空时间字段
  last_maintenance_time: models.DateTimeField[datetime.datetime | None, datetime.datetime | None] = models.DateTimeField(null=True)
  

• 外键字段（ForeignKey）
  第一个泛型参数传关联模型的类型，第二个泛型参数传关联模型主键的类型；如果外键设置了null=True，第二个参数补充None：

  # 关联Workshop模型，默认主键为int类型
  workshop: models.ForeignKey["Workshop", int] = models.ForeignKey("Workshop", on_delete=models.CASCADE, verbose_name="所属车间")
  # 可空外键，关联Django内置User模型
  operator: models.ForeignKey["auth.User", int | None] = models.ForeignKey("auth.User", on_delete=models.SET_NULL, null=True, blank=True)
  

• 多对多字段（ManyToManyField）
  仅需传一个关联模型类型作为泛型参数即可：

  tags: models.ManyToManyField["Tag"] = models.ManyToManyField("Tag", blank=True, verbose_name="设备标签")
  

• 其他常规字段

  from decimal import Decimal
  # 布尔字段
  is_active: models.BooleanField[bool, bool] = models.BooleanField(default=True, verbose_name="是否启用")
  # 十进制字段
  purchase_price: models.DecimalField[Decimal, Decimal] = models.DecimalField(max_digits=10, decimal_places=2)
  

• 带choices枚举的字段
  如果用Django内置的TextChoices/IntegerChoices定义选项，第一个泛型参数传枚举类型，第二个参数传枚举值的基础类型加枚举类型即可：

  class MachineStatus(models.TextChoices):
      RUNNING = "RUN", "运行中"
      STOPPED = "STOP", "已停机"
  status: models.CharField[MachineStatus, str | MachineStatus] = models.CharField(max_length=10, choices=MachineStatus.choices, default=MachineStatus.STOPPED)
  

小提示：如果字段配置了default值，不需要额外调整泛型参数，django-stubs会自动识别default值的类型做适配。

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