[ty] Understand legacy and PEP 695 ParamSpec

Author: dhruvmanila

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

@@ -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: Unknown
+    reveal_type(P1.kwargs)  # revealed: Unknown
 
     # TODO: Signature should be (**P1) -> int
     reveal_type(c)  # revealed: (...) -> int

crates/ty_python_semantic/resources/mdtest/annotations/unsupported_special_forms.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[Unknown, ...]
+    reveal_type(kwargs)  # revealed: dict[str, Unknown]
     return callback(42, *args, **kwargs)
 
 class Foo:

crates/ty_python_semantic/resources/mdtest/generics/legacy/classes.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/paramspec.md

@@ -0,0 +1,131 @@
+# `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
+```
+
+### `TypeVar` 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"
+```
+
+```py
+from typing import ParamSpec
+
+# TODO: This is not an error
+# error: [invalid-type-form]
+P = ParamSpec("P", default=[int, str])
+```
+
+### 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
+```
+
+#### 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.
+We could do a better job in recovering from these errors.
+
+```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
+```

crates/ty_python_semantic/resources/mdtest/type_properties/is_assignable_to.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/src/types.rs

@@ -7633,6 +7633,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
@@ -7697,7 +7700,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")?;
@@ -8123,12 +8132,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.
@@ -8481,6 +8498,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/diagnostic.rs

@@ -63,6 +63,7 @@ pub(crate) fn register_lints(registry: &mut LintRegistryBuilder) {
     registry.register_lint(&INVALID_EXCEPTION_CAUGHT);
     registry.register_lint(&INVALID_GENERIC_CLASS);
     registry.register_lint(&INVALID_LEGACY_TYPE_VARIABLE);
+    registry.register_lint(&INVALID_PARAMSPEC);
     registry.register_lint(&INVALID_TYPE_ALIAS_TYPE);
     registry.register_lint(&INVALID_METACLASS);
     registry.register_lint(&INVALID_OVERLOAD);
@@ -872,6 +873,27 @@ declare_lint! {
     }
 }
 
+declare_lint! {
+    /// ## What it does
+    /// Checks for the creation of invalid `ParamSpec`s
+    ///
+    /// ## Why is this bad?
+    /// There are several requirements that you must follow when creating a `ParamSpec`.
+    ///
+    /// ## Examples
+    /// ```python
+    /// TODO
+    /// ```
+    ///
+    /// ## References
+    /// - [Typing spec: ParamSpec](https://typing.python.org/en/latest/spec/generics.html#paramspec)
+    pub(crate) static INVALID_PARAMSPEC = {
+        summary: "detects invalid ParamSpec usage",
+        status: LintStatus::stable("0.0.1-alpha.1"),
+        default_level: Level::Error,
+    }
+}
+
 declare_lint! {
     /// ## What it does
     /// Checks for the creation of invalid `TypeAliasType`s