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

3.2 KiB

Attribute access

Boundness

def _(flag: bool):
    class A:
        always_bound: int = 1

        if flag:
            union = 1
        else:
            union = "abc"

        if flag:
            union_declared: int = 1
        else:
            union_declared: str = "abc"

        if flag:
            possibly_unbound: str = "abc"

    reveal_type(A.always_bound)  # revealed: int

    reveal_type(A.union)  # revealed: int | str

    reveal_type(A.union_declared)  # revealed: int | str

    # error: [possibly-missing-attribute] "Attribute `possibly_unbound` may be missing on class `A`"
    reveal_type(A.possibly_unbound)  # revealed: str

    # error: [missing-attribute] "Class `A` has no attribute `non_existent`"
    reveal_type(A.non_existent)  # revealed: Unknown

Walrus attribute access after later rebinding

class IntBox:
    attr: int

class StrBox:
    attr: str

def f() -> None:
    (box := IntBox()).attr = 1
    box = StrBox()
    reveal_type(box.attr)  # revealed: str

Local prefixes block enclosing whole-place bindings

When a nested function binds the root name of a whole-place access, the local root binding takes precedence over the root binding from the enclosing scope.

class IntBox:
    attr: int

class StrBox:
    attr: str

box = IntBox()

def outer_root() -> None:
    box.attr = 1

    def inner() -> None:
        box = StrBox()
        reveal_type(box.attr)  # revealed: str

Similarly, a nested rebinding of an intermediate member, rather than the root, takes precedence over the enclosing binding of that same intermediate member.

class Holder:
    box: IntBox | StrBox

def outer_member() -> None:
    holder = Holder()
    holder.box = IntBox()
    holder.box.attr = 1

    def inner() -> None:
        holder.box = StrBox()
        reveal_type(holder.box.attr)  # revealed: str

Under Python's function name-resolution rules, even a conditional assignment to the root name makes the local root take precedence over the enclosing binding. When the condition is false, the unbound local root cannot fall back to the binding in the enclosing scope.

def with_inner_conditional_root(flag: bool) -> None:
    box = IntBox()
    box.attr = 1

    def inner() -> None:
        if flag:
            box = StrBox()
        # error: [possibly-unresolved-reference] "Name `box` used when possibly not defined"
        reveal_type(box.attr)  # revealed: str

By contrast, binding an intermediate member does not affect resolution of the root, which still comes from the enclosing scope. When the intermediate member is conditionally rebound, it can refer to either object, so both member types remain visible in the whole-place access.

def with_inner_conditional_member(flag: bool) -> None:
    holder = Holder()
    holder.box = IntBox()
    holder.box.attr = 1

    def inner() -> None:
        if flag:
            holder.box = StrBox()
        reveal_type(holder.box.attr)  # revealed: int | str

If none of the prefixes are bound in the nested scope, the enclosing whole-place binding remains visible.

def outer_fallback() -> None:
    box = IntBox()
    box.attr = 1

    def inner() -> None:
        reveal_type(box.attr)  # revealed: int