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

Attribute assignment

This test suite demonstrates various kinds of diagnostics that can be emitted in a obj.attr = value assignment.

Instance attributes with class-level defaults

These can be set on instances and on class objects.

class C:
    attr: int = 0

instance = C()
instance.attr = 1  # fine

C.attr = 1  # fine

But if the type is incorrect, we emit an error:

instance.attr = "wrong"  # snapshot: invalid-assignment
error[invalid-assignment]: Object of type `Literal["wrong"]` is not assignable to attribute `attr` of type `int`
 --> src/mdtest_snippet.py:8:1
  |
8 | instance.attr = "wrong"  # snapshot: invalid-assignment
  | ^^^^^^^^^^^^^

And on the class object:

C.attr = "wrong"  # snapshot: invalid-assignment
error[invalid-assignment]: Object of type `Literal["wrong"]` is not assignable to attribute `attr` of type `int`
 --> src/mdtest_snippet.py:9:1
  |
9 | C.attr = "wrong"  # snapshot: invalid-assignment
  | ^^^^^^

Pure instance attributes

These can only be set on instances.

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

instance = C()
instance.attr = 1  # fine
instance.attr = "wrong"  # error: [invalid-assignment]

When trying to set them on class objects, we generate a useful diagnostic that mentions that the attribute is only available on instances:

C.attr = 1  # snapshot: invalid-attribute-access
error[invalid-attribute-access]: Cannot assign to instance attribute `attr` from the class object `<class 'C'>`
 --> src/mdtest_snippet.py:8:1
  |
8 | C.attr = 1  # snapshot: invalid-attribute-access
  | ^^^^^^

Invalid annotated assignment to attribute

Annotated assignments to attributes on method receivers should be validated against their annotation.

class C:
    def __init__(self):
        self.attr: str = None  # snapshot: invalid-assignment
        self.attr2: int = 1  # fine

    @classmethod
    def initialize(cls):
        cls.class_attr1: str = None  # snapshot: invalid-assignment
        cls.class_attr2: int = 1  # fine
error[invalid-assignment]: Object of type `None` is not assignable to `str`
 --> src/mdtest_snippet.py:3:26
  |
3 |         self.attr: str = None  # snapshot: invalid-assignment
  |                    ---   ^^^^ Incompatible value of type `None`
  |                    |
  |                    Declared type


error[invalid-assignment]: Object of type `None` is not assignable to `str`
 --> src/mdtest_snippet.py:8:32
  |
8 |         cls.class_attr1: str = None  # snapshot: invalid-assignment
  |                          ---   ^^^^ Incompatible value of type `None`
  |                          |
  |                          Declared type

Annotations on other attribute targets are ignored, and the assignment is checked against the attribute already declared on the object's type.

class C:
    declared: int

instance = C()

# error: [invalid-type-form] "Type annotations are not allowed on this attribute expression"
# error: [invalid-assignment]
instance.declared: str = "wrong"

# error: [invalid-type-form]
# error: [missing-attribute]
instance.missing: str = "wrong"

class Other:
    declared: int

class Static:
    @staticmethod
    def assign(other: Other):
        # error: [invalid-type-form]
        # error: [invalid-assignment]
        other.declared: str = "wrong"

class WithNew:
    declared: int

    def __new__(cls):
        # error: [invalid-type-form]
        # error: [invalid-assignment]
        cls.declared: str = "wrong"
        return super().__new__(cls)

ClassVars

These can only be set on class objects:

from typing import ClassVar

class C:
    attr: ClassVar[int] = 0

C.attr = 1  # fine
C.attr = "wrong"  # error: [invalid-assignment]

When trying to set them on instances, we generate a useful diagnostic that mentions that the attribute is only available on class objects.

instance = C()
instance.attr = 1  # snapshot: invalid-attribute-access
error[invalid-attribute-access]: Cannot assign to ClassVar `attr` from an instance of type `C`
 --> src/mdtest_snippet.py:9:1
  |
