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.4 KiB

replace

The replace function and the replace protocol were added in Python 3.13: https://docs.python.org/3/whatsnew/3.13.html#copy

[environment]
python-version = "3.13"

Basic

from copy import replace
from datetime import time

t = time(12, 0, 0)
t = replace(t, minute=30)

reveal_type(t)  # revealed: time

The __replace__ protocol

Dataclasses

Dataclasses support the __replace__ protocol:

from dataclasses import dataclass
from copy import replace

@dataclass
class Point:
    x: int
    y: int

reveal_type(Point.__replace__)  # revealed: (self: Point, *, x: int = ..., y: int = ...) -> Point

The __replace__ method can either be called directly or through the replace function:

a = Point(1, 2)

b = a.__replace__(x=3, y=4)
reveal_type(b)  # revealed: Point

b = replace(a, x=3, y=4)
reveal_type(b)  # revealed: Point

A call to replace does not require all keyword arguments:

c = a.__replace__(y=4)
reveal_type(c)  # revealed: Point

d = replace(a, y=4)
reveal_type(d)  # revealed: Point

Invalid calls to __replace__ or replace will raise an error:

e = a.__replace__(x="wrong")  # error: [invalid-argument-type]

# error: [invalid-argument-type] "Argument to function `replace` is incorrect: Expected `int`, found `Literal["wrong"]`"
e = replace(a, x="wrong")

Dataclass transforms

Classes transformed through a base class or metaclass also support the __replace__ protocol.

from copy import replace
from typing import dataclass_transform

@dataclass_transform()
class ModelBase: ...

class BaseModel(ModelBase):
    value: int

# revealed: (self: BaseModel, *, value: int = ...) -> BaseModel
reveal_type(BaseModel.__replace__)

base_model = BaseModel(value=1)
reveal_type(base_model.__replace__(value=2))  # revealed: BaseModel
reveal_type(replace(base_model, value=2))  # revealed: BaseModel

@dataclass_transform()
class ModelMetaclass(type): ...

class MetaclassModel(metaclass=ModelMetaclass):
    value: int

# revealed: (self: MetaclassModel, *, value: int = ...) -> MetaclassModel
reveal_type(MetaclassModel.__replace__)

metaclass_model = MetaclassModel(value=1)
reveal_type(metaclass_model.__replace__(value=2))  # revealed: MetaclassModel
reveal_type(replace(metaclass_model, value=2))  # revealed: MetaclassModel

NamedTuples

NamedTuples also support the __replace__ protocol:

from typing import NamedTuple
from copy import replace

class Point(NamedTuple):
    x: int
    y: int

reveal_type(Point.__replace__)  # revealed: (self: Self, *, x: int = ..., y: int = ...) -> Self

The __replace__ method can either be called directly or through the replace function:

a = Point(1, 2)

b = a.__replace__(x=3, y=4)
reveal_type(b)  # revealed: Point

b = replace(a, x=3, y=4)
reveal_type(b)  # revealed: Point

Invalid calls to __replace__ will raise an error:

# error: [unknown-argument] "Argument `z` does not match any known parameter"
a.__replace__(z=42)

Before Python 3.13

Dataclass transforms do not synthesize __replace__ before the replacement protocol exists.

[environment]
python-version = "3.12"
from typing import dataclass_transform

@dataclass_transform()
class ModelBase: ...

class Model(ModelBase):
    value: int

Model.__replace__  # error: [missing-attribute]
Model(value=1).__replace__  # error: [missing-attribute]