[ty] Gradual isinstance narrowing for generic classes

crates/ruff_benchmark/benches/ty_walltime.rs

@@ -110,7 +110,7 @@ static ALTAIR: Benchmark = Benchmark::new(
         max_dep_date: TY_ECOSYSTEM_PIN,
         python_version: SupportedPythonVersion::Py311,
     },
-    5,
+    9,
 );
 
 static COLOUR_SCIENCE: Benchmark = Benchmark::new(

crates/ty_project/src/metadata/options.rs

@@ -1438,6 +1438,32 @@ pub struct TerminalOptions {
 #[serde(rename_all = "kebab-case", deny_unknown_fields)]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct AnalysisOptions {
+    /// Whether ty should use strict narrowing for unspecialized generic classes in
+    /// `isinstance()` and `issubclass()` checks, as well as `match` class patterns.
+    ///
+    /// When enabled, ty narrows to the top materialization of the class. For example,
+    /// `isinstance(value, list)` narrows a value of type `object` to `Top[list[Unknown]]`,
+    /// representing the (infinite) union of all possible `list` specializations. Iterating
+    /// over the list would yield values of type `object`.
+    ///
+    /// When disabled, ty uses gradual generic narrowing, preserving compatible type
+    /// arguments from the original type where possible. For example,
+    /// `isinstance(value, list)` narrows a value of type `Sequence[int]` to `list[int]`.
+    /// If no specialization is available, the same check narrows a value of type `object`
+    /// to `list[Unknown]`; items of any type can then be appended to the list. Class
+    /// patterns such as `case list():` follow the same behavior.
+    ///
+    /// Defaults to `false`.
+    #[option(
+        default = r#"false"#,
+        value_type = "bool",
+        example = r#"
+            # Use the top materialization when narrowing to an unspecialized generic class
+            strict-generic-narrowing = true
+        "#
+    )]
+    pub strict_generic_narrowing: Option<bool>,
+
     /// Configure ty's behavior regarding type inference and narrowing of equality
     /// checks. Defaults to `false`.
     ///
