[ty] Substitute for typing.Self when checking protocol members

[dcreager]

This patch updates our protocol assignability checks to substitute for any occurrences of typing.Self in method signatures, replacing it with the class being checked for assignability against the protocol.

This requires a new helper method on signatures, apply_self, which substitutes occurrences of typing.Self without binding the self parameter.

We also update the try_upcast_to_callable method. Before, it would return a Type, since certain types upcast to a union of callables, not to a single callable. However, even in that case, we know that every element of the union is a callable. We now return a vector of CallableType. (Actually a smallvec to handle the most common case of a single callable; and wrapped in a new type so that we can provide helper methods.) If there is more than one element in the result, it represents a union of callables. This lets callers get at the CallableType instances in a more type-safe way. (This makes it easier for our protocol checking code to call the new apply_self helper.) We also provide an into_type method so that callers that really do want a Type can get the original result easily.

[dcreager]

There are other Self-related tests in this file that are still TODO, since they also require being able to check against generic protocol members correctly.

[astral-sh-bot]

Diagnostic diff on typing conformance tests

Changes were detected when running ty on typing conformance tests

--- old-output.txt	2025-11-21 21:39:25.413968494 +0000
+++ new-output.txt	2025-11-21 21:39:28.924985349 +0000
@@ -504,6 +504,7 @@
 generics_self_basic.py:64:38: error[invalid-return-type] Function always implicitly returns `None`, which is not assignable to return type `Self@set_value`
 generics_self_basic.py:67:26: error[invalid-type-form] Special form `typing.Self` expected no type parameter
 generics_self_protocols.py:61:19: error[invalid-argument-type] Argument to function `accepts_shape` is incorrect: Expected `ShapeProtocol`, found `BadReturnType`
+generics_self_protocols.py:64:19: error[invalid-argument-type] Argument to function `accepts_shape` is incorrect: Expected `ShapeProtocol`, found `ReturnDifferentClass`
 generics_self_usage.py:50:34: error[invalid-assignment] Object of type `def foo(self) -> int` is not assignable to `(typing.Self, /) -> int`
 generics_self_usage.py:73:14: error[invalid-type-form] Variable of type `typing.Self` is not allowed in a type expression
 generics_self_usage.py:73:23: error[invalid-type-form] Variable of type `typing.Self` is not allowed in a type expression
@@ -1001,5 +1002,5 @@
 typeddicts_usage.py:28:17: error[missing-typed-dict-key] Missing required key 'name' in TypedDict `Movie` constructor
 typeddicts_usage.py:28:18: error[invalid-key] Unknown key "title" for TypedDict `Movie`: Unknown key "title"
 typeddicts_usage.py:40:24: error[invalid-type-form] The special form `typing.TypedDict` is not allowed in type expressions. Did you mean to use a concrete TypedDict or `collections.abc.Mapping[str, object]` instead?
-Found 1003 diagnostics
+Found 1004 diagnostics
 WARN A fatal error occurred while checking some files. Not all project files were analyzed. See the diagnostics list above for details.

[astral-sh-bot]

mypy_primer results

Changes were detected when running on open source projects

