[ty] fix deferred name loading in PEP695 generic classes/functions (#19888)

## Summary

For PEP 695 generic functions and classes, there is an extra "type
params scope" (a child of the outer scope, and wrapping the body scope)
in which the type parameters are defined; class bases and function
parameter/return annotations are resolved in that type-params scope.

This PR fixes some longstanding bugs in how we resolve name loads from
inside these PEP 695 type parameter scopes, and also defers type
inference of PEP 695 typevar bounds/constraints/default, so we can
handle cycles without panicking.

We were previously treating these type-param scopes as lazy nested
scopes, which is wrong. In fact they are eager nested scopes; the class
`C` here inherits `int`, not `str`, and previously we got that wrong:

```py
Base = int

class C[T](Base): ...

Base = str
```

But certain syntactic positions within type param scopes (typevar
bounds/constraints/defaults) are lazy at runtime, and we should use
deferred name resolution for them. This also means they can have cycles;
in order to handle that without panicking in type inference, we need to
actually defer their type inference until after we have constructed the
`TypeVarInstance`.

PEP 695 does specify that typevar bounds and constraints cannot be
generic, and that typevar defaults can only reference prior typevars,
not later ones. This reduces the scope of (valid from the type-system
perspective) cycles somewhat, although cycles are still possible (e.g.
`class C[T: list[C]]`). And this is a type-system-only restriction; from
the runtime perspective an "invalid" case like `class C[T: T]` actually
works fine.

I debated whether to implement the PEP 695 restrictions as a way to
avoid some cycles up-front, but I ended up deciding against that; I'd
rather model the runtime name-resolution semantics accurately, and
implement the PEP 695 restrictions as a separate diagnostic on top.
(This PR doesn't yet implement those diagnostics, thus some `# TODO:
error` in the added tests.)

Introducing the possibility of cyclic typevars made typevar display
potentially stack overflow. For now I've handled this by simply removing
typevar details (bounds/constraints/default) from typevar display. This
impacts display of two kinds of types. If you `reveal_type(T)` on an
unbound `T` you now get just `typing.TypeVar` instead of
`typing.TypeVar("T", ...)` where `...` is the bound/constraints/default.
This matches pyright and mypy; pyrefly uses `type[TypeVar[T]]` which
seems a bit confusing, but does include the name. (We could easily
include the name without cycle issues, if there's a syntax we like for
that.)

It also means that displaying a generic function type like `def f[T:
int](x: T) -> T: ...` now displays as `f[T](x: T) -> T` instead of `f[T:
int](x: T) -> T`. This matches pyright and pyrefly; mypy does include
bound/constraints/defaults of typevars in function/callable type
display. If we wanted to add this, we would either need to thread a
visitor through all the type display code, or add a `decycle` type
transformation that replaced recursive reoccurrence of a type with a
marker.

## Test Plan

Added mdtests and modified existing tests to improve their correctness.

After this PR, there's only a single remaining py-fuzzer seed in the
0-500 range that panics! (Before this PR, there were 10; the fuzzer
likes to generate cyclic PEP 695 syntax.)

## Ecosystem report

It's all just the changes to `TypeVar` display.

Author: carljm

crates/ty_ide/src/hover.rs

@@ -728,11 +728,11 @@ mod tests {
         );
 
         // TODO: This should render T@Alias once we create GenericContexts for type alias scopes.
-        assert_snapshot!(test.hover(), @r#"
-        typing.TypeVar("T", bound=int, default=bool)
+        assert_snapshot!(test.hover(), @r###"
+        typing.TypeVar
         ---------------------------------------------
         ```python
-        typing.TypeVar("T", bound=int, default=bool)
+        typing.TypeVar
         ```
         ---------------------------------------------
         info[hover]: Hovered content is
@@ -743,7 +743,7 @@ mod tests {
           |                                              |
           |                                              source
           |
-        "#);
+        "###);
     }
 
     #[test]

crates/ty_ide/src/inlay_hints.rs

@@ -793,17 +793,17 @@ mod tests {
             identity('hello')",
         );
 
-        assert_snapshot!(test.inlay_hints(), @r#"
+        assert_snapshot!(test.inlay_hints(), @r###"
         from typing import TypeVar, Generic
 
-        T[: typing.TypeVar("T")] = TypeVar([name=]'T')
+        T[: typing.TypeVar] = TypeVar([name=]'T')
 
         def identity(x: T) -> T:
             return x
 
         identity([x=]42)
         identity([x=]'hello')
-        "#);
+        "###);
     }
 
     #[test]

crates/ty_python_semantic/resources/corpus/cyclic_pep695_typevars.py

@@ -0,0 +1,5 @@
+def name_1[name_0: name_0](name_2: name_0):
+    try:
+        pass
+    except name_2:
+        pass

crates/ty_python_semantic/resources/corpus/except_handler_with_Any_bound_typevar.py

@@ -1,9 +1,3 @@
-def name_1[name_0: name_0](name_2: name_0):
-    try:
-        pass
-    except name_2:
-        pass
-
 from typing import Any
 
 def name_2[T: Any](x: T):

crates/ty_python_semantic/resources/mdtest/generics/legacy/variables.md

@@ -20,7 +20,7 @@ from typing import TypeVar
 
 T = TypeVar("T")
 reveal_type(type(T))  # revealed: <class 'TypeVar'>
-reveal_type(T)  # revealed: typing.TypeVar("T")
+reveal_type(T)  # revealed: typing.TypeVar
 reveal_type(T.__name__)  # revealed: Literal["T"]
 ```
 
@@ -80,7 +80,7 @@ from typing import TypeVar
 
 T = TypeVar("T", default=int)
 reveal_type(type(T))  # revealed: <class 'TypeVar'>
-reveal_type(T)  # revealed: typing.TypeVar("T", default=int)
+reveal_type(T)  # revealed: typing.TypeVar
 reveal_type(T.__default__)  # revealed: int
 reveal_type(T.__bound__)  # revealed: None
 reveal_type(T.__constraints__)  # revealed: tuple[()]
@@ -116,7 +116,7 @@ from typing import TypeVar
 
 T = TypeVar("T", bound=int)
 reveal_type(type(T))  # revealed: <class 'TypeVar'>
-reveal_type(T)  # revealed: typing.TypeVar("T", bound=int)
+reveal_type(T)  # revealed: typing.TypeVar
 reveal_type(T.__bound__)  # revealed: int
 reveal_type(T.__constraints__)  # revealed: tuple[()]
 
@@ -131,7 +131,7 @@ from typing import TypeVar
 
 T = TypeVar("T", int, str)
 reveal_type(type(T))  # revealed: <class 'TypeVar'>
-reveal_type(T)  # revealed: typing.TypeVar("T", int, str)
+reveal_type(T)  # revealed: typing.TypeVar
 reveal_type(T.__constraints__)  # revealed: tuple[int, str]
 
 S = TypeVar("S")

crates/ty_python_semantic/resources/mdtest/generics/pep695/classes.md

@@ -391,6 +391,7 @@ wrong_innards: C[int] = C("five", 1)
 ### Some `__init__` overloads only apply to certain specializations
 
 ```py
+from __future__ import annotations
 from typing import overload
 
 class C[T]:
@@ -541,6 +542,23 @@ class WithOverloadedMethod[T]:
 reveal_type(WithOverloadedMethod[int].method)
 ```
 
+## Scoping of typevars
+
+### No back-references
+
+Typevar bounds/constraints/defaults are lazy, but cannot refer to later typevars:
+
+```py
+# TODO error
+class C[S: T, T]:
+    pass
+
+class D[S: X]:
+    pass
+
+X = int
+```
+
 ## Cyclic class definitions
 
 ### F-bounded quantification
@@ -591,7 +609,7 @@ class Derived[T](list[Derived[T]]): ...
 
 Inheritance that would result in a cyclic MRO is detected as an error.
 
-```py
+```pyi
 # error: [cyclic-class-definition]
 class C[T](C): ...
 

crates/ty_python_semantic/resources/mdtest/generics/pep695/variables.md

@@ -2,7 +2,7 @@
 
 ```toml
 [environment]
-python-version = "3.12"
+python-version = "3.13"
 ```
 
 [PEP 695] and Python 3.12 introduced new, more ergonomic syntax for type variables.
@@ -17,7 +17,7 @@ instances of `typing.TypeVar`, just like legacy type variables.
 ```py
 def f[T]():
     reveal_type(type(T))  # revealed: <class 'TypeVar'>
-    reveal_type(T)  # revealed: typing.TypeVar("T")
+    reveal_type(T)  # revealed: typing.TypeVar
     reveal_type(T.__name__)  # revealed: Literal["T"]
 ```
 
@@ -33,7 +33,7 @@ python-version = "3.13"
 ```py
 def f[T = int]():
     reveal_type(type(T))  # revealed: <class 'TypeVar'>
-    reveal_type(T)  # revealed: typing.TypeVar("T", default=int)
+    reveal_type(T)  # revealed: typing.TypeVar
     reveal_type(T.__default__)  # revealed: int
     reveal_type(T.__bound__)  # revealed: None
     reveal_type(T.__constraints__)  # revealed: tuple[()]
@@ -66,7 +66,7 @@ class Invalid[S = T]: ...
 ```py
 def f[T: int]():
     reveal_type(type(T))  # revealed: <class 'TypeVar'>
-    reveal_type(T)  # revealed: typing.TypeVar("T", bound=int)
+    reveal_type(T)  # revealed: typing.TypeVar
     reveal_type(T.__bound__)  # revealed: int
     reveal_type(T.__constraints__)  # revealed: tuple[()]
 
@@ -79,7 +79,7 @@ def g[S]():
 ```py
 def f[T: (int, str)]():
     reveal_type(type(T))  # revealed: <class 'TypeVar'>
-    reveal_type(T)  # revealed: typing.TypeVar("T", int, str)
+    reveal_type(T)  # revealed: typing.TypeVar
     reveal_type(T.__constraints__)  # revealed: tuple[int, str]
     reveal_type(T.__bound__)  # revealed: None
 
@@ -745,4 +745,88 @@ def constrained[T: (int, str)](x: T):
     reveal_type(type(x))  # revealed: type[int] | type[str]
 ```
 
+## Cycles
+
+### Bounds and constraints
+
+A typevar's bounds and constraints cannot be generic, cyclic or otherwise:
+
+```py
+from typing import Any
+
+# TODO: error
+def f[S, T: list[S]](x: S, y: T) -> S | T:
+    return x or y
+
+# TODO: error
+class C[S, T: list[S]]:
+    x: S
+    y: T
+
+reveal_type(C[int, list[Any]]().x)  # revealed: int
+reveal_type(C[int, list[Any]]().y)  # revealed: list[Any]
+
+# TODO: error
+def g[T: list[T]](x: T) -> T:
+    return x
+
+# TODO: error
+class D[T: list[T]]:
+    x: T
+
+reveal_type(D[list[Any]]().x)  # revealed: list[Any]
+
+# TODO: error
+def h[S, T: (list[S], str)](x: S, y: T) -> S | T:
+    return x or y
+
+# TODO: error
+class E[S, T: (list[S], str)]:
+    x: S
+    y: T
+
+reveal_type(E[int, str]().x)  # revealed: int
+reveal_type(E[int, str]().y)  # revealed: str
+
+# TODO: error
+def i[T: (list[T], str)](x: T) -> T:
+    return x
+
+# TODO: error
+class F[T: (list[T], str)]:
+    x: T
+
+reveal_type(F[list[Any]]().x)  # revealed: list[Any]
+```
+
+However, they are lazily evaluated and can cyclically refer to their own type:
+
+```py
+class G[T: list[G]]:
+    x: T
+
+reveal_type(G[list[G]]().x)  # revealed: list[G[Unknown]]
+```
+
+### Defaults
+
+Defaults can be generic, but can only refer to earlier typevars:
+
+```py
+class C[T, U = T]:
+    x: T
+    y: U
+
+reveal_type(C[int, str]().x)  # revealed: int
+reveal_type(C[int, str]().y)  # revealed: str
+reveal_type(C[int]().x)  # revealed: int
+reveal_type(C[int]().y)  # revealed: int
+
+# TODO: error
+class D[T = T]:
+    x: T
+
+reveal_type(D().x)  # revealed: T@D
+```
+
 [pep 695]: https://peps.python.org/pep-0695/

crates/ty_python_semantic/resources/mdtest/protocols.md

@@ -2051,6 +2051,7 @@ python-version = "3.12"
 ```
 
 ```py
+from __future__ import annotations
 from typing import cast, Protocol
 
 class Iterator[T](Protocol):

crates/ty_python_semantic/resources/mdtest/scopes/eager.md

@@ -410,4 +410,47 @@ reveal_type(C.var)  # revealed: int | str
 x = str
 ```
 
+### Annotation scopes
+
+```toml
+[environment]
+python-version = "3.12"
+```
+
+#### Type alias annotation scopes are lazy
+
+```py
+type Foo = Bar
+
+class Bar:
+    pass
+
+def _(x: Foo):
+    if isinstance(x, Bar):
+        reveal_type(x)  # revealed: Bar
+    else:
+        reveal_type(x)  # revealed: Never
+```
+
+#### Type-param scopes are eager, but bounds/constraints are deferred
+
+```py
+# error: [unresolved-reference]
+class D[T](Bar):
+    pass
+
+class E[T: Bar]:
+    pass
+
+# error: [unresolved-reference]
+def g[T](x: Bar):
+    pass
+
+def h[T: Bar](x: T):
+    pass
+
+class Bar:
+    pass
+```
+
 [generators]: https://docs.python.org/3/reference/expressions.html#generator-expressions