@@ -1604,13 +1630,15 @@ impl AnalysisOptions {
         diagnostics: &mut Vec<OptionDiagnostic>,
     ) -> AnalysisSettings {
         let Self {
+            strict_generic_narrowing,
             strict_equality_semantics,
             respect_type_ignore_comments,
             allowed_unresolved_imports,
             replace_imports_with_any,
         } = self;
 
         let AnalysisSettings {
+            strict_generic_narrowing: strict_generic_narrowing_default,
             strict_equality_semantics: strict_equality_semantics_default,
             respect_type_ignore_comments: respect_type_ignore_default,
             allowed_unresolved_imports: allowed_unresolved_imports_default,
@@ -1640,6 +1668,8 @@ impl AnalysisOptions {
             };
 
         AnalysisSettings {
+            strict_generic_narrowing: strict_generic_narrowing
+                .unwrap_or(strict_generic_narrowing_default),
             strict_equality_semantics: strict_equality_semantics
                 .unwrap_or(strict_equality_semantics_default),
             respect_type_ignore_comments: respect_type_ignore_comments

crates/ty_python_semantic/resources/mdtest/call/builtins.md

@@ -517,6 +517,11 @@ for function in map(Function, [object()]):
 Several `dict` overloads accept one positional argument. When none matches, an arbitrarily selected
 overload must not make an otherwise compatible return type fail.
 
+```toml
+[analysis]
+strict-generic-narrowing = true
+```
+
 ```py
 from collections.abc import Mapping
 
@@ -531,6 +536,11 @@ def copy(value: object) -> dict[str, str]:
 An invalid `dict` call must not invalidate an assignment inside a branch where the original value
 has already been narrowed to a mapping.
 
+```toml
+[analysis]
+strict-generic-narrowing = true
+```
+
 ```py
 from collections.abc import Mapping
 

crates/ty_python_semantic/resources/mdtest/loops/for.md

@@ -679,14 +679,13 @@ def _(x: Sequence[int], y: object):
         reveal_type(item)  # revealed: int
 
     if isinstance(y, list):
-        reveal_type(y)  # revealed: Top[list[Unknown]]
+        reveal_type(y)  # revealed: list[Unknown]
         for item in y:
-            reveal_type(item)  # revealed: object
+            reveal_type(item)  # revealed: Unknown
 
     if isinstance(x, list):
-        reveal_type(x)  # revealed: Sequence[int] & Top[list[Unknown]]
+        reveal_type(x)  # revealed: list[int]
         for item in x:
-            # int & object simplifies to int
             reveal_type(item)  # revealed: int
 ```
 
@@ -1541,12 +1540,10 @@ simplify to `Never`, leaving only the iterable parts.
 ```py
 def f[T: tuple[int, ...] | int](x: T):
     if isinstance(x, tuple):
-        reveal_type(x)  # revealed: T@f & tuple[object, ...]
+        reveal_type(x)  # revealed: T@f & tuple[int, ...]
         for item in x:
-            # The intersection `(tuple[int, ...] | int) & tuple[object, ...]` distributes to:
-            # `(tuple[int, ...] & tuple[object, ...]) | (int & tuple[object, ...])`
-            # which simplifies to `tuple[int, ...] | Never` = `tuple[int, ...]`
-            # so iterating gives `int`.
+            # The `int` alternative in the TypeVar bound is disjoint from `tuple`. The
+            # remaining `tuple[int, ...]` alternative supplies the narrowed specialization.
             reveal_type(item)  # revealed: int
 ```
 
@@ -1558,13 +1555,10 @@ constraint, those parts should also simplify to `Never`.
 ```py
 def g[T: tuple[int, ...] | list[str]](x: T):
     if isinstance(x, tuple):
-        reveal_type(x)  # revealed: T@g & tuple[object, ...]
+        reveal_type(x)  # revealed: T@g & tuple[int, ...]
         for item in x:
-            # The intersection `(tuple[int, ...] | list[str]) & tuple[object, ...]` distributes to:
-            # `(tuple[int, ...] & tuple[object, ...]) | (list[str] & tuple[object, ...])`
-            # Since `list[str]` is disjoint from `tuple[object, ...]`, this simplifies to:
-            # `tuple[int, ...] | Never` = `tuple[int, ...]`
-            # so iterating gives `int`, NOT `int | str`.
+            # The `list[str]` alternative in the TypeVar bound is disjoint from `tuple`. The
+            # remaining `tuple[int, ...]` alternative supplies the narrowed specialization.
             reveal_type(item)  # revealed: int
 ```
 

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

@@ -54,7 +54,15 @@ def f(x: object):
 
 ## Calling narrowed callables
 
-The narrowed type `Top[Callable[..., object]]` represents the set of all possible callable types
+### Strict generic narrowing mode
+
+```toml
+[analysis]
+strict-generic-narrowing = true
+```
+
+In strict generic narrowing mode, an `isinstance(.., Callable)` check intersects the type with
+`Top[Callable[..., object]]`. This type represents the set of all possible callable types
 (including, e.g., functions that take no arguments and functions that require arguments). While such
 objects *are* callable (they pass `callable()`), no specific set of arguments can be guaranteed to
 be valid.
@@ -80,6 +88,28 @@ def resolve(value: str):
         reveal_type(value())  # revealed: object
 ```
 
+### Gradual generic narrowing mode
+
+```toml
+[analysis]
+strict-generic-narrowing = false
+```
+
+In gradual generic narrowing mode, an `isinstance(.., Callable)` check narrows to a gradual
+callable. Its parameters accept arbitrary arguments, and its return type is `Unknown`:
+
+```py
+from typing import Callable
+
+def call_with_args(y: object):
+    if isinstance(y, Callable):
+        reveal_type(y)  # revealed: (...) -> Unknown
+
+        reveal_type(y())  # revealed: Unknown
+        reveal_type(y(1, "foo"))  # revealed: Unknown
+        reveal_type(y(1, "foo", keyword_arg="bar"))  # revealed: Unknown
+```
+
 ## Narrowing with named expressions (walrus operator)
 
 When `callable()` is used with a named expression, the target of the named expression should be
@@ -139,9 +169,14 @@ import collections.abc
 
 def f(x: object):
     if isinstance(x, typing.Callable):
-        reveal_type(x)  # revealed: Top[(...) -> object]
+        reveal_type(x)  # revealed: (...) -> Unknown
+    else:
+        reveal_type(x)  # revealed: ~Top[(...) -> object]
+
     if isinstance(x, collections.abc.Callable):
-        reveal_type(x)  # revealed: Top[(...) -> object]
+        reveal_type(x)  # revealed: (...) -> Unknown
+    else:
+        reveal_type(x)  # revealed: ~Top[(...) -> object]
 ```
 
 ## `Callable` special-form identity

crates/ty_python_semantic/resources/mdtest/narrow/conditionals/in.md

@@ -1157,6 +1157,11 @@ After the `isinstance` check, `values` has type `Iterable[Literal[1]] & tuple[ob
 semantics were checked: the `tuple` component establishes that membership compares against its
 elements, while the `Iterable` component constrains those elements to `Literal[1]`.
 
+```toml
+[analysis]
+strict-generic-narrowing = true
+```
+
 ```py
 from collections.abc import Iterable
 from typing import Literal, final