Files
Alex WaygoodandBrent Westbrook ce0077c3e5 [ty] Distinguish attributes missing from some union members (#29944)
## Summary

Users can now suppress an attribute error that affects only some union
members and still catch names that are missing from every member. For
example, both lines below previously reported `unresolved-attribute`:

```python
def clean(value: str | int) -> str:
    value.stirp()          # missing-attribute: neither str nor int has stirp
    return value.strip()   # missing-union-attribute: str has strip, int does not
```

The motivation is that a project adopting ty may want `value.strip()` on
`str | None` to only warn while a typo remains an error-severity
diagnostic.

Both rules default to errors. The same distinction applies to optional
values such as `str | None` and to attribute deletion. Attributes
defined only conditionally on a class continue to use
`possibly-missing-attribute`.

### Comparison to other type checkers

Pyright distinguishes between `reportOptionalMemberAccess` (which is
specifically for unions with `None`) and `reportAttributeAccessIssue`,
which is for all other unions. mypy, meanwhile, distinguishes between
`union-attr` (which is an error code for all attribute-access errors on
union types) and `attr-defined` (which is an error code for all
attribute-access errors on non-union types). So this new split doesn't
_exactly_ align with either precedent -- but I _do_ think it's probably
the most useful split we can do, and it's the one that makes the most
sense _a priori_ in my opinion.

### Compatibility

`unresolved-attribute` remains an alias for `missing-attribute` in
configuration and inline ignores. To preserve a setting such as
`unresolved-attribute = "warn"` for both cases, also set
`missing-union-attribute = "warn"`. On an access that fails for only
some union members, replace `# ty: ignore[unresolved-attribute]` with `#
ty: ignore[missing-union-attribute]`. Tools that consume diagnostic
codes should recognize both new names.

Fixes astral-sh/ty#2839 and fixes astral-sh/ty#2471.

## Test Plan

A comparison with ty 0.0.96 on typeshed-stats, docstring-adder,
sphinx-lint, and typing_extensions found the same messages, locations,
and severities. Eight diagnostics received `missing-union-attribute`
across those four projects (two in sphinx-lint and six in
typing_extensions).

---------

Co-authored-by: Brent Westbrook <brentrwestbrook@gmail.com>
2026-11-06 14:46:50 -05:00

12 KiB

Narrowing by assignment

Attribute

Basic

class A:
    x: int | None = None
    y = None

    def __init__(self):
        self.z = None

a = A()
a.x = 0
a.y = 0
a.z = 0

reveal_type(a.x)  # revealed: Literal[0]
reveal_type(a.y)  # revealed: Literal[0]
reveal_type(a.z)  # revealed: Literal[0]

# Make sure that we infer the narrowed type for eager
# scopes (class, comprehension) and the non-narrowed
# public type for lazy scopes (function)
class _:
    reveal_type(a.x)  # revealed: Literal[0]
    reveal_type(a.y)  # revealed: Literal[0]
    reveal_type(a.z)  # revealed: Literal[0]

[reveal_type(a.x) for _ in range(1)]  # revealed: Literal[0]
[reveal_type(a.y) for _ in range(1)]  # revealed: Literal[0]
[reveal_type(a.z) for _ in range(1)]  # revealed: Literal[0]

def _():
    reveal_type(a.x)  # revealed: int | None
    reveal_type(a.y)  # revealed: None | Unknown
    reveal_type(a.z)  # revealed: None | Unknown

if False:
    a = A()
reveal_type(a.x)  # revealed: Literal[0]
reveal_type(a.y)  # revealed: Literal[0]
reveal_type(a.z)  # revealed: Literal[0]

if True:
    a = A()
reveal_type(a.x)  # revealed: int | None
reveal_type(a.y)  # revealed: None | Unknown
reveal_type(a.z)  # revealed: None | Unknown

a.x = 0
a.y = 0
a.z = 0
reveal_type(a.x)  # revealed: Literal[0]
reveal_type(a.y)  # revealed: Literal[0]
reveal_type(a.z)  # revealed: Literal[0]

class _:
    a = A()
    reveal_type(a.x)  # revealed: int | None
    reveal_type(a.y)  # revealed: None | Unknown
    reveal_type(a.z)  # revealed: None | Unknown

def cond() -> bool:
    return True

class _:
    if False:
        a = A()
    reveal_type(a.x)  # revealed: Literal[0]
    reveal_type(a.y)  # revealed: Literal[0]
    reveal_type(a.z)  # revealed: Literal[0]

    if cond():
        a = A()
    reveal_type(a.x)  # revealed: int | None
    reveal_type(a.y)  # revealed: None | Unknown
    reveal_type(a.z)  # revealed: None | Unknown

class _:
    a = A()

    class Inner:
        reveal_type(a.x)  # revealed: int | None
        reveal_type(a.y)  # revealed: None | Unknown
        reveal_type(a.z)  # revealed: None | Unknown

a = A()
# error: [missing-attribute]
a.dynamically_added = 0
# error: [missing-attribute]
reveal_type(a.dynamically_added)  # revealed: Literal[0]

# error: [unresolved-reference]
does.nt.exist = 0
# error: [unresolved-reference]
reveal_type(does.nt.exist)  # revealed: Literal[0]

Narrowing chain

class D: ...

class C:
    d: D | None = None

class B:
    c1: C | None = None
    c2: C | None = None

class A:
    b: B | None = None

a = A()
a.b = B()
a.b.c1 = C()
a.b.c2 = C()
a.b.c1.d = D()
a.b.c2.d = D()
reveal_type(a.b)  # revealed: B
reveal_type(a.b.c1)  # revealed: C
reveal_type(a.b.c1.d)  # revealed: D

a.b.c1 = C()
reveal_type(a.b)  # revealed: B
reveal_type(a.b.c1)  # revealed: C
reveal_type(a.b.c1.d)  # revealed: D | None
reveal_type(a.b.c2.d)  # revealed: D

a.b.c1.d = D()
a.b = B()
reveal_type(a.b)  # revealed: B
reveal_type(a.b.c1)  # revealed: C | None
reveal_type(a.b.c2)  # revealed: C | None
# error: [missing-union-attribute]
reveal_type(a.b.c1.d)  # revealed: D | None
# error: [missing-union-attribute]
reveal_type(a.b.c2.d)  # revealed: D | None

Do not narrow the type of a property by assignment

class C:
    def __init__(self):
        self._x: int = 0

    @property
    def x(self) -> int:
        return self._x

    @x.setter
    def x(self, value: int) -> None:
        self._x = abs(value)

c = C()
c.x = -1
# Don't infer `c.x` to be `Literal[-1]`
reveal_type(c.x)  # revealed: int

Do not narrow the type of a descriptor by assignment

class Descriptor:
    def __get__(self, instance: object, owner: type) -> int:
        return 1

    def __set__(self, instance: object, value: int) -> None:
        pass

class C:
    desc: Descriptor = Descriptor()

c = C()
c.desc = -1
# Don't infer `c.desc` to be `Literal[-1]`
reveal_type(c.desc)  # revealed: int

Dynamic attributes

An attribute provided by __getattr__ need not return the value assigned to it. Here, __setattr__ ignores assignments, and __getattr__ always returns "hello". Assigning "goodbye" therefore does not make later reads return "goodbye":

class AlwaysString:
    def __getattr__(self, name: str) -> str:
        return "hello"

    def __setattr__(self, name: str, value: object) -> None:
        pass

obj = AlwaysString()
obj.value = "goodbye"
reveal_type(obj.value)  # revealed: str

Dynamic attributes returning Any

When __getattr__ returns Any, assigning a value does not make later reads more precise:

from typing import Any

class Props:
    def __getattr__(self, name: str) -> Any: ...
    def __setattr__(self, name: str, value: object) -> None: ...

def update(props: Props) -> None:
    props.status = "Closed"
    reveal_type(props.status)  # revealed: Any

A hasattr check tells us that an attribute exists, but not what it returns after an assignment:

def update_if_present(props: Props) -> None:
    if hasattr(props, "status"):
        props.status = "Open"
        reveal_type(props.status)  # revealed: Any

Dynamic attributes after an isinstance check

An isinstance check can narrow the type of a dynamic attribute. Assigning to that attribute discards the narrowing, since __getattr__ may return a different value on the next read:

class Values:
    def __getattr__(self, name: str) -> int | str:
        return 0

    def __setattr__(self, name: str, value: object) -> None: ...

def update(values: Values) -> None:
    if isinstance(values.value, int):
        reveal_type(values.value)  # revealed: int
        values.value = 2
        reveal_type(values.value)  # revealed: int | str

Dynamic attributes without a custom setter

Defining __getattr__ does not make assignments to missing attributes valid. We report the invalid assignment and continue to use the getter's return type for later reads:

class GetterOnly:
    def __getattr__(self, name: str) -> str:
        return "hello"

def update(obj: GetterOnly) -> None:
    obj.value = "goodbye"  # error: [missing-attribute]
    reveal_type(obj.value)  # revealed: str

Declared and inferred attributes

Ordinary attributes still narrow after assignment when a class defines __getattr__ and __setattr__. This applies both to annotated attributes and to attributes inferred from assignments in the class body or __init__:

from typing import Any

class Values:
    declared: int | str
    class_value = None

    def __init__(self) -> None:
        self.instance_value = None

    def __getattr__(self, name: str) -> Any: ...
    def __setattr__(self, name: str, value: object) -> None: ...

def update(obj: Values) -> None:
    obj.declared = 1
    reveal_type(obj.declared)  # revealed: Literal[1]
    obj.class_value = 1
    reveal_type(obj.class_value)  # revealed: Literal[1]
    obj.instance_value = 1
    reveal_type(obj.instance_value)  # revealed: Literal[1]

Dynamic attributes on unions

A union may include a class that provides value through __getattr__. In that case, assigning value does not determine the type of the next read, even if another class in the union declares the attribute:

class Dynamic:
    def __getattr__(self, name: str) -> int | str:
        return 0

    def __setattr__(self, name: str, value: object) -> None: ...

class Declared:
    value: int | str

def update(obj: Dynamic | Declared) -> None:
    obj.value = 1
    reveal_type(obj.value)  # revealed: int | str

Module attributes

This module defines neither value nor __getattr__, so assigning value produces an error. We still track the assigned type and report an incompatible use later:

module.py:

main.py:

import module

module.value = 1  # error: [missing-attribute]

# error: [invalid-assignment]
# error: [missing-attribute]
value: str = module.value

Modules with __getattr__

A module's __getattr__ is only called for missing attributes. Assigning an attribute adds it to the module, so later reads use the assigned value:

module.py:

def __getattr__(name: str) -> int:
    return 0

main.py:

import module

module.value = 1
reveal_type(module.value)  # revealed: Literal[1]

Subscript

Specialization for builtin types

Type narrowing based on assignment to a subscript expression is generally unsound, because arbitrary __getitem__/__setitem__ methods on a class do not necessarily guarantee that the passed-in value for __setitem__ is stored and can be retrieved unmodified via __getitem__. Therefore, we currently only perform assignment-based narrowing on a few built-in classes (list, dict, bytesarray, TypedDict and collections types) where we are confident that this kind of narrowing can be performed soundly. This is the same approach as pyright.

from typing import TypedDict
from collections import ChainMap, defaultdict

l: list[int | None] = [None]
l[0] = 0
d: dict[int, int] = {1: 1}
d[0] = 0
b: bytearray = bytearray(b"abc")
b[0] = 0
dd: defaultdict[int, int] = defaultdict(int)
dd[0] = 0
cm: ChainMap[int, int] = ChainMap({1: 1}, {0: 0})
cm[0] = 0
reveal_type(cm)  # revealed: ChainMap[int, int]

reveal_type(l[0])  # revealed: Literal[0]
reveal_type(d[0])  # revealed: Literal[0]
reveal_type(b[0])  # revealed: Literal[0]
reveal_type(dd[0])  # revealed: Literal[0]
reveal_type(cm[0])  # revealed: Literal[0]

class C:
    reveal_type(l[0])  # revealed: Literal[0]
    reveal_type(d[0])  # revealed: Literal[0]
    reveal_type(b[0])  # revealed: Literal[0]
    reveal_type(dd[0])  # revealed: Literal[0]
    reveal_type(cm[0])  # revealed: Literal[0]

[reveal_type(l[0]) for _ in range(1)]  # revealed: Literal[0]
[reveal_type(d[0]) for _ in range(1)]  # revealed: Literal[0]
[reveal_type(b[0]) for _ in range(1)]  # revealed: Literal[0]
[reveal_type(dd[0]) for _ in range(1)]  # revealed: Literal[0]
[reveal_type(cm[0]) for _ in range(1)]  # revealed: Literal[0]

def _():
    reveal_type(l[0])  # revealed: int | None
    reveal_type(d[0])  # revealed: int
    reveal_type(b[0])  # revealed: int
    reveal_type(dd[0])  # revealed: int
    reveal_type(cm[0])  # revealed: int

class D(TypedDict):
    x: int
    label: str

td = D(x=1, label="a")
td["x"] = 0
reveal_type(td["x"])  # revealed: Literal[0]

# error: [unresolved-reference]
does["not"]["exist"] = 0
# error: [unresolved-reference]
reveal_type(does["not"]["exist"])  # revealed: Unknown

not_subscriptable = 1
# error: [invalid-assignment]
not_subscriptable[0] = 0
# error: [not-subscriptable]
reveal_type(not_subscriptable[0])  # revealed: Unknown

No narrowing for custom classes with arbitrary __getitem__ / __setitem__

class C:
    def __init__(self):
        self.l: list[str] = []

    def __getitem__(self, index: int) -> str:
        return self.l[index]

    def __setitem__(self, index: int, value: str | int) -> None:
        if len(self.l) == index:
            self.l.append(str(value))
        else:
            self.l[index] = str(value)

c = C()
c[0] = 0
reveal_type(c[0])  # revealed: str

Complex target

from typing import Any

class A:
    x: list[int | None] = []

class B:
    a: A | None = None

b = B()
b.a = A()
b.a.x[0] = 0

reveal_type(b.a.x[0])  # revealed: Literal[0]

class C:
    reveal_type(b.a.x[0])  # revealed: Literal[0]

def _():
    # error: [missing-union-attribute]
    reveal_type(b.a.x[0])  # revealed: int | None
    # error: [missing-union-attribute]
    reveal_type(b.a.x)  # revealed: list[int | None]
    reveal_type(b.a)  # revealed: A | None

class D: ...

class E:
    def __init__(self):
        self.d = D()

class F:
    def __init__(self):
        self.e = E()

class Mock(Any): ...

f = F()
reveal_type(f.e)  # revealed: E
f.e = Mock()
reveal_type(f.e)  # revealed: Mock

f2 = F()
reveal_type(f2.e.d)  # revealed: D
f2.e.d = Mock()
reveal_type(f2.e.d)  # revealed: Mock

Invalid assignments are not used for narrowing

class C:
    x: int | None
    l: list[int]

def f(c: C, s: str):
    c.x = s  # error: [invalid-assignment]
    reveal_type(c.x)  # revealed: int | None
    s = c.x  # error: [invalid-assignment]

    # error: [invalid-assignment] "Invalid subscript assignment with key of type `Literal[0]` and value of type `str` on object of type `list[int]`"
    c.l[0] = s
    reveal_type(c.l[0])  # revealed: int