Invalid argument type when overload `self` uses a different `TypeVar` than the class definition

[hoxbro]

When a generic class is defined with one TypeVar('T') but its __init__ overloads use a different TypeVar('CT') in the self-type annotation,

Playground: https://play.ty.dev/05042e22-0dc4-48c8-8899-60539b5e23fb

Both pyright, pyrefly, and mypy report this as what I expect, see below.

Minimal Reproduction

from __future__ import annotations

import typing as t
from typing_extensions import assert_type, reveal_type

T = t.TypeVar("T")
CT = t.TypeVar("CT")


class ClassSelector(t.Generic[T]):
    if t.TYPE_CHECKING:

        @t.overload
        def __init__(
            self: ClassSelector[CT],
            *,
            default: CT,
            class_: type[CT],
        ) -> None: ...

        @t.overload
        def __init__(
            self: ClassSelector[CT | None],
            *,
            default: None = None,
            class_: type[CT],
        ) -> None: ...

    def __init__(self, *, default=None, class_=None): ...


class MyClass:
    pass


a = ClassSelector(default=MyClass(), class_=MyClass)
assert_type(a, "ClassSelector[MyClass]")
reveal_type(a)

b = ClassSelector(class_=MyClass)
assert_type(b, "ClassSelector[MyClass | None]")
reveal_type(b)

Expected Behavior

Revealed type: ClassSelector[MyClass]
Revealed type: ClassSelector[MyClass | None]

Actual Behavior

ty

info[revealed-type]: Revealed type
  --> mre_minimal.py:38:13
   |
36 | a = ClassSelector(default=MyClass(), class_=MyClass)
37 | assert_type(a, "ClassSelector[MyClass]")
38 | reveal_type(a)
   |             ^ `ClassSelector[MyClass]`
39 |
40 | b = ClassSelector(class_=MyClass)
   |

error[invalid-argument-type]: Argument to bound method `__init__` is incorrect
  --> mre_minimal.py:40:5
   |
38 | reveal_type(a)
39 |
40 | b = ClassSelector(class_=MyClass)
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Expected `ClassSelector[None | MyClass]`, found `ClassSelector[None]`
41 | assert_type(b, "ClassSelector[MyClass | None]")
42 | reveal_type(b)
   |
info: Matching overload defined here
  --> mre_minimal.py:22:13
   |
