[ty] Understand legacy and PEP 695 ParamSpec (#21139)

## Summary

This PR adds support for understanding the legacy definition and PEP 695
definition for `ParamSpec`.

This is still very initial and doesn't really implement any of the
semantics.

Part of astral-sh/ty#157

## Test Plan

Add mdtest cases.

## Ecosystem analysis

Most of the diagnostics in `starlette` are due to the fact that ty now
understands `ParamSpec` is not a `Todo` type, so the assignability check
fails. The code looks something like:

```py
class _MiddlewareFactory(Protocol[P]):
    def __call__(self, app: ASGIApp, /, *args: P.args, **kwargs: P.kwargs) -> ASGIApp: ...  # pragma: no cover

class Middleware:
    def __init__(
        self,
        cls: _MiddlewareFactory[P],
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> None:
        self.cls = cls
        self.args = args
        self.kwargs = kwargs

# ty complains that `ServerErrorMiddleware` is not assignable to `_MiddlewareFactory[P]`
Middleware(ServerErrorMiddleware, handler=error_handler, debug=debug)
```

There are multiple diagnostics where there's an attribute access on the
`Wrapped` object of `functools` which Pyright also raises:
```py
from functools import wraps

def my_decorator(f):
    @wraps(f)
    def wrapper(*args, **kwds):
        return f(*args, **kwds)

	# Pyright: Cannot access attribute "__signature__" for class "_Wrapped[..., Unknown, ..., Unknown]"
      Attribute "__signature__" is unknown [reportAttributeAccessIssue]
	# ty: Object of type `_Wrapped[Unknown, Unknown, Unknown, Unknown]` has no attribute `__signature__` [unresolved-attribute]
    wrapper.__signature__
    return wrapper
```

There are additional diagnostics that is due to the assignability checks
failing because ty now infers the `ParamSpec` instead of using the
`Todo` type which would always succeed. This results in a few
`no-matching-overload` diagnostics because the assignability checks
fail.

There are a few diagnostics related to
astral-sh/ty#491 where there's a variable
which is either a bound method or a variable that's annotated with
`Callable` that doesn't contain the instance as the first parameter.

Another set of (valid) diagnostics are where the code hasn't provided
all the type variables. ty is now raising diagnostics for these because
we include `ParamSpec` type variable in the signature. For example,
`staticmethod[Any]` which contains two type variables.

Author: dhruvmanila

crates/ty/docs/rules.md

@@ -276,10 +276,20 @@ mod tests {
             "#,
         );
 
-        // TODO: Goto type definition currently doesn't work for type param specs
-        // because the inference doesn't support them yet.
-        // This snapshot should show a single target pointing to `T`
-        assert_snapshot!(test.goto_type_definition(), @"No type definitions found");
+        assert_snapshot!(test.goto_type_definition(), @r"
+        info[goto-type-definition]: Type definition
+         --> main.py:2:14
+          |
+        2 | type Alias[**P = [int, str]] = Callable[P, int]
+          |              ^
+          |
+        info: Source
+         --> main.py:2:41
+          |
+        2 | type Alias[**P = [int, str]] = Callable[P, int]
+          |                                         ^
+          |
+        ");
     }
 
     #[test]

crates/ty_ide/src/goto_type_definition.rs

@@ -1633,11 +1633,12 @@ def ab(a: int, *, c: int):
             "#,
         );
 