9 | instance.attr = 1  # snapshot: invalid-attribute-access
  | ^^^^^^^^^^^^^

Unknown attributes

When trying to set an attribute that is not defined, we also emit errors:

class C: ...

C.non_existent = 1  # snapshot: missing-attribute
error[missing-attribute]: Unresolved attribute `non_existent` on type `<class 'C'>`.
 --> src/mdtest_snippet.py:3:1
  |
3 | C.non_existent = 1  # snapshot: missing-attribute
  | ^^^^^^^^^^^^^^

And on instances:

instance = C()
instance.non_existent = 1  # snapshot: missing-attribute
error[missing-attribute]: Unresolved attribute `non_existent` on type `C`
 --> src/mdtest_snippet.py:5:1
  |
5 | instance.non_existent = 1  # snapshot: missing-attribute
  | ^^^^^^^^^^^^^^^^^^^^^

Attributes declared without instance storage

An instance attribute annotation does not create storage. Assigning to an attribute declared on a slotted class explains that the class has neither a matching slot nor an instance dictionary.

class Slotted:
    value: int
    __slots__ = ()

Slotted().value = 1  # snapshot: missing-slot
error[missing-slot]: Cannot assign to attribute `value`: `Slotted` has no slot or instance dictionary
 --> src/mdtest_snippet.py:5:1
  |
5 | Slotted().value = 1  # snapshot: missing-slot
  | ^^^^^^^^^^^^^^^
info: Attribute `value` is declared but is not included in `__slots__`

A genuinely undeclared attribute keeps the ordinary missing-attribute diagnostic.

Slotted().missing = 1  # error: [missing-attribute] "Unresolved attribute `missing` on type `Slotted`"

An inherited annotation also does not provide storage for a slotted subclass.

class SlottedChild(Slotted):
    __slots__ = ()

# error: [missing-slot] "Cannot assign to attribute `value`: `SlottedChild` has no slot or instance dictionary"
SlottedChild().value = 1

Possibly-missing attributes

When trying to set an attribute that is not defined in all branches, we emit errors:

def _(flag: bool) -> None:
    class C:
        if flag:
            attr: int = 0

    C.attr = 1  # snapshot: possibly-missing-attribute
info[possibly-missing-attribute]: Attribute `attr` may be missing on class `C`
 --> src/mdtest_snippet.py:6:5
  |
6 |     C.attr = 1  # snapshot: possibly-missing-attribute
  |     ^^^^^^

And on instances:

    instance = C()
    instance.attr = 1  # snapshot: possibly-missing-attribute
info[possibly-missing-attribute]: Attribute `attr` may be missing on object of type `C`
 --> src/mdtest_snippet.py:8:5
  |
8 |     instance.attr = 1  # snapshot: possibly-missing-attribute
  |     ^^^^^^^^^^^^^

Data descriptors

When assigning to a data descriptor attribute, we implicitly call the descriptor's __set__ method. This can lead to various kinds of diagnostics.

Invalid argument type

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

class C:
    attr: Descriptor = Descriptor()

instance = C()
instance.attr = 1  # fine

instance.attr = "wrong"  # snapshot: invalid-assignment

# Check that the concise diagnostic retains the useful expected and provided types.
# error: [invalid-assignment] "Expected `int`, found `Literal["also wrong"]`"
instance.attr = "also wrong"
error[invalid-assignment]: Invalid assignment to data descriptor attribute `attr` on type `C`
  --> src/mdtest_snippet.py:11:17
   |
11 | instance.attr = "wrong"  # snapshot: invalid-assignment
   |                 ^^^^^^^ Expected `int`, found `Literal["wrong"]`
info: Argument to bound method `Descriptor.__set__` is incorrect
info: This assignment implicitly calls `__set__` on a descriptor of type `Descriptor`
info: Method defined here
 --> src/mdtest_snippet.py:2:9
  |
