Mypy检查dataclass的field别名时报默认值顺序错误的问题咨询

基础复现场景 #

以下代码可正常通过Python运行时校验和mypy静态检查：

from dataclasses import field, dataclass

@dataclass
class C:
    some_int: int
    some_str: str = field(metadata={"doc": "foo"})
    another_int: int

c = C(42, "bla", 43)

上述代码在运行和静态检查环节均无报错。

问题现象 #

为简化文档元数据的重复写入操作，封装了轻量的field辅助函数快速配置字段元数据：

def doc(documentation: str):
    return field(metadata={"doc": documentation})

将原生field替换为自定义辅助函数后，dataclass定义变为：

@dataclass
class C:
    some_int: int
    some_str: str = doc("foo")
    another_int: int

此时mypy抛出如下类型错误：

error: Attributes without a default cannot follow attributes with one

从Python运行时逻辑判断，两种写法完全等价。对照mypy 0.790版本的dataclass插件源码（mypy/plugins/dataclasses.py第359行）可以确认：mypy仅对原生field函数做了特殊识别逻辑，自定义封装的field别名无法被插件正确判定为带默认值的字段定义，才会触发上述顺序校验报错。

可行兼容方案 #

针对自定义field别名的识别问题，可落地的兼容方式包括：

• 通过mypy配置指定自定义field的等价关系：在mypy配置文件的dataclasses插件配置段，将自定义的doc函数加入field_decorators识别列表，告知插件该函数返回值等价于原生field的返回结果，可正确识别字段的默认值属性
• 调整dataclass字段声明顺序：将所有带默认值的字段统一放置在无默认值字段的后方，匹配mypy当前的识别逻辑，避免触发顺序校验报错
• 为自定义的doc函数补充精确的返回类型标注，声明返回值为dataclasses.Field类型，部分新版本mypy可基于明确的类型标注正确推导字段属性

问题定性 #

这类场景不属于需要向mypy项目提交的正式bug。mypy的dataclass插件从设计上就是硬编码识别原生field函数，没有内置自动发现自定义field别名的机制，报错本质是插件识别逻辑与自定义封装的预期存在不匹配。目前mypy已经提供了配置自定义field识别规则的能力，这类场景属于可通过配置覆盖的已知行为，不属于逻辑错误范畴。

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