21 |         @t.overload
22 |         def __init__(
   |             ^^^^^^^^
23 |             self: ClassSelector[CT | None],
   |             ------------------------------ Parameter declared here
24 |             *,
25 |             default: None = None,
   |
info: Non-matching overloads for bound method `__init__`:
info:   [CT](self: ClassSelector[CT], *, default: CT, class_: type[CT]) -> None
info: `ClassSelector` is invariant in its type parameter
info: For more information, see https://docs.astral.sh/ty/reference/typing-faq/#invariant-generics
info: rule `invalid-argument-type` is enabled by default

error[type-assertion-failure]: Argument does not have asserted type `ClassSelector[MyClass | None]`
  --> mre_minimal.py:41:1
   |
40 | b = ClassSelector(class_=MyClass)
41 | assert_type(b, "ClassSelector[MyClass | None]")
   | ^^^^^^^^^^^^-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |             |
   |             Inferred type is `ClassSelector[T@ClassSelector]`
42 | reveal_type(b)
   |
info: `ClassSelector[MyClass | None]` and `ClassSelector[T@ClassSelector]` are not equivalent types
info: rule `type-assertion-failure` is enabled by default

info[revealed-type]: Revealed type
  --> mre_minimal.py:42:13
   |
40 | b = ClassSelector(class_=MyClass)
41 | assert_type(b, "ClassSelector[MyClass | None]")
42 | reveal_type(b)
   |             ^ `ClassSelector[T@ClassSelector]`
   |

Found 4 diagnostics

pyright:

/home/shh/projects/holoviz/repos/param/mre_minimal.py
  /home/shh/projects/holoviz/repos/param/mre_minimal.py:38:13 - information: Type of "a" is "ClassSelector[MyClass]"
  /home/shh/projects/holoviz/repos/param/mre_minimal.py:42:13 - information: Type of "b" is "ClassSelector[MyClass | None]"
0 errors, 0 warnings, 2 informations

pyrefly

 INFO revealed type: ClassSelector[MyClass] [reveal-type]
  --> mre_minimal.py:38:12
   |
38 | reveal_type(a)
   |            ---
   |
 INFO revealed type: ClassSelector[MyClass | None] [reveal-type]
  --> mre_minimal.py:42:12
   |
42 | reveal_type(b)
   |            ---
   |
 INFO 0 errors

mypy

mre_minimal.py:38: note: Revealed type is "mre_minimal.ClassSelector[mre_minimal.MyClass]"
mre_minimal.py:42: note: Revealed type is "mre_minimal.ClassSelector[mre_minimal.MyClass | None]"
Success: no issues found in 1 source file

Version

ty 0.0.29

Note:

If I change CT to T it works for ty, but makes other type checker fails:

+ pyright mre_minimal2.py
/home/shh/projects/holoviz/repos/param/mre_minimal2.py
  /home/shh/projects/holoviz/repos/param/mre_minimal2.py:14:19 - warning: Type annotation for "self" parameter of "__init__" method cannot contain class-scoped type variables (reportInvalidTypeVarUse)
  /home/shh/projects/holoviz/repos/param/mre_minimal2.py:22:19 - warning: Type annotation for "self" parameter of "__init__" method cannot contain class-scoped type variables (reportInvalidTypeVarUse)
  /home/shh/projects/holoviz/repos/param/mre_minimal2.py:37:13 - information: Type of "a" is "ClassSelector[MyClass]"
  /home/shh/projects/holoviz/repos/param/mre_minimal2.py:40:13 - error: "assert_type" mismatch: expected "ClassSelector[MyClass | None]" but received "ClassSelector[T@ClassSelector | None]" (reportAssertTypeFailure)
  /home/shh/projects/holoviz/repos/param/mre_minimal2.py:41:13 - information: Type of "b" is "ClassSelector[T@ClassSelector | None]"
1 error, 2 warnings, 2 informations
+ pyrefly check mre_minimal2.py
ERROR `__init__` method self type cannot reference class type parameter `T` [invalid-annotation]
  --> mre_minimal2.py:13:13
   |
13 |         def __init__(
   |             ^^^^^^^^
   |
ERROR `__init__` method self type cannot reference class type parameter `T` [invalid-annotation]
  --> mre_minimal2.py:21:13
   |
21 |         def __init__(
   |             ^^^^^^^^
   |
 INFO revealed type: ClassSelector[MyClass] [reveal-type]
  --> mre_minimal2.py:37:12
   |
37 | reveal_type(a)
   |            ---
   |
ERROR `MyClass` is not assignable to upper bound `object` of type variable `T` [bad-specialization]
  --> mre_minimal2.py:39:18
   |
39 | b = ClassSelector(class_=MyClass)
   |                  ^^^^^^^^^^^^^^^^
   |
ERROR Argument `type[MyClass]` is not assignable to parameter `class_` with type `type[Unknown | None]` in function `ClassSelector.__init__` [bad-argument-type]
  --> mre_minimal2.py:39:26
   |
39 | b = ClassSelector(class_=MyClass)
   |                          ^^^^^^^
   |
ERROR assert_type(ClassSelector[Unknown | None], ClassSelector[MyClass | None]) failed [assert-type]
  --> mre_minimal2.py:40:12
   |
40 | assert_type(b, "ClassSelector[MyClass | None]")
   |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
 INFO revealed type: ClassSelector[Unknown | None] [reveal-type]
  --> mre_minimal2.py:41:12
   |
41 | reveal_type(b)
   |            ---
   |
 INFO 5 errors
+ mypy mre_minimal2.py
mre_minimal2.py:37: note: Revealed type is "mre_minimal2.ClassSelector[mre_minimal2.MyClass]"
mre_minimal2.py:41: note: Revealed type is "mre_minimal2.ClassSelector[mre_minimal2.MyClass | None]"
Success: no issues found in 1 source file
+ ty check mre_minimal2.py
info[revealed-type]: Revealed type
  --> mre_minimal2.py:37:13
   |
35 | a = ClassSelector(default=MyClass(), class_=MyClass)
36 | assert_type(a, "ClassSelector[MyClass]")
37 | reveal_type(a)
   |             ^ `ClassSelector[MyClass]`
38 |
39 | b = ClassSelector(class_=MyClass)
   |

info[revealed-type]: Revealed type
  --> mre_minimal2.py:41:13
   |
39 | b = ClassSelector(class_=MyClass)
40 | assert_type(b, "ClassSelector[MyClass | None]")
41 | reveal_type(b)
   |             ^ `ClassSelector[None | MyClass]`
   |

Found 2 diagnostics

[hoxbro]

Using Opus 4.6 to suggest a fix and it came up with this one:

diff --git a/crates/ty_python_semantic/resources/mdtest/call/constructor.md b/crates/ty_python_semantic/resources/mdtest/call/constructor.md
index 277f2b12a9..89b024d732 100644
--- a/crates/ty_python_semantic/resources/mdtest/call/constructor.md
+++ b/crates/ty_python_semantic/resources/mdtest/call/constructor.md
@@ -1152,6 +1152,34 @@ reveal_type(Class7(0, ""))  # revealed: Class7[str, int]
 reveal_type(Class7[str, int](0, ""))  # revealed: Class7[str, int]
 ```
 
+## `__init__` overloads use `self` annotation to widen class generic
+
+A `self` annotation in an `__init__` overload can widen the class's generic parameter by combining
+the method's own typevars with extra types (e.g. `None`). When a second overload produces a
+`default=None` with the class generic unbound, the `self` annotation should drive the final
+specialization.
+
+```py
+from __future__ import annotations
+
+from typing import Generic, TypeVar, overload
+
+T = TypeVar("T")
+CT = TypeVar("CT")
+
+class ClassSelector(Generic[T]):
+    @overload
+    def __init__(self: ClassSelector[CT], *, default: CT, class_: type[CT]) -> None: ...
+    @overload
+    def __init__(self: ClassSelector[CT | None], *, default: None = None, class_: type[CT]) -> None: ...
+    def __init__(self, *, default=None, class_=None) -> None: ...
+
+class MyClass: ...
+
+reveal_type(ClassSelector(default=MyClass(), class_=MyClass))  # revealed: ClassSelector[MyClass]
+reveal_type(ClassSelector(class_=MyClass))  # revealed: ClassSelector[MyClass | None]
+```
+
 ## Constructor calls through `type[T]` with a bound TypeVar
 
 ```py
diff --git a/crates/ty_python_semantic/src/types/generics.rs b/crates/ty_python_semantic/src/types/generics.rs
index c9c42f08f0..dd6d7f27f6 100644
--- a/crates/ty_python_semantic/src/types/generics.rs
+++ b/crates/ty_python_semantic/src/types/generics.rs
@@ -1992,6 +1992,19 @@ impl<'db, 'c> SpecializationBuilder<'db, 'c> {
                 self.add_type_mapping(*formal_bound_typevar, remaining_actual, polarity, f);
             }
             (Type::Union(union_formal), _) => {
+                // If the actual type is itself an inferable bare TypeVar, we treat the whole
+                // formal union as the inferred type. Peeling the union element-by-element (as
+                // the fallback loop below does) would otherwise incorrectly bind the actual
+                // TypeVar to individual formal elements (e.g. matching `T` against `CT | None`
+                // under invariance would yield `T = None` from the literal branch).
+                if let Type::TypeVar(actual_typevar) = actual
+                    && actual_typevar.is_inferable(self.db, self.inferable)
+                    && matches!(polarity, TypeVarVariance::Invariant)
+                {
+                    self.add_type_mapping(actual_typevar, formal, polarity, f);
+                    return Ok(());
+                }
+
                 // Second, if the formal is a union, and the actual type is assignable to precisely
                 // one union element, then we don't add any type mapping. This handles a case like
                 //

Output:

❯ cargo run --bin ty -- check mre.py
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.16s
     Running `target/debug/ty check mre.py`
info[revealed-type]: Revealed type
  --> mre.py:39:13
   |
39 | reveal_type(a)
   |             ^ `ClassSelector[MyClass]`
   |

info[revealed-type]: Revealed type
  --> mre.py:43:13
   |
43 | reveal_type(b)
   |             ^ `ClassSelector[MyClass | None]`
   |

Found 2 diagnostics

plan

Plan: Support self annotations in generic __init__ overloads

Reproducer

/home/shh/projects/ruff/mre.py

from __future__ import annotations
import typing as t
from typing_extensions import assert_type

T = t.TypeVar("T")
CT = t.TypeVar("CT")

class ClassSelector(t.Generic[T]):
    if t.TYPE_CHECKING:
        @t.overload
        def __init__(self: ClassSelector[CT], *, default: CT, class_: type[CT]) -> None: ...
        @t.overload
        def __init__(self: ClassSelector[CT | None], *, default: None = None, class_: type[CT]) -> None: ...
    def __init__(self, *, default=None, class_=None) -> None: ...

class MyClass: ...

a = ClassSelector(default=MyClass(), class_=MyClass)
assert_type(a, "ClassSelector[MyClass]")          # ty: OK

b = ClassSelector(class_=MyClass)
assert_type(b, "ClassSelector[MyClass | None]")    # ty: FAILS — infers ClassSelector[T@ClassSelector]

Failure mode: ty emits invalid-argument-type with Expected ClassSelector[None | MyClass], found ClassSelector[None], and reveal_type yields ClassSelector[T@ClassSelector] (unspecialized). Other type checkers accept the pattern.

mdtest

A test case has been added under crates/ty_python_semantic/resources/mdtest/call/constructor.md, section "__init__ overloads use self annotation to widen class generic". It fails on main with:

unmatched assertion: revealed: ClassSelector[MyClass | None]
unexpected [revealed-type]: ClassSelector[T@ClassSelector]
unexpected [invalid-argument-type]: Expected ClassSelector[None | MyClass], found ClassSelector[None]

Deeper findings from investigation

Corrected model (Step A complete, 2026-04-17)

The plan's earlier premise that bound_type is unset for __init__ was wrong. The path is:

1. constructor_bindings builds init_method via member_lookup on ClassSelector[T] (identity specialization). init_method is a Type::BoundMethod.
2. When init_method.bindings(db) runs (types.rs:3774-3778), the BoundMethod arm calls .with_bound_type(bound_method.self_instance(db)), setting bound_type = ClassSelector[T].
3. with_self(bound_type) in bind.rs:2616 / 2632 DOES prepend a synthetic self argument of type ClassSelector[T].
4. The synthetic self IS fed into infer_argument_constraints, so both T and CT are constrained.

What actually goes wrong

Instrumented check_argument_type with eprintln! showed, for overload 2 in call ClassSelector(class_=MyClass):

DEBUG InvalidArgumentType: param_idx=0 arg=Synthetic
  expected=ClassSelector[None | MyClass]
  provided=ClassSelector[None]
  spec=["None | MyClass", "None"]
DEBUG InvalidArgumentType: param_idx=1 arg=Keyword("default")
  expected=None
  provided=MyClass
  spec=["None | MyClass", "None"]

The overload's generic context has two typevars (order matches overload sig: CT first, T second). The solver is producing:

• CT = None | MyClass
• T = None

Both are wrong. The correct solution is CT = MyClass, T = MyClass | None.

Why the solver picks this assignment

Constraints the solver sees for overload 2:

• class_: type[CT] with arg type[MyClass] → CT ⊇ MyClass
• default: None = None (default value used) → None ≤ None (no info on CT/T)
• self: ClassSelector[CT | None] provided ClassSelector[T] (invariant) → T ≡ CT | None

The invariant self constraint has two unknowns on it. The solver appears to be splitting the union: it assigns T = None (picking the literal branch of CT | None) and then lets CT absorb the remaining constraints, yielding CT = None | MyClass. This is the actual bug — the inference is making an arbitrary choice in a bi-variable invariant match instead of deferring to other constraints first.

Downstream consequences

• The invalid-argument-type diagnostic is emitted because provided=ClassSelector[None] (T=None applied to ClassSelector[T]) doesn't match expected=ClassSelector[None | MyClass] (CT=None|MyClass applied to ClassSelector[CT | None]).
• Because overload 2 fails the assignability check, overload resolution collapses and the reveal degenerates to the unspecialized ClassSelector[T@ClassSelector].
• instance_return_specialization never has a chance to apply its self-parameter-derived specialization cleanly because the erroneous overload.specialization already contains bogus entries for T and CT.

Why the plan's original step 2 isn't straightforward

The "tactical fix" was premised on instance_return_specialization being the place where the self-annotation → class-typevar derivation happens. In practice:

• The self-annotation isn't wired into specialization inference for __init__ at all (no synthetic self-arg).
• The error-emitting code path that produces found: ClassSelector[None] is not yet located.
• instance_return_specialization exists as a post-hoc patch, but downstream logic (argument type checking) may have already errored and influenced the reveal.

Revised plan

Step B — reframe: fix is in the specialization solver

Since self is already a synthetic argument, the "wire self as a synthetic argument" fix (old B.1) is moot — it already happens. The real fix is in how the solver resolves an invariant-arity match where both sides contain free typevars.

Two candidate fixes:

1. Constraint ordering / delayed union decomposition. In SpecializationBuilder::infer_map, when inferring from an invariant union where the expected side contains both a free method-typevar (CT) and a literal (None), don't commit to a decomposition until other constraints have been incorporated. Prefer T = CT | None as a symbolic assignment, then substitute CT after it gets solved from class_: type[CT].

2. Post-solve self-param reconciliation. Keep the solver as-is but, after initial solving, re-check the self-parameter constraint and re-solve T from the now-grounded CT.

Step C — concrete investigation targets

• crates/ty_python_semantic/src/types/generics.rs — SpecializationBuilder, infer_map on union types under invariance.
• crates/ty_python_semantic/src/types/constraints.rs — constraint set handling.
• Determine whether other type checkers handle this pattern with ordering or with a more expressive constraint-set representation.

Step D — test and prek

• Verify crates/ty_python_semantic/resources/mdtest/call/constructor.md "widen class generic" case passes.
• Run cargo nextest run -p ty_python_semantic mdtest.
• Run uvx prek run -a.

Recommendation

Step B.1 (fix the solver to avoid premature union decomposition) is the correct long-term fix but may be significant. Step B.2 (post-solve reconciliation in instance_return_specialization or adjacent) is a more contained patch that addresses the symptom. Before committing, worth reading infer_map to judge whether B.1 is tractable without a larger refactor of constraint-set solving.

Code locations referenced

• crates/ty_python_semantic/src/types.rs
  • constructor_bindings() — line 4448
  • identity-specialized self_type — lines 4558-4563
  • constructor_instance_ty = self_type.to_instance(db) — line 4575
  • __init__ binding construction (no bound_type) — lines 4617-4623
• crates/ty_python_semantic/src/types/call/bind.rs
  • ArgumentTypeChecker::infer_specialization — line 4269
  • infer_argument_constraints — line 4492 (iterates actual arguments only)
  • with_bound_type / bake_bound_type_into_overloads — lines 2585-2597
  • match_parameters prepending self via with_self — line 2616
• crates/ty_python_semantic/src/types/call/bind/constructor.rs
  • instance_return_specialization() — line 233
  • TODO about hacky workaround — lines 254-260
  • self-parameter specialization extraction — lines 269-276
  • refined specialization (Unknown/promotion handling) — lines 277-301
• crates/ty_python_semantic/src/types/call/arguments.rs
  • with_self — line 206

[carljm]

Thanks for the report, and suggested fix! The proper fix here is to fix #2799, but in this case the narrowly-targeted fix in the old constraint solver seems pretty reasonable. Put up the fix (with a few additional tests, and adjusted comment) in astral-sh/ruff#24698.