[ty] linear variance inference for PEP-695 type parameters

[ericmarkmartin]

Summary

Implement linear-time variance inference for type variables (astral-sh/ty#488).

Inspired by Martin Huschenbett's PyCon 2025 Talk.

Test Plan

update tests
add new test case for mutually recursive classes

[github-actions]

mypy_primer results

No ecosystem changes detected ✅
No memory usage changes detected ✅

[dcreager]

Some initial comments

[carljm]

This is looking good! I think we can leave a lot of stuff as TODOs for follow-up PRs, just want to make sure we clearly record all the TODOs. I would really like to have more thorough tests here.

Regarding the failing test, I suspect what is happening is that we now see that type as bivariant in T (because T is unused), and that means that every specialization of C is equivalent to every other specialization, so the __init__ overloads no longer discriminate the instantiation argument, the overloads just all match, resulting in Unknown.

If I change the class like this (to make it covariant in T), the test passes:

class C[T]:
    @overload
    def __init__(self: C[str], x: str) -> None: ...
    @overload
    def __init__(self: C[bytes], x: bytes) -> None: ...
    @overload
    def __init__(self: C[int], x: bytes) -> None: ...
    @overload
    def __init__(self, x: int) -> None: ...
    def __init__(self, x: str | bytes | int) -> None:
        self.x = x

    def method(self) -> T:
        return self.x

[carljm]

I'm kind of shocked that there is zero ecosystem impact reported here? Is PEP 695 uptake still that low? Or maybe because we previously assumed "invariant" for PEP 695 typevars, this doesn't actually result in any new diagnostics? (Also maybe due to some issues pointed out above, e.g. the __init__ thing, in practice we are still inferring ~all PEP 695 typevars in the ecosystem as invariant?)

[github-actions]

Diagnostic diff on typing conformance tests

Changes were detected when running ty on typing conformance tests

--- old-output.txt	2025-08-20 00:39:59.104775161 +0000
+++ new-output.txt	2025-08-20 00:40:01.565795171 +0000
@@ -580,21 +580,15 @@
 generics_variance_inference.py:19:26: error[invalid-return-type] Function always implicitly returns `None`, which is not assignable to return type `T3@ClassA`
 generics_variance_inference.py:24:5: error[invalid-assignment] Object of type `ClassA[int | float, int, int]` is not assignable to `ClassA[int, int, int]`
 generics_variance_inference.py:25:5: error[invalid-assignment] Object of type `ClassA[int | float, int, int]` is not assignable to `ClassA[int | float, int | float, int]`
-generics_variance_inference.py:26:5: error[invalid-assignment] Object of type `ClassA[int | float, int, int]` is not assignable to `ClassA[int | float, int, int | float]`
 generics_variance_inference.py:28:5: error[invalid-assignment] Object of type `ClassA[int, int | float, int | float]` is not assignable to `ClassA[int, int, int]`
-generics_variance_inference.py:29:5: error[invalid-assignment] Object of type `ClassA[int, int | float, int | float]` is not assignable to `ClassA[int, int, int | float]`
 generics_variance_inference.py:33:42: error[invalid-return-type] Function always implicitly returns `None`, which is not assignable to return type `T@ShouldBeCovariant1`
 generics_variance_inference.py:36:27: error[invalid-return-type] Function always implicitly returns `None`, which is not assignable to return type `Iterator[T@ShouldBeCovariant1]`
-generics_variance_inference.py:40:1: error[invalid-assignment] Object of type `ShouldBeCovariant1[int]` is not assignable to `ShouldBeCovariant1[int | float]`
 generics_variance_inference.py:41:1: error[invalid-assignment] Object of type `ShouldBeCovariant1[int | float]` is not assignable to `ShouldBeCovariant1[int]`
-generics_variance_inference.py:48:1: error[invalid-assignment] Object of type `ShouldBeCovariant2[int]` is not assignable to `ShouldBeCovariant2[int | float]`
 generics_variance_inference.py:49:1: error[invalid-assignment] Object of type `ShouldBeCovariant2[int | float]` is not assignable to `ShouldBeCovariant2[int]`
 generics_variance_inference.py:53:26: error[invalid-return-type] Function always implicitly returns `None`, which is not assignable to return type `ShouldBeCovariant2[T@ShouldBeCovariant3]`
-generics_variance_inference.py:57:1: error[invalid-assignment] Object of type `ShouldBeCovariant3[int]` is not assignable to `ShouldBeCovariant3[int | float]`
 generics_variance_inference.py:58:1: error[invalid-assignment] Object of type `ShouldBeCovariant3[int | float]` is not assignable to `ShouldBeCovariant3[int]`
 generics_variance_inference.py:66:1: error[invalid-assignment] Object of type `ShouldBeCovariant4[int]` is not assignable to `ShouldBeCovariant4[int | float]`
 generics_variance_inference.py:67:1: error[invalid-assignment] Object of type `ShouldBeCovariant4[int | float]` is not assignable to `ShouldBeCovariant4[int]`
-generics_variance_inference.py:79:1: error[invalid-assignment] Object of type `ShouldBeCovariant5[int]` is not assignable to `ShouldBeCovariant5[int | float]`
 generics_variance_inference.py:80:1: error[invalid-assignment] Object of type `ShouldBeCovariant5[int | float]` is not assignable to `ShouldBeCovariant5[int]`
 generics_variance_inference.py:96:1: error[invalid-assignment] Object of type `ShouldBeInvariant1[int]` is not assignable to `ShouldBeInvariant1[int | float]`
 generics_variance_inference.py:97:1: error[invalid-assignment] Object of type `ShouldBeInvariant1[int | float]` is not assignable to `ShouldBeInvariant1[int]`
@@ -607,12 +601,9 @@
 generics_variance_inference.py:130:1: error[invalid-assignment] Object of type `ShouldBeInvariant4[int]` is not assignable to `ShouldBeInvariant4[int | float]`
 generics_variance_inference.py:138:1: error[invalid-assignment] Object of type `ShouldBeInvariant5[int]` is not assignable to `ShouldBeInvariant5[int | float]`
 generics_variance_inference.py:149:1: error[invalid-assignment] Object of type `ShouldBeContravariant1[int]` is not assignable to `ShouldBeContravariant1[int | float]`
-generics_variance_inference.py:150:1: error[invalid-assignment] Object of type `ShouldBeContravariant1[int | float]` is not assignable to `ShouldBeContravariant1[int]`
 generics_variance_inference.py:169:1: error[invalid-assignment] Object of type `ShouldBeInvariant6[int | float]` is not assignable to `ShouldBeInvariant6[int]`
 generics_variance_inference.py:170:1: error[invalid-assignment] Object of type `ShouldBeInvariant6[int]` is not assignable to `ShouldBeInvariant6[int | float]`
 generics_variance_inference.py:181:1: error[invalid-assignment] Object of type `ShouldBeCovariant6[int | float]` is not assignable to `ShouldBeCovariant6[int]`
-generics_variance_inference.py:182:1: error[invalid-assignment] Object of type `ShouldBeCovariant6[int]` is not assignable to `ShouldBeCovariant6[int | float]`
-generics_variance_inference.py:193:1: error[invalid-assignment] Object of type `ShouldBeContravariant2[int | float]` is not assignable to `ShouldBeContravariant2[int]`
 generics_variance_inference.py:194:1: error[invalid-assignment] Object of type `ShouldBeContravariant2[int]` is not assignable to `ShouldBeContravariant2[int | float]`
 literals_interactions.py:15:5: error[index-out-of-bounds] Index 5 is out of bounds for tuple `tuple[int, str, list[bool]]` with length 3
 literals_interactions.py:16:5: error[index-out-of-bounds] Index -5 is out of bounds for tuple `tuple[int, str, list[bool]]` with length 3
@@ -859,5 +850,5 @@
 typeddicts_operations.py:60:1: error[type-assertion-failure] Argument does not have asserted type `str | None`
 typeddicts_type_consistency.py:101:1: error[invalid-assignment] Object of type `Unknown | None` is not assignable to `str`
 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 860 diagnostics
+Found 851 diagnostics
 WARN A fatal error occurred while checking some files. Not all project files were analyzed. See the diagnostics list above for details.

[carljm]

Didn't quite get the whole way through reviewing this, but to me it's looking pretty much land-ready so far with some minor adjustments. I would probably just make the adjustments myself and land it now, but I'm out of time for today. Will try to get back to it as soon as I can; would love to get it landed before it accumulates more conflicts.

[carljm]

Looks like there are also a couple clippy / cargo doc issues we need to address, and then we also need to review the conformance-suite diff for correctness.

[carljm]

Finished my code review, and I reviewed the conformance suite impact. Mostly the result is good (we stop emitting wrong diagnostics where previously we assumed invariance and now we infer correct variance.)

On these lines, which are testing variance in derived classes, we now miss all the errors; it seems like we are inferring all these as bivariant now somehow? Will explore this a bit more.

ETA: Oh, I think this is the issue I mentioned inline in my code review, where when we encounter another generic class while inferring variance, we are ignoring explicit variance.

[carljm]

With the fix I just pushed, the conformance suite changes all look correct now.

[carljm]

Ok, I pushed some things here, but didn't address all the comments yet. Out of time for now. I don't have any more changes locally, so @ericmarkmartin if you have time/inclination, feel free to push changes addressing additional comments! I'll come back to this next week (but I'll comment before I make any further changes.)

[ericmarkmartin]

I think I've addressed the last few comments that you didn't resolve yourself, thanks!

I tried to push out the code quickly the other night because I'm away for a little bit now and didn't want to delay the PR more, and I appreciate the thorough review. Fortunately the WiFi up here is actually quite good 😃.

I'm noticing that with the bound typevars, you write typevar and not type_var. Would you like me to update my code likewise?

[carljm]

I'm noticing that with the bound typevars, you write typevar and not type_var. Would you like me to update my code likewise?

I don't have strong feelings between the two, but consistency is good. Maybe a mild preference for avoiding unnecessary underscores.

[carljm]

I'm about to rebase this and make some more updates to it, hopefully resulting in a merge. (Just commenting in advance so as to avoid simultaneous duplication of work.)

[carljm]

Merged! Thank you @ericmarkmartin for all your excellent work here