Files
2f8e8d8b20 [ty] Do not narrow Field[..] specializations to expanded unions (#30264)
## Summary

When a dataclass has a field declaration with a union annotation like
the following, ty speculatively uses each union element individually as
type context to infer a type for `field(..)`.

```py
def returns_any() -> Any: ...

@dataclass
class Entry:
    value: str | None = field(default_factory=returns_any, kw_only=True)
```

When both inference paths succeed, ty infers the field call as
`Field[str] | Field[None]` which then prevents proper recognition of
field metadata like `kw_only`. Here, we avoid this speculative inference
and use the full `str | None` type as context to end up with `Field[str
| None]` in this example.

Fixes https://github.com/astral-sh/ty/issues/4986.

Co-authored-by: @carljm 

## Test Plan

Added regression test

Co-authored-by: Carl Meyer <carl@astral.sh>
2026-11-10 09:02:12 -08:00

8.7 KiB

Dataclass fields

Basic

from dataclasses import dataclass, field

@dataclass
class Member:
    name: str
    role: str = field(default="user")
    tag: str | None = field(default=None, init=False)

# revealed: (self: Member, name: str, role: str = "user") -> None
reveal_type(Member.__init__)

alice = Member(name="Alice", role="admin")
reveal_type(alice.role)  # revealed: str
alice.role = "moderator"

# `tag` is marked as `init=False`, so this is an
# error: [unknown-argument] "Argument `tag` does not match any known parameter"
bob = Member(name="Bob", tag="VIP")

Any annotations preserve field specifier metadata

Even when a field is explicitly annotated as Any, field(...) should still be recognized as a dataclass field specifier. The synthesized field metadata comes from the right-hand side, not from the declared type.

from dataclasses import dataclass, field
from typing import Any

@dataclass
class AnyFieldSpecifier:
    proto: Any = field(repr=False)
    key: str | None

reveal_type(AnyFieldSpecifier.__init__)  # revealed: (self: AnyFieldSpecifier, proto: Any, key: str | None) -> None

@dataclass
class AnyInitFalseField:
    key: str | None
    proto: Any = field(init=False)

reveal_type(AnyInitFalseField.__init__)  # revealed: (self: AnyInitFalseField, key: str | None) -> None

Inheritance with defaults

from dataclasses import dataclass

class Configuration: ...

@dataclass(frozen=True)
class SomeClass:
    config: Configuration | None

    def foo(self) -> int:
        raise NotImplementedError

class SpecificConfiguration(Configuration):
    x: int = 0

@dataclass(frozen=True)
class SpecificClass(SomeClass):
    config: SpecificConfiguration | None = None

    def foo(self) -> int:
        if self.config is None:
            return SpecificConfiguration().x
        return self.config.x

reveal_type(SpecificClass().config)  # revealed: SpecificConfiguration | None

@dataclass(frozen=True)
class NoDefaultSpecificClass(SomeClass):
    config: SpecificConfiguration | None

reveal_type(NoDefaultSpecificClass(SpecificConfiguration()).config)  # revealed: SpecificConfiguration | None

Descriptor-typed fields with defaults

A dataclass field whose declared type is a descriptor should still resolve through the descriptor protocol on instance access, even when the field has a default value.

Desc2 has __get__ but no __set__, making it a non-data descriptor.

from dataclasses import dataclass
from typing import Any, Generic, TypeVar, overload

T = TypeVar("T")

class Desc2(Generic[T]):
    @overload
    def __get__(self, instance: None, owner: Any) -> list[T]: ...
    @overload
    def __get__(self, instance: object, owner: Any) -> T: ...
    def __get__(self, instance: object | None, owner: Any) -> list[T] | T:
        raise NotImplementedError

@dataclass
class DC2:
    x: Desc2[int]
    y: Desc2[str]
    z: Desc2[str] = Desc2()

dc2 = DC2(Desc2(), Desc2(), Desc2())

# On the class, __get__(None, owner) is called, returning list[T].
reveal_type(DC2.z)  # revealed: list[str]

# On instances, __get__(instance, owner) is called, returning T.
# The default value should not cause the declared descriptor type
# to leak into the instance attribute type.
reveal_type(dc2.z)  # revealed: str

default_factory

The default_factory argument can be used to specify a callable that provides a default value for a field:

from dataclasses import dataclass, field
from datetime import datetime

@dataclass
class Data:
    content: list[int] = field(default_factory=list)
    timestamp: datetime = field(default_factory=datetime.now, init=False)

# revealed: (self: Data, content: list[int] = ...) -> None
reveal_type(Data.__init__)

data = Data([1, 2, 3])
reveal_type(data.content)  # revealed: list[int]
reveal_type(data.timestamp)  # revealed: datetime

kw_only

[environment]
python-version = "3.12"

If kw_only is set to True, the field can only be set using keyword arguments:

from dataclasses import dataclass, field

@dataclass
class Person:
    name: str
    age: int | None = field(default=None, kw_only=True)
    role: str = field(default="user", kw_only=True)

# revealed: (self: Person, name: str, *, age: int | None = None, role: str = "user") -> None
reveal_type(Person.__init__)

alice = Person(role="admin", name="Alice")

# error: [too-many-positional-arguments] "Too many positional arguments: expected 1, got 2"
bob = Person("Bob", 30)

KW_ONLY sentinel

The KW_ONLY sentinel is a marker, not a real attribute. It should not appear as an instance or class attribute.

[environment]
python-version = "3.12"

Although _ is the conventional name, any name can be used for the sentinel. Accessing the sentinel field on an instance or the class should not resolve to KW_ONLY:

from dataclasses import dataclass, KW_ONLY

@dataclass
class DC:
    sentinel: KW_ONLY
    name: str

dc = DC(name="Alice")

# error: [missing-attribute]
dc.sentinel

# error: [missing-attribute]
DC.sentinel

When a child uses _: KW_ONLY and a parent defines _ as a real field, the parent's _ field is inherited and the sentinel only affects subsequent fields in the child:

from dataclasses import dataclass, KW_ONLY

@dataclass
class Parent:
    _: int

@dataclass
class Child(Parent):
    _: KW_ONLY
    name: str

# Parent's `_: int` field is inherited; the sentinel makes `name` keyword-only.
# revealed: (self: Child, _: int, *, name: str) -> None
reveal_type(Child.__init__)

c = Child(1, name="Alice")
reveal_type(c._)  # revealed: int

dataclass_transform field_specifiers

If field_specifiers is not specified, it defaults to an empty tuple, meaning no field specifiers are supported and dataclasses.field and dataclasses.Field should not be accepted by default.

from typing_extensions import dataclass_transform
from dataclasses import field, dataclass
from typing import Any, TypeVar

T = TypeVar("T")

@dataclass_transform()
def create_model(*, init: bool = True):
    def deco(cls: type[T]) -> type[T]:
        return cls
    return deco

@create_model()
class A:
    name: str = field(init=False)

# Without explicit field_specifiers, field(init=False) is an ordinary default RHS.
reveal_type(A.__init__)  # revealed: (self: A, name: str = ...) -> None

class OtherFieldInfo:
    def __init__(self, default: Any = None, **kwargs: Any) -> None: ...

def other_field(default: Any = None, **kwargs: Any) -> OtherFieldInfo:
    return OtherFieldInfo(default=default, **kwargs)

@dataclass_transform(field_specifiers=(other_field, OtherFieldInfo))
def create_model_with_other_specifiers(*, init: bool = True):
    def deco(cls: type[T]) -> type[T]:
        return cls
    return deco

@create_model_with_other_specifiers()
class C:
    name: str = field(init=False)

# Even with other active field_specifiers, an unlisted RHS is an ordinary default value.
reveal_type(C.__init__)  # revealed: (self: C, name: str = ...) -> None

@dataclass
class B:
    name: str = field(init=False)

# Regular @dataclass should respect field(init=False)
reveal_type(B.__init__)  # revealed: (self: B) -> None

Test constructor calls:

# These should NOT error because A's `field(...)` call is treated like any other default value
A()
A(name="foo")
C()
C(name="foo")

# This should error because field(init=False) is respected for B
# error: [unknown-argument]
B(name="foo")

Union-annotated fields

[environment]
python-version = "3.12"

When a field is annotated with a union type, the field(..) call is inferred with the full union as type context, so that a single Field[..] specialization is inferred, instead of e.g. Field[str] | Field[None]. This ensures that the field's metadata can be accurately captured.

For the values field, the field(..) call is inferred with a narrower Field[list[int]] specialization due to the default factory argument, but the declared type is what determines the constructor signature, so lists of strings are still allowed.

from dataclasses import dataclass, field
from typing import Any

def returns_any() -> Any:
    return None

@dataclass
class Entry:
    value: str | None = field(default_factory=returns_any, kw_only=True)
    reveal_type(value)  # revealed: dataclasses.Field[str | None]

    values: list[int] | list[str] = field(default_factory=lambda: [1], kw_only=True)
    reveal_type(values)  # revealed: dataclasses.Field[list[int]]

# revealed: (self: Entry, *, value: str | None = ..., values: list[int] | list[str] = ...) -> None
reveal_type(Entry.__init__)

Entry()
Entry(value=None)
Entry(values=[1, 2])
Entry(value="value", values=["other"])

The kw_only argument is respected:

Entry("value", [1, 2])  # error: [too-many-positional-arguments]