+        // TODO: This should be `P@Alias (<variance>)`
         assert_snapshot!(test.hover(), @r"
-        @Todo
+        typing.ParamSpec
         ---------------------------------------------
         ```python
-        @Todo
+        typing.ParamSpec
         ```
         ---------------------------------------------
         info[hover]: Hovered content is

crates/ty_ide/src/hover.rs

@@ -307,8 +307,9 @@ Using a `ParamSpec` in a `Callable` annotation:
 from typing_extensions import Callable
 
 def _[**P1](c: Callable[P1, int]):
-    reveal_type(P1.args)  # revealed: @Todo(ParamSpec)
-    reveal_type(P1.kwargs)  # revealed: @Todo(ParamSpec)
+    # TODO: Should reveal `ParamSpecArgs` and `ParamSpecKwargs`
+    reveal_type(P1.args)  # revealed: @Todo(ParamSpecArgs / ParamSpecKwargs)
+    reveal_type(P1.kwargs)  # revealed: @Todo(ParamSpecArgs / ParamSpecKwargs)
 
     # TODO: Signature should be (**P1) -> int
     reveal_type(c)  # revealed: (...) -> int

crates/ty_python_semantic/resources/mdtest/annotations/callable.md

@@ -21,8 +21,9 @@ def f(*args: Unpack[Ts]) -> tuple[Unpack[Ts]]:
 
 def g() -> TypeGuard[int]: ...
 def i(callback: Callable[Concatenate[int, P], R_co], *args: P.args, **kwargs: P.kwargs) -> R_co:
-    reveal_type(args)  # revealed: tuple[@Todo(Support for `typing.ParamSpec`), ...]
-    reveal_type(kwargs)  # revealed: dict[str, @Todo(Support for `typing.ParamSpec`)]
+    # TODO: Should reveal a type representing `P.args` and `P.kwargs`
+    reveal_type(args)  # revealed: tuple[@Todo(ParamSpecArgs / ParamSpecKwargs), ...]
+    reveal_type(kwargs)  # revealed: dict[str, @Todo(ParamSpecArgs / ParamSpecKwargs)]
     return callback(42, *args, **kwargs)
 
 class Foo:

crates/ty_python_semantic/resources/mdtest/annotations/unsupported_special_forms.md

@@ -26,9 +26,12 @@ reveal_type(generic_context(SingleTypevar))
 # revealed: tuple[T@MultipleTypevars, S@MultipleTypevars]
 reveal_type(generic_context(MultipleTypevars))
 
-# TODO: support `ParamSpec`/`TypeVarTuple` properly (these should not reveal `None`)
-reveal_type(generic_context(SingleParamSpec))  # revealed: None
-reveal_type(generic_context(TypeVarAndParamSpec))  # revealed: None
+# revealed: tuple[P@SingleParamSpec]
+reveal_type(generic_context(SingleParamSpec))
+# revealed: tuple[P@TypeVarAndParamSpec, T@TypeVarAndParamSpec]
+reveal_type(generic_context(TypeVarAndParamSpec))
+
+# TODO: support `TypeVarTuple` properly (these should not reveal `None`)
 reveal_type(generic_context(SingleTypeVarTuple))  # revealed: None
 reveal_type(generic_context(TypeVarAndTypeVarTuple))  # revealed: None
 ```

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

@@ -0,0 +1,159 @@
+# `ParamSpec`
+
+## Definition
+
+### Valid
+
+```py
+from typing import ParamSpec
+
+P = ParamSpec("P")
+reveal_type(type(P))  # revealed: <class 'ParamSpec'>
+reveal_type(P)  # revealed: typing.ParamSpec
+reveal_type(P.__name__)  # revealed: Literal["P"]
+```
+
+The paramspec name can also be provided as a keyword argument:
+
+```py
+from typing import ParamSpec
+
+P = ParamSpec(name="P")
+reveal_type(P.__name__)  # revealed: Literal["P"]
+```
+
+### Must be directly assigned to a variable
+
+```py
+from typing import ParamSpec
+
+P = ParamSpec("P")
+# error: [invalid-paramspec]
+P1: ParamSpec = ParamSpec("P1")
+
+# error: [invalid-paramspec]
+tuple_with_typevar = ("foo", ParamSpec("W"))
+reveal_type(tuple_with_typevar[1])  # revealed: ParamSpec
+```
+
+```py
+from typing_extensions import ParamSpec
+
+T = ParamSpec("T")
+# error: [invalid-paramspec]
+P1: ParamSpec = ParamSpec("P1")
+
+# error: [invalid-paramspec]
+tuple_with_typevar = ("foo", ParamSpec("P2"))
+reveal_type(tuple_with_typevar[1])  # revealed: ParamSpec
+```
+
+### `ParamSpec` parameter must match variable name
+
+```py
+from typing import ParamSpec
+
+P1 = ParamSpec("P1")
+
+# error: [invalid-paramspec]
+P2 = ParamSpec("P3")
+```
+
+### Accepts only a single `name` argument
+
+> The runtime should accept bounds and covariant and contravariant arguments in the declaration just
+> as typing.TypeVar does, but for now we will defer the standardization of the semantics of those
+> options to a later PEP.
+
+```py
+from typing import ParamSpec
+
+# error: [invalid-paramspec]
+P1 = ParamSpec("P1", bound=int)
+# error: [invalid-paramspec]
+P2 = ParamSpec("P2", int, str)
+# error: [invalid-paramspec]
+P3 = ParamSpec("P3", covariant=True)
+# error: [invalid-paramspec]
+P4 = ParamSpec("P4", contravariant=True)
+```
+
+### Defaults
+
+```toml
+[environment]
+python-version = "3.13"
+```
+
+The default value for a `ParamSpec` can be either a list of types, `...`, or another `ParamSpec`.
+
+```py
+from typing import ParamSpec
+
+P1 = ParamSpec("P1", default=[int, str])
+P2 = ParamSpec("P2", default=...)
+P3 = ParamSpec("P3", default=P2)
+```
+
+Other values are invalid.
+
+```py
+# error: [invalid-paramspec]
+P4 = ParamSpec("P4", default=int)
+```
+
+### PEP 695
+
+```toml
+[environment]
+python-version = "3.12"
+```
+
+#### Valid
+
+```py
+def foo1[**P]() -> None:
+    reveal_type(P)  # revealed: typing.ParamSpec
+
+def foo2[**P = ...]() -> None:
+    reveal_type(P)  # revealed: typing.ParamSpec
+
+def foo3[**P = [int, str]]() -> None:
+    reveal_type(P)  # revealed: typing.ParamSpec
+
+def foo4[**P, **Q = P]():
+    reveal_type(P)  # revealed: typing.ParamSpec
+    reveal_type(Q)  # revealed: typing.ParamSpec
+```
+
+#### Invalid
+
+ParamSpec, when defined using the new syntax, does not allow defining bounds or constraints.
+
+This results in a lot of syntax errors mainly because the AST doesn't accept them in this position.
+The parser could do a better job in recovering from these errors.
+
+<!-- blacken-docs:off -->
+
+```py
+# error: [invalid-syntax]
+# error: [invalid-syntax]
+# error: [invalid-syntax]
+# error: [invalid-syntax]
+# error: [invalid-syntax]
+# error: [invalid-syntax]
+def foo[**P: int]() -> None:
+    # error: [invalid-syntax]
+    # error: [invalid-syntax]
+    pass
+```
+
+<!-- blacken-docs:on -->
+
+#### Invalid default
+
+```py
+# error: [invalid-paramspec]
+def foo[**P = int]() -> None:
+    pass
+```

crates/ty_python_semantic/resources/mdtest/paramspec.md

@@ -1171,9 +1171,7 @@ class EggsLegacy(Generic[T, P]): ...
 static_assert(not is_assignable_to(Spam, Callable[..., Any]))
 static_assert(not is_assignable_to(SpamLegacy, Callable[..., Any]))
 static_assert(not is_assignable_to(Eggs, Callable[..., Any]))
-
-# TODO: should pass
-static_assert(not is_assignable_to(EggsLegacy, Callable[..., Any]))  # error: [static-assert-error]
+static_assert(not is_assignable_to(EggsLegacy, Callable[..., Any]))
 ```
 
 ### Classes with `__call__` as attribute

crates/ty_python_semantic/resources/mdtest/type_properties/is_assignable_to.md

@@ -4358,6 +4358,13 @@ impl<'db> Type<'db> {
                     .into()
             }
 
+            Type::KnownInstance(KnownInstanceType::TypeVar(typevar))
+                if typevar.kind(db).is_paramspec()
+                    && matches!(name.as_str(), "args" | "kwargs") =>
+            {
+                Place::bound(todo_type!("ParamSpecArgs / ParamSpecKwargs")).into()
+            }
+
             Type::NominalInstance(..)
             | Type::ProtocolInstance(..)
             | Type::BooleanLiteral(..)
@@ -7024,7 +7031,7 @@ impl<'db> Type<'db> {
             Type::TypeVar(bound_typevar) => {
                 if matches!(
                     bound_typevar.typevar(db).kind(db),
-                    TypeVarKind::Legacy | TypeVarKind::TypingSelf
+                    TypeVarKind::Legacy | TypeVarKind::TypingSelf | TypeVarKind::ParamSpec
                 ) && binding_context.is_none_or(|binding_context| {
                     bound_typevar.binding_context(db) == BindingContext::Definition(binding_context)
                 }) {
@@ -7743,6 +7750,9 @@ impl<'db> KnownInstanceType<'db> {
     fn class(self, db: &'db dyn Db) -> KnownClass {
         match self {
             Self::SubscriptedProtocol(_) | Self::SubscriptedGeneric(_) => KnownClass::SpecialForm,
+            Self::TypeVar(typevar_instance) if typevar_instance.kind(db).is_paramspec() => {
+                KnownClass::ParamSpec
+            }
             Self::TypeVar(_) => KnownClass::TypeVar,
             Self::TypeAliasType(TypeAliasType::PEP695(alias)) if alias.is_specialized(db) => {
                 KnownClass::GenericAlias
@@ -7808,7 +7818,13 @@ impl<'db> KnownInstanceType<'db> {
                     // This is a legacy `TypeVar` _outside_ of any generic class or function, so we render
                     // it as an instance of `typing.TypeVar`. Inside of a generic class or function, we'll
                     // have a `Type::TypeVar(_)`, which is rendered as the typevar's name.
-                    KnownInstanceType::TypeVar(_) => f.write_str("typing.TypeVar"),
+                    KnownInstanceType::TypeVar(typevar_instance) => {
+                        if typevar_instance.kind(self.db).is_paramspec() {
+                            f.write_str("typing.ParamSpec")
+                        } else {
+                            f.write_str("typing.TypeVar")
+                        }
+                    }
                     KnownInstanceType::Deprecated(_) => f.write_str("warnings.deprecated"),
                     KnownInstanceType::Field(field) => {
                         f.write_str("dataclasses.Field")?;
@@ -7864,9 +7880,6 @@ pub enum DynamicType<'db> {
     ///
     /// This variant should be created with the `todo_type!` macro.
     Todo(TodoType),
-    /// A special Todo-variant for PEP-695 `ParamSpec` types. A temporary variant to detect and special-
-    /// case the handling of these types in `Callable` annotations.
-    TodoPEP695ParamSpec,
     /// A special Todo-variant for type aliases declared using `typing.TypeAlias`.
     /// A temporary variant to detect and special-case the handling of these aliases in autocomplete suggestions.
     TodoTypeAlias,
@@ -7894,13 +7907,6 @@ impl std::fmt::Display for DynamicType<'_> {
             // `DynamicType::Todo`'s display should be explicit that is not a valid display of
             // any other type
             DynamicType::Todo(todo) => write!(f, "@Todo{todo}"),
-            DynamicType::TodoPEP695ParamSpec => {
-                if cfg!(debug_assertions) {
-                    f.write_str("@Todo(ParamSpec)")
-                } else {
-                    f.write_str("@Todo")
-                }
-            }
             DynamicType::TodoUnpack => {
                 if cfg!(debug_assertions) {
                     f.write_str("@Todo(typing.Unpack)")
@@ -8239,12 +8245,20 @@ pub enum TypeVarKind {
     Pep695,
     /// `typing.Self`
     TypingSelf,
+    /// `P = ParamSpec("P")`
+    ParamSpec,
+    /// `def foo[**P]() -> None: ...`
+    Pep695ParamSpec,
 }
 
 impl TypeVarKind {
     const fn is_self(self) -> bool {
         matches!(self, Self::TypingSelf)
     }
+
+    const fn is_paramspec(self) -> bool {
+        matches!(self, Self::ParamSpec | Self::Pep695ParamSpec)
+    }
 }
 
 /// The identity of a type variable.
@@ -8597,6 +8611,15 @@ impl<'db> TypeVarInstance<'db> {
                 let expr = &call_expr.arguments.find_keyword("default")?.value;
                 Some(definition_expression_type(db, definition, expr))
             }
+            // PEP 695 ParamSpec
+            DefinitionKind::ParamSpec(paramspec) => {
+                let paramspec_node = paramspec.node(&module);
+                Some(definition_expression_type(
+                    db,
+                    definition,
+                    paramspec_node.default.as_ref()?,
+                ))
+            }
             _ => None,
         }
     }

crates/ty_python_semantic/src/types.rs

@@ -49,10 +49,7 @@ impl<'db> ClassBase<'db> {
             ClassBase::Dynamic(DynamicType::Any) => "Any",
             ClassBase::Dynamic(DynamicType::Unknown) => "Unknown",
             ClassBase::Dynamic(
-                DynamicType::Todo(_)
-                | DynamicType::TodoPEP695ParamSpec
-                | DynamicType::TodoTypeAlias
-                | DynamicType::TodoUnpack,
+                DynamicType::Todo(_) | DynamicType::TodoTypeAlias | DynamicType::TodoUnpack,
             ) => "@Todo",
             ClassBase::Dynamic(DynamicType::Divergent(_)) => "Divergent",
             ClassBase::Protocol => "Protocol",