## 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>
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