2 |     def __set__(self, instance: object, value: int) -> None:
  |         ^^^^^^^                         ---------- Parameter declared here

Invalid __set__ method signature

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

class C:
    attr: WrongDescriptor = WrongDescriptor()

instance = C()

instance.attr = 1  # snapshot: invalid-assignment
error[invalid-assignment]: Invalid assignment to data descriptor attribute `attr` on type `C`
  --> src/mdtest_snippet.py:10:1
   |
10 | instance.attr = 1  # snapshot: invalid-assignment
   | ^^^^^^^^^^^^^ No argument provided for required parameter `extra` of bound method `WrongDescriptor.__set__`
info: This assignment implicitly calls `__set__` on a descriptor of type `WrongDescriptor`
info: Parameter declared here
 --> src/mdtest_snippet.py:2:53
  |
2 |     def __set__(self, instance: object, value: int, extra: int) -> None:
  |                                                     ^^^^^^^^^^

Invalid property setter argument type

class Document: ...

class HasDocumentRef:
    @property
    def document(self) -> Document | None: ...
    @document.setter
    def document(self, document: Document) -> None: ...

class Model(HasDocumentRef):
    def detach(self) -> None:
        self.document = None  # snapshot: invalid-assignment

        # Check that the concise diagnostic identifies the actual setter argument mismatch.
        # error: [invalid-assignment] "Expected `Document`, found `None`"
        self.document = None
error[invalid-assignment]: Invalid assignment to data descriptor attribute `document` on type `Self@detach`
  --> src/mdtest_snippet.py:11:25
   |
11 |         self.document = None  # snapshot: invalid-assignment
   |                         ^^^^ Expected `Document`, found `None`
info: Argument to function `HasDocumentRef.document` is incorrect
info: This assignment implicitly calls `__set__` on a descriptor of type `property`
info: Function defined here
 --> src/mdtest_snippet.py:7:9
  |
7 |     def document(self, document: Document) -> None: ...
  |         ^^^^^^^^       ------------------ Parameter declared here

Nested argument type

class Descriptor:
    def __set__(self, instance, value: tuple[int, str]) -> None: ...

class C:
    x = Descriptor()

c = C()
c.x = (1, b"")  # snapshot: invalid-assignment
error[invalid-assignment]: Invalid assignment to data descriptor attribute `x` on type `C`
 --> src/mdtest_snippet.py:8:7
  |
8 | c.x = (1, b"")  # snapshot: invalid-assignment
  |       ^^^^^^^^ Expected `tuple[int, str]`, found `tuple[Literal[1], Literal[b""]]`
info: Argument to bound method `Descriptor.__set__` is incorrect
info: This assignment implicitly calls `__set__` on a descriptor of type `Descriptor`
info: the second tuple element is not compatible: `Literal[b""]` is not assignable to `str`
info: Method defined here
 --> src/mdtest_snippet.py:2:9
  |
2 |     def __set__(self, instance, value: tuple[int, str]) -> None: ...
  |         ^^^^^^^                 ---------------------- Parameter declared here

Setting attributes on union types

def _(flag: bool) -> None:
    if flag:
        class C1:
            attr: int = 0

    else:
        class C1:
            attr: str = ""

    C1.attr = 1  # snapshot: invalid-assignment

    class C2:
        if flag:
            attr: int = 0
        else:
            attr: str = ""

    # TODO: This should be an error
    C2.attr = 1

TODO: The error message here could be improved to explain why the assignment fails.

error[invalid-assignment]: Object of type `Literal[1]` is not assignable to attribute `attr` on type `<class 'mdtest_snippet.<locals of function '_'>.C1 @ src/mdtest_snippet.py:3:15'> | <class 'mdtest_snippet.<locals of function '_'>.C1 @ src/mdtest_snippet.py:7:15'>`
  --> src/mdtest_snippet.py:10:5
   |
10 |     C1.attr = 1  # snapshot: invalid-assignment
   |     ^^^^^^^