本文介绍在 attrs 中定义支持 int | str 等联合类型的字段时，如何绕过 attrs.validators.or_() 引发的 mypy 类型推断错误。推荐使用 instance_of((str, int)) 这一简洁、安全且完全兼容的替代方案。

这段内容主要讲的是：在 attrs 里为字段声明类似 int | str 这样的联合类型时，怎样避开 attrs.validators.or_() 带来的 mypy 类型推断报错。

更稳妥也更省事的做法，是直接使用 instance_of((str, int))。写法更简洁，类型检查也更安全，同时兼容性也更完整。

问题背景

在使用 attrs 构建类型化数据类时，常需对字段进行运行时验证，例如允许 str 或 int。

最新文档中推荐的 attrs.validators.or_() 看似理想：

import attrs

@attrs.define
class C:
val: int | str = attrs.field(
validator=attrs.validators.or_(
attrs.validators.instance_of(int),
attrs.validators.instance_of(str),
)
)

然而，mypy 会报错：

error: Cannot infer type argument 1 of "or_"[misc]

报错原因

这是因为 or_ 是一个泛型验证器。其内部类型推导在 mypy 当前版本（截至 2024）中尚不完善。

因此，mypy 无法从多个 instance_of(...) 调用中，准确统一泛型参数。

推荐方案

使用元组形式的 instance_of。

attrs.validators.instance_of 支持传入类型元组，例如 (str, int)。其语义等价于“是其中任一类型”，且完全被 mypy 正确识别。

import attrs

@attrs.define
class C:
val: int | str = attrs.field(
validator=attrs.validators.instance_of((str, int))
)

#  mypy 无报错，运行时验证正常
c1 = C(42)# OK
c2 = C("hello") # OK
c3 = C(3.14)# Raises ValueError at runtime

方案优势

• 写法更简洁：无需组合多个 instance_of。
• 类型检查更稳定：可避开 or_() 的 mypy 类型推断问题。
• 语义更直接：明确表达字段可接受多个指定类型。
• 兼容性更完整：在常见使用场景下更稳妥。

注意事项

• 元组中的类型顺序无关紧要，(int, str) 与 (str, int) 效果一致；
• 必须使用元组（(...)），而非列表（[...]）或集合（{...}）——只有元组被 instance_of 显式支持；
• 此方式在 attrs >= 23.2.0 及主流 mypy（≥1.8）中稳定可用；
• 若需更复杂的逻辑（如条件验证、自定义错误消息），仍可封装为 @attrs.validator 方法，但简单类型校验优先用 instance_of(tuple)。

结论

如果目的只是判断某个字段是否落在几个明确类型之一，那么优先选 instance_of((T1, T2, ...))。

通常它比 or_(instance_of(T1), instance_of(T2)) 更利落，也更稳妥，对类型系统也更友好。

它不仅写法更简洁，语义更直接，同时还能保持零运行时开销，并把完整的静态类型安全性保留下来。

《夸克》非常好用的免费AI浏览器

下载APP查看