sympy (https://github.com/sympy/sympy)
- sympy/polys/domains/domain.py:586:51: warning[unused-ignore-comment] Unused blanket `type: ignore` directive
- Found 14541 diagnostics
+ Found 14540 diagnostics

core (https://github.com/home-assistant/core)
- homeassistant/helpers/storage.py:395:13: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[Any] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[dict[str, Any] | list[Any] | str | ... omitted 3 union elements]]` cannot be called with key of type `Literal["version"]` on object of type `list[JsonValueType]`
+ homeassistant/helpers/storage.py:395:13: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[JsonValueType] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[JsonValueType]]` cannot be called with key of type `Literal["version"]` on object of type `list[JsonValueType]`
- homeassistant/helpers/storage.py:396:17: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[Any] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[dict[str, Any] | list[Any] | str | ... omitted 3 union elements]]` cannot be called with key of type `Literal["minor_version"]` on object of type `list[JsonValueType]`
+ homeassistant/helpers/storage.py:396:17: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[JsonValueType] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[JsonValueType]]` cannot be called with key of type `Literal["minor_version"]` on object of type `list[JsonValueType]`
- homeassistant/helpers/storage.py:398:22: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[Any] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[dict[str, Any] | list[Any] | str | ... omitted 3 union elements]]` cannot be called with key of type `Literal["data"]` on object of type `list[JsonValueType]`
+ homeassistant/helpers/storage.py:398:22: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[JsonValueType] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[JsonValueType]]` cannot be called with key of type `Literal["data"]` on object of type `list[JsonValueType]`
- homeassistant/helpers/storage.py:403:17: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[Any] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[dict[str, Any] | list[Any] | str | ... omitted 3 union elements]]` cannot be called with key of type `Literal["version"]` on object of type `list[JsonValueType]`
+ homeassistant/helpers/storage.py:403:17: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[JsonValueType] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[JsonValueType]]` cannot be called with key of type `Literal["version"]` on object of type `list[JsonValueType]`
- homeassistant/helpers/storage.py:404:17: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[Any] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[dict[str, Any] | list[Any] | str | ... omitted 3 union elements]]` cannot be called with key of type `Literal["minor_version"]` on object of type `list[JsonValueType]`
+ homeassistant/helpers/storage.py:404:17: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[JsonValueType] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[JsonValueType]]` cannot be called with key of type `Literal["minor_version"]` on object of type `list[JsonValueType]`
- homeassistant/helpers/storage.py:409:57: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[Any] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[dict[str, Any] | list[Any] | str | ... omitted 3 union elements]]` cannot be called with key of type `Literal["version"]` on object of type `list[JsonValueType]`
+ homeassistant/helpers/storage.py:409:57: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[JsonValueType] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[JsonValueType]]` cannot be called with key of type `Literal["version"]` on object of type `list[JsonValueType]`
- homeassistant/helpers/storage.py:409:74: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[Any] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[dict[str, Any] | list[Any] | str | ... omitted 3 union elements]]` cannot be called with key of type `Literal["data"]` on object of type `list[JsonValueType]`
+ homeassistant/helpers/storage.py:409:74: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[JsonValueType] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[JsonValueType]]` cannot be called with key of type `Literal["data"]` on object of type `list[JsonValueType]`
- homeassistant/helpers/storage.py:413:25: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[Any] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[dict[str, Any] | list[Any] | str | ... omitted 3 union elements]]` cannot be called with key of type `Literal["version"]` on object of type `list[JsonValueType]`
+ homeassistant/helpers/storage.py:413:25: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[JsonValueType] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[JsonValueType]]` cannot be called with key of type `Literal["version"]` on object of type `list[JsonValueType]`
- homeassistant/helpers/storage.py:413:42: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[Any] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[dict[str, Any] | list[Any] | str | ... omitted 3 union elements]]` cannot be called with key of type `Literal["minor_version"]` on object of type `list[JsonValueType]`
+ homeassistant/helpers/storage.py:413:42: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[JsonValueType] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[JsonValueType]]` cannot be called with key of type `Literal["minor_version"]` on object of type `list[JsonValueType]`
- homeassistant/helpers/storage.py:413:65: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[Any] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[dict[str, Any] | list[Any] | str | ... omitted 3 union elements]]` cannot be called with key of type `Literal["data"]` on object of type `list[JsonValueType]`
+ homeassistant/helpers/storage.py:413:65: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[JsonValueType] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[JsonValueType]]` cannot be called with key of type `Literal["data"]` on object of type `list[JsonValueType]`
- homeassistant/helpers/storage.py:416:24: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[Any] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[dict[str, Any] | list[Any] | str | ... omitted 3 union elements]]` cannot be called with key of type `Literal["version"]` on object of type `list[JsonValueType]`
+ homeassistant/helpers/storage.py:416:24: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[JsonValueType] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[JsonValueType]]` cannot be called with key of type `Literal["version"]` on object of type `list[JsonValueType]`
- homeassistant/helpers/storage.py:418:30: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[Any] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[dict[str, Any] | list[Any] | str | ... omitted 3 union elements]]` cannot be called with key of type `Literal["data"]` on object of type `list[JsonValueType]`
+ homeassistant/helpers/storage.py:418:30: error[invalid-argument-type] Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> dict[str, Any] | list[JsonValueType] | str | ... omitted 3 union elements, (s: slice[Any, Any, Any], /) -> list[JsonValueType]]` cannot be called with key of type `Literal["data"]` on object of type `list[JsonValueType]`

Memory usage changes were detected when running on open source projects

trio (https://github.com/python-trio/trio)
-     memo metadata = ~31MB
+     memo metadata = ~33MB

sphinx (https://github.com/sphinx-doc/sphinx)
-     memo metadata = ~66MB
+     memo metadata = ~69MB

[astral-sh-bot]

ecosystem-analyzer results

Lint rule	Added	Removed	Changed
invalid-argument-type	0	0	12
unused-ignore-comment	0	1	0
Total	0	1	12

Full report with detailed diff (timing results)

[dcreager]

Typing conformance result is a new true positive

[dcreager]

Ecosystem results look good now, too ­— showing a more precise type in the diagnostics