[ty] Temporary SQLAlchemy special-case

Builds on range suppressions from
https://github.com/astral-sh/ruff/pull/21441

Filters diagnostics based on parsed valid range suppressions.

Issue: #3711

.github/renovate.json5

@@ -75,14 +75,6 @@
       matchManagers: ["cargo"],
       enabled: false,
     },
-    {
-      // `mkdocs-material` requires a manual update to keep the version in sync
-      // with `mkdocs-material-insider`.
-      // See: https://squidfunk.github.io/mkdocs-material/insiders/upgrade/
-      matchManagers: ["pip_requirements"],
-      matchPackageNames: ["mkdocs-material"],
-      enabled: false,
-    },
     {
       groupName: "pre-commit dependencies",
       matchManagers: ["pre-commit"],

.github/workflows/ci.yaml

@@ -24,6 +24,8 @@ env:
   PACKAGE_NAME: ruff
   PYTHON_VERSION: "3.14"
   NEXTEST_PROFILE: ci
+  # Enable mdtests that require external dependencies
+  MDTEST_EXTERNAL: "1"
 
 jobs:
   determine_changes:
@@ -779,8 +781,6 @@ jobs:
     name: "mkdocs"
     runs-on: ubuntu-latest
     timeout-minutes: 10
-    env:
-      MKDOCS_INSIDERS_SSH_KEY_EXISTS: ${{ secrets.MKDOCS_INSIDERS_SSH_KEY != '' }}
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
@@ -788,11 +788,6 @@ jobs:
       - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2.8.2
         with:
           save-if: ${{ github.ref == 'refs/heads/main' }}
-      - name: "Add SSH key"
-        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
-        uses: webfactory/ssh-agent@a6f90b1f127823b31d4d4a8d96047790581349bd # v0.9.1
-        with:
-          ssh-private-key: ${{ secrets.MKDOCS_INSIDERS_SSH_KEY }}
       - name: "Install Rust toolchain"
         run: rustup show
       - name: Install uv
@@ -800,11 +795,7 @@ jobs:
         with:
           python-version: 3.13
           activate-environment: true
-      - name: "Install Insiders dependencies"
-        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
-        run: uv pip install -r docs/requirements-insiders.txt
       - name: "Install dependencies"
-        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }}
         run: uv pip install -r docs/requirements.txt
       - name: "Update README File"
         run: python scripts/transform_readme.py --target mkdocs
@@ -812,12 +803,8 @@ jobs:
         run: python scripts/generate_mkdocs.py
       - name: "Check docs formatting"
         run: python scripts/check_docs_formatted.py
-      - name: "Build Insiders docs"
-        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
-        run: mkdocs build --strict -f mkdocs.insiders.yml
       - name: "Build docs"
-        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }}
-        run: mkdocs build --strict -f mkdocs.public.yml
+        run: mkdocs build --strict -f mkdocs.yml
 
   check-formatter-instability-and-black-similarity:
     name: "formatter instabilities and black similarity"

.github/workflows/publish-docs.yml

@@ -20,8 +20,6 @@ on:
 jobs:
   mkdocs:
     runs-on: ubuntu-latest
-    env:
-      MKDOCS_INSIDERS_SSH_KEY_EXISTS: ${{ secrets.MKDOCS_INSIDERS_SSH_KEY != '' }}
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
@@ -59,23 +57,12 @@ jobs:
           echo "branch_name=update-docs-$branch_display_name-$timestamp" >> "$GITHUB_ENV"
           echo "timestamp=$timestamp" >> "$GITHUB_ENV"
 
-      - name: "Add SSH key"
-        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
-        uses: webfactory/ssh-agent@a6f90b1f127823b31d4d4a8d96047790581349bd # v0.9.1
-        with:
-          ssh-private-key: ${{ secrets.MKDOCS_INSIDERS_SSH_KEY }}
-
       - name: "Install Rust toolchain"
         run: rustup show
 
       - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2.8.2
 
-      - name: "Install Insiders dependencies"
-        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
-        run: pip install -r docs/requirements-insiders.txt
-
       - name: "Install dependencies"
-        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }}
         run: pip install -r docs/requirements.txt
 
       - name: "Copy README File"
@@ -83,13 +70,8 @@ jobs:
           python scripts/transform_readme.py --target mkdocs
           python scripts/generate_mkdocs.py
 
-      - name: "Build Insiders docs"
-        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
-        run: mkdocs build --strict -f mkdocs.insiders.yml
-
       - name: "Build docs"
-        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }}
-        run: mkdocs build --strict -f mkdocs.public.yml
+        run: mkdocs build --strict -f mkdocs.yml
 
       - name: "Clone docs repo"
         run: git clone https://${{ secrets.ASTRAL_DOCS_PAT }}@github.com/astral-sh/docs.git astral-docs

CONTRIBUTING.md

@@ -331,13 +331,6 @@ you addressed them.
 
 ## MkDocs
 
-> [!NOTE]
->
-> The documentation uses Material for MkDocs Insiders, which is closed-source software.
-> This means only members of the Astral organization can preview the documentation exactly as it
-> will appear in production.
-> Outside contributors can still preview the documentation, but there will be some differences. Consult [the Material for MkDocs documentation](https://squidfunk.github.io/mkdocs-material/insiders/benefits/#features) for which features are exclusively available in the insiders version.
-
 To preview any changes to the documentation locally:
 
 1. Install the [Rust toolchain](https://www.rust-lang.org/tools/install).
@@ -351,11 +344,7 @@ To preview any changes to the documentation locally:
 1. Run the development server with:
 
     ```shell
-    # For contributors.
-    uvx --with-requirements docs/requirements.txt -- mkdocs serve -f mkdocs.public.yml
-
-    # For members of the Astral org, which has access to MkDocs Insiders via sponsorship.
-    uvx --with-requirements docs/requirements-insiders.txt -- mkdocs serve -f mkdocs.insiders.yml
+    uvx --with-requirements docs/requirements.txt -- mkdocs serve -f mkdocs.yml
     ```
 
 The documentation should then be available locally at

Cargo.lock

@@ -4557,6 +4557,7 @@ dependencies = [
  "anyhow",
  "camino",
  "colored 3.0.0",
+ "dunce",
  "insta",
  "memchr",
  "path-slash",

Cargo.toml

@@ -272,6 +272,12 @@ large_stack_arrays = "allow"
 lto = "fat"
 codegen-units = 16
 
+# Profile to build a minimally sized binary for ruff/ty
+[profile.minimal-size]
+inherits = "release"
+opt-level = "z"
+codegen-units = 1
+
 # Some crates don't change as much but benefit more from
 # more expensive optimization passes, so we selectively
 # decrease codegen-units in some cases.

crates/ruff/tests/cli/lint.rs

@@ -1440,6 +1440,78 @@ def function():
     Ok(())
 }
 
+#[test]
+fn ignore_noqa() -> Result<()> {
+    let fixture = CliTest::new()?;
+    fixture.write_file(
+        "ruff.toml",
+        r#"
+[lint]
+select = ["F401"]
+"#,
+    )?;
+
+    fixture.write_file(
+        "noqa.py",
+        r#"
+import os  # noqa: F401
+
+# ruff: disable[F401]
+import sys
+"#,
+    )?;
+
+    // without --ignore-noqa
+    assert_cmd_snapshot!(fixture
+        .check_command()
+        .args(["--config", "ruff.toml"])
+        .arg("noqa.py"),
+        @r"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    noqa.py:5:8: F401 [*] `sys` imported but unused
+    Found 1 error.
+    [*] 1 fixable with the `--fix` option.
+
+    ----- stderr -----
+    ");
+
+    assert_cmd_snapshot!(fixture
+        .check_command()
+        .args(["--config", "ruff.toml"])
+        .arg("noqa.py")
+        .args(["--preview"]),
+        @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    All checks passed!
+
+    ----- stderr -----
+    ");
+
+    // with --ignore-noqa --preview
+    assert_cmd_snapshot!(fixture
+        .check_command()
+        .args(["--config", "ruff.toml"])
+        .arg("noqa.py")
+        .args(["--ignore-noqa", "--preview"]),
+        @r"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    noqa.py:2:8: F401 [*] `os` imported but unused
+    noqa.py:5:8: F401 [*] `sys` imported but unused
+    Found 2 errors.
+    [*] 2 fixable with the `--fix` option.
+
+    ----- stderr -----
+    ");
+
+    Ok(())
+}
+
 #[test]
 fn add_noqa() -> Result<()> {
     let fixture = CliTest::new()?;
@@ -1632,6 +1704,100 @@ def unused(x):  # noqa: ANN001, ARG001, D103
     Ok(())
 }
 
+#[test]
+fn add_noqa_existing_file_level_noqa() -> Result<()> {
+    let fixture = CliTest::new()?;
+    fixture.write_file(
+        "ruff.toml",
+        r#"
+[lint]
+select = ["F401"]
+"#,
+    )?;
+
+    fixture.write_file(
+        "noqa.py",
+        r#"
+# ruff: noqa F401
+import os
+"#,
+    )?;
+
+    assert_cmd_snapshot!(fixture
+        .check_command()
+        .args(["--config", "ruff.toml"])
+        .arg("noqa.py")
+        .arg("--preview")
+        .args(["--add-noqa"])
+        .arg("-")
+        .pass_stdin(r#"
+
+"#), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    ");
+
+    let test_code =
+        fs::read_to_string(fixture.root().join("noqa.py")).expect("should read test file");
+
+    insta::assert_snapshot!(test_code, @r"
+    # ruff: noqa F401
+    import os
+    ");
+
+    Ok(())
+}
+
+#[test]
+fn add_noqa_existing_range_suppression() -> Result<()> {
+    let fixture = CliTest::new()?;
+    fixture.write_file(
+        "ruff.toml",
+        r#"
+[lint]
+select = ["F401"]
+"#,
+    )?;
+
+    fixture.write_file(
+        "noqa.py",
+        r#"
+# ruff: disable[F401]
+import os
+"#,
+    )?;
+
+    assert_cmd_snapshot!(fixture
+        .check_command()
+        .args(["--config", "ruff.toml"])
+        .arg("noqa.py")
+        .arg("--preview")
+        .args(["--add-noqa"])
+        .arg("-")
+        .pass_stdin(r#"
+
+"#), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    ");
+
+    let test_code =
+        fs::read_to_string(fixture.root().join("noqa.py")).expect("should read test file");
+
+    insta::assert_snapshot!(test_code, @r"
+    # ruff: disable[F401]
+    import os
+    ");
+
+    Ok(())
+}
+
 #[test]
 fn add_noqa_multiline_comment() -> Result<()> {
     let fixture = CliTest::new()?;

crates/ruff_db/src/diagnostic/mod.rs

@@ -166,28 +166,8 @@ impl Diagnostic {
     /// Returns the primary message for this diagnostic.
     ///
     /// A diagnostic always has a message, but it may be empty.
-    ///
-    /// NOTE: At present, this routine will return the first primary
-    /// annotation's message as the primary message when the main diagnostic
-    /// message is empty. This is meant to facilitate an incremental migration
-    /// in ty over to the new diagnostic data model. (The old data model
-    /// didn't distinguish between messages on the entire diagnostic and
-    /// messages attached to a particular span.)
     pub fn primary_message(&self) -> &str {
-        if !self.inner.message.as_str().is_empty() {
-            return self.inner.message.as_str();
-        }
-        // FIXME: As a special case, while we're migrating ty
-        // to the new diagnostic data model, we'll look for a primary
-        // message from the primary annotation. This is because most
-        // ty diagnostics are created with an empty diagnostic
-        // message and instead attach the message to the annotation.
-        // Fixing this will require touching basically every diagnostic
-        // in ty, so we do it this way for now to match the old
-        // semantics. ---AG
-        self.primary_annotation()
-            .and_then(|ann| ann.get_message())
-            .unwrap_or_default()
+        self.inner.message.as_str()
     }
 
     /// Introspects this diagnostic and returns what kind of "primary" message
@@ -199,18 +179,6 @@ impl Diagnostic {
     /// contains *essential* information or context for understanding the
     /// diagnostic.
     ///
-    /// The reason why we don't just always return both the main diagnostic
-    /// message and the primary annotation message is because this was written
-    /// in the midst of an incremental migration of ty over to the new
-    /// diagnostic data model. At time of writing, diagnostics were still
-    /// constructed in the old model where the main diagnostic message and the
-    /// primary annotation message were not distinguished from each other. So
-    /// for now, we carefully return what kind of messages this diagnostic
-    /// contains. In effect, if this diagnostic has a non-empty main message
-    /// *and* a non-empty primary annotation message, then the diagnostic is
-    /// 100% using the new diagnostic data model and we can format things
-    /// appropriately.
-    ///
     /// The type returned implements the `std::fmt::Display` trait. In most
     /// cases, just converting it to a string (or printing it) will do what
     /// you want.
@@ -224,11 +192,10 @@ impl Diagnostic {
             .primary_annotation()
             .and_then(|ann| ann.get_message())
             .unwrap_or_default();
-        match (main.is_empty(), annotation.is_empty()) {
-            (false, true) => ConciseMessage::MainDiagnostic(main),
-            (true, false) => ConciseMessage::PrimaryAnnotation(annotation),
-            (false, false) => ConciseMessage::Both { main, annotation },
-            (true, true) => ConciseMessage::Empty,
+        if annotation.is_empty() {
+            ConciseMessage::MainDiagnostic(main)
+        } else {
+            ConciseMessage::Both { main, annotation }
         }
     }
 
@@ -693,18 +660,6 @@ impl SubDiagnostic {
     /// contains *essential* information or context for understanding the
     /// diagnostic.
     ///
-    /// The reason why we don't just always return both the main diagnostic
-    /// message and the primary annotation message is because this was written
-    /// in the midst of an incremental migration of ty over to the new
-    /// diagnostic data model. At time of writing, diagnostics were still
-    /// constructed in the old model where the main diagnostic message and the
-    /// primary annotation message were not distinguished from each other. So
-    /// for now, we carefully return what kind of messages this diagnostic
-    /// contains. In effect, if this diagnostic has a non-empty main message
-    /// *and* a non-empty primary annotation message, then the diagnostic is
-    /// 100% using the new diagnostic data model and we can format things
-    /// appropriately.
-    ///
     /// The type returned implements the `std::fmt::Display` trait. In most
     /// cases, just converting it to a string (or printing it) will do what
     /// you want.
@@ -714,11 +669,10 @@ impl SubDiagnostic {
             .primary_annotation()
             .and_then(|ann| ann.get_message())
             .unwrap_or_default();
-        match (main.is_empty(), annotation.is_empty()) {
-            (false, true) => ConciseMessage::MainDiagnostic(main),
-            (true, false) => ConciseMessage::PrimaryAnnotation(annotation),
-            (false, false) => ConciseMessage::Both { main, annotation },
-            (true, true) => ConciseMessage::Empty,
+        if annotation.is_empty() {
+            ConciseMessage::MainDiagnostic(main)
+        } else {
+            ConciseMessage::Both { main, annotation }
         }
     }
 }
@@ -888,6 +842,10 @@ impl Annotation {
     pub fn hide_snippet(&mut self, yes: bool) {
         self.hide_snippet = yes;
     }
+
+    pub fn is_primary(&self) -> bool {
+        self.is_primary
+    }
 }
 
 /// Tags that can be associated with an annotation.
@@ -1508,28 +1466,10 @@ pub enum DiagnosticFormat {
 pub enum ConciseMessage<'a> {
     /// A diagnostic contains a non-empty main message and an empty
     /// primary annotation message.
-    ///
-    /// This strongly suggests that the diagnostic is using the
-    /// "new" data model.
     MainDiagnostic(&'a str),
-    /// A diagnostic contains an empty main message and a non-empty
-    /// primary annotation message.
-    ///
-    /// This strongly suggests that the diagnostic is using the
-    /// "old" data model.
-    PrimaryAnnotation(&'a str),
     /// A diagnostic contains a non-empty main message and a non-empty
     /// primary annotation message.
-    ///
-    /// This strongly suggests that the diagnostic is using the
-    /// "new" data model.
     Both { main: &'a str, annotation: &'a str },
-    /// A diagnostic contains an empty main message and an empty
-    /// primary annotation message.
-    ///
-    /// This indicates that the diagnostic is probably using the old
-    /// model.
-    Empty,
     /// A custom concise message has been provided.
     Custom(&'a str),
 }
@@ -1540,13 +1480,9 @@ impl std::fmt::Display for ConciseMessage<'_> {
             ConciseMessage::MainDiagnostic(main) => {
                 write!(f, "{main}")
             }
-            ConciseMessage::PrimaryAnnotation(annotation) => {
-                write!(f, "{annotation}")
-            }
             ConciseMessage::Both { main, annotation } => {
                 write!(f, "{main}: {annotation}")
             }
-            ConciseMessage::Empty => Ok(()),
             ConciseMessage::Custom(message) => {
                 write!(f, "{message}")
             }

crates/ruff_linter/resources/test/fixtures/flake8_bandit/S506.py

@@ -28,9 +28,11 @@ yaml.load("{}", SafeLoader)
 yaml.load("{}", yaml.SafeLoader)
 yaml.load("{}", CSafeLoader)
 yaml.load("{}", yaml.CSafeLoader)
+yaml.load("{}", yaml.cyaml.CSafeLoader)
 yaml.load("{}", NewSafeLoader)
 yaml.load("{}", Loader=SafeLoader)
 yaml.load("{}", Loader=yaml.SafeLoader)
 yaml.load("{}", Loader=CSafeLoader)
 yaml.load("{}", Loader=yaml.CSafeLoader)
+yaml.load("{}", Loader=yaml.cyaml.CSafeLoader)
 yaml.load("{}", Loader=NewSafeLoader)

crates/ruff_linter/resources/test/fixtures/flake8_bugbear/B006_B008.py

@@ -199,6 +199,9 @@ def bytes_okay(value=bytes(1)):
 def int_okay(value=int("12")):
     pass
 
+# Allow immutable slice()
+def slice_okay(value=slice(1,2)):
+    pass
 
 # Allow immutable complex() value
 def complex_okay(value=complex(1,2)):

crates/ruff_linter/resources/test/fixtures/pydocstyle/D417.py

@@ -218,3 +218,26 @@ def should_not_fail(payload, Args):
         Args:
             The other arguments.
     """
+
+
+# Test cases for Unpack[TypedDict] kwargs
+from typing import TypedDict
+from typing_extensions import Unpack
+
+class User(TypedDict):
+    id: int
+    name: str
+
+def function_with_unpack_args_should_not_fail(query: str, **kwargs: Unpack[User]):
+    """Function with Unpack kwargs.
+
+    Args:
+        query: some arg
+    """
+
+def function_with_unpack_and_missing_arg_doc_should_fail(query: str, **kwargs: Unpack[User]):
+    """Function with Unpack kwargs but missing query arg documentation.
+
+    Args:
+        **kwargs: keyword arguments
+    """

crates/ruff_linter/resources/test/fixtures/ruff/suppressions.py

@@ -0,0 +1,56 @@
+def f():
+    # These should both be ignored by the range suppression.
+    # ruff: disable[E741, F841]
+    I = 1
+    # ruff: enable[E741, F841]
+
+
+def f():
+    # These should both be ignored by the implicit range suppression.
+    # Should also generate an "unmatched suppression" warning.
+    # ruff:disable[E741,F841]
+    I = 1
+
+
+def f():
+    # Neither warning is ignored, and an "unmatched suppression"
+    # should be generated.
+    I = 1
+    # ruff: enable[E741, F841]
+
+
+def f():
+    # One should be ignored by the range suppression, and
+    # the other logged to the user.
+    # ruff: disable[E741]
+    I = 1
+    # ruff: enable[E741]
+
+
+def f():
+    # Test interleaved range suppressions. The first and last
+    # lines should each log a different warning, while the
+    # middle line should be completely silenced.
+    # ruff: disable[E741]
+    l = 0
+    # ruff: disable[F841]
+    O = 1
+    # ruff: enable[E741]
+    I = 2
+    # ruff: enable[F841]
+
+
+def f():
+    # Neither of these are ignored and warnings are
+    # logged to user
+    # ruff: disable[E501]
+    I = 1
+    # ruff: enable[E501]
+
+
+def f():
+    # These should both be ignored by the range suppression,
+    # and an unusued noqa diagnostic should be logged.
+    # ruff:disable[E741,F841]
+    I = 1  # noqa: E741,F841
+    # ruff:enable[E741,F841]

crates/ruff_linter/src/checkers/noqa.rs

@@ -12,17 +12,20 @@ use crate::fix::edits::delete_comment;
 use crate::noqa::{
     Code, Directive, FileExemption, FileNoqaDirectives, NoqaDirectives, NoqaMapping,
 };
+use crate::preview::is_range_suppressions_enabled;
 use crate::registry::Rule;
 use crate::rule_redirects::get_redirect_target;
 use crate::rules::pygrep_hooks;
 use crate::rules::ruff;
 use crate::rules::ruff::rules::{UnusedCodes, UnusedNOQA};
 use crate::settings::LinterSettings;
+use crate::suppression::Suppressions;
 use crate::{Edit, Fix, Locator};
 
 use super::ast::LintContext;
 
 /// RUF100
+#[expect(clippy::too_many_arguments)]
 pub(crate) fn check_noqa(
     context: &mut LintContext,
     path: &Path,
@@ -31,6 +34,7 @@ pub(crate) fn check_noqa(
     noqa_line_for: &NoqaMapping,
     analyze_directives: bool,
     settings: &LinterSettings,
+    suppressions: &Suppressions,
 ) -> Vec<usize> {
     // Identify any codes that are globally exempted (within the current file).
     let file_noqa_directives =
@@ -40,7 +44,7 @@ pub(crate) fn check_noqa(
     let mut noqa_directives =
         NoqaDirectives::from_commented_ranges(comment_ranges, &settings.external, path, locator);
 
-    if file_noqa_directives.is_empty() && noqa_directives.is_empty() {
+    if file_noqa_directives.is_empty() && noqa_directives.is_empty() && suppressions.is_empty() {
         return Vec::new();
     }
 
@@ -60,11 +64,19 @@ pub(crate) fn check_noqa(
             continue;
         }
 
+        // Apply file-level suppressions first
         if exemption.contains_secondary_code(code) {
             ignored_diagnostics.push(index);
             continue;
         }
 
+        // Apply ranged suppressions next
+        if is_range_suppressions_enabled(settings) && suppressions.check_diagnostic(diagnostic) {
+            ignored_diagnostics.push(index);
+            continue;
+        }
+
+        // Apply end-of-line noqa suppressions last
         let noqa_offsets = diagnostic
             .parent()
             .into_iter()

crates/ruff_linter/src/linter.rs

@@ -32,6 +32,7 @@ use crate::rules::ruff::rules::test_rules::{self, TEST_RULES, TestRule};
 use crate::settings::types::UnsafeFixes;
 use crate::settings::{LinterSettings, TargetVersion, flags};
 use crate::source_kind::SourceKind;
+use crate::suppression::Suppressions;
 use crate::{Locator, directives, fs};
 
 pub(crate) mod float;
@@ -128,6 +129,7 @@ pub fn check_path(
     source_type: PySourceType,
     parsed: &Parsed<ModModule>,
     target_version: TargetVersion,
+    suppressions: &Suppressions,
 ) -> Vec<Diagnostic> {
     // Aggregate all diagnostics.
     let mut context = LintContext::new(path, locator.contents(), settings);
@@ -339,6 +341,7 @@ pub fn check_path(
             &directives.noqa_line_for,
             parsed.has_valid_syntax(),
             settings,
+            suppressions,
         );
         if noqa.is_enabled() {
             for index in ignored.iter().rev() {
@@ -400,6 +403,9 @@ pub fn add_noqa_to_path(
         &indexer,
     );
 
+    // Parse range suppression comments
+    let suppressions = Suppressions::from_tokens(settings, locator.contents(), parsed.tokens());
+
     // Generate diagnostics, ignoring any existing `noqa` directives.
     let diagnostics = check_path(
         path,
@@ -414,6 +420,7 @@ pub fn add_noqa_to_path(
         source_type,
         &parsed,
         target_version,
+        &suppressions,
     );
 
     // Add any missing `# noqa` pragmas.
@@ -427,6 +434,7 @@ pub fn add_noqa_to_path(
         &directives.noqa_line_for,
         stylist.line_ending(),
         reason,
+        &suppressions,
     )
 }
 
@@ -461,6 +469,9 @@ pub fn lint_only(
         &indexer,
     );
 
+    // Parse range suppression comments
+    let suppressions = Suppressions::from_tokens(settings, locator.contents(), parsed.tokens());
+
     // Generate diagnostics.
     let diagnostics = check_path(
         path,
@@ -475,6 +486,7 @@ pub fn lint_only(
         source_type,
         &parsed,
         target_version,
+        &suppressions,
     );
 
     LinterResult {
@@ -566,6 +578,9 @@ pub fn lint_fix<'a>(
             &indexer,
         );
 
+        // Parse range suppression comments
+        let suppressions = Suppressions::from_tokens(settings, locator.contents(), parsed.tokens());
+
         // Generate diagnostics.
         let diagnostics = check_path(
             path,
@@ -580,6 +595,7 @@ pub fn lint_fix<'a>(
             source_type,
             &parsed,
             target_version,
+            &suppressions,
         );
 
         if iterations == 0 {
@@ -769,6 +785,7 @@ mod tests {
     use crate::registry::Rule;
     use crate::settings::LinterSettings;
     use crate::source_kind::SourceKind;
+    use crate::suppression::Suppressions;
     use crate::test::{TestedNotebook, assert_notebook_path, test_contents, test_snippet};
     use crate::{Locator, assert_diagnostics, directives, settings};
 
@@ -944,6 +961,7 @@ mod tests {
             &locator,
             &indexer,
         );
+        let suppressions = Suppressions::from_tokens(settings, locator.contents(), parsed.tokens());
         let mut diagnostics = check_path(
             path,
             None,
@@ -957,6 +975,7 @@ mod tests {
             source_type,
             &parsed,
             target_version,
+            &suppressions,
         );
         diagnostics.sort_by(Diagnostic::ruff_start_ordering);
         diagnostics

crates/ruff_linter/src/noqa.rs

@@ -20,12 +20,14 @@ use crate::Locator;
 use crate::fs::relativize_path;
 use crate::registry::Rule;
 use crate::rule_redirects::get_redirect_target;
+use crate::suppression::Suppressions;
 
 /// Generates an array of edits that matches the length of `messages`.
 /// Each potential edit in the array is paired, in order, with the associated diagnostic.
 /// Each edit will add a `noqa` comment to the appropriate line in the source to hide
 /// the diagnostic. These edits may conflict with each other and should not be applied
 /// simultaneously.
+#[expect(clippy::too_many_arguments)]
 pub fn generate_noqa_edits(
     path: &Path,
     diagnostics: &[Diagnostic],
@@ -34,11 +36,19 @@ pub fn generate_noqa_edits(
     external: &[String],
     noqa_line_for: &NoqaMapping,
     line_ending: LineEnding,
+    suppressions: &Suppressions,
 ) -> Vec<Option<Edit>> {
     let file_directives = FileNoqaDirectives::extract(locator, comment_ranges, external, path);
     let exemption = FileExemption::from(&file_directives);
     let directives = NoqaDirectives::from_commented_ranges(comment_ranges, external, path, locator);
-    let comments = find_noqa_comments(diagnostics, locator, &exemption, &directives, noqa_line_for);
+    let comments = find_noqa_comments(
+        diagnostics,
+        locator,
+        &exemption,
+        &directives,
+        noqa_line_for,
+        suppressions,
+    );
     build_noqa_edits_by_diagnostic(comments, locator, line_ending, None)
 }
 
@@ -725,6 +735,7 @@ pub(crate) fn add_noqa(
     noqa_line_for: &NoqaMapping,
     line_ending: LineEnding,
     reason: Option<&str>,
+    suppressions: &Suppressions,
 ) -> Result<usize> {
     let (count, output) = add_noqa_inner(
         path,
@@ -735,6 +746,7 @@ pub(crate) fn add_noqa(
         noqa_line_for,
         line_ending,
         reason,
+        suppressions,
     );
 
     fs::write(path, output)?;
@@ -751,6 +763,7 @@ fn add_noqa_inner(
     noqa_line_for: &NoqaMapping,
     line_ending: LineEnding,
     reason: Option<&str>,
+    suppressions: &Suppressions,
 ) -> (usize, String) {
     let mut count = 0;
 
@@ -760,7 +773,14 @@ fn add_noqa_inner(
 
     let directives = NoqaDirectives::from_commented_ranges(comment_ranges, external, path, locator);
 
-    let comments = find_noqa_comments(diagnostics, locator, &exemption, &directives, noqa_line_for);
+    let comments = find_noqa_comments(
+        diagnostics,
+        locator,
+        &exemption,
+        &directives,
+        noqa_line_for,
+        suppressions,
+    );
 
     let edits = build_noqa_edits_by_line(comments, locator, line_ending, reason);
 
@@ -859,6 +879,7 @@ fn find_noqa_comments<'a>(
     exemption: &'a FileExemption,
     directives: &'a NoqaDirectives,
     noqa_line_for: &NoqaMapping,
+    suppressions: &Suppressions,
 ) -> Vec<Option<NoqaComment<'a>>> {
     // List of noqa comments, ordered to match up with `messages`
     let mut comments_by_line: Vec<Option<NoqaComment<'a>>> = vec![];
@@ -875,6 +896,12 @@ fn find_noqa_comments<'a>(
             continue;
         }
 
+        // Apply ranged suppressions next
+        if suppressions.check_diagnostic(message) {
+            comments_by_line.push(None);
+            continue;
+        }
+
         // Is the violation ignored by a `noqa` directive on the parent line?
         if let Some(parent) = message.parent() {
             if let Some(directive_line) =
@@ -1253,6 +1280,7 @@ mod tests {
     use crate::rules::pycodestyle::rules::{AmbiguousVariableName, UselessSemicolon};
     use crate::rules::pyflakes::rules::UnusedVariable;
     use crate::rules::pyupgrade::rules::PrintfStringFormatting;
+    use crate::suppression::Suppressions;
     use crate::{Edit, Violation};
     use crate::{Locator, generate_noqa_edits};
 
@@ -2848,6 +2876,7 @@ mod tests {
             &noqa_line_for,
             LineEnding::Lf,
             None,
+            &Suppressions::default(),
         );
         assert_eq!(count, 0);
         assert_eq!(output, format!("{contents}"));
@@ -2872,6 +2901,7 @@ mod tests {
             &noqa_line_for,
             LineEnding::Lf,
             None,
+            &Suppressions::default(),
         );
         assert_eq!(count, 1);
         assert_eq!(output, "x = 1  # noqa: F841\n");
@@ -2903,6 +2933,7 @@ mod tests {
             &noqa_line_for,
             LineEnding::Lf,
             None,
+            &Suppressions::default(),
         );
         assert_eq!(count, 1);
         assert_eq!(output, "x = 1  # noqa: E741, F841\n");
@@ -2934,6 +2965,7 @@ mod tests {
             &noqa_line_for,
             LineEnding::Lf,
             None,
+            &Suppressions::default(),
         );
         assert_eq!(count, 0);
         assert_eq!(output, "x = 1  # noqa");
@@ -2956,6 +2988,7 @@ print(
         let messages = [PrintfStringFormatting
             .into_diagnostic(TextRange::new(12.into(), 79.into()), &source_file)];
         let comment_ranges = CommentRanges::default();
+        let suppressions = Suppressions::default();
         let edits = generate_noqa_edits(
             path,
             &messages,
@@ -2964,6 +2997,7 @@ print(
             &[],
             &noqa_line_for,
             LineEnding::Lf,
+            &suppressions,
         );
         assert_eq!(
             edits,
@@ -2987,6 +3021,7 @@ bar =
             [UselessSemicolon.into_diagnostic(TextRange::new(4.into(), 5.into()), &source_file)];
         let noqa_line_for = NoqaMapping::default();
         let comment_ranges = CommentRanges::default();
+        let suppressions = Suppressions::default();
         let edits = generate_noqa_edits(
             path,
             &messages,
@@ -2995,6 +3030,7 @@ bar =
             &[],
             &noqa_line_for,
             LineEnding::Lf,
+            &suppressions,
         );
         assert_eq!(
             edits,

crates/ruff_linter/src/preview.rs

@@ -286,3 +286,8 @@ pub(crate) const fn is_s310_resolve_string_literal_bindings_enabled(
 ) -> bool {
     settings.preview.is_enabled()
 }
+
+// https://github.com/astral-sh/ruff/pull/21623
+pub(crate) const fn is_range_suppressions_enabled(settings: &LinterSettings) -> bool {
+    settings.preview.is_enabled()
+}

crates/ruff_linter/src/rules/flake8_bandit/rules/unsafe_yaml_load.rs

@@ -75,6 +75,7 @@ pub(crate) fn unsafe_yaml_load(checker: &Checker, call: &ast::ExprCall) {
                         qualified_name.segments(),
                         ["yaml", "SafeLoader" | "CSafeLoader"]
                             | ["yaml", "loader", "SafeLoader" | "CSafeLoader"]
+                            | ["yaml", "cyaml", "CSafeLoader"]
                     )
                 })
             {

crates/ruff_linter/src/rules/flake8_bugbear/snapshots/ruff_linter__rules__flake8_bugbear__tests__B006_B006_B008.py.snap

@@ -236,227 +236,227 @@ help: Replace with `None`; initialize within function
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:239:20
+   --> B006_B008.py:242:20
     |
-237 | # B006 and B008
-238 | # We should handle arbitrary nesting of these B008.
-239 | def nested_combo(a=[float(3), dt.datetime.now()]):
+240 | # B006 and B008
+241 | # We should handle arbitrary nesting of these B008.
+242 | def nested_combo(a=[float(3), dt.datetime.now()]):
     |                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-240 |     pass
+243 |     pass
     |
 help: Replace with `None`; initialize within function
-236 | 
-237 | # B006 and B008
-238 | # We should handle arbitrary nesting of these B008.
+239 | 
+240 | # B006 and B008
+241 | # We should handle arbitrary nesting of these B008.
     - def nested_combo(a=[float(3), dt.datetime.now()]):
-239 + def nested_combo(a=None):
-240 |     pass
-241 | 
-242 | 
+242 + def nested_combo(a=None):
+243 |     pass
+244 | 
+245 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:276:27
+   --> B006_B008.py:279:27
     |
-275 | def mutable_annotations(
-276 |     a: list[int] | None = [],
+278 | def mutable_annotations(
+279 |     a: list[int] | None = [],
     |                           ^^
-277 |     b: Optional[Dict[int, int]] = {},
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+280 |     b: Optional[Dict[int, int]] = {},
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
     |
 help: Replace with `None`; initialize within function
-273 | 
-274 | 
-275 | def mutable_annotations(
+276 | 
+277 | 
+278 | def mutable_annotations(
     -     a: list[int] | None = [],
-276 +     a: list[int] | None = None,
-277 |     b: Optional[Dict[int, int]] = {},
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-279 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+279 +     a: list[int] | None = None,
+280 |     b: Optional[Dict[int, int]] = {},
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+282 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:277:35
+   --> B006_B008.py:280:35
     |
-275 | def mutable_annotations(
-276 |     a: list[int] | None = [],
-277 |     b: Optional[Dict[int, int]] = {},
+278 | def mutable_annotations(
+279 |     a: list[int] | None = [],
+280 |     b: Optional[Dict[int, int]] = {},
     |                                   ^^
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-279 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+282 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
     |
 help: Replace with `None`; initialize within function
-274 | 
-275 | def mutable_annotations(
-276 |     a: list[int] | None = [],
+277 | 
+278 | def mutable_annotations(
+279 |     a: list[int] | None = [],
     -     b: Optional[Dict[int, int]] = {},
-277 +     b: Optional[Dict[int, int]] = None,
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-279 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-280 | ):
+280 +     b: Optional[Dict[int, int]] = None,
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+282 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+283 | ):
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:278:62
+   --> B006_B008.py:281:62
     |
-276 |     a: list[int] | None = [],
-277 |     b: Optional[Dict[int, int]] = {},
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+279 |     a: list[int] | None = [],
+280 |     b: Optional[Dict[int, int]] = {},
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
     |                                                              ^^^^^
-279 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-280 | ):
+282 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+283 | ):
     |
 help: Replace with `None`; initialize within function
-275 | def mutable_annotations(
-276 |     a: list[int] | None = [],
-277 |     b: Optional[Dict[int, int]] = {},
+278 | def mutable_annotations(
+279 |     a: list[int] | None = [],
+280 |     b: Optional[Dict[int, int]] = {},
     -     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-278 +     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = None,
-279 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-280 | ):
-281 |     pass
+281 +     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = None,
+282 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+283 | ):
+284 |     pass
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:279:80
+   --> B006_B008.py:282:80
     |
-277 |     b: Optional[Dict[int, int]] = {},
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-279 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+280 |     b: Optional[Dict[int, int]] = {},
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+282 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
     |                                                                                ^^^^^
-280 | ):
-281 |     pass
+283 | ):
+284 |     pass
     |
 help: Replace with `None`; initialize within function
-276 |     a: list[int] | None = [],
-277 |     b: Optional[Dict[int, int]] = {},
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+279 |     a: list[int] | None = [],
+280 |     b: Optional[Dict[int, int]] = {},
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
     -     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-279 +     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = None,
-280 | ):
-281 |     pass
-282 | 
+282 +     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = None,
+283 | ):
+284 |     pass
+285 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:284:52
+   --> B006_B008.py:287:52
     |
-284 | def single_line_func_wrong(value: dict[str, str] = {}):
+287 | def single_line_func_wrong(value: dict[str, str] = {}):
     |                                                    ^^
-285 |     """Docstring"""
+288 |     """Docstring"""
     |
 help: Replace with `None`; initialize within function
-281 |     pass
-282 | 
-283 | 
-    - def single_line_func_wrong(value: dict[str, str] = {}):
-284 + def single_line_func_wrong(value: dict[str, str] = None):
-285 |     """Docstring"""
+284 |     pass
+285 | 
 286 | 
-287 | 
+    - def single_line_func_wrong(value: dict[str, str] = {}):
+287 + def single_line_func_wrong(value: dict[str, str] = None):
+288 |     """Docstring"""
+289 | 
+290 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:288:52
+   --> B006_B008.py:291:52
     |
-288 | def single_line_func_wrong(value: dict[str, str] = {}):
+291 | def single_line_func_wrong(value: dict[str, str] = {}):
     |                                                    ^^
-289 |     """Docstring"""
-290 |     ...
+292 |     """Docstring"""
+293 |     ...
     |
 help: Replace with `None`; initialize within function
-285 |     """Docstring"""
-286 | 
-287 | 
+288 |     """Docstring"""
+289 | 
+290 | 
     - def single_line_func_wrong(value: dict[str, str] = {}):
-288 + def single_line_func_wrong(value: dict[str, str] = None):
-289 |     """Docstring"""
-290 |     ...
-291 | 
+291 + def single_line_func_wrong(value: dict[str, str] = None):
+292 |     """Docstring"""
+293 |     ...
+294 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:293:52
+   --> B006_B008.py:296:52
     |
-293 | def single_line_func_wrong(value: dict[str, str] = {}):
+296 | def single_line_func_wrong(value: dict[str, str] = {}):
     |                                                    ^^
-294 |     """Docstring"""; ...
+297 |     """Docstring"""; ...
     |
 help: Replace with `None`; initialize within function
-290 |     ...
-291 | 
-292 | 
-    - def single_line_func_wrong(value: dict[str, str] = {}):
-293 + def single_line_func_wrong(value: dict[str, str] = None):
-294 |     """Docstring"""; ...
+293 |     ...
+294 | 
 295 | 
-296 | 
+    - def single_line_func_wrong(value: dict[str, str] = {}):
+296 + def single_line_func_wrong(value: dict[str, str] = None):
+297 |     """Docstring"""; ...
+298 | 
+299 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:297:52
+   --> B006_B008.py:300:52
     |
-297 | def single_line_func_wrong(value: dict[str, str] = {}):
+300 | def single_line_func_wrong(value: dict[str, str] = {}):
     |                                                    ^^
-298 |     """Docstring"""; \
-299 |         ...
+301 |     """Docstring"""; \
+302 |         ...
     |
 help: Replace with `None`; initialize within function
-294 |     """Docstring"""; ...
-295 | 
-296 | 
+297 |     """Docstring"""; ...
+298 | 
+299 | 
     - def single_line_func_wrong(value: dict[str, str] = {}):
-297 + def single_line_func_wrong(value: dict[str, str] = None):
-298 |     """Docstring"""; \
-299 |         ...
-300 | 
+300 + def single_line_func_wrong(value: dict[str, str] = None):
+301 |     """Docstring"""; \
+302 |         ...
+303 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:302:52
+   --> B006_B008.py:305:52
     |
-302 |   def single_line_func_wrong(value: dict[str, str] = {
+305 |   def single_line_func_wrong(value: dict[str, str] = {
     |  ____________________________________________________^
-303 | |     # This is a comment
-304 | | }):
+306 | |     # This is a comment
+307 | | }):
     | |_^
-305 |       """Docstring"""
+308 |       """Docstring"""
     |
 help: Replace with `None`; initialize within function
-299 |         ...
-300 | 
-301 | 
+302 |         ...
+303 | 
+304 | 
     - def single_line_func_wrong(value: dict[str, str] = {
     -     # This is a comment
     - }):
-302 + def single_line_func_wrong(value: dict[str, str] = None):
-303 |     """Docstring"""
-304 | 
-305 | 
+305 + def single_line_func_wrong(value: dict[str, str] = None):
+306 |     """Docstring"""
+307 | 
+308 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 Do not use mutable data structures for argument defaults
-   --> B006_B008.py:308:52
+   --> B006_B008.py:311:52
     |
-308 | def single_line_func_wrong(value: dict[str, str] = {}) \
+311 | def single_line_func_wrong(value: dict[str, str] = {}) \
     |                                                    ^^
-309 |     : \
-310 |     """Docstring"""
+312 |     : \
+313 |     """Docstring"""
     |
 help: Replace with `None`; initialize within function
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:313:52
+   --> B006_B008.py:316:52
     |
-313 | def single_line_func_wrong(value: dict[str, str] = {}):
+316 | def single_line_func_wrong(value: dict[str, str] = {}):
     |                                                    ^^
-314 |     """Docstring without newline"""
+317 |     """Docstring without newline"""
     |
 help: Replace with `None`; initialize within function
-310 |     """Docstring"""
-311 | 
-312 | 
+313 |     """Docstring"""
+314 | 
+315 | 
     - def single_line_func_wrong(value: dict[str, str] = {}):
-313 + def single_line_func_wrong(value: dict[str, str] = None):
-314 |     """Docstring without newline"""
+316 + def single_line_func_wrong(value: dict[str, str] = None):
+317 |     """Docstring without newline"""
 note: This is an unsafe fix and may change runtime behavior

crates/ruff_linter/src/rules/flake8_bugbear/snapshots/ruff_linter__rules__flake8_bugbear__tests__B008_B006_B008.py.snap

@@ -53,39 +53,39 @@ B008 Do not perform function call in argument defaults; instead, perform the cal
     |
 
 B008 Do not perform function call `dt.datetime.now` in argument defaults; instead, perform the call within the function, or read the default from a module-level singleton variable
-   --> B006_B008.py:239:31
+   --> B006_B008.py:242:31
     |
-237 | # B006 and B008
-238 | # We should handle arbitrary nesting of these B008.
-239 | def nested_combo(a=[float(3), dt.datetime.now()]):
+240 | # B006 and B008
+241 | # We should handle arbitrary nesting of these B008.
+242 | def nested_combo(a=[float(3), dt.datetime.now()]):
     |                               ^^^^^^^^^^^^^^^^^
-240 |     pass
+243 |     pass
     |
 
 B008 Do not perform function call `map` in argument defaults; instead, perform the call within the function, or read the default from a module-level singleton variable
-   --> B006_B008.py:245:22
+   --> B006_B008.py:248:22
     |
-243 | # Don't flag nested B006 since we can't guarantee that
-244 | # it isn't made mutable by the outer operation.
-245 | def no_nested_b006(a=map(lambda s: s.upper(), ["a", "b", "c"])):
+246 | # Don't flag nested B006 since we can't guarantee that
+247 | # it isn't made mutable by the outer operation.
+248 | def no_nested_b006(a=map(lambda s: s.upper(), ["a", "b", "c"])):
     |                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-246 |     pass
+249 |     pass
     |
 
 B008 Do not perform function call `random.randint` in argument defaults; instead, perform the call within the function, or read the default from a module-level singleton variable
-   --> B006_B008.py:250:19
+   --> B006_B008.py:253:19
     |
-249 | # B008-ception.
-250 | def nested_b008(a=random.randint(0, dt.datetime.now().year)):
+252 | # B008-ception.
+253 | def nested_b008(a=random.randint(0, dt.datetime.now().year)):
     |                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-251 |     pass
+254 |     pass
     |
 
 B008 Do not perform function call `dt.datetime.now` in argument defaults; instead, perform the call within the function, or read the default from a module-level singleton variable
-   --> B006_B008.py:250:37
+   --> B006_B008.py:253:37
     |
-249 | # B008-ception.
-250 | def nested_b008(a=random.randint(0, dt.datetime.now().year)):
+252 | # B008-ception.
+253 | def nested_b008(a=random.randint(0, dt.datetime.now().year)):
     |                                     ^^^^^^^^^^^^^^^^^
-251 |     pass
+254 |     pass
     |

crates/ruff_linter/src/rules/flake8_bugbear/snapshots/ruff_linter__rules__flake8_bugbear__tests__preview__B006_B006_B008.py.snap

@@ -236,227 +236,227 @@ help: Replace with `None`; initialize within function
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:239:20
+   --> B006_B008.py:242:20
     |
-237 | # B006 and B008
-238 | # We should handle arbitrary nesting of these B008.
-239 | def nested_combo(a=[float(3), dt.datetime.now()]):
+240 | # B006 and B008
+241 | # We should handle arbitrary nesting of these B008.
+242 | def nested_combo(a=[float(3), dt.datetime.now()]):
     |                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-240 |     pass
+243 |     pass
     |
 help: Replace with `None`; initialize within function
-236 | 
-237 | # B006 and B008
-238 | # We should handle arbitrary nesting of these B008.
+239 | 
+240 | # B006 and B008
+241 | # We should handle arbitrary nesting of these B008.
     - def nested_combo(a=[float(3), dt.datetime.now()]):
-239 + def nested_combo(a=None):
-240 |     pass
-241 | 
-242 | 
+242 + def nested_combo(a=None):
+243 |     pass
+244 | 
+245 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:276:27
+   --> B006_B008.py:279:27
     |
-275 | def mutable_annotations(
-276 |     a: list[int] | None = [],
+278 | def mutable_annotations(
+279 |     a: list[int] | None = [],
     |                           ^^
-277 |     b: Optional[Dict[int, int]] = {},
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+280 |     b: Optional[Dict[int, int]] = {},
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
     |
 help: Replace with `None`; initialize within function
-273 | 
-274 | 
-275 | def mutable_annotations(
+276 | 
+277 | 
+278 | def mutable_annotations(
     -     a: list[int] | None = [],
-276 +     a: list[int] | None = None,
-277 |     b: Optional[Dict[int, int]] = {},
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-279 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+279 +     a: list[int] | None = None,
+280 |     b: Optional[Dict[int, int]] = {},
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+282 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:277:35
+   --> B006_B008.py:280:35
     |
-275 | def mutable_annotations(
-276 |     a: list[int] | None = [],
-277 |     b: Optional[Dict[int, int]] = {},
+278 | def mutable_annotations(
+279 |     a: list[int] | None = [],
+280 |     b: Optional[Dict[int, int]] = {},
     |                                   ^^
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-279 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+282 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
     |
 help: Replace with `None`; initialize within function
-274 | 
-275 | def mutable_annotations(
-276 |     a: list[int] | None = [],
+277 | 
+278 | def mutable_annotations(
+279 |     a: list[int] | None = [],
     -     b: Optional[Dict[int, int]] = {},
-277 +     b: Optional[Dict[int, int]] = None,
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-279 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-280 | ):
+280 +     b: Optional[Dict[int, int]] = None,
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+282 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+283 | ):
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:278:62
+   --> B006_B008.py:281:62
     |
-276 |     a: list[int] | None = [],
-277 |     b: Optional[Dict[int, int]] = {},
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+279 |     a: list[int] | None = [],
+280 |     b: Optional[Dict[int, int]] = {},
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
     |                                                              ^^^^^
-279 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-280 | ):
+282 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+283 | ):
     |
 help: Replace with `None`; initialize within function
-275 | def mutable_annotations(
-276 |     a: list[int] | None = [],
-277 |     b: Optional[Dict[int, int]] = {},
+278 | def mutable_annotations(
+279 |     a: list[int] | None = [],
+280 |     b: Optional[Dict[int, int]] = {},
     -     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-278 +     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = None,
-279 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-280 | ):
-281 |     pass
+281 +     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = None,
+282 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+283 | ):
+284 |     pass
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:279:80
+   --> B006_B008.py:282:80
     |
-277 |     b: Optional[Dict[int, int]] = {},
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-279 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+280 |     b: Optional[Dict[int, int]] = {},
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+282 |     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
     |                                                                                ^^^^^
-280 | ):
-281 |     pass
+283 | ):
+284 |     pass
     |
 help: Replace with `None`; initialize within function
-276 |     a: list[int] | None = [],
-277 |     b: Optional[Dict[int, int]] = {},
-278 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
+279 |     a: list[int] | None = [],
+280 |     b: Optional[Dict[int, int]] = {},
+281 |     c: Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
     -     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = set(),
-279 +     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = None,
-280 | ):
-281 |     pass
-282 | 
+282 +     d: typing_extensions.Annotated[Union[Set[str], abc.Sized], "annotation"] = None,
+283 | ):
+284 |     pass
+285 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:284:52
+   --> B006_B008.py:287:52
     |
-284 | def single_line_func_wrong(value: dict[str, str] = {}):
+287 | def single_line_func_wrong(value: dict[str, str] = {}):
     |                                                    ^^
-285 |     """Docstring"""
+288 |     """Docstring"""
     |
 help: Replace with `None`; initialize within function
-281 |     pass
-282 | 
-283 | 
-    - def single_line_func_wrong(value: dict[str, str] = {}):
-284 + def single_line_func_wrong(value: dict[str, str] = None):
-285 |     """Docstring"""
+284 |     pass
+285 | 
 286 | 
-287 | 
+    - def single_line_func_wrong(value: dict[str, str] = {}):
+287 + def single_line_func_wrong(value: dict[str, str] = None):
+288 |     """Docstring"""
+289 | 
+290 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:288:52
+   --> B006_B008.py:291:52
     |
-288 | def single_line_func_wrong(value: dict[str, str] = {}):
+291 | def single_line_func_wrong(value: dict[str, str] = {}):
     |                                                    ^^
-289 |     """Docstring"""
-290 |     ...
+292 |     """Docstring"""
+293 |     ...
     |
 help: Replace with `None`; initialize within function
-285 |     """Docstring"""
-286 | 
-287 | 
+288 |     """Docstring"""
+289 | 
+290 | 
     - def single_line_func_wrong(value: dict[str, str] = {}):
-288 + def single_line_func_wrong(value: dict[str, str] = None):
-289 |     """Docstring"""
-290 |     ...
-291 | 
+291 + def single_line_func_wrong(value: dict[str, str] = None):
+292 |     """Docstring"""
+293 |     ...
+294 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:293:52
+   --> B006_B008.py:296:52
     |
-293 | def single_line_func_wrong(value: dict[str, str] = {}):
+296 | def single_line_func_wrong(value: dict[str, str] = {}):
     |                                                    ^^
-294 |     """Docstring"""; ...
+297 |     """Docstring"""; ...
     |
 help: Replace with `None`; initialize within function
-290 |     ...
-291 | 
-292 | 
-    - def single_line_func_wrong(value: dict[str, str] = {}):
-293 + def single_line_func_wrong(value: dict[str, str] = None):
-294 |     """Docstring"""; ...
+293 |     ...
+294 | 
 295 | 
-296 | 
+    - def single_line_func_wrong(value: dict[str, str] = {}):
+296 + def single_line_func_wrong(value: dict[str, str] = None):
+297 |     """Docstring"""; ...
+298 | 
+299 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:297:52
+   --> B006_B008.py:300:52
     |
-297 | def single_line_func_wrong(value: dict[str, str] = {}):
+300 | def single_line_func_wrong(value: dict[str, str] = {}):
     |                                                    ^^
-298 |     """Docstring"""; \
-299 |         ...
+301 |     """Docstring"""; \
+302 |         ...
     |
 help: Replace with `None`; initialize within function
-294 |     """Docstring"""; ...
-295 | 
-296 | 
+297 |     """Docstring"""; ...
+298 | 
+299 | 
     - def single_line_func_wrong(value: dict[str, str] = {}):
-297 + def single_line_func_wrong(value: dict[str, str] = None):
-298 |     """Docstring"""; \
-299 |         ...
-300 | 
+300 + def single_line_func_wrong(value: dict[str, str] = None):
+301 |     """Docstring"""; \
+302 |         ...
+303 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:302:52
+   --> B006_B008.py:305:52
     |
-302 |   def single_line_func_wrong(value: dict[str, str] = {
+305 |   def single_line_func_wrong(value: dict[str, str] = {
     |  ____________________________________________________^
-303 | |     # This is a comment
-304 | | }):
+306 | |     # This is a comment
+307 | | }):
     | |_^
-305 |       """Docstring"""
+308 |       """Docstring"""
     |
 help: Replace with `None`; initialize within function
-299 |         ...
-300 | 
-301 | 
+302 |         ...
+303 | 
+304 | 
     - def single_line_func_wrong(value: dict[str, str] = {
     -     # This is a comment
     - }):
-302 + def single_line_func_wrong(value: dict[str, str] = None):
-303 |     """Docstring"""
-304 | 
-305 | 
+305 + def single_line_func_wrong(value: dict[str, str] = None):
+306 |     """Docstring"""
+307 | 
+308 | 
 note: This is an unsafe fix and may change runtime behavior
 
 B006 Do not use mutable data structures for argument defaults
-   --> B006_B008.py:308:52
+   --> B006_B008.py:311:52
     |
-308 | def single_line_func_wrong(value: dict[str, str] = {}) \
+311 | def single_line_func_wrong(value: dict[str, str] = {}) \
     |                                                    ^^
-309 |     : \
-310 |     """Docstring"""
+312 |     : \
+313 |     """Docstring"""
     |
 help: Replace with `None`; initialize within function
 
 B006 [*] Do not use mutable data structures for argument defaults
-   --> B006_B008.py:313:52
+   --> B006_B008.py:316:52
     |
-313 | def single_line_func_wrong(value: dict[str, str] = {}):
+316 | def single_line_func_wrong(value: dict[str, str] = {}):
     |                                                    ^^
-314 |     """Docstring without newline"""
+317 |     """Docstring without newline"""
     |
 help: Replace with `None`; initialize within function
-310 |     """Docstring"""
-311 | 
-312 | 
+313 |     """Docstring"""
+314 | 
+315 | 
     - def single_line_func_wrong(value: dict[str, str] = {}):
-313 + def single_line_func_wrong(value: dict[str, str] = None):
-314 |     """Docstring without newline"""
+316 + def single_line_func_wrong(value: dict[str, str] = None):
+317 |     """Docstring without newline"""
 note: This is an unsafe fix and may change runtime behavior

crates/ruff_linter/src/rules/pydocstyle/rules/sections.rs

@@ -4,7 +4,9 @@ use rustc_hash::FxHashSet;
 use std::sync::LazyLock;
 
 use ruff_macros::{ViolationMetadata, derive_message_formats};
+use ruff_python_ast::Parameter;
 use ruff_python_ast::docstrings::{clean_space, leading_space};
+use ruff_python_ast::helpers::map_subscript;
 use ruff_python_ast::identifier::Identifier;
 use ruff_python_semantic::analyze::visibility::is_staticmethod;
 use ruff_python_trivia::textwrap::dedent;
@@ -1184,6 +1186,9 @@ impl AlwaysFixableViolation for MissingSectionNameColon {
 /// This rule is enabled when using the `google` convention, and disabled when
 /// using the `pep257` and `numpy` conventions.
 ///
+/// Parameters annotated with `typing.Unpack` are exempt from this rule.
+/// This follows the Python typing specification for unpacking keyword arguments.
+///
 /// ## Example
 /// ```python
 /// def calculate_speed(distance: float, time: float) -> float:
@@ -1233,6 +1238,7 @@ impl AlwaysFixableViolation for MissingSectionNameColon {
 /// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
 /// - [PEP 287 – reStructuredText Docstring Format](https://peps.python.org/pep-0287/)
 /// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
+/// - [Python - Unpack for keyword arguments](https://typing.python.org/en/latest/spec/callables.html#unpack-kwargs)
 #[derive(ViolationMetadata)]
 #[violation_metadata(stable_since = "v0.0.73")]
 pub(crate) struct UndocumentedParam {
@@ -1808,7 +1814,9 @@ fn missing_args(checker: &Checker, docstring: &Docstring, docstrings_args: &FxHa
                 missing_arg_names.insert(starred_arg_name);
             }
         }
-        if let Some(arg) = function.parameters.kwarg.as_ref() {
+        if let Some(arg) = function.parameters.kwarg.as_ref()
+            && !has_unpack_annotation(checker, arg)
+        {
             let arg_name = arg.name.as_str();
             let starred_arg_name = format!("**{arg_name}");
             if !arg_name.starts_with('_')
@@ -1834,6 +1842,15 @@ fn missing_args(checker: &Checker, docstring: &Docstring, docstrings_args: &FxHa
     }
 }
 
+/// Returns `true` if the parameter is annotated with `typing.Unpack`
+fn has_unpack_annotation(checker: &Checker, parameter: &Parameter) -> bool {
+    parameter.annotation.as_ref().is_some_and(|annotation| {
+        checker
+            .semantic()
+            .match_typing_expr(map_subscript(annotation), "Unpack")
+    })
+}
+
 // See: `GOOGLE_ARGS_REGEX` in `pydocstyle/checker.py`.
 static GOOGLE_ARGS_REGEX: LazyLock<Regex> =
     LazyLock::new(|| Regex::new(r"^\s*(\*?\*?\w+)\s*(\(.*?\))?\s*:(\r\n|\n)?\s*.+").unwrap());

crates/ruff_linter/src/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__d417_google.snap

@@ -101,3 +101,13 @@ D417 Missing argument description in the docstring for `should_fail`: `Args`
 200 |     """
 201 |     Send a message.
     |
+
+D417 Missing argument description in the docstring for `function_with_unpack_and_missing_arg_doc_should_fail`: `query`
+   --> D417.py:238:5
+    |
+236 |     """
+237 |
+238 | def function_with_unpack_and_missing_arg_doc_should_fail(query: str, **kwargs: Unpack[User]):
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+239 |     """Function with Unpack kwargs but missing query arg documentation.
+    |

crates/ruff_linter/src/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__d417_google_ignore_var_parameters.snap

@@ -83,3 +83,13 @@ D417 Missing argument description in the docstring for `should_fail`: `Args`
 200 |     """
 201 |     Send a message.
     |
+
+D417 Missing argument description in the docstring for `function_with_unpack_and_missing_arg_doc_should_fail`: `query`
+   --> D417.py:238:5
+    |
+236 |     """
+237 |
+238 | def function_with_unpack_and_missing_arg_doc_should_fail(query: str, **kwargs: Unpack[User]):
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+239 |     """Function with Unpack kwargs but missing query arg documentation.
+    |

crates/ruff_linter/src/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__d417_unspecified.snap

@@ -101,3 +101,13 @@ D417 Missing argument description in the docstring for `should_fail`: `Args`
 200 |     """
 201 |     Send a message.
     |
+
+D417 Missing argument description in the docstring for `function_with_unpack_and_missing_arg_doc_should_fail`: `query`
+   --> D417.py:238:5
+    |
+236 |     """
+237 |
+238 | def function_with_unpack_and_missing_arg_doc_should_fail(query: str, **kwargs: Unpack[User]):
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+239 |     """Function with Unpack kwargs but missing query arg documentation.
+    |

crates/ruff_linter/src/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__d417_unspecified_ignore_var_parameters.snap

@@ -101,3 +101,13 @@ D417 Missing argument description in the docstring for `should_fail`: `Args`
 200 |     """
 201 |     Send a message.
     |
+
+D417 Missing argument description in the docstring for `function_with_unpack_and_missing_arg_doc_should_fail`: `query`
+   --> D417.py:238:5
+    |
+236 |     """
+237 |
+238 | def function_with_unpack_and_missing_arg_doc_should_fail(query: str, **kwargs: Unpack[User]):
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+239 |     """Function with Unpack kwargs but missing query arg documentation.
+    |

crates/ruff_linter/src/rules/pyflakes/mod.rs

@@ -28,6 +28,7 @@ mod tests {
     use crate::settings::types::PreviewMode;
     use crate::settings::{LinterSettings, flags};
     use crate::source_kind::SourceKind;
+    use crate::suppression::Suppressions;
     use crate::test::{test_contents, test_path, test_snippet};
     use crate::{Locator, assert_diagnostics, assert_diagnostics_diff, directives};
 
@@ -955,6 +956,8 @@ mod tests {
             &locator,
             &indexer,
         );
+        let suppressions =
+            Suppressions::from_tokens(&settings, locator.contents(), parsed.tokens());
         let mut messages = check_path(
             Path::new("<filename>"),
             None,
@@ -968,6 +971,7 @@ mod tests {
             source_type,
             &parsed,
             target_version,
+            &suppressions,
         );
         messages.sort_by(Diagnostic::ruff_start_ordering);
         let actual = messages

crates/ruff_linter/src/rules/ruff/mod.rs

@@ -305,6 +305,25 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn range_suppressions() -> Result<()> {
+        assert_diagnostics_diff!(
+            Path::new("ruff/suppressions.py"),
+            &settings::LinterSettings::for_rules(vec![
+                Rule::UnusedVariable,
+                Rule::AmbiguousVariableName,
+                Rule::UnusedNOQA,
+            ]),
+            &settings::LinterSettings::for_rules(vec![
+                Rule::UnusedVariable,
+                Rule::AmbiguousVariableName,
+                Rule::UnusedNOQA,
+            ])
+            .with_preview_mode(),
+        );
+        Ok(())
+    }
+
     #[test]
     fn ruf100_0() -> Result<()> {
         let diagnostics = test_path(

crates/ruff_linter/src/rules/ruff/snapshots/ruff_linter__rules__ruff__tests__range_suppressions.snap

@@ -0,0 +1,168 @@
+---
+source: crates/ruff_linter/src/rules/ruff/mod.rs
+---
+--- Linter settings ---
+-linter.preview = disabled
++linter.preview = enabled
+
+--- Summary ---
+Removed: 9
+Added: 1
+
+--- Removed ---
+E741 Ambiguous variable name: `I`
+ --> suppressions.py:4:5
+  |
+2 |     # These should both be ignored by the range suppression.
+3 |     # ruff: disable[E741, F841]
+4 |     I = 1
+  |     ^
+5 |     # ruff: enable[E741, F841]
+  |
+
+
+F841 [*] Local variable `I` is assigned to but never used
+ --> suppressions.py:4:5
+  |
+2 |     # These should both be ignored by the range suppression.
+3 |     # ruff: disable[E741, F841]
+4 |     I = 1
+  |     ^
+5 |     # ruff: enable[E741, F841]
+  |
+help: Remove assignment to unused variable `I`
+1 | def f():
+2 |     # These should both be ignored by the range suppression.
+3 |     # ruff: disable[E741, F841]
+  -     I = 1
+4 +     pass
+5 |     # ruff: enable[E741, F841]
+6 | 
+7 | 
+note: This is an unsafe fix and may change runtime behavior
+
+
+E741 Ambiguous variable name: `I`
+  --> suppressions.py:12:5
+   |
+10 |     # Should also generate an "unmatched suppression" warning.
+11 |     # ruff:disable[E741,F841]
+12 |     I = 1
+   |     ^
+   |
+
+
+F841 [*] Local variable `I` is assigned to but never used
+  --> suppressions.py:12:5
+   |
+10 |     # Should also generate an "unmatched suppression" warning.
+11 |     # ruff:disable[E741,F841]
+12 |     I = 1
+   |     ^
+   |
+help: Remove assignment to unused variable `I`
+9  |     # These should both be ignored by the implicit range suppression.
+10 |     # Should also generate an "unmatched suppression" warning.
+11 |     # ruff:disable[E741,F841]
+   -     I = 1
+12 +     pass
+13 | 
+14 | 
+15 | def f():
+note: This is an unsafe fix and may change runtime behavior
+
+
+E741 Ambiguous variable name: `I`
+  --> suppressions.py:26:5
+   |
+24 |     # the other logged to the user.
+25 |     # ruff: disable[E741]
+26 |     I = 1
+   |     ^
+27 |     # ruff: enable[E741]
+   |
+
+
+E741 Ambiguous variable name: `l`
+  --> suppressions.py:35:5
+   |
+33 |     # middle line should be completely silenced.
+34 |     # ruff: disable[E741]
+35 |     l = 0
+   |     ^
+36 |     # ruff: disable[F841]
+37 |     O = 1
+   |
+
+
+E741 Ambiguous variable name: `O`
+  --> suppressions.py:37:5
+   |
+35 |     l = 0
+36 |     # ruff: disable[F841]
+37 |     O = 1
+   |     ^
+38 |     # ruff: enable[E741]
+39 |     I = 2
+   |
+
+
+F841 [*] Local variable `O` is assigned to but never used
+  --> suppressions.py:37:5
+   |
+35 |     l = 0
+36 |     # ruff: disable[F841]
+37 |     O = 1
+   |     ^
+38 |     # ruff: enable[E741]
+39 |     I = 2
+   |
+help: Remove assignment to unused variable `O`
+34 |     # ruff: disable[E741]
+35 |     l = 0
+36 |     # ruff: disable[F841]
+   -     O = 1
+37 |     # ruff: enable[E741]
+38 |     I = 2
+39 |     # ruff: enable[F841]
+note: This is an unsafe fix and may change runtime behavior
+
+
+F841 [*] Local variable `I` is assigned to but never used
+  --> suppressions.py:39:5
+   |
+37 |     O = 1
+38 |     # ruff: enable[E741]
+39 |     I = 2
+   |     ^
+40 |     # ruff: enable[F841]
+   |
+help: Remove assignment to unused variable `I`
+36 |     # ruff: disable[F841]
+37 |     O = 1
+38 |     # ruff: enable[E741]
+   -     I = 2
+39 |     # ruff: enable[F841]
+40 | 
+41 | 
+note: This is an unsafe fix and may change runtime behavior
+
+
+
+--- Added ---
+RUF100 [*] Unused `noqa` directive (unused: `E741`, `F841`)
+  --> suppressions.py:55:12
+   |
+53 |     # and an unusued noqa diagnostic should be logged.
+54 |     # ruff:disable[E741,F841]
+55 |     I = 1  # noqa: E741,F841
+   |            ^^^^^^^^^^^^^^^^^
+56 |     # ruff:enable[E741,F841]
+   |
+help: Remove unused `noqa` directive
+52 |     # These should both be ignored by the range suppression,
+53 |     # and an unusued noqa diagnostic should be logged.
+54 |     # ruff:disable[E741,F841]
+   -     I = 1  # noqa: E741,F841
+55 +     I = 1
+56 |     # ruff:enable[E741,F841]

crates/ruff_linter/src/settings/mod.rs

@@ -465,6 +465,12 @@ impl LinterSettings {
         self
     }
 
+    #[must_use]
+    pub fn with_preview_mode(mut self) -> Self {
+        self.preview = PreviewMode::Enabled;
+        self
+    }
+
     /// Resolve the [`TargetVersion`] to use for linting.
     ///
     /// This method respects the per-file version overrides in

crates/ruff_linter/src/suppression.rs

@@ -1,5 +1,6 @@
 use compact_str::CompactString;
 use core::fmt;
+use ruff_db::diagnostic::Diagnostic;
 use ruff_python_ast::token::{TokenKind, Tokens};
 use ruff_python_ast::whitespace::indentation;
 use std::{error::Error, fmt::Formatter};
@@ -9,6 +10,9 @@ use ruff_python_trivia::Cursor;
 use ruff_text_size::{Ranged, TextLen, TextRange, TextSize, TextSlice};
 use smallvec::{SmallVec, smallvec};
 
+use crate::preview::is_range_suppressions_enabled;
+use crate::settings::LinterSettings;
+
 #[allow(unused)]
 #[derive(Clone, Debug, Eq, PartialEq)]
 enum SuppressionAction {
@@ -98,8 +102,8 @@ pub(crate) struct InvalidSuppression {
 }
 
 #[allow(unused)]
-#[derive(Debug)]
-pub(crate) struct Suppressions {
+#[derive(Debug, Default)]
+pub struct Suppressions {
     /// Valid suppression ranges with associated comments
     valid: Vec<Suppression>,
 
@@ -112,9 +116,41 @@ pub(crate) struct Suppressions {
 
 #[allow(unused)]
 impl Suppressions {
-    pub(crate) fn from_tokens(source: &str, tokens: &Tokens) -> Suppressions {
-        let builder = SuppressionsBuilder::new(source);
-        builder.load_from_tokens(tokens)
+    pub fn from_tokens(settings: &LinterSettings, source: &str, tokens: &Tokens) -> Suppressions {
+        if is_range_suppressions_enabled(settings) {
+            let builder = SuppressionsBuilder::new(source);
+            builder.load_from_tokens(tokens)
+        } else {
+            Suppressions::default()
+        }
+    }
+
+    pub(crate) fn is_empty(&self) -> bool {
+        self.valid.is_empty()
+    }
+
+    /// Check if a diagnostic is suppressed by any known range suppressions
+    pub(crate) fn check_diagnostic(&self, diagnostic: &Diagnostic) -> bool {
+        if self.valid.is_empty() {
+            return false;
+        }
+
+        let Some(code) = diagnostic.secondary_code() else {
+            return false;
+        };
+        let Some(span) = diagnostic.primary_span() else {
+            return false;
+        };
+        let Some(range) = span.range() else {
+            return false;
+        };
+
+        for suppression in &self.valid {
+            if *code == suppression.code.as_str() && suppression.range.contains_range(range) {
+                return true;
+            }
+        }
+        false
     }
 }
 
@@ -457,9 +493,12 @@ mod tests {
     use ruff_text_size::{TextRange, TextSize};
     use similar::DiffableStr;
 
-    use crate::suppression::{
-        InvalidSuppression, ParseError, Suppression, SuppressionAction, SuppressionComment,
-        SuppressionParser, Suppressions,
+    use crate::{
+        settings::LinterSettings,
+        suppression::{
+            InvalidSuppression, ParseError, Suppression, SuppressionAction, SuppressionComment,
+            SuppressionParser, Suppressions,
+        },
     };
 
     #[test]
@@ -1376,7 +1415,11 @@ def bar():
         /// Parse all suppressions and errors in a module for testing
         fn debug(source: &'_ str) -> DebugSuppressions<'_> {
             let parsed = parse(source, ParseOptions::from(Mode::Module)).unwrap();
-            let suppressions = Suppressions::from_tokens(source, parsed.tokens());
+            let suppressions = Suppressions::from_tokens(
+                &LinterSettings::default().with_preview_mode(),
+                source,
+                parsed.tokens(),
+            );
             DebugSuppressions {
                 source,
                 suppressions,

crates/ruff_linter/src/test.rs

@@ -32,6 +32,7 @@ use crate::packaging::detect_package_root;
 use crate::settings::types::UnsafeFixes;
 use crate::settings::{LinterSettings, flags};
 use crate::source_kind::SourceKind;
+use crate::suppression::Suppressions;
 use crate::{Applicability, FixAvailability};
 use crate::{Locator, directives};
 
@@ -234,6 +235,7 @@ pub(crate) fn test_contents<'a>(
         &locator,
         &indexer,
     );
+    let suppressions = Suppressions::from_tokens(settings, locator.contents(), parsed.tokens());
     let messages = check_path(
         path,
         path.parent()
@@ -249,6 +251,7 @@ pub(crate) fn test_contents<'a>(
         source_type,
         &parsed,
         target_version,
+        &suppressions,
     );
 
     let source_has_errors = parsed.has_invalid_syntax();
@@ -299,6 +302,8 @@ pub(crate) fn test_contents<'a>(
                 &indexer,
             );
 
+            let suppressions =
+                Suppressions::from_tokens(settings, locator.contents(), parsed.tokens());
             let fixed_messages = check_path(
                 path,
                 None,
@@ -312,6 +317,7 @@ pub(crate) fn test_contents<'a>(
                 source_type,
                 &parsed,
                 target_version,
+                &suppressions,
             );
 
             if parsed.has_invalid_syntax() && !source_has_errors {

crates/ruff_python_stdlib/src/typing.rs

@@ -326,7 +326,15 @@ pub fn is_immutable_return_type(qualified_name: &[&str]) -> bool {
             | ["re", "compile"]
             | [
                 "",
-                "bool" | "bytes" | "complex" | "float" | "frozenset" | "int" | "str" | "tuple"
+                "bool"
+                    | "bytes"
+                    | "complex"
+                    | "float"
+                    | "frozenset"
+                    | "int"
+                    | "str"
+                    | "tuple"
+                    | "slice"
             ]
     )
 }

crates/ruff_server/src/lint.rs

@@ -20,6 +20,7 @@ use ruff_linter::{
     packaging::detect_package_root,
     settings::flags,
     source_kind::SourceKind,
+    suppression::Suppressions,
 };
 use ruff_notebook::Notebook;
 use ruff_python_codegen::Stylist;
@@ -118,6 +119,10 @@ pub(crate) fn check(
     // Extract the `# noqa` and `# isort: skip` directives from the source.
     let directives = extract_directives(parsed.tokens(), Flags::all(), &locator, &indexer);
 
+    // Parse range suppression comments
+    let suppressions =
+        Suppressions::from_tokens(&settings.linter, locator.contents(), parsed.tokens());
+
     // Generate checks.
     let diagnostics = check_path(
         &document_path,
@@ -132,6 +137,7 @@ pub(crate) fn check(
         source_type,
         &parsed,
         target_version,
+        &suppressions,
     );
 
     let noqa_edits = generate_noqa_edits(
@@ -142,6 +148,7 @@ pub(crate) fn check(
         &settings.linter.external,
         &directives.noqa_line_for,
         stylist.line_ending(),
+        &suppressions,
     );
 
     let mut diagnostics_map = DiagnosticsMap::default();

crates/ruff_source_file/src/line_index.rs

@@ -33,26 +33,29 @@ impl LineIndex {
         line_starts.push(TextSize::default());
 
         let bytes = text.as_bytes();
-        let mut utf8 = false;
 
         assert!(u32::try_from(bytes.len()).is_ok());
 
-        for (i, byte) in bytes.iter().enumerate() {
-            utf8 |= !byte.is_ascii();
-
-            match byte {
-                // Only track one line break for `\r\n`.
-                b'\r' if bytes.get(i + 1) == Some(&b'\n') => continue,
-                b'\n' | b'\r' => {
-                    // SAFETY: Assertion above guarantees `i <= u32::MAX`
-                    #[expect(clippy::cast_possible_truncation)]
-                    line_starts.push(TextSize::from(i as u32) + TextSize::from(1));
-                }
-                _ => {}
+        for i in memchr::memchr2_iter(b'\n', b'\r', bytes) {
+            // Skip `\r` in `\r\n` sequences (only count the `\n`).
+            if bytes[i] == b'\r' && bytes.get(i + 1) == Some(&b'\n') {
+                continue;
             }
+            // SAFETY: Assertion above guarantees `i <= u32::MAX`
+            #[expect(clippy::cast_possible_truncation)]
+            line_starts.push(TextSize::from(i as u32) + TextSize::from(1));
         }
 
-        let kind = if utf8 {
+        // Determine whether the source text is ASCII.
+        //
+        // Empirically, this simple loop is auto-vectorized by LLVM and benchmarks faster than both
+        // `str::is_ascii()` and hand-written SIMD.
+        let mut has_non_ascii = false;
+        for byte in bytes {
+            has_non_ascii |= !byte.is_ascii();
+        }
+
+        let kind = if has_non_ascii {
             IndexKind::Utf8
         } else {
             IndexKind::Ascii

crates/ruff_wasm/src/lib.rs

@@ -2,6 +2,7 @@ use std::path::Path;
 
 use js_sys::Error;
 use ruff_linter::settings::types::PythonVersion;
+use ruff_linter::suppression::Suppressions;
 use serde::{Deserialize, Serialize};
 use wasm_bindgen::prelude::*;
 
@@ -212,6 +213,9 @@ impl Workspace {
             &indexer,
         );
 
+        let suppressions =
+            Suppressions::from_tokens(&self.settings.linter, locator.contents(), parsed.tokens());
+
         // Generate checks.
         let diagnostics = check_path(
             Path::new("<filename>"),
@@ -226,6 +230,7 @@ impl Workspace {
             source_type,
             &parsed,
             target_version,
+            &suppressions,
         );
 
         let source_code = locator.to_source_code();

crates/ty/tests/cli/python_environment.rs

@@ -43,7 +43,7 @@ fn config_override_python_version() -> anyhow::Result<()> {
       |
     2 | [tool.ty.environment]
     3 | python-version = "3.11"
-      |                  ^^^^^^ Python 3.11 assumed due to this configuration setting
+      |                  ^^^^^^ Python version configuration
       |
     info: rule `unresolved-attribute` is enabled by default
 
@@ -143,7 +143,7 @@ fn config_file_annotation_showing_where_python_version_set_typing_error() -> any
         ),
     ])?;
 
-    assert_cmd_snapshot!(case.command(), @r###"
+    assert_cmd_snapshot!(case.command(), @r#"
     success: false
     exit_code: 1
     ----- stdout -----
@@ -159,14 +159,14 @@ fn config_file_annotation_showing_where_python_version_set_typing_error() -> any
       |
     2 | [tool.ty.environment]
     3 | python-version = "3.8"
-      |                  ^^^^^ Python 3.8 assumed due to this configuration setting
+      |                  ^^^^^ Python version configuration
       |
     info: rule `unresolved-reference` is enabled by default
 
     Found 1 diagnostic
 
     ----- stderr -----
-    "###);
+    "#);
 
     assert_cmd_snapshot!(case.command().arg("--python-version=3.9"), @r###"
     success: false
@@ -772,7 +772,7 @@ fn pyvenv_cfg_file_annotation_showing_where_python_version_set() -> anyhow::Resu
         ("test.py", "aiter"),
     ])?;
 
-    assert_cmd_snapshot!(case.command(), @r###"
+    assert_cmd_snapshot!(case.command(), @r"
     success: false
     exit_code: 1
     ----- stdout -----
@@ -787,7 +787,7 @@ fn pyvenv_cfg_file_annotation_showing_where_python_version_set() -> anyhow::Resu
      --> venv/pyvenv.cfg:2:11
       |
     2 | version = 3.8
-      |           ^^^ Python version inferred from virtual environment metadata file
+      |           ^^^ Virtual environment metadata
     3 | home = foo/bar/bin
       |
     info: No Python version was specified on the command line or in a configuration file
@@ -796,7 +796,7 @@ fn pyvenv_cfg_file_annotation_showing_where_python_version_set() -> anyhow::Resu
     Found 1 diagnostic
 
     ----- stderr -----
-    "###);
+    ");
 
     Ok(())
 }
@@ -831,7 +831,7 @@ fn pyvenv_cfg_file_annotation_no_trailing_newline() -> anyhow::Result<()> {
         ("test.py", "aiter"),
     ])?;
 
-    assert_cmd_snapshot!(case.command(), @r###"
+    assert_cmd_snapshot!(case.command(), @r"
     success: false
     exit_code: 1
     ----- stdout -----
@@ -846,7 +846,7 @@ fn pyvenv_cfg_file_annotation_no_trailing_newline() -> anyhow::Result<()> {
      --> venv/pyvenv.cfg:4:23
       |
     4 |             version = 3.8
-      |                       ^^^ Python version inferred from virtual environment metadata file
+      |                       ^^^ Virtual environment metadata
       |
     info: No Python version was specified on the command line or in a configuration file
     info: rule `unresolved-reference` is enabled by default
@@ -854,7 +854,7 @@ fn pyvenv_cfg_file_annotation_no_trailing_newline() -> anyhow::Result<()> {
     Found 1 diagnostic
 
     ----- stderr -----
-    "###);
+    ");
 
     Ok(())
 }
@@ -898,7 +898,7 @@ fn config_file_annotation_showing_where_python_version_set_syntax_error() -> any
       |
     2 | [project]
     3 | requires-python = ">=3.8"
-      |                   ^^^^^^^ Python 3.8 assumed due to this configuration setting
+      |                   ^^^^^^^ Python version configuration
       |
 
     Found 1 diagnostic
@@ -1206,7 +1206,7 @@ fn defaults_to_a_new_python_version() -> anyhow::Result<()> {
       |
     2 | [environment]
     3 | python-version = "3.10"
-      |                  ^^^^^^ Python 3.10 assumed due to this configuration setting
+      |                  ^^^^^^ Python version configuration
     4 | python-platform = "linux"
       |
     info: rule `unresolved-attribute` is enabled by default
@@ -1225,7 +1225,7 @@ fn defaults_to_a_new_python_version() -> anyhow::Result<()> {
       |
     2 | [environment]
     3 | python-version = "3.10"
-      |                  ^^^^^^ Python 3.10 assumed due to this configuration setting
+      |                  ^^^^^^ Python version configuration
     4 | python-platform = "linux"
       |
     info: rule `unresolved-import` is enabled by default

crates/ty_completion_eval/completion-evaluation-tasks.csv

@@ -1,4 +1,7 @@
 name,file,index,rank
+auto-import-includes-modules,main.py,0,1
+auto-import-includes-modules,main.py,1,7
+auto-import-includes-modules,main.py,2,1
 auto-import-skips-current-module,main.py,0,1
 fstring-completions,main.py,0,1
 higher-level-symbols-preferred,main.py,0,
@@ -11,9 +14,9 @@ import-deprioritizes-type_check_only,main.py,2,1
 import-deprioritizes-type_check_only,main.py,3,2
 import-deprioritizes-type_check_only,main.py,4,3
 import-keyword-completion,main.py,0,1
-internal-typeshed-hidden,main.py,0,4
+internal-typeshed-hidden,main.py,0,2
 none-completion,main.py,0,2
-numpy-array,main.py,0,
+numpy-array,main.py,0,159
 numpy-array,main.py,1,1
 object-attr-instance-methods,main.py,0,1
 object-attr-instance-methods,main.py,1,1
@@ -23,6 +26,6 @@ scope-existing-over-new-import,main.py,0,1
 scope-prioritize-closer,main.py,0,2
 scope-simple-long-identifier,main.py,0,1
 tstring-completions,main.py,0,1
-ty-extensions-lower-stdlib,main.py,0,8
+ty-extensions-lower-stdlib,main.py,0,9
 type-var-typing-over-ast,main.py,0,3
-type-var-typing-over-ast,main.py,1,275
+type-var-typing-over-ast,main.py,1,251

crates/ty_completion_eval/src/main.rs

@@ -506,9 +506,21 @@ struct CompletionAnswer {
 impl CompletionAnswer {
     /// Returns true when this answer matches the completion given.
     fn matches(&self, completion: &Completion) -> bool {
+        if let Some(ref qualified) = completion.qualified {
+            if qualified.as_str() == self.qualified() {
+                return true;
+            }
+        }
         self.symbol == completion.name.as_str()
             && self.module.as_deref() == completion.module_name.map(ModuleName::as_str)
     }
+
+    fn qualified(&self) -> String {
+        self.module
+            .as_ref()
+            .map(|module| format!("{module}.{}", self.symbol))
+            .unwrap_or_else(|| self.symbol.clone())
+    }
 }
 
 /// Copy the Python project from `src_dir` to `dst_dir`.

crates/ty_completion_eval/truth/auto-import-includes-modules/completion.toml

@@ -0,0 +1,2 @@
+[settings]
+auto-import = true

crates/ty_completion_eval/truth/auto-import-includes-modules/main.py

@@ -0,0 +1,3 @@
+multiprocess<CURSOR: multiprocessing>
+collect<CURSOR: collections>
+collabc<CURSOR: collections.abc>

crates/ty_completion_eval/truth/auto-import-includes-modules/pyproject.toml

@@ -0,0 +1,5 @@
+[project]
+name = "test"
+version = "0.1.0"
+requires-python = ">=3.13"
+dependencies = []

crates/ty_completion_eval/truth/auto-import-includes-modules/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 3
+requires-python = ">=3.13"
+
+[[package]]
+name = "test"
+version = "0.1.0"
+source = { virtual = "." }

crates/ty_ide/src/all_symbols.rs

@@ -2,7 +2,10 @@ use ruff_db::files::File;
 use ty_project::Db;
 use ty_python_semantic::{Module, ModuleName, all_modules, resolve_real_shadowable_module};
 
-use crate::symbols::{QueryPattern, SymbolInfo, symbols_for_file_global_only};
+use crate::{
+    SymbolKind,
+    symbols::{QueryPattern, SymbolInfo, symbols_for_file_global_only},
+};
 
 /// Get all symbols matching the query string.
 ///
@@ -36,18 +39,39 @@ pub fn all_symbols<'db>(
                 let Some(file) = module.file(&*db) else {
                     continue;
                 };
+                // By convention, modules starting with an underscore
+                // are generally considered unexported. However, we
+                // should consider first party modules fair game.
+                //
+                // Note that we apply this recursively. e.g.,
+                // `numpy._core.multiarray` is considered private
+                // because it's a child of `_core`.
+                if module.name(&*db).components().any(|c| c.starts_with('_'))
+                    && module
+                        .search_path(&*db)
+                        .is_none_or(|sp| !sp.is_first_party())
+                {
+                    continue;
+                }
                 // TODO: also make it available in `TYPE_CHECKING` blocks
                 // (we'd need https://github.com/astral-sh/ty/issues/1553 to do this well)
                 if !is_typing_extensions_available && module.name(&*db) == &typing_extensions {
                     continue;
                 }
                 s.spawn(move |_| {
+                    if query.is_match_symbol_name(module.name(&*db)) {
+                        results.lock().unwrap().push(AllSymbolInfo {
+                            symbol: None,
+                            module,
+                            file,
+                        });
+                    }
                     for (_, symbol) in symbols_for_file_global_only(&*db, file).search(query) {
                         // It seems like we could do better here than
                         // locking `results` for every single symbol,
                         // but this works pretty well as it is.
                         results.lock().unwrap().push(AllSymbolInfo {
-                            symbol: symbol.to_owned(),
+                            symbol: Some(symbol.to_owned()),
                             module,
                             file,
                         });
@@ -59,8 +83,16 @@ pub fn all_symbols<'db>(
 
     let mut results = results.into_inner().unwrap();
     results.sort_by(|s1, s2| {
-        let key1 = (&s1.symbol.name, s1.file.path(db).as_str());
-        let key2 = (&s2.symbol.name, s2.file.path(db).as_str());
+        let key1 = (
+            s1.name_in_file()
+                .unwrap_or_else(|| s1.module().name(db).as_str()),
+            s1.file.path(db).as_str(),
+        );
+        let key2 = (
+            s2.name_in_file()
+                .unwrap_or_else(|| s2.module().name(db).as_str()),
+            s2.file.path(db).as_str(),
+        );
         key1.cmp(&key2)
     });
     results
@@ -71,14 +103,53 @@ pub fn all_symbols<'db>(
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AllSymbolInfo<'db> {
     /// The symbol information.
-    pub symbol: SymbolInfo<'static>,
+    ///
+    /// When absent, this implies the symbol is the module itself.
+    symbol: Option<SymbolInfo<'static>>,
     /// The module containing the symbol.
-    pub module: Module<'db>,
+    module: Module<'db>,
     /// The file containing the symbol.
     ///
     /// This `File` is guaranteed to be the same
     /// as the `File` underlying `module`.
-    pub file: File,
+    file: File,
+}
+
+impl<'db> AllSymbolInfo<'db> {
+    /// Returns the name of this symbol as it exists in a file.
+    ///
+    /// When absent, there is no concrete symbol in a module
+    /// somewhere. Instead, this represents importing a module.
+    /// In this case, if the caller needs a symbol name, they
+    /// should use `AllSymbolInfo::module().name()`.
+    pub fn name_in_file(&self) -> Option<&str> {
+        self.symbol.as_ref().map(|symbol| &*symbol.name)
+    }
+
+    /// Returns the "kind" of this symbol.
+    ///
+    /// The kind of a symbol in the context of auto-import is
+    /// determined on a best effort basis. It may be imprecise
+    /// in some cases, e.g., reporting a module as a variable.
+    pub fn kind(&self) -> SymbolKind {
+        self.symbol
+            .as_ref()
+            .map(|symbol| symbol.kind)
+            .unwrap_or(SymbolKind::Module)
+    }
+
+    /// Returns the module this symbol is exported from.
+    pub fn module(&self) -> Module<'db> {
+        self.module
+    }
+
+    /// Returns the `File` corresponding to the module.
+    ///
+    /// This is always equivalent to
+    /// `AllSymbolInfo::module().file().unwrap()`.
+    pub fn file(&self) -> File {
+        self.file
+    }
 }
 
 #[cfg(test)]
@@ -162,25 +233,31 @@ ABCDEFGHIJKLMNOP = 'https://api.example.com'
                 return "No symbols found".to_string();
             }
 
-            self.render_diagnostics(symbols.into_iter().map(AllSymbolDiagnostic::new))
+            self.render_diagnostics(symbols.into_iter().map(|symbol_info| AllSymbolDiagnostic {
+                db: &self.db,
+                symbol_info,
+            }))
         }
     }
 
     struct AllSymbolDiagnostic<'db> {
+        db: &'db dyn Db,
         symbol_info: AllSymbolInfo<'db>,
     }
 
-    impl<'db> AllSymbolDiagnostic<'db> {
-        fn new(symbol_info: AllSymbolInfo<'db>) -> Self {
-            Self { symbol_info }
-        }
-    }
-
     impl IntoDiagnostic for AllSymbolDiagnostic<'_> {
         fn into_diagnostic(self) -> Diagnostic {
-            let symbol_kind_str = self.symbol_info.symbol.kind.to_string();
+            let symbol_kind_str = self.symbol_info.kind().to_string();
 
-            let info_text = format!("{} {}", symbol_kind_str, self.symbol_info.symbol.name);
+            let info_text = format!(
+                "{} {}",
+                symbol_kind_str,
+                self.symbol_info.name_in_file().unwrap_or_else(|| self
+                    .symbol_info
+                    .module()
+                    .name(self.db)
+                    .as_str())
+            );
 
             let sub = SubDiagnostic::new(SubDiagnosticSeverity::Info, info_text);
 
@@ -189,9 +266,12 @@ ABCDEFGHIJKLMNOP = 'https://api.example.com'
                 Severity::Info,
                 "AllSymbolInfo".to_string(),
             );
-            main.annotate(Annotation::primary(
-                Span::from(self.symbol_info.file).with_range(self.symbol_info.symbol.name_range),
-            ));
+
+            let mut span = Span::from(self.symbol_info.file());
+            if let Some(ref symbol) = self.symbol_info.symbol {
+                span = span.with_range(symbol.name_range);
+            }
+            main.annotate(Annotation::primary(span));
             main.sub(sub);
 
             main

crates/ty_ide/src/code_action.rs

@@ -5,7 +5,8 @@ use ruff_diagnostics::Edit;
 use ruff_text_size::TextRange;
 use ty_project::Db;
 use ty_python_semantic::create_suppression_fix;
-use ty_python_semantic::types::UNRESOLVED_REFERENCE;
+use ty_python_semantic::lint::LintId;
+use ty_python_semantic::types::{UNDEFINED_REVEAL, UNRESOLVED_REFERENCE};
 
 /// A `QuickFix` Code Action
 #[derive(Debug, Clone)]
@@ -28,12 +29,17 @@ pub fn code_actions(
 
     let mut actions = Vec::new();
 
-    if lint_id.name() == UNRESOLVED_REFERENCE.name()
+    // Suggest imports for unresolved references (often ideal)
+    // TODO: suggest qualifying with an already imported symbol
+    let is_unresolved_reference =
+        lint_id == LintId::of(&UNRESOLVED_REFERENCE) || lint_id == LintId::of(&UNDEFINED_REVEAL);
+    if is_unresolved_reference
         && let Some(import_quick_fix) = create_import_symbol_quick_fix(db, file, diagnostic_range)
     {
         actions.extend(import_quick_fix);
     }
 
+    // Suggest just suppressing the lint (always a valid option, but never ideal)
     actions.push(QuickFix {
         title: format!("Ignore '{}' for this line", lint_id.name()),
         edits: create_suppression_fix(db, file, lint_id, diagnostic_range).into_edits(),

crates/ty_ide/src/completion.rs

@@ -9,6 +9,7 @@ use ruff_python_ast::token::{Token, TokenAt, TokenKind, Tokens};
 use ruff_python_ast::{self as ast, AnyNodeRef};
 use ruff_python_codegen::Stylist;
 use ruff_text_size::{Ranged, TextLen, TextRange, TextSize};
+use rustc_hash::FxHashSet;
 use ty_python_semantic::types::UnionType;
 use ty_python_semantic::{
     Completion as SemanticCompletion, KnownModule, ModuleName, NameKind, SemanticModel,
@@ -20,7 +21,7 @@ use crate::find_node::covering_node;
 use crate::goto::Definitions;
 use crate::importer::{ImportRequest, Importer};
 use crate::symbols::QueryPattern;
-use crate::{Db, all_symbols};
+use crate::{Db, all_symbols, signature_help};
 
 /// A collection of completions built up from various sources.
 #[derive(Clone)]
@@ -74,7 +75,7 @@ impl<'db> Completions<'db> {
             .into_iter()
             .filter_map(|item| {
                 Some(ImportEdit {
-                    label: format!("import {}.{}", item.module_name?, item.name),
+                    label: format!("import {}", item.qualified?),
                     edit: item.import?,
                 })
             })
@@ -160,6 +161,10 @@ impl<'db> Extend<Completion<'db>> for Completions<'db> {
 pub struct Completion<'db> {
     /// The label shown to the user for this suggestion.
     pub name: Name,
+    /// The fully qualified name, when available.
+    ///
+    /// This is only set when `module_name` is available.
+    pub qualified: Option<Name>,
     /// The text that should be inserted at the cursor
     /// when the completion is selected.
     ///
@@ -225,6 +230,7 @@ impl<'db> Completion<'db> {
         let is_type_check_only = semantic.is_type_check_only(db);
         Completion {
             name: semantic.name,
+            qualified: None,
             insert: None,
             ty: semantic.ty,
             kind: None,
@@ -306,6 +312,7 @@ impl<'db> Completion<'db> {
     fn keyword(name: &str) -> Self {
         Completion {
             name: name.into(),
+            qualified: None,
             insert: None,
             ty: None,
             kind: Some(CompletionKind::Keyword),
@@ -321,6 +328,7 @@ impl<'db> Completion<'db> {
     fn value_keyword(name: &str, ty: Type<'db>) -> Completion<'db> {
         Completion {
             name: name.into(),
+            qualified: None,
             insert: None,
             ty: Some(ty),
             kind: Some(CompletionKind::Keyword),
@@ -429,6 +437,10 @@ pub fn completion<'db>(
                 );
             }
         }
+
+        if let Some(arg_completions) = detect_function_arg_completions(db, file, &parsed, offset) {
+            completions.extend(arg_completions);
+        }
     }
 
     if is_raising_exception(tokens) {
@@ -444,10 +456,89 @@ pub fn completion<'db>(
             !ty.is_notimplemented(db)
         });
     }
-
     completions.into_completions()
 }
 
+/// Detect and construct completions for unset function arguments.
+///
+/// Suggestions are only provided if the cursor is currently inside a
+/// function call and the function arguments have not 1) already been
+/// set and 2) been defined as positional-only.
+fn detect_function_arg_completions<'db>(
+    db: &'db dyn Db,
+    file: File,
+    parsed: &ParsedModuleRef,
+    offset: TextSize,
+) -> Option<Vec<Completion<'db>>> {
+    let sig_help = signature_help(db, file, offset)?;
+    let set_function_args = detect_set_function_args(parsed, offset);
+
+    let completions = sig_help
+        .signatures
+        .iter()
+        .flat_map(|sig| &sig.parameters)
+        .filter(|p| !p.is_positional_only && !set_function_args.contains(&p.name.as_str()))
+        .map(|p| {
+            let name = Name::new(&p.name);
+            let documentation = p
+                .documentation
+                .as_ref()
+                .map(|d| Docstring::new(d.to_owned()));
+            let insert = Some(format!("{name}=").into_boxed_str());
+            Completion {
+                name,
+                qualified: None,
+                insert,
+                ty: p.ty,
+                kind: Some(CompletionKind::Variable),
+                module_name: None,
+                import: None,
+                builtin: false,
+                is_type_check_only: false,
+                is_definitively_raisable: false,
+                documentation,
+            }
+        })
+        .collect();
+    Some(completions)
+}
+
+/// Returns function arguments that have already been set.
+///
+/// If `offset` is inside an arguments node, this returns
+/// the list of argument names that are already set.
+///
+/// For example, given:
+///
+/// ```python
+/// def abc(foo, bar, baz): ...
+/// abc(foo=1, bar=2, b<CURSOR>)
+/// ```
+///
+/// the resulting value is `["foo", "bar"]`
+///
+/// This is useful to be able to exclude autocomplete suggestions
+/// for arguments that have already been set to some value.
+///
+/// If the parent node is not an arguments node, the return value
+/// is an empty Vec.
+fn detect_set_function_args(parsed: &ParsedModuleRef, offset: TextSize) -> FxHashSet<&str> {
+    let range = TextRange::empty(offset);
+    covering_node(parsed.syntax().into(), range)
+        .parent()
+        .and_then(|node| match node {
+            ast::AnyNodeRef::Arguments(args) => Some(args),
+            _ => None,
+        })
+        .map(|args| {
+            args.keywords
+                .iter()
+                .filter_map(|kw| kw.arg.as_ref().map(|ident| ident.id.as_str()))
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
 pub(crate) struct ImportEdit {
     pub label: String,
     pub edit: Edit,
@@ -537,12 +628,22 @@ fn add_unimported_completions<'db>(
     let members = importer.members_in_scope_at(scoped.node, scoped.node.start());
 
     for symbol in all_symbols(db, file, &completions.query) {
-        if symbol.module.file(db) == Some(file) || symbol.module.is_known(db, KnownModule::Builtins)
-        {
+        if symbol.file() == file || symbol.module().is_known(db, KnownModule::Builtins) {
             continue;
         }
 
-        let request = create_import_request(symbol.module.name(db), &symbol.symbol.name);
+        let module_name = symbol.module().name(db);
+        let (name, qualified, request) = symbol
+            .name_in_file()
+            .map(|name| {
+                let qualified = format!("{module_name}.{name}");
+                (name, qualified, create_import_request(module_name, name))
+            })
+            .unwrap_or_else(|| {
+                let name = module_name.as_str();
+                let qualified = name.to_string();
+                (name, qualified, ImportRequest::module(name))
+            });
         // FIXME: `all_symbols` doesn't account for wildcard imports.
         // Since we're looking at every module, this is probably
         // "fine," but it might mean that we import a symbol from the
@@ -551,11 +652,12 @@ fn add_unimported_completions<'db>(
         // N.B. We use `add` here because `all_symbols` already
         // takes our query into account.
         completions.force_add(Completion {
-            name: ast::name::Name::new(&symbol.symbol.name),
+            name: ast::name::Name::new(name),
+            qualified: Some(ast::name::Name::new(qualified)),
             insert: Some(import_action.symbol_text().into()),
             ty: None,
-            kind: symbol.symbol.kind.to_completion_kind(),
-            module_name: Some(symbol.module.name(db)),
+            kind: symbol.kind().to_completion_kind(),
+            module_name: Some(module_name),
             import: import_action.import().cloned(),
             builtin: false,
             // TODO: `is_type_check_only` requires inferring the type of the symbol
@@ -2368,10 +2470,11 @@ def frob(): ...
 ",
         );
 
-        // FIXME: Should include `foo`.
         assert_snapshot!(
             builder.skip_keywords().skip_builtins().build().snapshot(),
-            @"<No completions found after filtering out completions>",
+            @r"
+            foo
+            ",
         );
     }
 
@@ -2383,10 +2486,11 @@ def frob(): ...
 ",
         );
 
-        // FIXME: Should include `foo`.
         assert_snapshot!(
             builder.skip_keywords().skip_builtins().build().snapshot(),
-            @"<No completions found after filtering out completions>",
+            @r"
+            foo
+            ",
         );
     }
 
@@ -3021,7 +3125,6 @@ quux.<CURSOR>
         ");
     }
 
-    // We don't yet take function parameters into account.
     #[test]
     fn call_prefix1() {
         let builder = completion_test_builder(
@@ -3034,7 +3137,157 @@ bar(o<CURSOR>
 ",
         );
 
-        assert_snapshot!(builder.skip_keywords().skip_builtins().build().snapshot(), @"foo");
+        assert_snapshot!(
+            builder.skip_keywords().skip_builtins().build().snapshot(),
+            @r"
+        foo
+        okay
+        "
+        );
+    }
+
+    #[test]
+    fn call_keyword_only_argument() {
+        let builder = completion_test_builder(
+            "\
+def bar(*, okay): ...
+
+foo = 1
+
+bar(o<CURSOR>
+",
+        );
+
+        assert_snapshot!(
+            builder.skip_keywords().skip_builtins().build().snapshot(),
+            @r"
+        foo
+        okay
+        "
+        );
+    }
+
+    #[test]
+    fn call_multiple_keyword_arguments() {
+        let builder = completion_test_builder(
+            "\
+def foo(bar, baz, barbaz): ...
+
+foo(b<CURSOR>
+",
+        );
+
+        assert_snapshot!(
+            builder.skip_keywords().skip_builtins().build().snapshot(),
+            @r"
+        bar
+        barbaz
+        baz
+        "
+        );
+    }
+
+    #[test]
+    fn call_multiple_keyword_arguments_some_set() {
+        let builder = completion_test_builder(
+            "\
+def foo(bar, baz): ...
+
+foo(bar=1, b<CURSOR>
+",
+        );
+
+        assert_snapshot!(
+            builder.skip_keywords().skip_builtins().build().snapshot(),
+            @r"
+        baz
+        "
+        );
+    }
+
+    #[test]
+    fn call_arguments_multi_def() {
+        let builder = completion_test_builder(
+            "\
+def abc(okay, x): ...
+def bar(not_okay, y): ...
+def baz(foobarbaz, z): ...
+
+abc(o<CURSOR>
+",
+        );
+
+        assert_snapshot!(
+            builder.skip_keywords().skip_builtins().build().snapshot(),
+            @r"
+        okay
+        "
+        );
+    }
+
+    #[test]
+    fn call_arguments_cursor_middle() {
+        let builder = completion_test_builder(
+            "\
+def abc(okay, foo, bar, baz): ...
+
+abc(okay=1, ba<CURSOR> baz=5
+",
+        );
+
+        assert_snapshot!(
+            builder.skip_keywords().skip_builtins().build().snapshot(),
+            @r"
+        bar
+        "
+        );
+    }
+
+    #[test]
+    fn call_positional_only_argument() {
+        // If the parameter is positional only we don't
+        // want to suggest it as specifying by name
+        // is not valid.
+        let builder = completion_test_builder(
+            "\
+def bar(okay, /): ...
+
+foo = 1
+
+bar(o<CURSOR>
+",
+        );
+
+        assert_snapshot!(
+            builder.skip_keywords().skip_builtins().build().snapshot(),
+            @"foo"
+        );
+    }
+
+    #[test]
+    fn call_positional_only_keyword_only_argument_mix() {
+        // If the parameter is positional only we don't
+        // want to suggest it as specifying by name
+        // is not valid.
+        let builder = completion_test_builder(
+            "\
+def bar(not_okay, no, /, okay, *, okay_abc, okay_okay): ...
+
+foo = 1
+
+bar(o<CURSOR>
+",
+        );
+
+        assert_snapshot!(
+            builder.skip_keywords().skip_builtins().build().snapshot(),
+            @r"
+        foo
+        okay
+        okay_abc
+        okay_okay
+        "
+        );
     }
 
     #[test]
@@ -3052,6 +3305,7 @@ bar(<CURSOR>
         assert_snapshot!(builder.skip_keywords().skip_builtins().build().snapshot(), @r"
         bar
         foo
+        okay
         ");
     }
 
@@ -4350,7 +4604,7 @@ from os.<CURSOR>
             .build()
             .snapshot();
         assert_snapshot!(snapshot, @r"
-        Kadabra :: Literal[1] :: Current module
+        Kadabra :: Literal[1] :: <no import required>
         AbraKadabra :: Unavailable :: package
         ");
     }
@@ -5534,7 +5788,7 @@ def foo(param: s<CURSOR>)
         // Even though long_namea is alphabetically before long_nameb,
         // long_nameb is currently imported and should be preferred.
         assert_snapshot!(snapshot, @r"
-        long_nameb :: Literal[1] :: Current module
+        long_nameb :: Literal[1] :: <no import required>
         long_namea :: Unavailable :: foo
         ");
     }
@@ -5804,7 +6058,7 @@ from .imp<CURSOR>
     #[test]
     fn typing_extensions_excluded_from_import() {
         let builder = completion_test_builder("from typing<CURSOR>").module_names();
-        assert_snapshot!(builder.build().snapshot(), @"typing :: Current module");
+        assert_snapshot!(builder.build().snapshot(), @"typing :: <no import required>");
     }
 
     #[test]
@@ -5812,13 +6066,7 @@ from .imp<CURSOR>
         let builder = completion_test_builder("deprecated<CURSOR>")
             .auto_import()
             .module_names();
-        assert_snapshot!(builder.build().snapshot(), @r"
-        Deprecated :: importlib.metadata
-        DeprecatedList :: importlib.metadata
-        DeprecatedNonAbstract :: importlib.metadata
-        DeprecatedTuple :: importlib.metadata
-        deprecated :: warnings
-        ");
+        assert_snapshot!(builder.build().snapshot(), @"deprecated :: warnings");
     }
 
     #[test]
@@ -5829,8 +6077,8 @@ from .imp<CURSOR>
             .completion_test_builder()
             .module_names();
         assert_snapshot!(builder.build().snapshot(), @r"
-        typing :: Current module
-        typing_extensions :: Current module
+        typing :: <no import required>
+        typing_extensions :: <no import required>
         ");
     }
 
@@ -5843,10 +6091,6 @@ from .imp<CURSOR>
             .auto_import()
             .module_names();
         assert_snapshot!(builder.build().snapshot(), @r"
-        Deprecated :: importlib.metadata
-        DeprecatedList :: importlib.metadata
-        DeprecatedNonAbstract :: importlib.metadata
-        DeprecatedTuple :: importlib.metadata
         deprecated :: typing_extensions
         deprecated :: warnings
         ");
@@ -5859,8 +6103,8 @@ from .imp<CURSOR>
             .completion_test_builder()
             .module_names();
         assert_snapshot!(builder.build().snapshot(), @r"
-        typing :: Current module
-        typing_extensions :: Current module
+        typing :: <no import required>
+        typing_extensions :: <no import required>
         ");
     }
 
@@ -5872,15 +6116,284 @@ from .imp<CURSOR>
             .auto_import()
             .module_names();
         assert_snapshot!(builder.build().snapshot(), @r"
-        Deprecated :: importlib.metadata
-        DeprecatedList :: importlib.metadata
-        DeprecatedNonAbstract :: importlib.metadata
-        DeprecatedTuple :: importlib.metadata
         deprecated :: typing_extensions
         deprecated :: warnings
         ");
     }
 
+    #[test]
+    fn reexport_simple_import_noauto() {
+        let snapshot = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+import foo
+foo.ZQ<CURSOR>
+"#,
+            )
+            .source("foo.py", r#"from bar import ZQZQ"#)
+            .source("bar.py", r#"ZQZQ = 1"#)
+            .completion_test_builder()
+            .module_names()
+            .build()
+            .snapshot();
+        assert_snapshot!(snapshot, @"ZQZQ :: <no import required>");
+    }
+
+    #[test]
+    fn reexport_simple_import_auto() {
+        let snapshot = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+ZQ<CURSOR>
+"#,
+            )
+            .source("foo.py", r#"from bar import ZQZQ"#)
+            .source("bar.py", r#"ZQZQ = 1"#)
+            .completion_test_builder()
+            .auto_import()
+            .module_names()
+            .build()
+            .snapshot();
+        // We're specifically looking for `ZQZQ` in `bar`
+        // here but *not* in `foo`. Namely, in `foo`,
+        // `ZQZQ` is a "regular" import that is not by
+        // convention considered a re-export.
+        assert_snapshot!(snapshot, @"ZQZQ :: bar");
+    }
+
+    #[test]
+    fn reexport_redundant_convention_import_noauto() {
+        let snapshot = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+import foo
+foo.ZQ<CURSOR>
+"#,
+            )
+            .source("foo.py", r#"from bar import ZQZQ as ZQZQ"#)
+            .source("bar.py", r#"ZQZQ = 1"#)
+            .completion_test_builder()
+            .module_names()
+            .build()
+            .snapshot();
+        assert_snapshot!(snapshot, @"ZQZQ :: <no import required>");
+    }
+
+    #[test]
+    fn reexport_redundant_convention_import_auto() {
+        let snapshot = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+ZQ<CURSOR>
+"#,
+            )
+            .source("foo.py", r#"from bar import ZQZQ as ZQZQ"#)
+            .source("bar.py", r#"ZQZQ = 1"#)
+            .completion_test_builder()
+            .auto_import()
+            .module_names()
+            .build()
+            .snapshot();
+        assert_snapshot!(snapshot, @r"
+        ZQZQ :: bar
+        ZQZQ :: foo
+        ");
+    }
+
+    #[test]
+    fn auto_import_respects_all() {
+        let snapshot = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+ZQ<CURSOR>
+"#,
+            )
+            .source(
+                "bar.py",
+                r#"
+                ZQZQ1 = 1
+                ZQZQ2 = 1
+                __all__ = ['ZQZQ1']
+            "#,
+            )
+            .completion_test_builder()
+            .auto_import()
+            .module_names()
+            .build()
+            .snapshot();
+        // We specifically do not want `ZQZQ2` here, since
+        // it is not part of `__all__`.
+        assert_snapshot!(snapshot, @r"
+        ZQZQ1 :: bar
+        ");
+    }
+
+    // This test confirms current behavior (as of 2025-12-04), but
+    // it's not consistent with auto-import. That is, it doesn't
+    // strictly respect `__all__` on `bar`, but perhaps it should.
+    //
+    // See: https://github.com/astral-sh/ty/issues/1757
+    #[test]
+    fn object_attr_ignores_all() {
+        let snapshot = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+import bar
+bar.ZQ<CURSOR>
+"#,
+            )
+            .source(
+                "bar.py",
+                r#"
+                ZQZQ1 = 1
+                ZQZQ2 = 1
+                __all__ = ['ZQZQ1']
+            "#,
+            )
+            .completion_test_builder()
+            .auto_import()
+            .module_names()
+            .build()
+            .snapshot();
+        // We specifically do not want `ZQZQ2` here, since
+        // it is not part of `__all__`.
+        assert_snapshot!(snapshot, @r"
+        ZQZQ1 :: <no import required>
+        ZQZQ2 :: <no import required>
+        ");
+    }
+
+    #[test]
+    fn auto_import_ignores_modules_with_leading_underscore() {
+        let snapshot = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+Quitter<CURSOR>
+"#,
+            )
+            .completion_test_builder()
+            .auto_import()
+            .module_names()
+            .build()
+            .snapshot();
+        // There is a `Quitter` in `_sitebuiltins` in the standard
+        // library. But this is skipped by auto-import because it's
+        // 1) not first party and 2) starts with an `_`.
+        assert_snapshot!(snapshot, @"<No completions found>");
+    }
+
+    #[test]
+    fn auto_import_includes_modules_with_leading_underscore_in_first_party() {
+        let snapshot = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+ZQ<CURSOR>
+"#,
+            )
+            .source(
+                "bar.py",
+                r#"
+                ZQZQ1 = 1
+            "#,
+            )
+            .source(
+                "_foo.py",
+                r#"
+                ZQZQ1 = 1
+            "#,
+            )
+            .completion_test_builder()
+            .auto_import()
+            .module_names()
+            .build()
+            .snapshot();
+        assert_snapshot!(snapshot, @r"
+        ZQZQ1 :: _foo
+        ZQZQ1 :: bar
+        ");
+    }
+
+    #[test]
+    fn auto_import_includes_stdlib_modules_as_suggestions() {
+        let snapshot = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+multiprocess<CURSOR>
+"#,
+            )
+            .completion_test_builder()
+            .auto_import()
+            .build()
+            .snapshot();
+        assert_snapshot!(snapshot, @r"
+        multiprocessing
+        multiprocessing.connection
+        multiprocessing.context
+        multiprocessing.dummy
+        multiprocessing.dummy.connection
+        multiprocessing.forkserver
+        multiprocessing.heap
+        multiprocessing.managers
+        multiprocessing.pool
+        multiprocessing.popen_fork
+        multiprocessing.popen_forkserver
+        multiprocessing.popen_spawn_posix
+        multiprocessing.popen_spawn_win32
+        multiprocessing.process
+        multiprocessing.queues
+        multiprocessing.reduction
+        multiprocessing.resource_sharer
+        multiprocessing.resource_tracker
+        multiprocessing.shared_memory
+        multiprocessing.sharedctypes
+        multiprocessing.spawn
+        multiprocessing.synchronize
+        multiprocessing.util
+        ");
+    }
+
+    #[test]
+    fn auto_import_includes_first_party_modules_as_suggestions() {
+        let snapshot = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+zqzqzq<CURSOR>
+"#,
+            )
+            .source("zqzqzqzqzq.py", "")
+            .completion_test_builder()
+            .auto_import()
+            .build()
+            .snapshot();
+        assert_snapshot!(snapshot, @"zqzqzqzqzq");
+    }
+
+    #[test]
+    fn auto_import_includes_sub_modules_as_suggestions() {
+        let snapshot = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+collabc<CURSOR>
+"#,
+            )
+            .completion_test_builder()
+            .auto_import()
+            .build()
+            .snapshot();
+        assert_snapshot!(snapshot, @"collections.abc");
+    }
+
     /// A way to create a simple single-file (named `main.py`) completion test
     /// builder.
     ///
@@ -6055,7 +6568,7 @@ from .imp<CURSOR>
                         let module_name = c
                             .module_name
                             .map(ModuleName::as_str)
-                            .unwrap_or("Current module");
+                            .unwrap_or("<no import required>");
                         snapshot = format!("{snapshot} :: {module_name}");
                     }
                     snapshot

crates/ty_ide/src/doc_highlights.rs

@@ -230,10 +230,58 @@ calc = Calculator()
             "
 def test():
     # Cursor on a position with no symbol
-    <CURSOR>  
+    <CURSOR>
 ",
         );
 
         assert_snapshot!(test.document_highlights(), @"No highlights found");
     }
+
+    // TODO: Should only highlight the last use and the last declaration
+    #[test]
+    fn redeclarations() {
+        let test = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+                a: str = "test"
+
+                a: int = 10
+
+                print(a<CURSOR>)
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.document_highlights(), @r#"
+        info[document_highlights]: Highlight 1 (Write)
+         --> main.py:2:1
+          |
+        2 | a: str = "test"
+          | ^
+        3 |
+        4 | a: int = 10
+          |
+
+        info[document_highlights]: Highlight 2 (Write)
+         --> main.py:4:1
+          |
+        2 | a: str = "test"
+        3 |
+        4 | a: int = 10
+          | ^
+        5 |
+        6 | print(a)
+          |
+
+        info[document_highlights]: Highlight 3 (Read)
+         --> main.py:6:7
+          |
+        4 | a: int = 10
+        5 |
+        6 | print(a)
+          |       ^
+          |
+        "#);
+    }
 }

crates/ty_ide/src/docstring.rs

@@ -824,12 +824,12 @@ mod tests {
         Check out this great example code::
 
             x_y = "hello"
-            
+
             if len(x_y) > 4:
                 print(x_y)
             else:
                 print("too short :(")
-            
+
             print("done")
 
         You love to see it.
@@ -862,12 +862,12 @@ mod tests {
         Check out this great example code ::
 
             x_y = "hello"
-            
+
             if len(x_y) > 4:
                 print(x_y)
             else:
                 print("too short :(")
-            
+
             print("done")
 
         You love to see it.
@@ -901,12 +901,12 @@ mod tests {
             ::
 
             x_y = "hello"
-            
+
             if len(x_y) > 4:
                 print(x_y)
             else:
                 print("too short :(")
-            
+
             print("done")
 
         You love to see it.
@@ -939,12 +939,12 @@ mod tests {
         let docstring = r#"
         Check out this great example code::
             x_y = "hello"
-            
+
             if len(x_y) > 4:
                 print(x_y)
             else:
                 print("too short :(")
-            
+
             print("done")
         You love to see it.
         "#;
@@ -975,12 +975,12 @@ mod tests {
         Check out this great example code::
 
             x_y = "hello"
-            
+
             if len(x_y) > 4:
                 print(x_y)
             else:
                 print("too short :(")
-            
+
             print("done")"#;
 
         let docstring = Docstring::new(docstring.to_owned());

crates/ty_ide/src/find_references.rs

@@ -2113,4 +2113,52 @@ func<CURSOR>_alias()
           |
         ");
     }
+
+    // TODO: Should only return references to the last declaration
+    #[test]
+    fn declarations() {
+        let test = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+                a: str = "test"
+
+                a: int = 10
+
+                print(a<CURSOR>)
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.references(), @r#"
+        info[references]: Reference 1
+         --> main.py:2:1
+          |
+        2 | a: str = "test"
+          | ^
+        3 |
+        4 | a: int = 10
+          |
+
+        info[references]: Reference 2
+         --> main.py:4:1
+          |
+        2 | a: str = "test"
+        3 |
+        4 | a: int = 10
+          | ^
+        5 |
+        6 | print(a)
+          |
+
+        info[references]: Reference 3
+         --> main.py:6:7
+          |
+        4 | a: int = 10
+        5 |
+        6 | print(a)
+          |       ^
+          |
+        "#);
+    }
 }

crates/ty_ide/src/goto.rs

@@ -73,19 +73,29 @@ pub(crate) enum GotoTarget<'a> {
     /// ```
     ImportModuleAlias {
         alias: &'a ast::Alias,
+        asname: &'a ast::Identifier,
+    },
+
+    /// In an import statement, the named under which the symbol is exported
+    /// in the imported file.
+    ///
+    /// ```py
+    /// from foo import bar as baz
+    ///                 ^^^
+    /// ```
+    ImportExportedName {
+        alias: &'a ast::Alias,
+        import_from: &'a ast::StmtImportFrom,
     },
 
     /// Import alias in from import statement
     /// ```py
     /// from foo import bar as baz
-    ///                 ^^^
-    /// from foo import bar as baz
     ///                        ^^^
     /// ```
     ImportSymbolAlias {
         alias: &'a ast::Alias,
-        range: TextRange,
-        import_from: &'a ast::StmtImportFrom,
+        asname: &'a ast::Identifier,
     },
 
     /// Go to on the exception handler variable
@@ -290,8 +300,9 @@ impl GotoTarget<'_> {
             GotoTarget::FunctionDef(function) => function.inferred_type(model),
             GotoTarget::ClassDef(class) => class.inferred_type(model),
             GotoTarget::Parameter(parameter) => parameter.inferred_type(model),
-            GotoTarget::ImportSymbolAlias { alias, .. } => alias.inferred_type(model),
-            GotoTarget::ImportModuleAlias { alias } => alias.inferred_type(model),
+            GotoTarget::ImportSymbolAlias { alias, .. }
+            | GotoTarget::ImportModuleAlias { alias, .. }
+            | GotoTarget::ImportExportedName { alias, .. } => alias.inferred_type(model),
             GotoTarget::ExceptVariable(except) => except.inferred_type(model),
             GotoTarget::KeywordArgument { keyword, .. } => keyword.value.inferred_type(model),
             // When asking the type of a callable, usually you want the callable itself?
@@ -378,7 +389,9 @@ impl GotoTarget<'_> {
         alias_resolution: ImportAliasResolution,
     ) -> Option<Definitions<'db>> {
         let definitions = match self {
-            GotoTarget::Expression(expression) => definitions_for_expression(model, *expression),
+            GotoTarget::Expression(expression) => {
+                definitions_for_expression(model, *expression, alias_resolution)
+            }
             // For already-defined symbols, they are their own definitions
             GotoTarget::FunctionDef(function) => Some(vec![ResolvedDefinition::Definition(
                 function.definition(model),
@@ -393,22 +406,21 @@ impl GotoTarget<'_> {
             )]),
 
             // For import aliases (offset within 'y' or 'z' in "from x import y as z")
-            GotoTarget::ImportSymbolAlias {
-                alias, import_from, ..
-            } => {
-                if let Some(asname) = alias.asname.as_ref()
-                    && alias_resolution == ImportAliasResolution::PreserveAliases
-                {
-                    Some(definitions_for_name(model, asname.as_str(), asname.into()))
-                } else {
-                    let symbol_name = alias.name.as_str();
-                    Some(definitions_for_imported_symbol(
-                        model,
-                        import_from,
-                        symbol_name,
-                        alias_resolution,
-                    ))
-                }
+            GotoTarget::ImportSymbolAlias { asname, .. } => Some(definitions_for_name(
+                model,
+                asname.as_str(),
+                AnyNodeRef::from(*asname),
+                alias_resolution,
+            )),
+
+            GotoTarget::ImportExportedName { alias, import_from } => {
+                let symbol_name = alias.name.as_str();
+                Some(definitions_for_imported_symbol(
+                    model,
+                    import_from,
+                    symbol_name,
+                    alias_resolution,
+                ))
             }
 
             GotoTarget::ImportModuleComponent {
@@ -423,15 +435,12 @@ impl GotoTarget<'_> {
             }
 
             // Handle import aliases (offset within 'z' in "import x.y as z")
-            GotoTarget::ImportModuleAlias { alias } => {
-                if let Some(asname) = alias.asname.as_ref()
-                    && alias_resolution == ImportAliasResolution::PreserveAliases
-                {
-                    Some(definitions_for_name(model, asname.as_str(), asname.into()))
-                } else {
-                    definitions_for_module(model, Some(alias.name.as_str()), 0)
-                }
-            }
+            GotoTarget::ImportModuleAlias { asname, .. } => Some(definitions_for_name(
+                model,
+                asname.as_str(),
+                AnyNodeRef::from(*asname),
+                alias_resolution,
+            )),
 
             // Handle keyword arguments in call expressions
             GotoTarget::KeywordArgument {
@@ -454,12 +463,22 @@ impl GotoTarget<'_> {
             // because they're not expressions
             GotoTarget::PatternMatchRest(pattern_mapping) => {
                 pattern_mapping.rest.as_ref().map(|name| {
-                    definitions_for_name(model, name.as_str(), AnyNodeRef::Identifier(name))
+                    definitions_for_name(
+                        model,
+                        name.as_str(),
+                        AnyNodeRef::Identifier(name),
+                        alias_resolution,
+                    )
                 })
             }
 
             GotoTarget::PatternMatchAsName(pattern_as) => pattern_as.name.as_ref().map(|name| {
-                definitions_for_name(model, name.as_str(), AnyNodeRef::Identifier(name))
+                definitions_for_name(
+                    model,
+                    name.as_str(),
+                    AnyNodeRef::Identifier(name),
+                    alias_resolution,
+                )
             }),
 
             GotoTarget::PatternKeywordArgument(pattern_keyword) => {
@@ -468,12 +487,18 @@ impl GotoTarget<'_> {
                     model,
                     name.as_str(),
                     AnyNodeRef::Identifier(name),
+                    alias_resolution,
                 ))
             }
 
             GotoTarget::PatternMatchStarName(pattern_star) => {
                 pattern_star.name.as_ref().map(|name| {
-                    definitions_for_name(model, name.as_str(), AnyNodeRef::Identifier(name))
+                    definitions_for_name(
+                        model,
+                        name.as_str(),
+                        AnyNodeRef::Identifier(name),
+                        alias_resolution,
+                    )
                 })
             }
 
@@ -481,9 +506,18 @@ impl GotoTarget<'_> {
             //
             // Prefer the function impl over the callable so that its docstrings win if defined.
             GotoTarget::Call { callable, call } => {
-                let mut definitions = definitions_for_callable(model, call);
+                let mut definitions = Vec::new();
+
+                // We prefer the specific overload for hover, go-to-def etc. However,
+                // `definitions_for_callable` always resolves import aliases. That's why we
+                // skip it in cases import alias resolution is turned of (rename, highlight references).
+                if alias_resolution == ImportAliasResolution::ResolveAliases {
+                    definitions.extend(definitions_for_callable(model, call));
+                }
+
                 let expr_definitions =
-                    definitions_for_expression(model, *callable).unwrap_or_default();
+                    definitions_for_expression(model, *callable, alias_resolution)
+                        .unwrap_or_default();
                 definitions.extend(expr_definitions);
 
                 if definitions.is_empty() {
@@ -517,7 +551,7 @@ impl GotoTarget<'_> {
                 let subexpr = covering_node(subast.syntax().into(), *subrange)
                     .node()
                     .as_expr_ref()?;
-                definitions_for_expression(&submodel, subexpr)
+                definitions_for_expression(&submodel, subexpr, alias_resolution)
             }
 
             // nonlocal and global are essentially loads, but again they're statements,
@@ -527,6 +561,7 @@ impl GotoTarget<'_> {
                     model,
                     identifier.as_str(),
                     AnyNodeRef::Identifier(identifier),
+                    alias_resolution,
                 ))
             }
 
@@ -537,6 +572,7 @@ impl GotoTarget<'_> {
                     model,
                     name.as_str(),
                     AnyNodeRef::Identifier(name),
+                    alias_resolution,
                 ))
             }
 
@@ -546,6 +582,7 @@ impl GotoTarget<'_> {
                     model,
                     name.as_str(),
                     AnyNodeRef::Identifier(name),
+                    alias_resolution,
                 ))
             }
 
@@ -555,6 +592,7 @@ impl GotoTarget<'_> {
                     model,
                     name.as_str(),
                     AnyNodeRef::Identifier(name),
+                    alias_resolution,
                 ))
             }
         };
@@ -580,12 +618,9 @@ impl GotoTarget<'_> {
             GotoTarget::FunctionDef(function) => Some(Cow::Borrowed(function.name.as_str())),
             GotoTarget::ClassDef(class) => Some(Cow::Borrowed(class.name.as_str())),
             GotoTarget::Parameter(parameter) => Some(Cow::Borrowed(parameter.name.as_str())),
-            GotoTarget::ImportSymbolAlias { alias, .. } => {
-                if let Some(asname) = &alias.asname {
-                    Some(Cow::Borrowed(asname.as_str()))
-                } else {
-                    Some(Cow::Borrowed(alias.name.as_str()))
-                }
+            GotoTarget::ImportSymbolAlias { asname, .. } => Some(Cow::Borrowed(asname.as_str())),
+            GotoTarget::ImportExportedName { alias, .. } => {
+                Some(Cow::Borrowed(alias.name.as_str()))
             }
             GotoTarget::ImportModuleComponent {
                 module_name,
@@ -599,13 +634,7 @@ impl GotoTarget<'_> {
                     Some(Cow::Borrowed(module_name))
                 }
             }
-            GotoTarget::ImportModuleAlias { alias } => {
-                if let Some(asname) = &alias.asname {
-                    Some(Cow::Borrowed(asname.as_str()))
-                } else {
-                    Some(Cow::Borrowed(alias.name.as_str()))
-                }
-            }
+            GotoTarget::ImportModuleAlias { asname, .. } => Some(Cow::Borrowed(asname.as_str())),
             GotoTarget::ExceptVariable(except) => {
                 Some(Cow::Borrowed(except.name.as_ref()?.as_str()))
             }
@@ -667,7 +696,7 @@ impl GotoTarget<'_> {
                             // Is the offset within the alias name (asname) part?
                             if let Some(asname) = &alias.asname {
                                 if asname.range.contains_inclusive(offset) {
-                                    return Some(GotoTarget::ImportModuleAlias { alias });
+                                    return Some(GotoTarget::ImportModuleAlias { alias, asname });
                                 }
                             }
 
@@ -699,21 +728,13 @@ impl GotoTarget<'_> {
                             // Is the offset within the alias name (asname) part?
                             if let Some(asname) = &alias.asname {
                                 if asname.range.contains_inclusive(offset) {
-                                    return Some(GotoTarget::ImportSymbolAlias {
-                                        alias,
-                                        range: asname.range,
-                                        import_from,
-                                    });
+                                    return Some(GotoTarget::ImportSymbolAlias { alias, asname });
                                 }
                             }
 
                             // Is the offset in the original name part?
                             if alias.name.range.contains_inclusive(offset) {
-                                return Some(GotoTarget::ImportSymbolAlias {
-                                    alias,
-                                    range: alias.name.range,
-                                    import_from,
-                                });
+                                return Some(GotoTarget::ImportExportedName { alias, import_from });
                             }
 
                             None
@@ -893,12 +914,13 @@ impl Ranged for GotoTarget<'_> {
             GotoTarget::FunctionDef(function) => function.name.range,
             GotoTarget::ClassDef(class) => class.name.range,
             GotoTarget::Parameter(parameter) => parameter.name.range,
-            GotoTarget::ImportSymbolAlias { range, .. } => *range,
+            GotoTarget::ImportSymbolAlias { asname, .. } => asname.range,
+            Self::ImportExportedName { alias, .. } => alias.name.range,
             GotoTarget::ImportModuleComponent {
                 component_range, ..
             } => *component_range,
             GotoTarget::StringAnnotationSubexpr { subrange, .. } => *subrange,
-            GotoTarget::ImportModuleAlias { alias } => alias.asname.as_ref().unwrap().range,
+            GotoTarget::ImportModuleAlias { asname, .. } => asname.range,
             GotoTarget::ExceptVariable(except) => except.name.as_ref().unwrap().range,
             GotoTarget::KeywordArgument { keyword, .. } => keyword.arg.as_ref().unwrap().range,
             GotoTarget::PatternMatchRest(rest) => rest.rest.as_ref().unwrap().range,
@@ -955,12 +977,14 @@ fn convert_resolved_definitions_to_targets<'db>(
 fn definitions_for_expression<'db>(
     model: &SemanticModel<'db>,
     expression: ruff_python_ast::ExprRef<'_>,
+    alias_resolution: ImportAliasResolution,
 ) -> Option<Vec<ResolvedDefinition<'db>>> {
     match expression {
         ast::ExprRef::Name(name) => Some(definitions_for_name(
             model,
             name.id.as_str(),
             expression.into(),
+            alias_resolution,
         )),
         ast::ExprRef::Attribute(attribute) => Some(ty_python_semantic::definitions_for_attribute(
             model, attribute,

crates/ty_ide/src/goto_declaration.rs

@@ -273,7 +273,7 @@ mod tests {
             r#"
 class A:
     x = 1
-    
+
     def method(self):
         def inner():
             return <CURSOR>x  # Should NOT find class variable x
@@ -1255,12 +1255,12 @@ x: i<CURSOR>nt = 42
             r#"
 def outer():
     x = "outer_value"
-    
+
     def inner():
         nonlocal x
         x = "modified"
         return x<CURSOR>  # Should find the nonlocal x declaration in outer scope
-    
+
     return inner
 "#,
         );
@@ -1295,12 +1295,12 @@ def outer():
             r#"
 def outer():
     xy = "outer_value"
-    
+
     def inner():
         nonlocal x<CURSOR>y
         xy = "modified"
         return x  # Should find the nonlocal x declaration in outer scope
-    
+
     return inner
 "#,
         );
@@ -1636,7 +1636,7 @@ def function():
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Click(x, button=a<CURSOR>b):
@@ -1675,7 +1675,7 @@ def function():
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Click(x, button=ab):
@@ -1713,7 +1713,7 @@ def function():
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Cl<CURSOR>ick(x, button=ab):
@@ -1751,7 +1751,7 @@ def function():
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Click(x, but<CURSOR>ton=ab):
@@ -1919,7 +1919,7 @@ def function():
             class C:
                 def __init__(self):
                     self._value = 0
-                
+
                 @property
                 def value(self):
                     return self._value
@@ -2029,7 +2029,7 @@ def function():
             r#"
 class MyClass:
     ClassType = int
-    
+
     def generic_method[T](self, value: Class<CURSOR>Type) -> T:
         return value
 "#,
@@ -2894,6 +2894,86 @@ def ab(a: int, *, c: int): ...
         ");
     }
 
+    // TODO: Should only return `a: int`
+    #[test]
+    fn redeclarations() {
+        let test = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+                a: str = "test"
+
+                a: int = 10
+
+                print(a<CURSOR>)
+
+                a: bool = True
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.goto_declaration(), @r#"
+        info[goto-declaration]: Declaration
+         --> main.py:2:1
+          |
+        2 | a: str = "test"
+          | ^
+        3 |
+        4 | a: int = 10
+          |
+        info: Source
+         --> main.py:6:7
+          |
+        4 | a: int = 10
+        5 |
+        6 | print(a)
+          |       ^
+        7 |
+        8 | a: bool = True
+          |
+
+        info[goto-declaration]: Declaration
+         --> main.py:4:1
+          |
+        2 | a: str = "test"
+        3 |
+        4 | a: int = 10
+          | ^
+        5 |
+        6 | print(a)
+          |
+        info: Source
+         --> main.py:6:7
+          |
+        4 | a: int = 10
+        5 |
+        6 | print(a)
+          |       ^
+        7 |
+        8 | a: bool = True
+          |
+
+        info[goto-declaration]: Declaration
+         --> main.py:8:1
+          |
+        6 | print(a)
+        7 |
+        8 | a: bool = True
+          | ^
+          |
+        info: Source
+         --> main.py:6:7
+          |
+        4 | a: int = 10
+        5 |
+        6 | print(a)
+          |       ^
+        7 |
+        8 | a: bool = True
+          |
+        "#);
+    }
+
     impl CursorTest {
         fn goto_declaration(&self) -> String {
             let Some(targets) = goto_declaration(&self.db, self.cursor.file, self.cursor.offset)

crates/ty_ide/src/goto_definition.rs

@@ -1714,6 +1714,86 @@ Traceb<CURSOR>ackType
         assert_snapshot!(test.goto_definition(), @"No goto target found");
     }
 
+    // TODO: Should only list `a: int`
+    #[test]
+    fn redeclarations() {
+        let test = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+                a: str = "test"
+
+                a: int = 10
+
+                print(a<CURSOR>)
+
+                a: bool = True
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.goto_definition(), @r#"
+        info[goto-definition]: Definition
+         --> main.py:2:1
+          |
+        2 | a: str = "test"
+          | ^
+        3 |
+        4 | a: int = 10
+          |
+        info: Source
+         --> main.py:6:7
+          |
+        4 | a: int = 10
+        5 |
+        6 | print(a)
+          |       ^
+        7 |
+        8 | a: bool = True
+          |
+
+        info[goto-definition]: Definition
+         --> main.py:4:1
+          |
+        2 | a: str = "test"
+        3 |
+        4 | a: int = 10
+          | ^
+        5 |
+        6 | print(a)
+          |
+        info: Source
+         --> main.py:6:7
+          |
+        4 | a: int = 10
+        5 |
+        6 | print(a)
+          |       ^
+        7 |
+        8 | a: bool = True
+          |
+
+        info[goto-definition]: Definition
+         --> main.py:8:1
+          |
+        6 | print(a)
+        7 |
+        8 | a: bool = True
+          | ^
+          |
+        info: Source
+         --> main.py:6:7
+          |
+        4 | a: int = 10
+        5 |
+        6 | print(a)
+          |       ^
+        7 |
+        8 | a: bool = True
+          |
+        "#);
+    }
+
     impl CursorTest {
         fn goto_definition(&self) -> String {
             let Some(targets) = goto_definition(&self.db, self.cursor.file, self.cursor.offset)

crates/ty_ide/src/goto_type_definition.rs

@@ -1111,7 +1111,7 @@ mod tests {
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Click(x, button=a<CURSOR>b):
@@ -1131,7 +1131,7 @@ mod tests {
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Click(x, button=ab):
@@ -1151,7 +1151,7 @@ mod tests {
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Cl<CURSOR>ick(x, button=ab):
@@ -1189,7 +1189,7 @@ mod tests {
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Click(x, but<CURSOR>ton=ab):
@@ -1398,12 +1398,12 @@ f(**kwargs<CURSOR>)
             r#"
 def outer():
     x = "outer_value"
-    
+
     def inner():
         nonlocal x
         x = "modified"
         return x<CURSOR>  # Should find the nonlocal x declaration in outer scope
-    
+
     return inner
 "#,
         );
@@ -1438,12 +1438,12 @@ def outer():
             r#"
 def outer():
     xy = "outer_value"
-    
+
     def inner():
         nonlocal x<CURSOR>y
         xy = "modified"
         return x  # Should find the nonlocal x declaration in outer scope
-    
+
     return inner
 "#,
         );

crates/ty_ide/src/hover.rs

@@ -1708,12 +1708,12 @@ def ab(a: int, *, c: int):
             r#"
 def outer():
     x = "outer_value"
-    
+
     def inner():
         nonlocal x
         x = "modified"
         return x<CURSOR>  # Should find the nonlocal x declaration in outer scope
-    
+
     return inner
 "#,
         );
@@ -1747,12 +1747,12 @@ def outer():
             r#"
 def outer():
     xy = "outer_value"
-    
+
     def inner():
         nonlocal x<CURSOR>y
         xy = "modified"
         return x  # Should find the nonlocal x declaration in outer scope
-    
+
     return inner
 "#,
         );
@@ -1960,7 +1960,7 @@ def function():
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Click(x, button=a<CURSOR>b):
@@ -1980,7 +1980,7 @@ def function():
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Click(x, button=ab):
@@ -2018,7 +2018,7 @@ def function():
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Cl<CURSOR>ick(x, button=ab):
@@ -2057,7 +2057,7 @@ def function():
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Click(x, but<CURSOR>ton=ab):
@@ -2143,15 +2143,13 @@ def function():
             "#,
         );
 
+        // TODO: This should just be `**AB@Alias2 (<variance>)`
+        // https://github.com/astral-sh/ty/issues/1581
         assert_snapshot!(test.hover(), @r"
-        (
-            ...
-        ) -> tuple[typing.ParamSpec]
+        (**AB@Alias2) -> tuple[AB@Alias2]
         ---------------------------------------------
         ```python
-        (
-            ...
-        ) -> tuple[typing.ParamSpec]
+        (**AB@Alias2) -> tuple[AB@Alias2]
         ```
         ---------------------------------------------
         info[hover]: Hovered content is
@@ -2292,12 +2290,12 @@ def function():
             "#,
         );
 
-        // TODO: This should be `P@Alias (<variance>)`
+        // TODO: Should this be constravariant instead?
         assert_snapshot!(test.hover(), @r"
-        typing.ParamSpec
+        P@Alias (bivariant)
         ---------------------------------------------
         ```python
-        typing.ParamSpec
+        P@Alias (bivariant)
         ```
         ---------------------------------------------
         info[hover]: Hovered content is

crates/ty_ide/src/importer.rs

@@ -145,7 +145,7 @@ impl<'a> Importer<'a> {
         members: &MembersInScope,
     ) -> ImportAction {
         let request = request.avoid_conflicts(self.db, self.file, members);
-        let mut symbol_text: Box<str> = request.member.into();
+        let mut symbol_text: Box<str> = request.member.unwrap_or(request.module).into();
         let Some(response) = self.find(&request, members.at) else {
             let insertion = if let Some(future) = self.find_last_future_import(members.at) {
                 Insertion::end_of_statement(future.stmt, self.source, self.stylist)
@@ -157,14 +157,27 @@ impl<'a> Importer<'a> {
                 Insertion::start_of_file(self.parsed.suite(), self.source, self.stylist, range)
             };
             let import = insertion.into_edit(&request.to_string());
-            if matches!(request.style, ImportStyle::Import) {
-                symbol_text = format!("{}.{}", request.module, request.member).into();
+            if let Some(member) = request.member
+                && matches!(request.style, ImportStyle::Import)
+            {
+                symbol_text = format!("{}.{}", request.module, member).into();
             }
             return ImportAction {
                 import: Some(import),
                 symbol_text,
             };
         };
+
+        // When we just have a request to import a module (and not
+        // any members from that module), then the only way we can be
+        // here is if we found a pre-existing import that definitively
+        // satisfies the request. So we're done.
+        let Some(member) = request.member else {
+            return ImportAction {
+                import: None,
+                symbol_text,
+            };
+        };
         match response.kind {
             ImportResponseKind::Unqualified { ast, alias } => {
                 let member = alias.asname.as_ref().unwrap_or(&alias.name).as_str();
@@ -189,13 +202,10 @@ impl<'a> Importer<'a> {
                 let import = if let Some(insertion) =
                     Insertion::existing_import(response.import.stmt, self.tokens)
                 {
-                    insertion.into_edit(request.member)
+                    insertion.into_edit(member)
                 } else {
                     Insertion::end_of_statement(response.import.stmt, self.source, self.stylist)
-                        .into_edit(&format!(
-                            "from {} import {}",
-                            request.module, request.member
-                        ))
+                        .into_edit(&format!("from {} import {member}", request.module))
                 };
                 ImportAction {
                     import: Some(import),
@@ -481,6 +491,17 @@ impl<'ast> AstImportKind<'ast> {
                 Some(ImportResponseKind::Qualified { ast, alias })
             }
             AstImportKind::ImportFrom(ast) => {
+                // If the request is for a module itself, then we
+                // assume that it can never be satisfies by a
+                // `from ... import ...` statement. For example, a
+                // `request for collections.abc` needs an
+                // `import collections.abc`. Now, there could be a
+                // `from collections import abc`, and we could
+                // plausibly consider that a match and return a
+                // symbol text of `abc`. But it's not clear if that's
+                // the right choice or not.
+                let member = request.member?;
+
                 if request.force_style && !matches!(request.style, ImportStyle::ImportFrom) {
                     return None;
                 }
@@ -492,9 +513,7 @@ impl<'ast> AstImportKind<'ast> {
                 let kind = ast
                     .names
                     .iter()
-                    .find(|alias| {
-                        alias.name.as_str() == "*" || alias.name.as_str() == request.member
-                    })
+                    .find(|alias| alias.name.as_str() == "*" || alias.name.as_str() == member)
                     .map(|alias| ImportResponseKind::Unqualified { ast, alias })
                     .unwrap_or_else(|| ImportResponseKind::Partial(ast));
                 Some(kind)
@@ -510,7 +529,10 @@ pub(crate) struct ImportRequest<'a> {
     /// `foo`, in `from foo import bar`).
     module: &'a str,
     /// The member to import (e.g., `bar`, in `from foo import bar`).
-    member: &'a str,
+    ///
+    /// When `member` is absent, then this request reflects an import
+    /// of the module itself. i.e., `import module`.
+    member: Option<&'a str>,
     /// The preferred style to use when importing the symbol (e.g.,
     /// `import foo` or `from foo import bar`).
     ///
@@ -532,7 +554,7 @@ impl<'a> ImportRequest<'a> {
     pub(crate) fn import(module: &'a str, member: &'a str) -> Self {
         Self {
             module,
-            member,
+            member: Some(member),
             style: ImportStyle::Import,
             force_style: false,
         }
@@ -545,12 +567,26 @@ impl<'a> ImportRequest<'a> {
     pub(crate) fn import_from(module: &'a str, member: &'a str) -> Self {
         Self {
             module,
-            member,
+            member: Some(member),
             style: ImportStyle::ImportFrom,
             force_style: false,
         }
     }
 
+    /// Create a new [`ImportRequest`] for bringing the given module
+    /// into scope.
+    ///
+    /// This is for just importing the module itself, always via an
+    /// `import` statement.
+    pub(crate) fn module(module: &'a str) -> Self {
+        Self {
+            module,
+            member: None,
+            style: ImportStyle::Import,
+            force_style: false,
+        }
+    }
+
     /// Causes this request to become a command. This will force the
     /// requested import style, even if another style would be more
     /// appropriate generally.
@@ -565,7 +601,13 @@ impl<'a> ImportRequest<'a> {
     /// of an import conflict are minimized (although not always reduced
     /// to zero).
     fn avoid_conflicts(self, db: &dyn Db, importing_file: File, members: &MembersInScope) -> Self {
-        match (members.map.get(self.module), members.map.get(self.member)) {
+        let Some(member) = self.member else {
+            return Self {
+                style: ImportStyle::Import,
+                ..self
+            };
+        };
+        match (members.map.get(self.module), members.map.get(member)) {
             // Neither symbol exists, so we can just proceed as
             // normal.
             (None, None) => self,
@@ -630,7 +672,10 @@ impl std::fmt::Display for ImportRequest<'_> {
     fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
         match self.style {
             ImportStyle::Import => write!(f, "import {}", self.module),
-            ImportStyle::ImportFrom => write!(f, "from {} import {}", self.module, self.member),
+            ImportStyle::ImportFrom => match self.member {
+                None => write!(f, "import {}", self.module),
+                Some(member) => write!(f, "from {} import {member}", self.module),
+            },
         }
     }
 }
@@ -843,6 +888,10 @@ mod tests {
             self.add(ImportRequest::import_from(module, member))
         }
 
+        fn module(&self, module: &str) -> String {
+            self.add(ImportRequest::module(module))
+        }
+
         fn add(&self, request: ImportRequest<'_>) -> String {
             let node = covering_node(
                 self.cursor.parsed.syntax().into(),
@@ -2156,4 +2205,73 @@ except ImportError:
         (bar.MAGIC)
         ");
     }
+
+    #[test]
+    fn import_module_blank() {
+        let test = cursor_test(
+            "\
+<CURSOR>
+        ",
+        );
+        assert_snapshot!(
+            test.module("collections"), @r"
+        import collections
+        collections
+        ");
+    }
+
+    #[test]
+    fn import_module_exists() {
+        let test = cursor_test(
+            "\
+import collections
+<CURSOR>
+        ",
+        );
+        assert_snapshot!(
+            test.module("collections"), @r"
+        import collections
+        collections
+        ");
+    }
+
+    #[test]
+    fn import_module_from_exists() {
+        let test = cursor_test(
+            "\
+from collections import defaultdict
+<CURSOR>
+        ",
+        );
+        assert_snapshot!(
+            test.module("collections"), @r"
+        import collections
+        from collections import defaultdict
+        collections
+        ");
+    }
+
+    // This test is working as intended. That is,
+    // `abc` is already in scope, so requesting an
+    // import for `collections.abc` could feasibly
+    // reuse the import and rewrite the symbol text
+    // to just `abc`. But for now it seems better
+    // to respect what has been written and add the
+    // `import collections.abc`. This behavior could
+    // plausibly be changed.
+    #[test]
+    fn import_module_from_via_member_exists() {
+        let test = cursor_test(
+            "\
+from collections import abc
+<CURSOR>
+        ",
+        );
+        assert_snapshot!(
+            test.module("collections.abc"), @r"
+        import collections.abc
+        from collections import abc
+        collections.abc
+        ");
+    }
 }

crates/ty_ide/src/inlay_hints.rs

@@ -19,11 +19,22 @@ pub struct InlayHint {
 }
 
 impl InlayHint {
-    fn variable_type(expr: &Expr, ty: Type, db: &dyn Db, allow_edits: bool) -> Self {
+    fn variable_type(
+        expr: &Expr,
+        rhs: &Expr,
+        ty: Type,
+        db: &dyn Db,
+        allow_edits: bool,
+    ) -> Option<Self> {
         let position = expr.range().end();
         // Render the type to a string, and get subspans for all the types that make it up
         let details = ty.display(db).to_string_parts();
 
+        // Filter out a reptitive hints like `x: T = T()`
+        if call_matches_name(rhs, &details.label) {
+            return None;
+        }
+
         // Ok so the idea here is that we potentially have a random soup of spans here,
         // and each byte of the string can have at most one target associate with it.
         // Thankfully, they were generally pushed in print order, with the inner smaller types
@@ -73,12 +84,12 @@ impl InlayHint {
             vec![]
         };
 
-        Self {
+        Some(Self {
             position,
             kind: InlayHintKind::Type,
             label: InlayHintLabel { parts: label_parts },
             text_edits,
-        }
+        })
     }
 
     fn call_argument_name(
@@ -250,7 +261,7 @@ struct InlayHintVisitor<'a, 'db> {
     db: &'db dyn Db,
     model: SemanticModel<'db>,
     hints: Vec<InlayHint>,
-    in_assignment: bool,
+    assignment_rhs: Option<&'a Expr>,
     range: TextRange,
     settings: &'a InlayHintSettings,
     in_no_edits_allowed: bool,
@@ -262,21 +273,21 @@ impl<'a, 'db> InlayHintVisitor<'a, 'db> {
             db,
             model: SemanticModel::new(db, file),
             hints: Vec::new(),
-            in_assignment: false,
+            assignment_rhs: None,
             range,
             settings,
             in_no_edits_allowed: false,
         }
     }
 
-    fn add_type_hint(&mut self, expr: &Expr, ty: Type<'db>, allow_edits: bool) {
+    fn add_type_hint(&mut self, expr: &Expr, rhs: &Expr, ty: Type<'db>, allow_edits: bool) {
         if !self.settings.variable_types {
             return;
         }
 
-        let inlay_hint = InlayHint::variable_type(expr, ty, self.db, allow_edits);
-
-        self.hints.push(inlay_hint);
+        if let Some(inlay_hint) = InlayHint::variable_type(expr, rhs, ty, self.db, allow_edits) {
+            self.hints.push(inlay_hint);
+        }
     }
 
     fn add_call_argument_name(
@@ -299,8 +310,8 @@ impl<'a, 'db> InlayHintVisitor<'a, 'db> {
     }
 }
 
-impl SourceOrderVisitor<'_> for InlayHintVisitor<'_, '_> {
-    fn enter_node(&mut self, node: AnyNodeRef<'_>) -> TraversalSignal {
+impl<'a> SourceOrderVisitor<'a> for InlayHintVisitor<'a, '_> {
+    fn enter_node(&mut self, node: AnyNodeRef<'a>) -> TraversalSignal {
         if self.range.intersect(node.range()).is_some() {
             TraversalSignal::Traverse
         } else {
@@ -308,7 +319,7 @@ impl SourceOrderVisitor<'_> for InlayHintVisitor<'_, '_> {
         }
     }
 
-    fn visit_stmt(&mut self, stmt: &Stmt) {
+    fn visit_stmt(&mut self, stmt: &'a Stmt) {
         let node = AnyNodeRef::from(stmt);
 
         if !self.enter_node(node).is_traverse() {
@@ -317,7 +328,9 @@ impl SourceOrderVisitor<'_> for InlayHintVisitor<'_, '_> {
 
         match stmt {
             Stmt::Assign(assign) => {
-                self.in_assignment = !type_hint_is_excessive_for_expr(&assign.value);
+                if !type_hint_is_excessive_for_expr(&assign.value) {
+                    self.assignment_rhs = Some(&*assign.value);
+                }
                 if !annotations_are_valid_syntax(assign) {
                     self.in_no_edits_allowed = true;
                 }
@@ -325,7 +338,7 @@ impl SourceOrderVisitor<'_> for InlayHintVisitor<'_, '_> {
                     self.visit_expr(target);
                 }
                 self.in_no_edits_allowed = false;
-                self.in_assignment = false;
+                self.assignment_rhs = None;
 
                 self.visit_expr(&assign.value);
 
@@ -344,22 +357,22 @@ impl SourceOrderVisitor<'_> for InlayHintVisitor<'_, '_> {
         source_order::walk_stmt(self, stmt);
     }
 
-    fn visit_expr(&mut self, expr: &'_ Expr) {
+    fn visit_expr(&mut self, expr: &'a Expr) {
         match expr {
             Expr::Name(name) => {
-                if self.in_assignment {
+                if let Some(rhs) = self.assignment_rhs {
                     if name.ctx.is_store() {
                         let ty = expr.inferred_type(&self.model);
-                        self.add_type_hint(expr, ty, !self.in_no_edits_allowed);
+                        self.add_type_hint(expr, rhs, ty, !self.in_no_edits_allowed);
                     }
                 }
                 source_order::walk_expr(self, expr);
             }
             Expr::Attribute(attribute) => {
-                if self.in_assignment {
+                if let Some(rhs) = self.assignment_rhs {
                     if attribute.ctx.is_store() {
                         let ty = expr.inferred_type(&self.model);
-                        self.add_type_hint(expr, ty, !self.in_no_edits_allowed);
+                        self.add_type_hint(expr, rhs, ty, !self.in_no_edits_allowed);
                     }
                 }
                 source_order::walk_expr(self, expr);
@@ -416,6 +429,26 @@ fn arg_matches_name(arg_or_keyword: &ArgOrKeyword, name: &str) -> bool {
     }
 }
 
+/// Given a function call, check if the expression is the "same name"
+/// as the function being called.
+///
+/// This allows us to filter out reptitive inlay hints like `x: T = T(...)`.
+/// While still allowing non-trivial ones like `x: T[U] = T()`.
+fn call_matches_name(expr: &Expr, name: &str) -> bool {
+    // Only care about function calls
+    let Expr::Call(call) = expr else {
+        return false;
+    };
+
+    match &*call.func {
+        // `x: T = T()` is a match
+        Expr::Name(expr_name) => expr_name.id.as_str() == name,
+        // `x: T = a.T()` is a match
+        Expr::Attribute(expr_attribute) => expr_attribute.attr.as_str() == name,
+        _ => false,
+    }
+}
+
 /// Given an expression that's the RHS of an assignment, would it be excessive to
 /// emit an inlay type hint for the variable assigned to it?
 ///
@@ -1829,35 +1862,16 @@ mod tests {
             ",
         );
 
-        assert_snapshot!(test.inlay_hints(), @r#"
+        assert_snapshot!(test.inlay_hints(), @r"
         class A:
             def __init__(self, y):
-                self.x[: int] = int(1)
+                self.x = int(1)
                 self.y[: Unknown] = y
 
-        a[: A] = A([y=]2)
-        a.y[: int] = int(3)
+        a = A([y=]2)
+        a.y = int(3)
 
         ---------------------------------------------
-        info[inlay-hint-location]: Inlay Hint Target
-           --> stdlib/builtins.pyi:348:7
-            |
-        347 | @disjoint_base
-        348 | class int:
-            |       ^^^
-        349 |     """int([x]) -> integer
-        350 |     int(x, base=10) -> integer
-            |
-        info: Source
-         --> main2.py:4:18
-          |
-        2 | class A:
-        3 |     def __init__(self, y):
-        4 |         self.x[: int] = int(1)
-          |                  ^^^
-        5 |         self.y[: Unknown] = y
-          |
-
         info[inlay-hint-location]: Inlay Hint Target
           --> stdlib/ty_extensions.pyi:20:1
            |
@@ -1871,29 +1885,11 @@ mod tests {
          --> main2.py:5:18
           |
         3 |     def __init__(self, y):
-        4 |         self.x[: int] = int(1)
+        4 |         self.x = int(1)
         5 |         self.y[: Unknown] = y
           |                  ^^^^^^^
         6 |
-        7 | a[: A] = A([y=]2)
-          |
-
-        info[inlay-hint-location]: Inlay Hint Target
-         --> main.py:2:7
-          |
-        2 | class A:
-          |       ^
-        3 |     def __init__(self, y):
-        4 |         self.x = int(1)
-          |
-        info: Source
-         --> main2.py:7:5
-          |
-        5 |         self.y[: Unknown] = y
-        6 |
-        7 | a[: A] = A([y=]2)
-          |     ^
-        8 | a.y[: int] = int(3)
+        7 | a = A([y=]2)
           |
 
         info[inlay-hint-location]: Inlay Hint Target
@@ -1906,30 +1902,13 @@ mod tests {
         5 |         self.y = y
           |
         info: Source
-         --> main2.py:7:13
+         --> main2.py:7:8
           |
         5 |         self.y[: Unknown] = y
         6 |
-        7 | a[: A] = A([y=]2)
-          |             ^
-        8 | a.y[: int] = int(3)
-          |
-
-        info[inlay-hint-location]: Inlay Hint Target
-           --> stdlib/builtins.pyi:348:7
-            |
-        347 | @disjoint_base
-        348 | class int:
-            |       ^^^
-        349 |     """int([x]) -> integer
-        350 |     int(x, base=10) -> integer
-            |
-        info: Source
-         --> main2.py:8:7
-          |
-        7 | a[: A] = A([y=]2)
-        8 | a.y[: int] = int(3)
-          |       ^^^
+        7 | a = A([y=]2)
+          |        ^
+        8 | a.y = int(3)
           |
 
         ---------------------------------------------
@@ -1938,12 +1917,12 @@ mod tests {
 
         class A:
             def __init__(self, y):
-                self.x: int = int(1)
+                self.x = int(1)
                 self.y: Unknown = y
 
-        a: A = A(2)
-        a.y: int = int(3)
-        "#);
+        a = A(2)
+        a.y = int(3)
+        ");
     }
 
     #[test]
@@ -2012,7 +1991,7 @@ mod tests {
                 def __init__(self, pos, btn):
                     self.position: int = pos
                     self.button: str = btn
-            
+
             def my_func(event: Click):
                 match event:
                     case Click(x, button=ab):
@@ -2937,31 +2916,12 @@ mod tests {
             def __init__(self):
                 self.x: int = 1
 
-        x[: MyClass] = MyClass()
+        x = MyClass()
         y[: tuple[MyClass, MyClass]] = (MyClass(), MyClass())
         a[: MyClass], b[: MyClass] = MyClass(), MyClass()
         c[: MyClass], d[: MyClass] = (MyClass(), MyClass())
 
         ---------------------------------------------
-        info[inlay-hint-location]: Inlay Hint Target
-         --> main.py:2:7
-          |
-        2 | class MyClass:
-          |       ^^^^^^^
-        3 |     def __init__(self):
-        4 |         self.x: int = 1
-          |
-        info: Source
-         --> main2.py:6:5
-          |
-        4 |         self.x: int = 1
-        5 |
-        6 | x[: MyClass] = MyClass()
-          |     ^^^^^^^
-        7 | y[: tuple[MyClass, MyClass]] = (MyClass(), MyClass())
-        8 | a[: MyClass], b[: MyClass] = MyClass(), MyClass()
-          |
-
         info[inlay-hint-location]: Inlay Hint Target
             --> stdlib/builtins.pyi:2695:7
              |
@@ -2973,7 +2933,7 @@ mod tests {
         info: Source
          --> main2.py:7:5
           |
-        6 | x[: MyClass] = MyClass()
+        6 | x = MyClass()
         7 | y[: tuple[MyClass, MyClass]] = (MyClass(), MyClass())
           |     ^^^^^
         8 | a[: MyClass], b[: MyClass] = MyClass(), MyClass()
@@ -2991,7 +2951,7 @@ mod tests {
         info: Source
          --> main2.py:7:11
           |
-        6 | x[: MyClass] = MyClass()
+        6 | x = MyClass()
         7 | y[: tuple[MyClass, MyClass]] = (MyClass(), MyClass())
           |           ^^^^^^^
         8 | a[: MyClass], b[: MyClass] = MyClass(), MyClass()
@@ -3009,7 +2969,7 @@ mod tests {
         info: Source
          --> main2.py:7:20
           |
-        6 | x[: MyClass] = MyClass()
+        6 | x = MyClass()
         7 | y[: tuple[MyClass, MyClass]] = (MyClass(), MyClass())
           |                    ^^^^^^^
         8 | a[: MyClass], b[: MyClass] = MyClass(), MyClass()
@@ -3027,7 +2987,7 @@ mod tests {
         info: Source
          --> main2.py:8:5
           |
-        6 | x[: MyClass] = MyClass()
+        6 | x = MyClass()
         7 | y[: tuple[MyClass, MyClass]] = (MyClass(), MyClass())
         8 | a[: MyClass], b[: MyClass] = MyClass(), MyClass()
           |     ^^^^^^^
@@ -3045,7 +3005,7 @@ mod tests {
         info: Source
          --> main2.py:8:19
           |
-        6 | x[: MyClass] = MyClass()
+        6 | x = MyClass()
         7 | y[: tuple[MyClass, MyClass]] = (MyClass(), MyClass())
         8 | a[: MyClass], b[: MyClass] = MyClass(), MyClass()
           |                   ^^^^^^^
@@ -3094,7 +3054,7 @@ mod tests {
             def __init__(self):
                 self.x: int = 1
 
-        x: MyClass = MyClass()
+        x = MyClass()
         y: tuple[MyClass, MyClass] = (MyClass(), MyClass())
         a, b = MyClass(), MyClass()
         c, d = (MyClass(), MyClass())
@@ -4097,31 +4057,11 @@ mod tests {
             def __init__(self):
                 self.x: int = 1
                 self.y: int = 2
-        val[: MyClass] = MyClass()
+        val = MyClass()
 
         foo(val.x)
         foo([x=]val.y)
         ---------------------------------------------
-        info[inlay-hint-location]: Inlay Hint Target
-         --> main.py:3:7
-          |
-        2 | def foo(x: int): pass
-        3 | class MyClass:
-          |       ^^^^^^^
-        4 |     def __init__(self):
-        5 |         self.x: int = 1
-          |
-        info: Source
-         --> main2.py:7:7
-          |
-        5 |         self.x: int = 1
-        6 |         self.y: int = 2
-        7 | val[: MyClass] = MyClass()
-          |       ^^^^^^^
-        8 |
-        9 | foo(val.x)
-          |
-
         info[inlay-hint-location]: Inlay Hint Target
          --> main.py:2:9
           |
@@ -4137,20 +4077,6 @@ mod tests {
         10 | foo([x=]val.y)
            |      ^
            |
-
-        ---------------------------------------------
-        info[inlay-hint-edit]: File after edits
-        info: Source
-
-        def foo(x: int): pass
-        class MyClass:
-            def __init__(self):
-                self.x: int = 1
-                self.y: int = 2
-        val: MyClass = MyClass()
-
-        foo(val.x)
-        foo(val.y)
         ");
     }
 
@@ -4176,31 +4102,11 @@ mod tests {
             def __init__(self):
                 self.x: int = 1
                 self.y: int = 2
-        x[: MyClass] = MyClass()
+        x = MyClass()
 
         foo(x.x)
         foo([x=]x.y)
         ---------------------------------------------
-        info[inlay-hint-location]: Inlay Hint Target
-         --> main.py:3:7
-          |
-        2 | def foo(x: int): pass
-        3 | class MyClass:
-          |       ^^^^^^^
-        4 |     def __init__(self):
-        5 |         self.x: int = 1
-          |
-        info: Source
-         --> main2.py:7:5
-          |
-        5 |         self.x: int = 1
-        6 |         self.y: int = 2
-        7 | x[: MyClass] = MyClass()
-          |     ^^^^^^^
-        8 |
-        9 | foo(x.x)
-          |
-
         info[inlay-hint-location]: Inlay Hint Target
          --> main.py:2:9
           |
@@ -4216,20 +4122,6 @@ mod tests {
         10 | foo([x=]x.y)
            |      ^
            |
-
-        ---------------------------------------------
-        info[inlay-hint-edit]: File after edits
-        info: Source
-
-        def foo(x: int): pass
-        class MyClass:
-            def __init__(self):
-                self.x: int = 1
-                self.y: int = 2
-        x: MyClass = MyClass()
-
-        foo(x.x)
-        foo(x.y)
         ");
     }
 
@@ -4258,31 +4150,11 @@ mod tests {
                 return 1
             def y() -> int:
                 return 2
-        val[: MyClass] = MyClass()
+        val = MyClass()
 
         foo(val.x())
         foo([x=]val.y())
         ---------------------------------------------
-        info[inlay-hint-location]: Inlay Hint Target
-         --> main.py:3:7
-          |
-        2 | def foo(x: int): pass
-        3 | class MyClass:
-          |       ^^^^^^^
-        4 |     def __init__(self):
-        5 |     def x() -> int:
-          |
-        info: Source
-          --> main2.py:9:7
-           |
-         7 |     def y() -> int:
-         8 |         return 2
-         9 | val[: MyClass] = MyClass()
-           |       ^^^^^^^
-        10 |
-        11 | foo(val.x())
-           |
-
         info[inlay-hint-location]: Inlay Hint Target
          --> main.py:2:9
           |
@@ -4298,22 +4170,6 @@ mod tests {
         12 | foo([x=]val.y())
            |      ^
            |
-
-        ---------------------------------------------
-        info[inlay-hint-edit]: File after edits
-        info: Source
-
-        def foo(x: int): pass
-        class MyClass:
-            def __init__(self):
-            def x() -> int:
-                return 1
-            def y() -> int:
-                return 2
-        val: MyClass = MyClass()
-
-        foo(val.x())
-        foo(val.y())
         ");
     }
 
@@ -4346,31 +4202,11 @@ mod tests {
                 return 1
             def y() -> List[int]:
                 return 2
-        val[: MyClass] = MyClass()
+        val = MyClass()
 
         foo(val.x()[0])
         foo([x=]val.y()[1])
         ---------------------------------------------
-        info[inlay-hint-location]: Inlay Hint Target
-         --> main.py:5:7
-          |
-        4 | def foo(x: int): pass
-        5 | class MyClass:
-          |       ^^^^^^^
-        6 |     def __init__(self):
-        7 |     def x() -> List[int]:
-          |
-        info: Source
-          --> main2.py:11:7
-           |
-         9 |     def y() -> List[int]:
-        10 |         return 2
-        11 | val[: MyClass] = MyClass()
-           |       ^^^^^^^
-        12 |
-        13 | foo(val.x()[0])
-           |
-
         info[inlay-hint-location]: Inlay Hint Target
          --> main.py:4:9
           |
@@ -4388,24 +4224,6 @@ mod tests {
         14 | foo([x=]val.y()[1])
            |      ^
            |
-
-        ---------------------------------------------
-        info[inlay-hint-edit]: File after edits
-        info: Source
-
-        from typing import List
-
-        def foo(x: int): pass
-        class MyClass:
-            def __init__(self):
-            def x() -> List[int]:
-                return 1
-            def y() -> List[int]:
-                return 2
-        val: MyClass = MyClass()
-
-        foo(val.x()[0])
-        foo(val.y()[1])
         ");
     }
 
@@ -4697,7 +4515,7 @@ mod tests {
         class Foo:
             def __init__(self, x: int): pass
         Foo([x=]1)
-        f[: Foo] = Foo([x=]1)
+        f = Foo([x=]1)
         ---------------------------------------------
         info[inlay-hint-location]: Inlay Hint Target
          --> main.py:3:24
@@ -4715,24 +4533,7 @@ mod tests {
         3 |     def __init__(self, x: int): pass
         4 | Foo([x=]1)
           |      ^
-        5 | f[: Foo] = Foo([x=]1)
-          |
-
-        info[inlay-hint-location]: Inlay Hint Target
-         --> main.py:2:7
-          |
-        2 | class Foo:
-          |       ^^^
-        3 |     def __init__(self, x: int): pass
-        4 | Foo(1)
-          |
-        info: Source
-         --> main2.py:5:5
-          |
-        3 |     def __init__(self, x: int): pass
-        4 | Foo([x=]1)
-        5 | f[: Foo] = Foo([x=]1)
-          |     ^^^
+        5 | f = Foo([x=]1)
           |
 
         info[inlay-hint-location]: Inlay Hint Target
@@ -4745,22 +4546,13 @@ mod tests {
         5 | f = Foo(1)
           |
         info: Source
-         --> main2.py:5:17
+         --> main2.py:5:10
           |
         3 |     def __init__(self, x: int): pass
         4 | Foo([x=]1)
-        5 | f[: Foo] = Foo([x=]1)
-          |                 ^
+        5 | f = Foo([x=]1)
+          |          ^
           |
-
-        ---------------------------------------------
-        info[inlay-hint-edit]: File after edits
-        info: Source
-
-        class Foo:
-            def __init__(self, x: int): pass
-        Foo(1)
-        f: Foo = Foo(1)
         ");
     }
 
@@ -4778,7 +4570,7 @@ mod tests {
         class Foo:
             def __new__(cls, x: int): pass
         Foo([x=]1)
-        f[: Foo] = Foo([x=]1)
+        f = Foo([x=]1)
         ---------------------------------------------
         info[inlay-hint-location]: Inlay Hint Target
          --> main.py:3:22
@@ -4796,24 +4588,7 @@ mod tests {
         3 |     def __new__(cls, x: int): pass
         4 | Foo([x=]1)
           |      ^
-        5 | f[: Foo] = Foo([x=]1)
-          |
-
-        info[inlay-hint-location]: Inlay Hint Target
-         --> main.py:2:7
-          |
-        2 | class Foo:
-          |       ^^^
-        3 |     def __new__(cls, x: int): pass
-        4 | Foo(1)
-          |
-        info: Source
-         --> main2.py:5:5
-          |
-        3 |     def __new__(cls, x: int): pass
-        4 | Foo([x=]1)
-        5 | f[: Foo] = Foo([x=]1)
-          |     ^^^
+        5 | f = Foo([x=]1)
           |
 
         info[inlay-hint-location]: Inlay Hint Target
@@ -4826,22 +4601,13 @@ mod tests {
         5 | f = Foo(1)
           |
         info: Source
-         --> main2.py:5:17
+         --> main2.py:5:10
           |
         3 |     def __new__(cls, x: int): pass
         4 | Foo([x=]1)
-        5 | f[: Foo] = Foo([x=]1)
-          |                 ^
+        5 | f = Foo([x=]1)
+          |          ^
           |
-
-        ---------------------------------------------
-        info[inlay-hint-edit]: File after edits
-        info: Source
-
-        class Foo:
-            def __new__(cls, x: int): pass
-        Foo(1)
-        f: Foo = Foo(1)
         ");
     }
 

crates/ty_ide/src/references.rs

@@ -37,6 +37,38 @@ pub enum ReferencesMode {
     DocumentHighlights,
 }
 
+impl ReferencesMode {
+    pub(super) fn to_import_alias_resolution(self) -> ImportAliasResolution {
+        match self {
+            // Resolve import aliases for find references:
+            // ```py
+            // from warnings import deprecated as my_deprecated
+            //
+            // @my_deprecated
+            // def foo
+            // ```
+            //
+            // When finding references on `my_deprecated`, we want to find all usages of `deprecated` across the entire
+            // project.
+            Self::References | Self::ReferencesSkipDeclaration => {
+                ImportAliasResolution::ResolveAliases
+            }
+            // For rename, don't resolve import aliases.
+            //
+            // ```py
+            // from warnings import deprecated as my_deprecated
+            //
+            // @my_deprecated
+            // def foo
+            // ```
+            // When renaming `my_deprecated`, only rename the alias, but not the original definition in `warnings`.
+            Self::Rename | Self::RenameMultiFile | Self::DocumentHighlights => {
+                ImportAliasResolution::PreserveAliases
+            }
+        }
+    }
+}
+
 /// Find all references to a symbol at the given position.
 /// Search for references across all files in the project.
 pub(crate) fn references(
@@ -45,12 +77,9 @@ pub(crate) fn references(
     goto_target: &GotoTarget,
     mode: ReferencesMode,
 ) -> Option<Vec<ReferenceTarget>> {
-    // Get the definitions for the symbol at the cursor position
-
-    // When finding references, do not resolve any local aliases.
     let model = SemanticModel::new(db, file);
     let target_definitions = goto_target
-        .get_definition_targets(&model, ImportAliasResolution::PreserveAliases)?
+        .get_definition_targets(&model, mode.to_import_alias_resolution())?
         .declaration_targets(db)?;
 
     // Extract the target text from the goto target for fast comparison
@@ -318,7 +347,7 @@ impl LocalReferencesFinder<'_> {
         {
             // Get the definitions for this goto target
             if let Some(current_definitions) = goto_target
-                .get_definition_targets(self.model, ImportAliasResolution::PreserveAliases)
+                .get_definition_targets(self.model, self.mode.to_import_alias_resolution())
                 .and_then(|definitions| definitions.declaration_targets(self.model.db()))
             {
                 // Check if any of the current definitions match our target definitions

crates/ty_ide/src/rename.rs

@@ -3,7 +3,7 @@ use crate::references::{ReferencesMode, references};
 use crate::{Db, ReferenceTarget};
 use ruff_db::files::File;
 use ruff_text_size::{Ranged, TextSize};
-use ty_python_semantic::{ImportAliasResolution, SemanticModel};
+use ty_python_semantic::SemanticModel;
 
 /// Returns the range of the symbol if it can be renamed, None if not.
 pub fn can_rename(db: &dyn Db, file: File, offset: TextSize) -> Option<ruff_text_size::TextRange> {
@@ -24,26 +24,22 @@ pub fn can_rename(db: &dyn Db, file: File, offset: TextSize) -> Option<ruff_text
 
     let current_file_in_project = is_file_in_project(db, file);
 
-    if let Some(definition_targets) = goto_target
-        .get_definition_targets(&model, ImportAliasResolution::PreserveAliases)
-        .and_then(|definitions| definitions.declaration_targets(db))
-    {
-        for target in &definition_targets {
-            let target_file = target.file();
+    let definition_targets = goto_target
+        .get_definition_targets(&model, ReferencesMode::Rename.to_import_alias_resolution())?
+        .declaration_targets(db)?;
 
-            // If definition is outside the project, refuse rename
-            if !is_file_in_project(db, target_file) {
-                return None;
-            }
+    for target in &definition_targets {
+        let target_file = target.file();
 
-            // If current file is not in project and any definition is outside current file, refuse rename
-            if !current_file_in_project && target_file != file {
-                return None;
-            }
+        // If definition is outside the project, refuse rename
+        if !is_file_in_project(db, target_file) {
+            return None;
+        }
+
+        // If current file is not in project and any definition is outside current file, refuse rename
+        if !current_file_in_project && target_file != file {
+            return None;
         }
-    } else {
-        // No definition targets found. This happens for keywords, so refuse rename
-        return None;
     }
 
     Some(goto_target.range())
@@ -1186,7 +1182,6 @@ result = func(10, y=20)
         ");
     }
 
-    // TODO Should rename the alias
     #[test]
     fn import_alias() {
         let test = CursorTest::builder()
@@ -1202,10 +1197,80 @@ result = func(10, y=20)
             )
             .build();
 
-        assert_snapshot!(test.rename("z"), @"Cannot rename");
+        assert_snapshot!(test.rename("z"), @r"
+        info[rename]: Rename symbol (found 2 locations)
+         --> main.py:3:20
+          |
+        2 | import warnings
+        3 | import warnings as abc
+          |                    ^^^
+        4 |
+        5 | x = abc
+          |     ---
+        6 | y = warnings
+          |
+        ");
+    }
+
+    #[test]
+    fn import_alias_to_first_party_definition() {
+        let test = CursorTest::builder()
+            .source("lib.py", "def deprecated(): pass")
+            .source(
+                "main.py",
+                r#"
+                import lib as lib2<CURSOR>
+
+                x = lib2
+            "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("z"), @r"
+            info[rename]: Rename symbol (found 2 locations)
+             --> main.py:2:15
+              |
+            2 | import lib as lib2
+              |               ^^^^
+            3 |
+            4 | x = lib2
+              |     ----
+              |
+        ");
+    }
+
+    #[test]
+    fn imported_first_party_definition() {
+        let test = CursorTest::builder()
+            .source("lib.py", "def deprecated(): pass")
+            .source(
+                "main.py",
+                r#"
+                from lib import deprecated<CURSOR>
+
+                x = deprecated
+            "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("z"), @r"
+        info[rename]: Rename symbol (found 3 locations)
+         --> main.py:2:17
+          |
+        2 | from lib import deprecated
+          |                 ^^^^^^^^^^
+        3 |
+        4 | x = deprecated
+          |     ----------
+          |
+         ::: lib.py:1:5
+          |
+        1 | def deprecated(): pass
+          |     ----------
+          |
+        ");
     }
 
-    // TODO Should rename the alias
     #[test]
     fn import_alias_use() {
         let test = CursorTest::builder()
@@ -1221,7 +1286,19 @@ result = func(10, y=20)
             )
             .build();
 
-        assert_snapshot!(test.rename("z"), @"Cannot rename");
+        assert_snapshot!(test.rename("z"), @r"
+        info[rename]: Rename symbol (found 2 locations)
+         --> main.py:3:20
+          |
+        2 | import warnings
+        3 | import warnings as abc
+          |                    ^^^
+        4 |
+        5 | x = abc
+          |     ---
+        6 | y = warnings
+          |
+        ");
     }
 
     #[test]
@@ -1426,4 +1503,753 @@ result = func(10, y=20)
           |
         ");
     }
+
+    #[test]
+    fn rename_overloaded_function() {
+        let test = CursorTest::builder()
+            .source(
+                "lib.py",
+                r#"
+                from typing import overload, Any
+
+                @overload
+                def test<CURSOR>() -> None: ...
+                @overload
+                def test(a: str) -> str: ...
+                @overload
+                def test(a: int) -> int: ...
+
+                def test(a: Any) -> Any:
+                    return a
+                "#,
+            )
+            .source(
+                "main.py",
+                r#"
+                from lib import test
+
+                test("test")
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r#"
+        info[rename]: Rename symbol (found 3 locations)
+         --> lib.py:5:5
+          |
+        4 | @overload
+        5 | def test() -> None: ...
+          |     ^^^^
+        6 | @overload
+        7 | def test(a: str) -> str: ...
+          |
+         ::: main.py:2:17
+          |
+        2 | from lib import test
+          |                 ----
+        3 |
+        4 | test("test")
+          | ----
+          |
+        "#);
+    }
+
+    #[test]
+    fn rename_overloaded_method() {
+        let test = CursorTest::builder()
+            .source(
+                "lib.py",
+                r#"
+                from typing import overload, Any
+
+                class Test:
+                    @overload
+                    def test<CURSOR>() -> None: ...
+                    @overload
+                    def test(a: str) -> str: ...
+                    @overload
+                    def test(a: int) -> int: ...
+
+                    def test(a: Any) -> Any:
+                        return a
+
+                "#,
+            )
+            .source(
+                "main.py",
+                r#"
+                from lib import Test
+
+                Test().test("test")
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r#"
+        info[rename]: Rename symbol (found 2 locations)
+         --> lib.py:6:9
+          |
+        4 | class Test:
+        5 |     @overload
+        6 |     def test() -> None: ...
+          |         ^^^^
+        7 |     @overload
+        8 |     def test(a: str) -> str: ...
+          |
+         ::: main.py:4:8
+          |
+        2 | from lib import Test
+        3 |
+        4 | Test().test("test")
+          |        ----
+          |
+        "#);
+    }
+
+    #[test]
+    fn rename_overloaded_function_usage() {
+        let test = CursorTest::builder()
+            .source(
+                "lib.py",
+                r#"
+                from typing import overload, Any
+
+                @overload
+                def test() -> None: ...
+                @overload
+                def test(a: str) -> str: ...
+                @overload
+                def test(a: int) -> int: ...
+
+                def test(a: Any) -> Any:
+                    return a
+                "#,
+            )
+            .source(
+                "main.py",
+                r#"
+                from lib import test
+
+                test<CURSOR>("test")
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r#"
+        info[rename]: Rename symbol (found 3 locations)
+         --> main.py:2:17
+          |
+        2 | from lib import test
+          |                 ^^^^
+        3 |
+        4 | test("test")
+          | ----
+          |
+         ::: lib.py:5:5
+          |
+        4 | @overload
+        5 | def test() -> None: ...
+          |     ----
+        6 | @overload
+        7 | def test(a: str) -> str: ...
+          |
+        "#);
+    }
+
+    #[test]
+    fn rename_property() {
+        let test = CursorTest::builder()
+            .source(
+                "lib.py",
+                r#"
+                class Foo:
+                    @property
+                    def my_property<CURSOR>(self) -> int:
+                        return 42
+                "#,
+            )
+            .source(
+                "main.py",
+                r#"
+                from lib import Foo
+
+                print(Foo().my_property)
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r"
+        info[rename]: Rename symbol (found 2 locations)
+         --> lib.py:4:9
+          |
+        2 | class Foo:
+        3 |     @property
+        4 |     def my_property(self) -> int:
+          |         ^^^^^^^^^^^
+        5 |         return 42
+          |
+         ::: main.py:4:13
+          |
+        2 | from lib import Foo
+        3 |
+        4 | print(Foo().my_property)
+          |             -----------
+          |
+        ");
+    }
+
+    // TODO: this should rename the name of the function decorated with
+    // `@my_property.setter` as well as the getter function name
+    #[test]
+    fn rename_property_with_setter() {
+        let test = CursorTest::builder()
+            .source(
+                "lib.py",
+                r#"
+                class Foo:
+                    @property
+                    def my_property<CURSOR>(self) -> int:
+                        return 42
+
+                    @my_property.setter
+                    def my_property(self, value: int) -> None:
+                        pass
+                "#,
+            )
+            .source(
+                "main.py",
+                r#"
+                from lib import Foo
+
+                print(Foo().my_property)
+                Foo().my_property = 56
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r"
+        info[rename]: Rename symbol (found 4 locations)
+         --> lib.py:4:9
+          |
+        2 | class Foo:
+        3 |     @property
+        4 |     def my_property(self) -> int:
+          |         ^^^^^^^^^^^
+        5 |         return 42
+        6 |
+        7 |     @my_property.setter
+          |      -----------
+        8 |     def my_property(self, value: int) -> None:
+        9 |         pass
+          |
+         ::: main.py:4:13
+          |
+        2 | from lib import Foo
+        3 |
+        4 | print(Foo().my_property)
+          |             -----------
+        5 | Foo().my_property = 56
+          |       -----------
+          |
+        ");
+    }
+
+    // TODO: this should rename the name of the function decorated with
+    // `@my_property.deleter` as well as the getter function name
+    #[test]
+    fn rename_property_with_deleter() {
+        let test = CursorTest::builder()
+            .source(
+                "lib.py",
+                r#"
+                class Foo:
+                    @property
+                    def my_property<CURSOR>(self) -> int:
+                        return 42
+
+                    @my_property.deleter
+                    def my_property(self) -> None:
+                        pass
+                "#,
+            )
+            .source(
+                "main.py",
+                r#"
+                from lib import Foo
+
+                print(Foo().my_property)
+                del Foo().my_property
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r"
+        info[rename]: Rename symbol (found 4 locations)
+         --> lib.py:4:9
+          |
+        2 | class Foo:
+        3 |     @property
+        4 |     def my_property(self) -> int:
+          |         ^^^^^^^^^^^
+        5 |         return 42
+        6 |
+        7 |     @my_property.deleter
+          |      -----------
+        8 |     def my_property(self) -> None:
+        9 |         pass
+          |
+         ::: main.py:4:13
+          |
+        2 | from lib import Foo
+        3 |
+        4 | print(Foo().my_property)
+          |             -----------
+        5 | del Foo().my_property
+          |           -----------
+          |
+        ");
+    }
+
+    // TODO: this should rename the name of the functions decorated with
+    // `@my_property.deleter` and `@my_property.deleter` as well as the
+    // getter function name
+    #[test]
+    fn rename_property_with_setter_and_deleter() {
+        let test = CursorTest::builder()
+            .source(
+                "lib.py",
+                r#"
+                class Foo:
+                    @property
+                    def my_property<CURSOR>(self) -> int:
+                        return 42
+
+                    @my_property.setter
+                    def my_property(self, value: int) -> None:
+                        pass
+
+                    @my_property.deleter
+                    def my_property(self) -> None:
+                        pass
+                "#,
+            )
+            .source(
+                "main.py",
+                r#"
+                from lib import Foo
+
+                print(Foo().my_property)
+                Foo().my_property = 56
+                del Foo().my_property
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r"
+        info[rename]: Rename symbol (found 6 locations)
+          --> lib.py:4:9
+           |
+         2 | class Foo:
+         3 |     @property
+         4 |     def my_property(self) -> int:
+           |         ^^^^^^^^^^^
+         5 |         return 42
+         6 |
+         7 |     @my_property.setter
+           |      -----------
+         8 |     def my_property(self, value: int) -> None:
+         9 |         pass
+        10 |
+        11 |     @my_property.deleter
+           |      -----------
+        12 |     def my_property(self) -> None:
+        13 |         pass
+           |
+          ::: main.py:4:13
+           |
+         2 | from lib import Foo
+         3 |
+         4 | print(Foo().my_property)
+           |             -----------
+         5 | Foo().my_property = 56
+           |       -----------
+         6 | del Foo().my_property
+           |           -----------
+           |
+        ");
+    }
+
+    #[test]
+    fn rename_single_dispatch_function() {
+        let test = CursorTest::builder()
+            .source(
+                "foo.py",
+                r#"
+                from functools import singledispatch
+
+                @singledispatch
+                def f<CURSOR>(x: object):
+                    raise NotImplementedError
+
+                @f.register
+                def _(x: int) -> str:
+                    return "int"
+
+                @f.register
+                def _(x: str) -> int:
+                    return int(x)
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r#"
+        info[rename]: Rename symbol (found 3 locations)
+          --> foo.py:5:5
+           |
+         4 | @singledispatch
+         5 | def f(x: object):
+           |     ^
+         6 |     raise NotImplementedError
+         7 |
+         8 | @f.register
+           |  -
+         9 | def _(x: int) -> str:
+        10 |     return "int"
+        11 |
+        12 | @f.register
+           |  -
+        13 | def _(x: str) -> int:
+        14 |     return int(x)
+           |
+        "#);
+    }
+
+    #[test]
+    fn rename_single_dispatch_function_stacked_register() {
+        let test = CursorTest::builder()
+            .source(
+                "foo.py",
+                r#"
+                from functools import singledispatch
+
+                @singledispatch
+                def f<CURSOR>(x):
+                    raise NotImplementedError
+
+                @f.register(int)
+                @f.register(float)
+                def _(x) -> float:
+                    return "int"
+
+                @f.register(str)
+                def _(x) -> int:
+                    return int(x)
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r#"
+        info[rename]: Rename symbol (found 4 locations)
+          --> foo.py:5:5
+           |
+         4 | @singledispatch
+         5 | def f(x):
+           |     ^
+         6 |     raise NotImplementedError
+         7 |
+         8 | @f.register(int)
+           |  -
+         9 | @f.register(float)
+           |  -
+        10 | def _(x) -> float:
+        11 |     return "int"
+        12 |
+        13 | @f.register(str)
+           |  -
+        14 | def _(x) -> int:
+        15 |     return int(x)
+           |
+        "#);
+    }
+
+    #[test]
+    fn rename_single_dispatchmethod() {
+        let test = CursorTest::builder()
+            .source(
+                "foo.py",
+                r#"
+                from functools import singledispatchmethod
+
+                class Foo:
+                    @singledispatchmethod
+                    def f<CURSOR>(self, x: object):
+                        raise NotImplementedError
+
+                    @f.register
+                    def _(self, x: str) -> float:
+                        return "int"
+
+                    @f.register
+                    def _(self, x: str) -> int:
+                        return int(x)
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r#"
+        info[rename]: Rename symbol (found 3 locations)
+          --> foo.py:6:9
+           |
+         4 | class Foo:
+         5 |     @singledispatchmethod
+         6 |     def f(self, x: object):
+           |         ^
+         7 |         raise NotImplementedError
+         8 |
+         9 |     @f.register
+           |      -
+        10 |     def _(self, x: str) -> float:
+        11 |         return "int"
+        12 |
+        13 |     @f.register
+           |      -
+        14 |     def _(self, x: str) -> int:
+        15 |         return int(x)
+           |
+        "#);
+    }
+
+    #[test]
+    fn rename_single_dispatchmethod_staticmethod() {
+        let test = CursorTest::builder()
+            .source(
+                "foo.py",
+                r#"
+                from functools import singledispatchmethod
+
+                class Foo:
+                    @singledispatchmethod
+                    @staticmethod
+                    def f<CURSOR>(self, x):
+                        raise NotImplementedError
+
+                    @f.register(str)
+                    @staticmethod
+                    def _(x: int) -> str:
+                        return "int"
+
+                    @f.register
+                    @staticmethod
+                    def _(x: str) -> int:
+                        return int(x)
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r#"
+        info[rename]: Rename symbol (found 3 locations)
+          --> foo.py:7:9
+           |
+         5 |     @singledispatchmethod
+         6 |     @staticmethod
+         7 |     def f(self, x):
+           |         ^
+         8 |         raise NotImplementedError
+         9 |
+        10 |     @f.register(str)
+           |      -
+        11 |     @staticmethod
+        12 |     def _(x: int) -> str:
+        13 |         return "int"
+        14 |
+        15 |     @f.register
+           |      -
+        16 |     @staticmethod
+        17 |     def _(x: str) -> int:
+           |
+        "#);
+    }
+
+    #[test]
+    fn rename_single_dispatchmethod_classmethod() {
+        let test = CursorTest::builder()
+            .source(
+                "foo.py",
+                r#"
+                from functools import singledispatchmethod
+
+                class Foo:
+                    @singledispatchmethod
+                    @classmethod
+                    def f<CURSOR>(cls, x):
+                        raise NotImplementedError
+
+                    @f.register(str)
+                    @classmethod
+                    def _(cls, x) -> str:
+                        return "int"
+
+                    @f.register(int)
+                    @f.register(float)
+                    @staticmethod
+                    def _(cls, x) -> int:
+                        return int(x)
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r#"
+        info[rename]: Rename symbol (found 4 locations)
+          --> foo.py:7:9
+           |
+         5 |     @singledispatchmethod
+         6 |     @classmethod
+         7 |     def f(cls, x):
+           |         ^
+         8 |         raise NotImplementedError
+         9 |
+        10 |     @f.register(str)
+           |      -
+        11 |     @classmethod
+        12 |     def _(cls, x) -> str:
+        13 |         return "int"
+        14 |
+        15 |     @f.register(int)
+           |      -
+        16 |     @f.register(float)
+           |      -
+        17 |     @staticmethod
+        18 |     def _(cls, x) -> int:
+           |
+        "#);
+    }
+
+    #[test]
+    fn rename_attribute() {
+        let test = CursorTest::builder()
+            .source(
+                "foo.py",
+                r#"
+                class Test:
+                    attribute<CURSOR>: str
+
+                    def __init__(self, value: str):
+                        self.attribute = value
+
+                class Child(Test):
+                    def test(self):
+                        return self.attribute
+
+
+                c = Child("test")
+
+                print(c.attribute)
+                c.attribute = "new_value"
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r#"
+        info[rename]: Rename symbol (found 5 locations)
+          --> foo.py:3:5
+           |
+         2 | class Test:
+         3 |     attribute: str
+           |     ^^^^^^^^^
+         4 |
+         5 |     def __init__(self, value: str):
+         6 |         self.attribute = value
+           |              ---------
+         7 |
+         8 | class Child(Test):
+         9 |     def test(self):
+        10 |         return self.attribute
+           |                     ---------
+           |
+          ::: foo.py:15:9
+           |
+        13 | c = Child("test")
+        14 |
+        15 | print(c.attribute)
+           |         ---------
+        16 | c.attribute = "new_value"
+           |   ---------
+           |
+        "#);
+    }
+
+    // TODO: This should rename all attribute usages
+    // Note: Pylance only renames the assignment in `__init__`.
+    #[test]
+    fn rename_implicit_attribute() {
+        let test = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+                class Test:
+                    def __init__(self, value: str):
+                        self.<CURSOR>attribute = value
+
+                class Child(Test):
+                    def __init__(self, value: str):
+                        super().__init__(value)
+                        self.attribute = value + "child"
+
+                    def test(self):
+                        return self.attribute
+
+
+                c = Child("test")
+
+                print(c.attribute)
+                c.attribute = "new_value"
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r"
+        info[rename]: Rename symbol (found 1 locations)
+         --> main.py:4:14
+          |
+        2 | class Test:
+        3 |     def __init__(self, value: str):
+        4 |         self.attribute = value
+          |              ^^^^^^^^^
+        5 |
+        6 | class Child(Test):
+          |
+        ");
+    }
+
+    // TODO: Should not rename the first declaration
+    #[test]
+    fn rename_redeclarations() {
+        let test = CursorTest::builder()
+            .source(
+                "main.py",
+                r#"
+                a: str = "test"
+
+                a: int = 10
+
+                print(a<CURSOR>)
+                "#,
+            )
+            .build();
+
+        assert_snapshot!(test.rename("better_name"), @r#"
+        info[rename]: Rename symbol (found 3 locations)
+         --> main.py:2:1
+          |
+        2 | a: str = "test"
+          | ^
+        3 |
+        4 | a: int = 10
+          | -
+        5 |
+        6 | print(a)
+          |       -
+          |
+        "#);
+    }
 }

crates/ty_ide/src/semantic_tokens.rs

@@ -259,7 +259,11 @@ impl<'db> SemanticTokenVisitor<'db> {
 
     fn classify_name(&self, name: &ast::ExprName) -> (SemanticTokenType, SemanticTokenModifier) {
         // First try to classify the token based on its definition kind.
-        let definition = definition_for_name(self.model, name);
+        let definition = definition_for_name(
+            self.model,
+            name,
+            ty_python_semantic::ImportAliasResolution::ResolveAliases,
+        );
 
         if let Some(definition) = definition {
             let name_str = name.id.as_str();

crates/ty_ide/src/signature_help.rs

@@ -20,6 +20,7 @@ use ty_python_semantic::semantic_index::definition::Definition;
 use ty_python_semantic::types::ide_support::{
     CallSignatureDetails, call_signature_details, find_active_signature_from_details,
 };
+use ty_python_semantic::types::{ParameterKind, Type};
 
 // TODO: We may want to add special-case handling for calls to constructors
 // so the class docstring is used in place of (or inaddition to) any docstring
@@ -27,25 +28,29 @@ use ty_python_semantic::types::ide_support::{
 
 /// Information about a function parameter
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct ParameterDetails {
+pub struct ParameterDetails<'db> {
     /// The parameter name (e.g., "param1")
     pub name: String,
     /// The parameter label in the signature (e.g., "param1: str")
     pub label: String,
+    /// The annotated type of the parameter, if any
+    pub ty: Option<Type<'db>>,
     /// Documentation specific to the parameter, typically extracted from the
     /// function's docstring
     pub documentation: Option<String>,
+    /// True if the parameter is positional-only.
+    pub is_positional_only: bool,
 }
 
 /// Information about a function signature
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SignatureDetails {
+pub struct SignatureDetails<'db> {
     /// Text representation of the full signature (including input parameters and return type).
     pub label: String,
     /// Documentation for the signature, typically from the function's docstring.
     pub documentation: Option<Docstring>,
     /// Information about each of the parameters in left-to-right order.
-    pub parameters: Vec<ParameterDetails>,
+    pub parameters: Vec<ParameterDetails<'db>>,
     /// Index of the parameter that corresponds to the argument where the
     /// user's cursor is currently positioned.
     pub active_parameter: Option<usize>,
@@ -53,18 +58,18 @@ pub struct SignatureDetails {
 
 /// Signature help information for function calls
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SignatureHelpInfo {
+pub struct SignatureHelpInfo<'db> {
     /// Information about each of the signatures for the function call. We
     /// need to handle multiple because of unions, overloads, and composite
     /// calls like constructors (which invoke both __new__ and __init__).
-    pub signatures: Vec<SignatureDetails>,
+    pub signatures: Vec<SignatureDetails<'db>>,
     /// Index of the "active signature" which is the first signature where
     /// all arguments that are currently present in the code map to parameters.
     pub active_signature: Option<usize>,
 }
 
 /// Signature help information for function calls at the given position
-pub fn signature_help(db: &dyn Db, file: File, offset: TextSize) -> Option<SignatureHelpInfo> {
+pub fn signature_help(db: &dyn Db, file: File, offset: TextSize) -> Option<SignatureHelpInfo<'_>> {
     let parsed = parsed_module(db, file).load(db);
 
     // Get the call expression at the given position.
@@ -166,11 +171,11 @@ fn get_argument_index(call_expr: &ast::ExprCall, offset: TextSize) -> usize {
 }
 
 /// Create signature details from `CallSignatureDetails`.
-fn create_signature_details_from_call_signature_details(
+fn create_signature_details_from_call_signature_details<'db>(
     db: &dyn crate::Db,
-    details: &CallSignatureDetails,
+    details: &CallSignatureDetails<'db>,
     current_arg_index: usize,
-) -> SignatureDetails {
+) -> SignatureDetails<'db> {
     let signature_label = details.label.clone();
 
     let documentation = get_callable_documentation(db, details.definition);
@@ -200,6 +205,8 @@ fn create_signature_details_from_call_signature_details(
         &signature_label,
         documentation.as_ref(),
         &details.parameter_names,
+        &details.parameter_kinds,
+        &details.parameter_types,
     );
     SignatureDetails {
         label: signature_label,
@@ -218,12 +225,14 @@ fn get_callable_documentation(
 }
 
 /// Create `ParameterDetails` objects from parameter label offsets.
-fn create_parameters_from_offsets(
+fn create_parameters_from_offsets<'db>(
     parameter_offsets: &[TextRange],
     signature_label: &str,
     docstring: Option<&Docstring>,
     parameter_names: &[String],
-) -> Vec<ParameterDetails> {
+    parameter_kinds: &[ParameterKind],
+    parameter_types: &[Option<Type<'db>>],
+) -> Vec<ParameterDetails<'db>> {
     // Extract parameter documentation from the function's docstring if available.
     let param_docs = if let Some(docstring) = docstring {
         docstring.parameter_documentation()
@@ -245,11 +254,18 @@ fn create_parameters_from_offsets(
 
             // Get the parameter name for documentation lookup.
             let param_name = parameter_names.get(i).map(String::as_str).unwrap_or("");
+            let is_positional_only = matches!(
+                parameter_kinds.get(i),
+                Some(ParameterKind::PositionalOnly { .. })
+            );
+            let ty = parameter_types.get(i).copied().flatten();
 
             ParameterDetails {
                 name: param_name.to_string(),
                 label,
+                ty,
                 documentation: param_docs.get(param_name).cloned(),
+                is_positional_only,
             }
         })
         .collect()
@@ -1173,7 +1189,7 @@ def ab(a: int, *, c: int):
     }
 
     impl CursorTest {
-        fn signature_help(&self) -> Option<SignatureHelpInfo> {
+        fn signature_help(&self) -> Option<SignatureHelpInfo<'_>> {
             crate::signature_help::signature_help(&self.db, self.cursor.file, self.cursor.offset)
         }
 

crates/ty_python_semantic/mdtest.py

@@ -37,14 +37,16 @@ class MDTestRunner:
     mdtest_executable: Path | None
     console: Console
     filters: list[str]
+    enable_external: bool
 
-    def __init__(self, filters: list[str] | None = None) -> None:
+    def __init__(self, filters: list[str] | None, enable_external: bool) -> None:
         self.mdtest_executable = None
         self.console = Console()
         self.filters = [
             f.removesuffix(".md").replace("/", "_").replace("-", "_")
             for f in (filters or [])
         ]
+        self.enable_external = enable_external
 
     def _run_cargo_test(self, *, message_format: Literal["human", "json"]) -> str:
         return subprocess.check_output(
@@ -120,6 +122,7 @@ class MDTestRunner:
                 CLICOLOR_FORCE="1",
                 INSTA_FORCE_PASS="1",
                 INSTA_OUTPUT="none",
+                MDTEST_EXTERNAL="1" if self.enable_external else "0",
             ),
             capture_output=capture_output,
             text=True,
@@ -266,11 +269,19 @@ def main() -> None:
         nargs="*",
         help="Partial paths or mangled names, e.g., 'loops/for.md' or 'loops_for'",
     )
+    parser.add_argument(
+        "--enable-external",
+        "-e",
+        action="store_true",
+        help="Enable tests with external dependencies",
+    )
 
     args = parser.parse_args()
 
     try:
-        runner = MDTestRunner(filters=args.filters)
+        runner = MDTestRunner(
+            filters=args.filters, enable_external=args.enable_external
+        )
         runner.watch()
     except KeyboardInterrupt:
         print()

crates/ty_python_semantic/resources/corpus/future_annotations_recursive_annotation.py

@@ -0,0 +1,4 @@
+from __future__ import annotations
+
+class MyClass:
+    type: type = str

crates/ty_python_semantic/resources/corpus/inner_expression_inference_state.py

@@ -0,0 +1,6 @@
+# This is a regression test for `store_expression_type`.
+# ref: https://github.com/astral-sh/ty/issues/1688
+
+x: int
+
+type x[T] = x[T, U]

crates/ty_python_semantic/resources/corpus/invalid_typevar_constraints.py

@@ -0,0 +1,6 @@
+class C[T: (A, B)]:
+    def f(foo: T):
+        try:
+            pass
+        except foo:
+            pass

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

@@ -307,12 +307,10 @@ Using a `ParamSpec` in a `Callable` annotation:
 from typing_extensions import Callable
 
 def _[**P1](c: Callable[P1, int]):
-    # TODO: Should reveal `ParamSpecArgs` and `ParamSpecKwargs`
-    reveal_type(P1.args)  # revealed: @Todo(ParamSpecArgs / ParamSpecKwargs)
-    reveal_type(P1.kwargs)  # revealed: @Todo(ParamSpecArgs / ParamSpecKwargs)
+    reveal_type(P1.args)  # revealed: P1@_.args
+    reveal_type(P1.kwargs)  # revealed: P1@_.kwargs
 
-    # TODO: Signature should be (**P1) -> int
-    reveal_type(c)  # revealed: (...) -> int
+    reveal_type(c)  # revealed: (**P1@_) -> int
 ```
 
 And, using the legacy syntax:
@@ -322,9 +320,8 @@ from typing_extensions import ParamSpec
 
 P2 = ParamSpec("P2")
 
-# TODO: argument list should not be `...` (requires `ParamSpec` support)
 def _(c: Callable[P2, int]):
-    reveal_type(c)  # revealed: (...) -> int
+    reveal_type(c)  # revealed: (**P2@_) -> int
 ```
 
 ## Using `typing.Unpack`

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

@@ -18,9 +18,8 @@ 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:
-    # 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)]
+    reveal_type(args)  # revealed: P@i.args
+    reveal_type(kwargs)  # revealed: P@i.kwargs
     return callback(42, *args, **kwargs)
 
 class Foo:
@@ -65,8 +64,9 @@ def _(
     reveal_type(c)  # revealed: Unknown
     reveal_type(d)  # revealed: Unknown
 
+    # error: [invalid-type-form] "Variable of type `ParamSpec` is not allowed in a type expression"
     def foo(a_: e) -> None:
-        reveal_type(a_)  # revealed: @Todo(Support for `typing.ParamSpec`)
+        reveal_type(a_)  # revealed: Unknown
 ```
 
 ## Inheritance

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

@@ -227,17 +227,56 @@ def _(literals_2: Literal[0, 1], b: bool, flag: bool):
     literals_16 = 4 * literals_4 + literals_4  # Literal[0, 1, .., 15]
     literals_64 = 4 * literals_16 + literals_4  # Literal[0, 1, .., 63]
     literals_128 = 2 * literals_64 + literals_2  # Literal[0, 1, .., 127]
+    literals_256 = 2 * literals_128 + literals_2  # Literal[0, 1, .., 255]
 
-    # Going beyond the MAX_UNION_LITERALS limit (currently 200):
-    literals_256 = 16 * literals_16 + literals_16
-    reveal_type(literals_256)  # revealed: int
+    # Going beyond the MAX_NON_RECURSIVE_UNION_LITERALS limit (currently 256):
+    reveal_type(literals_256 if flag else 256)  # revealed: int
 
     # Going beyond the limit when another type is already part of the union
     bool_and_literals_128 = b if flag else literals_128  # bool | Literal[0, 1, ..., 127]
     literals_128_shifted = literals_128 + 128  # Literal[128, 129, ..., 255]
+    literals_256_shifted = literals_256 + 256  # Literal[256, 257, ..., 511]
 
     # Now union the two:
-    reveal_type(bool_and_literals_128 if flag else literals_128_shifted)  # revealed: int
+    two = bool_and_literals_128 if flag else literals_128_shifted
+    # revealed: bool | Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190, 191, 192, 193, 194, 195, 196, 197, 198, 199, 200, 201, 202, 203, 204, 205, 206, 207, 208, 209, 210, 211, 212, 213, 214, 215, 216, 217, 218, 219, 220, 221, 222, 223, 224, 225, 226, 227, 228, 229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243, 244, 245, 246, 247, 248, 249, 250, 251, 252, 253, 254, 255]
+    reveal_type(two)
+    reveal_type(two if flag else literals_256_shifted)  # revealed: int
+```
+
+Recursively defined literal union types are widened earlier than non-recursively defined types for
+faster convergence.
+
+```py
+class RecursiveAttr:
+    def __init__(self):
+        self.i = 0
+
+    def update(self):
+        self.i = self.i + 1
+
+reveal_type(RecursiveAttr().i)  # revealed: Unknown | int
+
+# Here are some recursive but saturating examples. Because it's difficult to statically determine whether literal unions saturate or diverge,
+# we widen them early, even though they may actually be convergent.
+class RecursiveAttr2:
+    def __init__(self):
+        self.i = 0
+
+    def update(self):
+        self.i = (self.i + 1) % 9
+
+reveal_type(RecursiveAttr2().i)  # revealed: Unknown | Literal[0, 1, 2, 3, 4, 5, 6, 7, 8]
+
+class RecursiveAttr3:
+    def __init__(self):
+        self.i = 0
+
+    def update(self):
+        self.i = (self.i + 1) % 10
+
+# Going beyond the MAX_RECURSIVE_UNION_LITERALS limit:
+reveal_type(RecursiveAttr3().i)  # revealed: Unknown | int
 ```
 
 ## Simplifying gradually-equivalent types

crates/ty_python_semantic/resources/mdtest/directives/assert_type.md

@@ -7,10 +7,11 @@
 ```py
 from typing_extensions import assert_type
 
-def _(x: int):
+def _(x: int, y: bool):
     assert_type(x, int)  # fine
     assert_type(x, str)  # error: [type-assertion-failure]
     assert_type(assert_type(x, int), int)
+    assert_type(y, int)  # error: [type-assertion-failure]
 ```
 
 ## Narrowing

crates/ty_python_semantic/resources/mdtest/external/README.md

@@ -0,0 +1,4 @@
+# mdtests with external dependencies
+
+This directory contains mdtests that make use of external packages. See the mdtest `README.md` for
+more information.

crates/ty_python_semantic/resources/mdtest/external/attrs.md

@@ -0,0 +1,78 @@
+# attrs
+
+```toml
+[environment]
+python-version = "3.13"
+python-platform = "linux"
+
+[project]
+dependencies = ["attrs==25.4.0"]
+```
+
+## Basic class (`attr`)
+
+```py
+import attr
+
+@attr.s
+class User:
+    id: int = attr.ib()
+    name: str = attr.ib()
+
+user = User(id=1, name="John Doe")
+
+reveal_type(user.id)  # revealed: int
+reveal_type(user.name)  # revealed: str
+```
+
+## Basic class (`define`)
+
+```py
+from attrs import define, field
+
+@define
+class User:
+    id: int = field()
+    internal_name: str = field(alias="name")
+
+user = User(id=1, name="John Doe")
+reveal_type(user.id)  # revealed: int
+reveal_type(user.internal_name)  # revealed: str
+```
+
+## Usage of `field` parameters
+
+```py
+from attrs import define, field
+
+@define
+class Product:
+    id: int = field(init=False)
+    name: str = field()
+    price_cent: int = field(kw_only=True)
+
+reveal_type(Product.__init__)  # revealed: (self: Product, name: str, *, price_cent: int) -> None
+```
+
+## Dedicated support for the `default` decorator?
+
+We currently do not support this:
+
+```py
+from attrs import define, field
+
+@define
+class Person:
+    id: int = field()
+    name: str = field()
+
+    # error: [call-non-callable] "Object of type `_MISSING_TYPE` is not callable"
+    @id.default
+    def _default_id(self) -> int:
+        raise NotImplementedError
+
+# error: [missing-argument] "No argument provided for required parameter `id`"
+person = Person(name="Alice")
+reveal_type(person.id)  # revealed: int
+reveal_type(person.name)  # revealed: str
+```

crates/ty_python_semantic/resources/mdtest/external/numpy.md

@@ -0,0 +1,23 @@
+# numpy
+
+```toml
+[environment]
+python-version = "3.13"
+python-platform = "linux"
+
+[project]
+dependencies = ["numpy==2.3.0"]
+```
+
+## Basic usage
+
+```py
+import numpy as np
+
+xs = np.array([1, 2, 3])
+reveal_type(xs)  # revealed: ndarray[tuple[Any, ...], dtype[Any]]
+
+xs = np.array([1.0, 2.0, 3.0], dtype=np.float64)
+# TODO: should be `ndarray[tuple[Any, ...], dtype[float64]]`
+reveal_type(xs)  # revealed: ndarray[tuple[Any, ...], dtype[Unknown]]
+```

crates/ty_python_semantic/resources/mdtest/external/pydantic.md

@@ -0,0 +1,48 @@
+# Pydantic
+
+```toml
+[environment]
+python-version = "3.12"
+python-platform = "linux"
+
+[project]
+dependencies = ["pydantic==2.12.2"]
+```
+
+## Basic model
+
+```py
+from pydantic import BaseModel
+
+class User(BaseModel):
+    id: int
+    name: str
+
+reveal_type(User.__init__)  # revealed: (self: User, *, id: int, name: str) -> None
+
+user = User(id=1, name="John Doe")
+reveal_type(user.id)  # revealed: int
+reveal_type(user.name)  # revealed: str
+
+# error: [missing-argument] "No argument provided for required parameter `name`"
+invalid_user = User(id=2)
+```
+
+## Usage of `Field`
+
+```py
+from pydantic import BaseModel, Field
+
+class Product(BaseModel):
+    id: int = Field(init=False)
+    name: str = Field(..., kw_only=False, min_length=1)
+    internal_price_cent: int = Field(..., gt=0, alias="price_cent")
+
+reveal_type(Product.__init__)  # revealed: (self: Product, name: str = Any, *, price_cent: int = Any) -> None
+
+product = Product("Laptop", price_cent=999_00)
+
+reveal_type(product.id)  # revealed: int
+reveal_type(product.name)  # revealed: str
+reveal_type(product.internal_price_cent)  # revealed: int
+```

crates/ty_python_semantic/resources/mdtest/external/pytest.md

@@ -0,0 +1,27 @@
+# pytest
+
+```toml
+[environment]
+python-version = "3.13"
+python-platform = "linux"
+
+[project]
+dependencies = ["pytest==9.0.1"]
+```
+
+## `pytest.fail`
+
+Make sure that we recognize `pytest.fail` calls as terminal:
+
+```py
+import pytest
+
+def some_runtime_condition() -> bool:
+    return True
+
+def test_something():
+    if not some_runtime_condition():
+        pytest.fail("Runtime condition failed")
+
+        no_error_here_this_is_unreachable
+```

crates/ty_python_semantic/resources/mdtest/external/sqlalchemy.md

@@ -0,0 +1,199 @@
+# SQLAlchemy
+
+```toml
+[environment]
+python-version = "3.13"
+python-platform = "linux"
+
+[project]
+dependencies = ["SQLAlchemy==2.0.44"]
+```
+
+## ORM Model
+
+This test makes sure that ty understands SQLAlchemy's `dataclass_transform` setup:
+
+```py
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "user"
+
+    id: Mapped[int] = mapped_column(primary_key=True, init=False)
+    internal_name: Mapped[str] = mapped_column(alias="name")
+
+user = User(name="John Doe")
+reveal_type(user.id)  # revealed: int
+reveal_type(user.internal_name)  # revealed: str
+```
+
+Unfortunately, SQLAlchemy overrides `__init__` and explicitly accepts all combinations of keyword
+arguments. This is why we currently cannot flag invalid constructor calls:
+
+```py
+reveal_type(User.__init__)  # revealed: def __init__(self, **kw: Any) -> Unknown
+
+# TODO: this should ideally be an error
+invalid_user = User(invalid_arg=42)
+```
+
+## Basic query example
+
+First, set up a `Session`:
+
+```py
+from sqlalchemy import select, Integer, Text, Boolean
+from sqlalchemy.orm import Session
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy import create_engine
+
+engine = create_engine("sqlite://example.db")
+session = Session(engine)
+```
+
+And define a simple model:
+
+```py
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(Text)
+    is_admin: Mapped[bool] = mapped_column(Boolean, default=False)
+```
+
+Finally, we can execute queries:
+
+```py
+stmt = select(User)
+reveal_type(stmt)  # revealed: Select[tuple[User]]
+
+users = session.scalars(stmt).all()
+reveal_type(users)  # revealed: Sequence[User]
+
+for row in session.execute(stmt):
+    reveal_type(row)  # revealed: Row[tuple[User]]
+
+stmt = select(User).where(User.name == "Alice")
+alice1 = session.scalars(stmt).first()
+reveal_type(alice1)  # revealed: User | None
+
+alice2 = session.scalar(stmt)
+reveal_type(alice2)  # revealed: User | None
+
+result = session.execute(stmt)
+row = result.one_or_none()
+assert row is not None
+(alice3,) = row._tuple()
+reveal_type(alice3)  # revealed: User
+```
+
+This also works with more complex queries:
+
+```py
+stmt = select(User).where(User.is_admin == True).order_by(User.name).limit(10)
+admin_users = session.scalars(stmt).all()
+reveal_type(admin_users)  # revealed: Sequence[User]
+```
+
+We can also specify particular columns to select:
+
+```py
+reveal_type(User.id)  # revealed: InstrumentedAttribute[int]
+stmt = select(User.id, User.name)
+reveal_type(stmt)  # revealed: Select[tuple[int, str]]
+
+ids_and_names = session.execute(stmt).all()
+reveal_type(ids_and_names)  # revealed: Sequence[Row[tuple[int, str]]]
+
+for row in session.execute(stmt):
+    reveal_type(row)  # revealed: Row[tuple[int, str]]
+
+for user_id, name in session.execute(stmt).tuples():
+    reveal_type(user_id)  # revealed: int
+    reveal_type(name)  # revealed: str
+
+result = session.execute(stmt)
+row = result.one_or_none()
+assert row is not None
+(user_id, name) = row._tuple()
+reveal_type(user_id)  # revealed: int
+reveal_type(name)  # revealed: str
+
+stmt = select(User.id).where(User.name == "Alice")
+
+reveal_type(stmt)  # revealed: Select[tuple[int]]
+
+alice_id = session.scalars(stmt).first()
+reveal_type(alice_id)  # revealed: int | None
+
+alice_id = session.scalar(stmt)
+reveal_type(alice_id)  # revealed: int | None
+```
+
+Using the legacy `query` API also works:
+
+```py
+users_legacy = session.query(User).all()
+reveal_type(users_legacy)  # revealed: list[User]
+
+query = session.query(User)
+reveal_type(query)  # revealed: Query[User]
+
+reveal_type(query.all())  # revealed: list[User]
+
+for row in query:
+    reveal_type(row)  # revealed: User
+```
+
+And similarly when specifying particular columns:
+
+```py
+query = session.query(User.id, User.name)
+# TODO: should be `RowReturningQuery[tuple[int, str]]`
+reveal_type(query)  # revealed: RowReturningQuery[tuple[Unknown, Unknown]]
+
+# TODO: should be `list[Row[tuple[int, str]]]`
+reveal_type(query.all())  # revealed: list[Row[tuple[Unknown, Unknown]]]
+
+for row in query:
+    # TODO: should be `Row[tuple[int, str]]`
+    reveal_type(row)  # revealed: Row[tuple[Unknown, Unknown]]
+```
+
+## Async API
+
+The async API is supported as well:
+
+```py
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, Integer, Text
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(Text)
+
+async def test_async(session: AsyncSession):
+    stmt = select(User).where(User.name == "Alice")
+    alice = await session.scalar(stmt)
+    reveal_type(alice)  # revealed: User | None
+
+    stmt = select(User.id, User.name)
+    result = await session.execute(stmt)
+    for user_id, name in result.tuples():
+        reveal_type(user_id)  # revealed: int
+        reveal_type(name)  # revealed: str
+```

crates/ty_python_semantic/resources/mdtest/external/sqlmodel.md

@@ -0,0 +1,30 @@
+# SQLModel
+
+```toml
+[environment]
+python-version = "3.13"
+python-platform = "linux"
+
+[project]
+dependencies = ["sqlmodel==0.0.27"]
+```
+
+## Basic model
+
+```py
+from sqlmodel import SQLModel
+
+class User(SQLModel):
+    id: int
+    name: str
+
+user = User(id=1, name="John Doe")
+reveal_type(user.id)  # revealed: int
+reveal_type(user.name)  # revealed: str
+
+# TODO: this should not mention `__pydantic_self__`, and have proper parameters defined by the fields
+reveal_type(User.__init__)  # revealed: def __init__(__pydantic_self__, **data: Any) -> None
+
+# TODO: this should be an error
+User()
+```

crates/ty_python_semantic/resources/mdtest/external/strawberry.md

@@ -0,0 +1,27 @@
+# Strawberry GraphQL
+
+```toml
+[environment]
+python-version = "3.13"
+python-platform = "linux"
+
+[project]
+dependencies = ["strawberry-graphql==0.283.3"]
+```
+
+## Basic model
+
+```py
+import strawberry
+
+@strawberry.type
+class User:
+    id: int
+    role: str = strawberry.field(default="user")
+
+reveal_type(User.__init__)  # revealed: (self: User, *, id: int, role: str = Any) -> None
+
+user = User(id=1)
+reveal_type(user.id)  # revealed: int
+reveal_type(user.role)  # revealed: str
+```

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

@@ -301,6 +301,7 @@ consistent with each other.
 
 ```py
 from typing_extensions import Generic, TypeVar
+from ty_extensions import generic_context, into_callable
 
 T = TypeVar("T")
 
@@ -308,6 +309,11 @@ class C(Generic[T]):
     def __new__(cls, x: T) -> "C[T]":
         return object.__new__(cls)
 
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C(1))  # revealed: C[int]
 
 # error: [invalid-assignment] "Object of type `C[int | str]` is not assignable to `C[int]`"
@@ -318,12 +324,18 @@ wrong_innards: C[int] = C("five")
 
 ```py
 from typing_extensions import Generic, TypeVar
+from ty_extensions import generic_context, into_callable
 
 T = TypeVar("T")
 
 class C(Generic[T]):
     def __init__(self, x: T) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C(1))  # revealed: C[int]
 
 # error: [invalid-assignment] "Object of type `C[int | str]` is not assignable to `C[int]`"
@@ -334,6 +346,7 @@ wrong_innards: C[int] = C("five")
 
 ```py
 from typing_extensions import Generic, TypeVar
+from ty_extensions import generic_context, into_callable
 
 T = TypeVar("T")
 
@@ -343,6 +356,11 @@ class C(Generic[T]):
 
     def __init__(self, x: T) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C(1))  # revealed: C[int]
 
 # error: [invalid-assignment] "Object of type `C[int | str]` is not assignable to `C[int]`"
@@ -353,6 +371,7 @@ wrong_innards: C[int] = C("five")
 
 ```py
 from typing_extensions import Generic, TypeVar
+from ty_extensions import generic_context, into_callable
 
 T = TypeVar("T")
 
@@ -362,6 +381,11 @@ class C(Generic[T]):
 
     def __init__(self, x: T) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C(1))  # revealed: C[int]
 
 # error: [invalid-assignment] "Object of type `C[int | str]` is not assignable to `C[int]`"
@@ -373,6 +397,11 @@ class D(Generic[T]):
 
     def __init__(self, *args, **kwargs) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@D]
+reveal_type(generic_context(D))
+# revealed: ty_extensions.GenericContext[T@D]
+reveal_type(generic_context(into_callable(D)))
+
 reveal_type(D(1))  # revealed: D[int]
 
 # error: [invalid-assignment] "Object of type `D[int | str]` is not assignable to `D[int]`"
@@ -386,6 +415,7 @@ to specialize the class.
 
 ```py
 from typing_extensions import Generic, TypeVar
+from ty_extensions import generic_context, into_callable
 
 T = TypeVar("T")
 U = TypeVar("U")
@@ -398,6 +428,11 @@ class C(Generic[T, U]):
 class D(C[V, int]):
     def __init__(self, x: V) -> None: ...
 
+# revealed: ty_extensions.GenericContext[V@D]
+reveal_type(generic_context(D))
+# revealed: ty_extensions.GenericContext[V@D]
+reveal_type(generic_context(into_callable(D)))
+
 reveal_type(D(1))  # revealed: D[int]
 ```
 
@@ -405,6 +440,7 @@ reveal_type(D(1))  # revealed: D[int]
 
 ```py
 from typing_extensions import Generic, TypeVar
+from ty_extensions import generic_context, into_callable
 
 T = TypeVar("T")
 U = TypeVar("U")
@@ -415,6 +451,11 @@ class C(Generic[T, U]):
 class D(C[T, U]):
     pass
 
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(D))
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(into_callable(D)))
+
 reveal_type(C(1, "str"))  # revealed: C[int, str]
 reveal_type(D(1, "str"))  # revealed: D[int, str]
 ```
@@ -425,6 +466,7 @@ This is a specific example of the above, since it was reported specifically by a
 
 ```py
 from typing_extensions import Generic, TypeVar
+from ty_extensions import generic_context, into_callable
 
 T = TypeVar("T")
 U = TypeVar("U")
@@ -432,6 +474,11 @@ U = TypeVar("U")
 class D(dict[T, U]):
     pass
 
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(D))
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(into_callable(D)))
+
 reveal_type(D(key=1))  # revealed: D[str, int]
 ```
 
@@ -443,12 +490,18 @@ context. But from the user's point of view, this is another example of the above
 
 ```py
 from typing_extensions import Generic, TypeVar
+from ty_extensions import generic_context, into_callable
 
 T = TypeVar("T")
 U = TypeVar("U")
 
 class C(tuple[T, U]): ...
 
+# revealed: ty_extensions.GenericContext[T@C, U@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C, U@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C((1, 2)))  # revealed: C[int, int]
 ```
 
@@ -480,6 +533,7 @@ def func8(t1: tuple[complex, list[int]], t2: tuple[int, *tuple[str, ...]], t3: t
 
 ```py
 from typing_extensions import Generic, TypeVar
+from ty_extensions import generic_context, into_callable
 
 S = TypeVar("S")
 T = TypeVar("T")
@@ -487,6 +541,11 @@ T = TypeVar("T")
 class C(Generic[T]):
     def __init__(self, x: T, y: S) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C, S@__init__]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C(1, 1))  # revealed: C[int]
 reveal_type(C(1, "string"))  # revealed: C[int]
 reveal_type(C(1, True))  # revealed: C[int]
@@ -499,6 +558,7 @@ wrong_innards: C[int] = C("five", 1)
 
 ```py
 from typing_extensions import overload, Generic, TypeVar
+from ty_extensions import generic_context, into_callable
 
 T = TypeVar("T")
 U = TypeVar("U")
@@ -514,6 +574,11 @@ class C(Generic[T]):
     def __init__(self, x: int) -> None: ...
     def __init__(self, x: str | bytes | int) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C("string"))  # revealed: C[str]
 reveal_type(C(b"bytes"))  # revealed: C[bytes]
 reveal_type(C(12))  # revealed: C[Unknown]
@@ -541,6 +606,11 @@ class D(Generic[T, U]):
     def __init__(self, t: T, u: U) -> None: ...
     def __init__(self, *args) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(D))
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(into_callable(D)))
+
 reveal_type(D("string"))  # revealed: D[str, str]
 reveal_type(D(1))  # revealed: D[str, int]
 reveal_type(D(1, "string"))  # revealed: D[int, str]
@@ -551,6 +621,7 @@ reveal_type(D(1, "string"))  # revealed: D[int, str]
 ```py
 from dataclasses import dataclass
 from typing_extensions import Generic, TypeVar
+from ty_extensions import generic_context, into_callable
 
 T = TypeVar("T")
 
@@ -558,6 +629,11 @@ T = TypeVar("T")
 class A(Generic[T]):
     x: T
 
+# revealed: ty_extensions.GenericContext[T@A]
+reveal_type(generic_context(A))
+# revealed: ty_extensions.GenericContext[T@A]
+reveal_type(generic_context(into_callable(A)))
+
 reveal_type(A(x=1))  # revealed: A[int]
 ```
 
@@ -565,17 +641,28 @@ reveal_type(A(x=1))  # revealed: A[int]
 
 ```py
 from typing_extensions import Generic, TypeVar
+from ty_extensions import generic_context, into_callable
 
 T = TypeVar("T")
 U = TypeVar("U", default=T)
 
 class C(Generic[T, U]): ...
 
+# revealed: ty_extensions.GenericContext[T@C, U@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C, U@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C())  # revealed: C[Unknown, Unknown]
 
 class D(Generic[T, U]):
     def __init__(self) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(D))
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(into_callable(D)))
+
 reveal_type(D())  # revealed: D[Unknown, Unknown]
 ```
 

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

@@ -102,6 +102,38 @@ Other values are invalid.
 P4 = ParamSpec("P4", default=int)
 ```
 
+### `default` parameter in `typing_extensions.ParamSpec`
+
+```toml
+[environment]
+python-version = "3.12"
+```
+
+The `default` parameter to `ParamSpec` is available from `typing_extensions` in Python 3.12 and
+earlier.
+
+```py
+from typing import ParamSpec
+from typing_extensions import ParamSpec as ExtParamSpec
+
+# This shouldn't emit a diagnostic
+P1 = ExtParamSpec("P1", default=[int, str])
+
+# But, this should
+# error: [invalid-paramspec] "The `default` parameter of `typing.ParamSpec` was added in Python 3.13"
+P2 = ParamSpec("P2", default=[int, str])
+```
+
+And, it allows the same set of values as `typing.ParamSpec`.
+
+```py
+P3 = ExtParamSpec("P3", default=...)
+P4 = ExtParamSpec("P4", default=P3)
+
+# error: [invalid-paramspec]
+P5 = ExtParamSpec("P5", default=int)
+```
+
 ### Forward references in stub files
 
 Stubs natively support forward references, so patterns that would raise `NameError` at runtime are
@@ -115,3 +147,297 @@ P = ParamSpec("P", default=[A, B])
 class A: ...
 class B: ...
 ```
+
+## Validating `ParamSpec` usage
+
+In type annotations, `ParamSpec` is only valid as the first element to `Callable`, the final element
+to `Concatenate`, or as a type parameter to `Protocol` or `Generic`.
+
+```py
+from typing import ParamSpec, Callable, Concatenate, Protocol, Generic
+
+P = ParamSpec("P")
+
+class ValidProtocol(Protocol[P]):
+    def method(self, c: Callable[P, int]) -> None: ...
+
+class ValidGeneric(Generic[P]):
+    def method(self, c: Callable[P, int]) -> None: ...
+
+def valid(
+    a1: Callable[P, int],
+    a2: Callable[Concatenate[int, P], int],
+) -> None: ...
+def invalid(
+    # TODO: error
+    a1: P,
+    # TODO: error
+    a2: list[P],
+    # TODO: error
+    a3: Callable[[P], int],
+    # TODO: error
+    a4: Callable[..., P],
+    # TODO: error
+    a5: Callable[Concatenate[P, ...], int],
+) -> None: ...
+```
+
+## Validating `P.args` and `P.kwargs` usage
+
+The components of `ParamSpec` i.e., `P.args` and `P.kwargs` are only valid when used as the
+annotated types of `*args` and `**kwargs` respectively.
+
+```py
+from typing import Generic, Callable, ParamSpec
+
+P = ParamSpec("P")
+
+def foo1(c: Callable[P, int]) -> None:
+    def nested1(*args: P.args, **kwargs: P.kwargs) -> None: ...
+    def nested2(
+        # error: [invalid-type-form] "`P.kwargs` is valid only in `**kwargs` annotation: Did you mean `P.args`?"
+        *args: P.kwargs,
+        # error: [invalid-type-form] "`P.args` is valid only in `*args` annotation: Did you mean `P.kwargs`?"
+        **kwargs: P.args,
+    ) -> None: ...
+
+    # TODO: error
+    def nested3(*args: P.args) -> None: ...
+
+    # TODO: error
+    def nested4(**kwargs: P.kwargs) -> None: ...
+
+    # TODO: error
+    def nested5(*args: P.args, x: int, **kwargs: P.kwargs) -> None: ...
+
+# TODO: error
+def bar1(*args: P.args, **kwargs: P.kwargs) -> None:
+    pass
+
+class Foo1:
+    # TODO: error
+    def method(self, *args: P.args, **kwargs: P.kwargs) -> None: ...
+```
+
+And, they need to be used together.
+
+```py
+def foo2(c: Callable[P, int]) -> None:
+    # TODO: error
+    def nested1(*args: P.args) -> None: ...
+
+    # TODO: error
+    def nested2(**kwargs: P.kwargs) -> None: ...
+
+class Foo2:
+    # TODO: error
+    args: P.args
+
+    # TODO: error
+    kwargs: P.kwargs
+```
+
+The name of these parameters does not need to be `args` or `kwargs`, it's the annotated type to the
+respective variadic parameter that matters.
+
+```py
+class Foo3(Generic[P]):
+    def method1(self, *paramspec_args: P.args, **paramspec_kwargs: P.kwargs) -> None: ...
+    def method2(
+        self,
+        # error: [invalid-type-form] "`P.kwargs` is valid only in `**kwargs` annotation: Did you mean `P.args`?"
+        *paramspec_args: P.kwargs,
+        # error: [invalid-type-form] "`P.args` is valid only in `*args` annotation: Did you mean `P.kwargs`?"
+        **paramspec_kwargs: P.args,
+    ) -> None: ...
+```
+
+## Specializing generic classes explicitly
+
+```py
+from typing import Any, Generic, ParamSpec, Callable, TypeVar
+
+P1 = ParamSpec("P1")
+P2 = ParamSpec("P2")
+T1 = TypeVar("T1")
+
+class OnlyParamSpec(Generic[P1]):
+    attr: Callable[P1, None]
+
+class TwoParamSpec(Generic[P1, P2]):
+    attr1: Callable[P1, None]
+    attr2: Callable[P2, None]
+
+class TypeVarAndParamSpec(Generic[T1, P1]):
+    attr: Callable[P1, T1]
+```
+
+Explicit specialization of a generic class involving `ParamSpec` is done by providing either a list
+of types, `...`, or another in-scope `ParamSpec`.
+
+```py
+reveal_type(OnlyParamSpec[[]]().attr)  # revealed: () -> None
+reveal_type(OnlyParamSpec[[int, str]]().attr)  # revealed: (int, str, /) -> None
+reveal_type(OnlyParamSpec[...]().attr)  # revealed: (...) -> None
+
+def func(c: Callable[P2, None]):
+    reveal_type(OnlyParamSpec[P2]().attr)  # revealed: (**P2@func) -> None
+
+# TODO: error: paramspec is unbound
+reveal_type(OnlyParamSpec[P2]().attr)  # revealed: (...) -> None
+
+# error: [invalid-type-arguments] "No type argument provided for required type variable `P1` of class `OnlyParamSpec`"
+reveal_type(OnlyParamSpec[()]().attr)  # revealed: (...) -> None
+```
+
+An explicit tuple expression (unlike an implicit one that omits the parentheses) is also accepted
+when the `ParamSpec` is the only type variable. But, this isn't recommended is mainly a fallout of
+it having the same AST as the one without the parentheses. Both mypy and Pyright also allow this.
+
+```py
+reveal_type(OnlyParamSpec[(int, str)]().attr)  # revealed: (int, str, /) -> None
+```
+
+<!-- blacken-docs:off -->
+
+```py
+# error: [invalid-syntax]
+reveal_type(OnlyParamSpec[]().attr)  # revealed: (...) -> None
+```
+
+<!-- blacken-docs:on -->
+
+The square brackets can be omitted when `ParamSpec` is the only type variable
+
+```py
+reveal_type(OnlyParamSpec[int, str]().attr)  # revealed: (int, str, /) -> None
+reveal_type(OnlyParamSpec[int,]().attr)  # revealed: (int, /) -> None
+
+# Even when there is only one element
+reveal_type(OnlyParamSpec[Any]().attr)  # revealed: (Any, /) -> None
+reveal_type(OnlyParamSpec[object]().attr)  # revealed: (object, /) -> None
+reveal_type(OnlyParamSpec[int]().attr)  # revealed: (int, /) -> None
+```
+
+But, they cannot be omitted when there are multiple type variables.
+
+```py
+reveal_type(TypeVarAndParamSpec[int, []]().attr)  # revealed: () -> int
+reveal_type(TypeVarAndParamSpec[int, [int, str]]().attr)  # revealed: (int, str, /) -> int
+reveal_type(TypeVarAndParamSpec[int, [str]]().attr)  # revealed: (str, /) -> int
+reveal_type(TypeVarAndParamSpec[int, ...]().attr)  # revealed: (...) -> int
+
+# TODO: We could still specialize for `T1` as the type is valid which would reveal `(...) -> int`
+# TODO: error: paramspec is unbound
+reveal_type(TypeVarAndParamSpec[int, P2]().attr)  # revealed: (...) -> Unknown
+# error: [invalid-type-arguments] "Type argument for `ParamSpec` must be"
+reveal_type(TypeVarAndParamSpec[int, int]().attr)  # revealed: (...) -> Unknown
+# error: [invalid-type-arguments] "Type argument for `ParamSpec` must be"
+reveal_type(TypeVarAndParamSpec[int, ()]().attr)  # revealed: (...) -> Unknown
+# error: [invalid-type-arguments] "Type argument for `ParamSpec` must be"
+reveal_type(TypeVarAndParamSpec[int, (int, str)]().attr)  # revealed: (...) -> Unknown
+```
+
+Nor can they be omitted when there are more than one `ParamSpec`s.
+
+```py
+p = TwoParamSpec[[int, str], [int]]()
+reveal_type(p.attr1)  # revealed: (int, str, /) -> None
+reveal_type(p.attr2)  # revealed: (int, /) -> None
+
+# error: [invalid-type-arguments]
+# error: [invalid-type-arguments]
+TwoParamSpec[int, str]
+```
+
+Specializing `ParamSpec` type variable using `typing.Any` isn't explicitly allowed by the spec but
+both mypy and Pyright allow this and there are usages of this in the wild e.g.,
+`staticmethod[Any, Any]`.
+
+```py
+reveal_type(TypeVarAndParamSpec[int, Any]().attr)  # revealed: (...) -> int
+```
+
+## Specialization when defaults are involved
+
+```toml
+[environment]
+python-version = "3.13"
+```
+
+```py
+from typing import Any, Generic, ParamSpec, Callable, TypeVar
+
+P = ParamSpec("P")
+PList = ParamSpec("PList", default=[int, str])
+PEllipsis = ParamSpec("PEllipsis", default=...)
+PAnother = ParamSpec("PAnother", default=P)
+PAnotherWithDefault = ParamSpec("PAnotherWithDefault", default=PList)
+```
+
+```py
+class ParamSpecWithDefault1(Generic[PList]):
+    attr: Callable[PList, None]
+
+reveal_type(ParamSpecWithDefault1().attr)  # revealed: (int, str, /) -> None
+reveal_type(ParamSpecWithDefault1[[int]]().attr)  # revealed: (int, /) -> None
+```
+
+```py
+class ParamSpecWithDefault2(Generic[PEllipsis]):
+    attr: Callable[PEllipsis, None]
+
+reveal_type(ParamSpecWithDefault2().attr)  # revealed: (...) -> None
+reveal_type(ParamSpecWithDefault2[[int, str]]().attr)  # revealed: (int, str, /) -> None
+```
+
+```py
+class ParamSpecWithDefault3(Generic[P, PAnother]):
+    attr1: Callable[P, None]
+    attr2: Callable[PAnother, None]
+
+# `P` hasn't been specialized, so it defaults to `Unknown` gradual form
+p1 = ParamSpecWithDefault3()
+reveal_type(p1.attr1)  # revealed: (...) -> None
+reveal_type(p1.attr2)  # revealed: (...) -> None
+
+p2 = ParamSpecWithDefault3[[int, str]]()
+reveal_type(p2.attr1)  # revealed: (int, str, /) -> None
+reveal_type(p2.attr2)  # revealed: (int, str, /) -> None
+
+p3 = ParamSpecWithDefault3[[int], [str]]()
+reveal_type(p3.attr1)  # revealed: (int, /) -> None
+reveal_type(p3.attr2)  # revealed: (str, /) -> None
+
+class ParamSpecWithDefault4(Generic[PList, PAnotherWithDefault]):
+    attr1: Callable[PList, None]
+    attr2: Callable[PAnotherWithDefault, None]
+
+p1 = ParamSpecWithDefault4()
+reveal_type(p1.attr1)  # revealed: (int, str, /) -> None
+reveal_type(p1.attr2)  # revealed: (int, str, /) -> None
+
+p2 = ParamSpecWithDefault4[[int]]()
+reveal_type(p2.attr1)  # revealed: (int, /) -> None
+reveal_type(p2.attr2)  # revealed: (int, /) -> None
+
+p3 = ParamSpecWithDefault4[[int], [str]]()
+reveal_type(p3.attr1)  # revealed: (int, /) -> None
+reveal_type(p3.attr2)  # revealed: (str, /) -> None
+
+# TODO: error
+# Un-ordered type variables as the default of `PAnother` is `P`
+class ParamSpecWithDefault5(Generic[PAnother, P]):
+    attr: Callable[PAnother, None]
+
+# TODO: error
+# PAnother has default as P (another ParamSpec) which is not in scope
+class ParamSpecWithDefault6(Generic[PAnother]):
+    attr: Callable[PAnother, None]
+```
+
+## Semantics
+
+The semantics of `ParamSpec` are described in
+[the PEP 695 `ParamSpec` document](./../pep695/paramspec.md) to avoid duplication unless there are
+any behavior specific to the legacy `ParamSpec` implementation.

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

@@ -25,11 +25,11 @@ reveal_type(generic_context(SingleTypevar))
 # revealed: ty_extensions.GenericContext[T@MultipleTypevars, S@MultipleTypevars]
 reveal_type(generic_context(MultipleTypevars))
 
-# TODO: support `ParamSpec`/`TypeVarTuple` properly
-# (these should include the `ParamSpec`s and `TypeVarTuple`s in their generic contexts)
-# revealed: ty_extensions.GenericContext[]
+# TODO: support `TypeVarTuple` properly
+# (these should include the `TypeVarTuple`s in their generic contexts)
+# revealed: ty_extensions.GenericContext[P@SingleParamSpec]
 reveal_type(generic_context(SingleParamSpec))
-# revealed: ty_extensions.GenericContext[T@TypeVarAndParamSpec]
+# revealed: ty_extensions.GenericContext[T@TypeVarAndParamSpec, P@TypeVarAndParamSpec]
 reveal_type(generic_context(TypeVarAndParamSpec))
 # revealed: ty_extensions.GenericContext[]
 reveal_type(generic_context(SingleTypeVarTuple))

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

@@ -25,11 +25,11 @@ reveal_type(generic_context(SingleTypevar))
 # revealed: ty_extensions.GenericContext[T@MultipleTypevars, S@MultipleTypevars]
 reveal_type(generic_context(MultipleTypevars))
 
-# TODO: support `ParamSpec`/`TypeVarTuple` properly
-# (these should include the `ParamSpec`s and `TypeVarTuple`s in their generic contexts)
-# revealed: ty_extensions.GenericContext[]
+# TODO: support `TypeVarTuple` properly
+# (these should include the `TypeVarTuple`s in their generic contexts)
+# revealed: ty_extensions.GenericContext[P@SingleParamSpec]
 reveal_type(generic_context(SingleParamSpec))
-# revealed: ty_extensions.GenericContext[T@TypeVarAndParamSpec]
+# revealed: ty_extensions.GenericContext[T@TypeVarAndParamSpec, P@TypeVarAndParamSpec]
 reveal_type(generic_context(TypeVarAndParamSpec))
 # revealed: ty_extensions.GenericContext[]
 reveal_type(generic_context(SingleTypeVarTuple))
@@ -264,12 +264,19 @@ signatures don't count towards variance).
 ### `__new__` only
 
 ```py
+from ty_extensions import generic_context, into_callable
+
 class C[T]:
     x: T
 
     def __new__(cls, x: T) -> "C[T]":
         return object.__new__(cls)
 
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C(1))  # revealed: C[int]
 
 # error: [invalid-assignment] "Object of type `C[int | str]` is not assignable to `C[int]`"
@@ -279,11 +286,18 @@ wrong_innards: C[int] = C("five")
 ### `__init__` only
 
 ```py
+from ty_extensions import generic_context, into_callable
+
 class C[T]:
     x: T
 
     def __init__(self, x: T) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C(1))  # revealed: C[int]
 
 # error: [invalid-assignment] "Object of type `C[int | str]` is not assignable to `C[int]`"
@@ -293,6 +307,8 @@ wrong_innards: C[int] = C("five")
 ### Identical `__new__` and `__init__` signatures
 
 ```py
+from ty_extensions import generic_context, into_callable
+
 class C[T]:
     x: T
 
@@ -301,6 +317,11 @@ class C[T]:
 
     def __init__(self, x: T) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C(1))  # revealed: C[int]
 
 # error: [invalid-assignment] "Object of type `C[int | str]` is not assignable to `C[int]`"
@@ -310,6 +331,8 @@ wrong_innards: C[int] = C("five")
 ### Compatible `__new__` and `__init__` signatures
 
 ```py
+from ty_extensions import generic_context, into_callable
+
 class C[T]:
     x: T
 
@@ -318,6 +341,11 @@ class C[T]:
 
     def __init__(self, x: T) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C(1))  # revealed: C[int]
 
 # error: [invalid-assignment] "Object of type `C[int | str]` is not assignable to `C[int]`"
@@ -331,6 +359,11 @@ class D[T]:
 
     def __init__(self, *args, **kwargs) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@D]
+reveal_type(generic_context(D))
+# revealed: ty_extensions.GenericContext[T@D]
+reveal_type(generic_context(into_callable(D)))
+
 reveal_type(D(1))  # revealed: D[int]
 
 # error: [invalid-assignment] "Object of type `D[int | str]` is not assignable to `D[int]`"
@@ -343,6 +376,8 @@ If either method comes from a generic base class, we don't currently use its inf
 to specialize the class.
 
 ```py
+from ty_extensions import generic_context, into_callable
+
 class C[T, U]:
     def __new__(cls, *args, **kwargs) -> "C[T, U]":
         return object.__new__(cls)
@@ -350,18 +385,30 @@ class C[T, U]:
 class D[V](C[V, int]):
     def __init__(self, x: V) -> None: ...
 
+# revealed: ty_extensions.GenericContext[V@D]
+reveal_type(generic_context(D))
+# revealed: ty_extensions.GenericContext[V@D]
+reveal_type(generic_context(into_callable(D)))
+
 reveal_type(D(1))  # revealed: D[Literal[1]]
 ```
 
 ### Generic class inherits `__init__` from generic base class
 
 ```py
+from ty_extensions import generic_context, into_callable
+
 class C[T, U]:
     def __init__(self, t: T, u: U) -> None: ...
 
 class D[T, U](C[T, U]):
     pass
 
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(D))
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(into_callable(D)))
+
 reveal_type(C(1, "str"))  # revealed: C[Literal[1], Literal["str"]]
 reveal_type(D(1, "str"))  # revealed: D[Literal[1], Literal["str"]]
 ```
@@ -371,9 +418,16 @@ reveal_type(D(1, "str"))  # revealed: D[Literal[1], Literal["str"]]
 This is a specific example of the above, since it was reported specifically by a user.
 
 ```py
+from ty_extensions import generic_context, into_callable
+
 class D[T, U](dict[T, U]):
     pass
 
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(D))
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(into_callable(D)))
+
 reveal_type(D(key=1))  # revealed: D[str, int]
 ```
 
@@ -384,8 +438,15 @@ for `tuple`, so we use a different mechanism to make sure it has the right inher
 context. But from the user's point of view, this is another example of the above.)
 
 ```py
+from ty_extensions import generic_context, into_callable
+
 class C[T, U](tuple[T, U]): ...
 
+# revealed: ty_extensions.GenericContext[T@C, U@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C, U@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C((1, 2)))  # revealed: C[Literal[1], Literal[2]]
 ```
 
@@ -409,11 +470,18 @@ def func8(t1: tuple[complex, list[int]], t2: tuple[int, *tuple[str, ...]], t3: t
 ### `__init__` is itself generic
 
 ```py
+from ty_extensions import generic_context, into_callable
+
 class C[T]:
     x: T
 
     def __init__[S](self, x: T, y: S) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C, S@__init__]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C(1, 1))  # revealed: C[int]
 reveal_type(C(1, "string"))  # revealed: C[int]
 reveal_type(C(1, True))  # revealed: C[int]
@@ -427,6 +495,7 @@ wrong_innards: C[int] = C("five", 1)
 ```py
 from __future__ import annotations
 from typing import overload
+from ty_extensions import generic_context, into_callable
 
 class C[T]:
     # we need to use the type variable or else the class is bivariant in T, and
@@ -443,6 +512,11 @@ class C[T]:
     def __init__(self, x: int) -> None: ...
     def __init__(self, x: str | bytes | int) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C("string"))  # revealed: C[str]
 reveal_type(C(b"bytes"))  # revealed: C[bytes]
 reveal_type(C(12))  # revealed: C[Unknown]
@@ -470,6 +544,11 @@ class D[T, U]:
     def __init__(self, t: T, u: U) -> None: ...
     def __init__(self, *args) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(D))
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(into_callable(D)))
+
 reveal_type(D("string"))  # revealed: D[str, Literal["string"]]
 reveal_type(D(1))  # revealed: D[str, Literal[1]]
 reveal_type(D(1, "string"))  # revealed: D[Literal[1], Literal["string"]]
@@ -479,24 +558,42 @@ reveal_type(D(1, "string"))  # revealed: D[Literal[1], Literal["string"]]
 
 ```py
 from dataclasses import dataclass
+from ty_extensions import generic_context, into_callable
 
 @dataclass
 class A[T]:
     x: T
 
+# revealed: ty_extensions.GenericContext[T@A]
+reveal_type(generic_context(A))
+# revealed: ty_extensions.GenericContext[T@A]
+reveal_type(generic_context(into_callable(A)))
+
 reveal_type(A(x=1))  # revealed: A[int]
 ```
 
 ### Class typevar has another typevar as a default
 
 ```py
+from ty_extensions import generic_context, into_callable
+
 class C[T, U = T]: ...
 
+# revealed: ty_extensions.GenericContext[T@C, U@C]
+reveal_type(generic_context(C))
+# revealed: ty_extensions.GenericContext[T@C, U@C]
+reveal_type(generic_context(into_callable(C)))
+
 reveal_type(C())  # revealed: C[Unknown, Unknown]
 
 class D[T, U = T]:
     def __init__(self) -> None: ...
 
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(D))
+# revealed: ty_extensions.GenericContext[T@D, U@D]
+reveal_type(generic_context(into_callable(D)))
+
 reveal_type(D())  # revealed: D[Unknown, Unknown]
 ```
 

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

@@ -62,3 +62,614 @@ Other values are invalid.
 def foo[**P = int]() -> None:
     pass
 ```
+
+## Validating `ParamSpec` usage
+
+`ParamSpec` is only valid as the first element to `Callable` or the final element to `Concatenate`.
+
+```py
+from typing import ParamSpec, Callable, Concatenate
+
+def valid[**P](
+    a1: Callable[P, int],
+    a2: Callable[Concatenate[int, P], int],
+) -> None: ...
+def invalid[**P](
+    # TODO: error
+    a1: P,
+    # TODO: error
+    a2: list[P],
+    # TODO: error
+    a3: Callable[[P], int],
+    # TODO: error
+    a4: Callable[..., P],
+    # TODO: error
+    a5: Callable[Concatenate[P, ...], int],
+) -> None: ...
+```
+
+## Validating `P.args` and `P.kwargs` usage
+
+The components of `ParamSpec` i.e., `P.args` and `P.kwargs` are only valid when used as the
+annotated types of `*args` and `**kwargs` respectively.
+
+```py
+from typing import Callable
+
+def foo[**P](c: Callable[P, int]) -> None:
+    def nested1(*args: P.args, **kwargs: P.kwargs) -> None: ...
+
+    # error: [invalid-type-form] "`P.kwargs` is valid only in `**kwargs` annotation: Did you mean `P.args`?"
+    # error: [invalid-type-form] "`P.args` is valid only in `*args` annotation: Did you mean `P.kwargs`?"
+    def nested2(*args: P.kwargs, **kwargs: P.args) -> None: ...
+
+    # TODO: error
+    def nested3(*args: P.args) -> None: ...
+
+    # TODO: error
+    def nested4(**kwargs: P.kwargs) -> None: ...
+
+    # TODO: error
+    def nested5(*args: P.args, x: int, **kwargs: P.kwargs) -> None: ...
+```
+
+And, they need to be used together.
+
+```py
+def foo[**P](c: Callable[P, int]) -> None:
+    # TODO: error
+    def nested1(*args: P.args) -> None: ...
+
+    # TODO: error
+    def nested2(**kwargs: P.kwargs) -> None: ...
+
+class Foo[**P]:
+    # TODO: error
+    args: P.args
+
+    # TODO: error
+    kwargs: P.kwargs
+```
+
+The name of these parameters does not need to be `args` or `kwargs`, it's the annotated type to the
+respective variadic parameter that matters.
+
+```py
+class Foo3[**P]:
+    def method1(self, *paramspec_args: P.args, **paramspec_kwargs: P.kwargs) -> None: ...
+    def method2(
+        self,
+        # error: [invalid-type-form] "`P.kwargs` is valid only in `**kwargs` annotation: Did you mean `P.args`?"
+        *paramspec_args: P.kwargs,
+        # error: [invalid-type-form] "`P.args` is valid only in `*args` annotation: Did you mean `P.kwargs`?"
+        **paramspec_kwargs: P.args,
+    ) -> None: ...
+```
+
+It isn't allowed to annotate an instance attribute either:
+
+```py
+class Foo4[**P]:
+    def __init__(self, fn: Callable[P, int], *args: P.args, **kwargs: P.kwargs) -> None:
+        self.fn = fn
+        # TODO: error
+        self.args: P.args = args
+        # TODO: error
+        self.kwargs: P.kwargs = kwargs
+```
+
+## Semantics of `P.args` and `P.kwargs`
+
+The type of `args` and `kwargs` inside the function is `P.args` and `P.kwargs` respectively instead
+of `tuple[P.args, ...]` and `dict[str, P.kwargs]`.
+
+### Passing `*args` and `**kwargs` to a callable
+
+```py
+from typing import Callable
+
+def f[**P](func: Callable[P, int]) -> Callable[P, None]:
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
+        reveal_type(args)  # revealed: P@f.args
+        reveal_type(kwargs)  # revealed: P@f.kwargs
+        reveal_type(func(*args, **kwargs))  # revealed: int
+
+        # error: [invalid-argument-type] "Argument is incorrect: Expected `P@f.args`, found `P@f.kwargs`"
+        # error: [invalid-argument-type] "Argument is incorrect: Expected `P@f.kwargs`, found `P@f.args`"
+        reveal_type(func(*kwargs, **args))  # revealed: int
+
+        # error: [invalid-argument-type] "Argument is incorrect: Expected `P@f.args`, found `P@f.kwargs`"
+        reveal_type(func(args, kwargs))  # revealed: int
+
+        # Both parameters are required
+        # TODO: error
+        reveal_type(func())  # revealed: int
+        reveal_type(func(*args))  # revealed: int
+        reveal_type(func(**kwargs))  # revealed: int
+    return wrapper
+```
+
+### Operations on `P.args` and `P.kwargs`
+
+The type of `P.args` and `P.kwargs` behave like a `tuple` and `dict` respectively. Internally, they
+are represented as a type variable that has an upper bound of `tuple[object, ...]` and
+`Top[dict[str, Any]]` respectively.
+
+```py
+from typing import Callable, Any
+
+def f[**P](func: Callable[P, int], *args: P.args, **kwargs: P.kwargs) -> None:
+    reveal_type(args + ("extra",))  # revealed: tuple[object, ...]
+    reveal_type(args + (1, 2, 3))  # revealed: tuple[object, ...]
+    reveal_type(args[0])  # revealed: object
+
+    reveal_type("key" in kwargs)  # revealed: bool
+    reveal_type(kwargs.get("key"))  # revealed: object
+    reveal_type(kwargs["key"])  # revealed: object
+```
+
+## Specializing generic classes explicitly
+
+```py
+from typing import Any, Callable, ParamSpec
+
+class OnlyParamSpec[**P1]:
+    attr: Callable[P1, None]
+
+class TwoParamSpec[**P1, **P2]:
+    attr1: Callable[P1, None]
+    attr2: Callable[P2, None]
+
+class TypeVarAndParamSpec[T1, **P1]:
+    attr: Callable[P1, T1]
+```
+
+Explicit specialization of a generic class involving `ParamSpec` is done by providing either a list
+of types, `...`, or another in-scope `ParamSpec`.
+
+```py
+reveal_type(OnlyParamSpec[[]]().attr)  # revealed: () -> None
+reveal_type(OnlyParamSpec[[int, str]]().attr)  # revealed: (int, str, /) -> None
+reveal_type(OnlyParamSpec[...]().attr)  # revealed: (...) -> None
+
+def func[**P2](c: Callable[P2, None]):
+    reveal_type(OnlyParamSpec[P2]().attr)  # revealed: (**P2@func) -> None
+
+P2 = ParamSpec("P2")
+
+# TODO: error: paramspec is unbound
+reveal_type(OnlyParamSpec[P2]().attr)  # revealed: (...) -> None
+
+# error: [invalid-type-arguments] "No type argument provided for required type variable `P1` of class `OnlyParamSpec`"
+reveal_type(OnlyParamSpec[()]().attr)  # revealed: (...) -> None
+```
+
+An explicit tuple expression (unlike an implicit one that omits the parentheses) is also accepted
+when the `ParamSpec` is the only type variable. But, this isn't recommended is mainly a fallout of
+it having the same AST as the one without the parentheses. Both mypy and Pyright also allow this.
+
+```py
+reveal_type(OnlyParamSpec[(int, str)]().attr)  # revealed: (int, str, /) -> None
+```
+
+<!-- blacken-docs:off -->
+
+```py
+# error: [invalid-syntax]
+reveal_type(OnlyParamSpec[]().attr)  # revealed: (...) -> None
+```
+
+<!-- blacken-docs:on -->
+
+The square brackets can be omitted when `ParamSpec` is the only type variable
+
+```py
+reveal_type(OnlyParamSpec[int, str]().attr)  # revealed: (int, str, /) -> None
+reveal_type(OnlyParamSpec[int,]().attr)  # revealed: (int, /) -> None
+
+# Even when there is only one element
+reveal_type(OnlyParamSpec[Any]().attr)  # revealed: (Any, /) -> None
+reveal_type(OnlyParamSpec[object]().attr)  # revealed: (object, /) -> None
+reveal_type(OnlyParamSpec[int]().attr)  # revealed: (int, /) -> None
+```
+
+But, they cannot be omitted when there are multiple type variables.
+
+```py
+reveal_type(TypeVarAndParamSpec[int, []]().attr)  # revealed: () -> int
+reveal_type(TypeVarAndParamSpec[int, [int, str]]().attr)  # revealed: (int, str, /) -> int
+reveal_type(TypeVarAndParamSpec[int, [str]]().attr)  # revealed: (str, /) -> int
+reveal_type(TypeVarAndParamSpec[int, ...]().attr)  # revealed: (...) -> int
+
+# TODO: error: paramspec is unbound
+reveal_type(TypeVarAndParamSpec[int, P2]().attr)  # revealed: (...) -> Unknown
+# error: [invalid-type-arguments] "Type argument for `ParamSpec` must be"
+reveal_type(TypeVarAndParamSpec[int, int]().attr)  # revealed: (...) -> Unknown
+# error: [invalid-type-arguments] "Type argument for `ParamSpec` must be"
+reveal_type(TypeVarAndParamSpec[int, ()]().attr)  # revealed: (...) -> Unknown
+# error: [invalid-type-arguments] "Type argument for `ParamSpec` must be"
+reveal_type(TypeVarAndParamSpec[int, (int, str)]().attr)  # revealed: (...) -> Unknown
+```
+
+Nor can they be omitted when there are more than one `ParamSpec`.
+
+```py
+p = TwoParamSpec[[int, str], [int]]()
+reveal_type(p.attr1)  # revealed: (int, str, /) -> None
+reveal_type(p.attr2)  # revealed: (int, /) -> None
+
+# error: [invalid-type-arguments] "Type argument for `ParamSpec` must be either a list of types, `ParamSpec`, `Concatenate`, or `...`"
+# error: [invalid-type-arguments] "Type argument for `ParamSpec` must be either a list of types, `ParamSpec`, `Concatenate`, or `...`"
+TwoParamSpec[int, str]
+```
+
+Specializing `ParamSpec` type variable using `typing.Any` isn't explicitly allowed by the spec but
+both mypy and Pyright allow this and there are usages of this in the wild e.g.,
+`staticmethod[Any, Any]`.
+
+```py
+reveal_type(TypeVarAndParamSpec[int, Any]().attr)  # revealed: (...) -> int
+```
+
+## Specialization when defaults are involved
+
+```py
+from typing import Callable, ParamSpec
+
+class ParamSpecWithDefault1[**P1 = [int, str]]:
+    attr: Callable[P1, None]
+
+reveal_type(ParamSpecWithDefault1().attr)  # revealed: (int, str, /) -> None
+reveal_type(ParamSpecWithDefault1[int]().attr)  # revealed: (int, /) -> None
+```
+
+```py
+class ParamSpecWithDefault2[**P1 = ...]:
+    attr: Callable[P1, None]
+
+reveal_type(ParamSpecWithDefault2().attr)  # revealed: (...) -> None
+reveal_type(ParamSpecWithDefault2[int, str]().attr)  # revealed: (int, str, /) -> None
+```
+
+```py
+class ParamSpecWithDefault3[**P1, **P2 = P1]:
+    attr1: Callable[P1, None]
+    attr2: Callable[P2, None]
+
+# `P1` hasn't been specialized, so it defaults to `...` gradual form
+p1 = ParamSpecWithDefault3()
+reveal_type(p1.attr1)  # revealed: (...) -> None
+reveal_type(p1.attr2)  # revealed: (...) -> None
+
+p2 = ParamSpecWithDefault3[[int, str]]()
+reveal_type(p2.attr1)  # revealed: (int, str, /) -> None
+reveal_type(p2.attr2)  # revealed: (int, str, /) -> None
+
+p3 = ParamSpecWithDefault3[[int], [str]]()
+reveal_type(p3.attr1)  # revealed: (int, /) -> None
+reveal_type(p3.attr2)  # revealed: (str, /) -> None
+
+class ParamSpecWithDefault4[**P1 = [int, str], **P2 = P1]:
+    attr1: Callable[P1, None]
+    attr2: Callable[P2, None]
+
+p1 = ParamSpecWithDefault4()
+reveal_type(p1.attr1)  # revealed: (int, str, /) -> None
+reveal_type(p1.attr2)  # revealed: (int, str, /) -> None
+
+p2 = ParamSpecWithDefault4[[int]]()
+reveal_type(p2.attr1)  # revealed: (int, /) -> None
+reveal_type(p2.attr2)  # revealed: (int, /) -> None
+
+p3 = ParamSpecWithDefault4[[int], [str]]()
+reveal_type(p3.attr1)  # revealed: (int, /) -> None
+reveal_type(p3.attr2)  # revealed: (str, /) -> None
+
+P2 = ParamSpec("P2")
+
+# TODO: error: paramspec is out of scope
+class ParamSpecWithDefault5[**P1 = P2]:
+    attr: Callable[P1, None]
+```
+
+## Semantics
+
+Most of these test cases are adopted from the
+[typing documentation on `ParamSpec` semantics](https://typing.python.org/en/latest/spec/generics.html#semantics).
+
+### Return type change using `ParamSpec` once
+
+```py
+from typing import Callable
+
+def converter[**P](func: Callable[P, int]) -> Callable[P, bool]:
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> bool:
+        func(*args, **kwargs)
+        return True
+    return wrapper
+
+def f1(x: int, y: str) -> int:
+    return 1
+
+# This should preserve all the information about the parameters of `f1`
+f2 = converter(f1)
+
+reveal_type(f2)  # revealed: (x: int, y: str) -> bool
+
+reveal_type(f1(1, "a"))  # revealed: int
+reveal_type(f2(1, "a"))  # revealed: bool
+
+# As it preserves the parameter kinds, the following should work as well
+reveal_type(f2(1, y="a"))  # revealed: bool
+reveal_type(f2(x=1, y="a"))  # revealed: bool
+reveal_type(f2(y="a", x=1))  # revealed: bool
+
+# error: [missing-argument] "No argument provided for required parameter `y`"
+f2(1)
+# error: [invalid-argument-type] "Argument is incorrect: Expected `int`, found `Literal["a"]`"
+f2("a", "b")
+```
+
+The `converter` function act as a decorator here:
+
+```py
+@converter
+def f3(x: int, y: str) -> int:
+    return 1
+
+# TODO: This should reveal `(x: int, y: str) -> bool` but there's a cycle: https://github.com/astral-sh/ty/issues/1729
+reveal_type(f3)  # revealed: ((x: int, y: str) -> bool) | ((x: Divergent, y: Divergent) -> bool)
+
+reveal_type(f3(1, "a"))  # revealed: bool
+reveal_type(f3(x=1, y="a"))  # revealed: bool
+reveal_type(f3(1, y="a"))  # revealed: bool
+reveal_type(f3(y="a", x=1))  # revealed: bool
+
+# TODO: There should only be one error but the type of `f3` is a union: https://github.com/astral-sh/ty/issues/1729
+# error: [missing-argument] "No argument provided for required parameter `y`"
+# error: [missing-argument] "No argument provided for required parameter `y`"
+f3(1)
+# error: [invalid-argument-type] "Argument is incorrect: Expected `int`, found `Literal["a"]`"
+f3("a", "b")
+```
+
+### Return type change using the same `ParamSpec` multiple times
+
+```py
+from typing import Callable
+
+def multiple[**P](func1: Callable[P, int], func2: Callable[P, int]) -> Callable[P, bool]:
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> bool:
+        func1(*args, **kwargs)
+        func2(*args, **kwargs)
+        return True
+    return wrapper
+```
+
+As per the spec,
+
+> A user may include the same `ParamSpec` multiple times in the arguments of the same function, to
+> indicate a dependency between multiple arguments. In these cases a type checker may choose to
+> solve to a common behavioral supertype (i.e. a set of parameters for which all of the valid calls
+> are valid in both of the subtypes), but is not obligated to do so.
+
+TODO: Currently, we don't do this
+
+```py
+def xy(x: int, y: str) -> int:
+    return 1
+
+def yx(y: int, x: str) -> int:
+    return 2
+
+reveal_type(multiple(xy, xy))  # revealed: (x: int, y: str) -> bool
+
+# The common supertype is `(int, str, /)` which is converting the positional-or-keyword parameters
+# into positional-only parameters because the position of the types are the same.
+# TODO: This shouldn't error
+# error: [invalid-argument-type]
+reveal_type(multiple(xy, yx))  # revealed: (x: int, y: str) -> bool
+
+def keyword_only_with_default_1(*, x: int = 42) -> int:
+    return 1
+
+def keyword_only_with_default_2(*, y: int = 42) -> int:
+    return 2
+
+# The common supertype for two functions with only keyword-only parameters would be an empty
+# parameter list i.e., `()`
+# TODO: This shouldn't error
+# error: [invalid-argument-type]
+# revealed: (*, x: int = Literal[42]) -> bool
+reveal_type(multiple(keyword_only_with_default_1, keyword_only_with_default_2))
+
+def keyword_only1(*, x: int) -> int:
+    return 1
+
+def keyword_only2(*, y: int) -> int:
+    return 2
+
+# On the other hand, combining two functions with only keyword-only parameters does not have a
+# common supertype, so it should result in an error.
+# error: [invalid-argument-type] "Argument to function `multiple` is incorrect: Expected `(*, x: int) -> int`, found `def keyword_only2(*, y: int) -> int`"
+reveal_type(multiple(keyword_only1, keyword_only2))  # revealed: (*, x: int) -> bool
+```
+
+### Constructors of user-defined generic class on `ParamSpec`
+
+```py
+from typing import Callable
+
+class C[**P]:
+    f: Callable[P, int]
+
+    def __init__(self, f: Callable[P, int]) -> None:
+        self.f = f
+
+def f(x: int, y: str) -> bool:
+    return True
+
+c = C(f)
+reveal_type(c.f)  # revealed: (x: int, y: str) -> int
+```
+
+### `ParamSpec` in prepended positional parameters
+
+> If one of these prepended positional parameters contains a free `ParamSpec`, we consider that
+> variable in scope for the purposes of extracting the components of that `ParamSpec`.
+
+```py
+from typing import Callable
+
+def foo1[**P1](func: Callable[P1, int], *args: P1.args, **kwargs: P1.kwargs) -> int:
+    return func(*args, **kwargs)
+
+def foo1_with_extra_arg[**P1](func: Callable[P1, int], extra: str, *args: P1.args, **kwargs: P1.kwargs) -> int:
+    return func(*args, **kwargs)
+
+def foo2[**P2](func: Callable[P2, int], *args: P2.args, **kwargs: P2.kwargs) -> None:
+    foo1(func, *args, **kwargs)
+
+    # error: [invalid-argument-type] "Argument to function `foo1` is incorrect: Expected `P2@foo2.args`, found `Literal[1]`"
+    foo1(func, 1, *args, **kwargs)
+
+    # error: [invalid-argument-type] "Argument to function `foo1_with_extra_arg` is incorrect: Expected `str`, found `P2@foo2.args`"
+    foo1_with_extra_arg(func, *args, **kwargs)
+
+    foo1_with_extra_arg(func, "extra", *args, **kwargs)
+```
+
+Here, the first argument to `f` can specialize `P` to the parameters of the callable passed to it
+which is then used to type the `ParamSpec` components used in `*args` and `**kwargs`.
+
+```py
+def f1(x: int, y: str) -> int:
+    return 1
+
+foo1(f1, 1, "a")
+foo1(f1, x=1, y="a")
+foo1(f1, 1, y="a")
+
+# error: [missing-argument] "No arguments provided for required parameters `x`, `y` of function `foo1`"
+foo1(f1)
+
+# error: [missing-argument] "No argument provided for required parameter `y` of function `foo1`"
+foo1(f1, 1)
+
+# error: [invalid-argument-type] "Argument to function `foo1` is incorrect: Expected `str`, found `Literal[2]`"
+foo1(f1, 1, 2)
+
+# error: [too-many-positional-arguments] "Too many positional arguments to function `foo1`: expected 2, got 3"
+foo1(f1, 1, "a", "b")
+
+# error: [missing-argument] "No argument provided for required parameter `y` of function `foo1`"
+# error: [unknown-argument] "Argument `z` does not match any known parameter of function `foo1`"
+foo1(f1, x=1, z="a")
+```
+
+### Specializing `ParamSpec` with another `ParamSpec`
+
+```py
+class Foo[**P]:
+    def __init__(self, *args: P.args, **kwargs: P.kwargs) -> None:
+        self.args = args
+        self.kwargs = kwargs
+
+def bar[**P](foo: Foo[P]) -> None:
+    reveal_type(foo)  # revealed: Foo[P@bar]
+    reveal_type(foo.args)  # revealed: Unknown | P@bar.args
+    reveal_type(foo.kwargs)  # revealed: Unknown | P@bar.kwargs
+```
+
+ty will check whether the argument after `**` is a mapping type but as instance attribute are
+unioned with `Unknown`, it shouldn't error here.
+
+```py
+from typing import Callable
+
+def baz[**P](fn: Callable[P, None], foo: Foo[P]) -> None:
+    fn(*foo.args, **foo.kwargs)
+```
+
+The `Unknown` can be eliminated by using annotating these attributes with `Final`:
+
+```py
+from typing import Final
+
+class FooWithFinal[**P]:
+    def __init__(self, *args: P.args, **kwargs: P.kwargs) -> None:
+        self.args: Final = args
+        self.kwargs: Final = kwargs
+
+def with_final[**P](foo: FooWithFinal[P]) -> None:
+    reveal_type(foo)  # revealed: FooWithFinal[P@with_final]
+    reveal_type(foo.args)  # revealed: P@with_final.args
+    reveal_type(foo.kwargs)  # revealed: P@with_final.kwargs
+```
+
+### Specializing `Self` when `ParamSpec` is involved
+
+```py
+class Foo[**P]:
+    def method(self, *args: P.args, **kwargs: P.kwargs) -> str:
+        return "hello"
+
+foo = Foo[int, str]()
+
+reveal_type(foo)  # revealed: Foo[(int, str, /)]
+reveal_type(foo.method)  # revealed: bound method Foo[(int, str, /)].method(int, str, /) -> str
+reveal_type(foo.method(1, "a"))  # revealed: str
+```
+
+### Overloads
+
+`overloaded.pyi`:
+
+```pyi
+from typing import overload
+
+@overload
+def int_int(x: int) -> int: ...
+@overload
+def int_int(x: str) -> int: ...
+
+@overload
+def int_str(x: int) -> int: ...
+@overload
+def int_str(x: str) -> str: ...
+
+@overload
+def str_str(x: int) -> str: ...
+@overload
+def str_str(x: str) -> str: ...
+```
+
+```py
+from typing import Callable
+from overloaded import int_int, int_str, str_str
+
+def change_return_type[**P](f: Callable[P, int]) -> Callable[P, str]:
+    def nested(*args: P.args, **kwargs: P.kwargs) -> str:
+        return str(f(*args, **kwargs))
+    return nested
+
+def with_parameters[**P](f: Callable[P, int], *args: P.args, **kwargs: P.kwargs) -> Callable[P, str]:
+    def nested(*args: P.args, **kwargs: P.kwargs) -> str:
+        return str(f(*args, **kwargs))
+    return nested
+
+reveal_type(change_return_type(int_int))  # revealed: Overload[(x: int) -> str, (x: str) -> str]
+
+# TODO: This shouldn't error and should pick the first overload because of the return type
+# error: [invalid-argument-type]
+reveal_type(change_return_type(int_str))  # revealed: Overload[(x: int) -> str, (x: str) -> str]
+
+# error: [invalid-argument-type]
+reveal_type(change_return_type(str_str))  # revealed: Overload[(x: int) -> str, (x: str) -> str]
+
+# TODO: Both of these shouldn't raise an error
+# error: [invalid-argument-type]
+reveal_type(with_parameters(int_int, 1))  # revealed: Overload[(x: int) -> str, (x: str) -> str]
+# error: [invalid-argument-type]
+reveal_type(with_parameters(int_int, "a"))  # revealed: Overload[(x: int) -> str, (x: str) -> str]
+```

crates/ty_python_semantic/resources/mdtest/implicit_type_aliases.md

@@ -398,7 +398,7 @@ reveal_type(Sum)  # revealed: <class 'tuple[T@Sum, U@Sum]'>
 reveal_type(ListOrTuple)  # revealed: <types.UnionType special form 'list[T@ListOrTuple] | tuple[T@ListOrTuple, ...]'>
 # revealed: <types.UnionType special form 'list[T@ListOrTupleLegacy] | tuple[T@ListOrTupleLegacy, ...]'>
 reveal_type(ListOrTupleLegacy)
-reveal_type(MyCallable)  # revealed: @Todo(Callable[..] specialized with ParamSpec)
+reveal_type(MyCallable)  # revealed: <typing.Callable special form '(**P@MyCallable) -> T@MyCallable'>
 reveal_type(AnnotatedType)  # revealed: <special form 'typing.Annotated[T@AnnotatedType, <metadata>]'>
 reveal_type(TransparentAlias)  # revealed: typing.TypeVar
 reveal_type(MyOptional)  # revealed: <types.UnionType special form 'T@MyOptional | None'>
@@ -425,8 +425,7 @@ def _(
     reveal_type(int_and_bytes)  # revealed: tuple[int, bytes]
     reveal_type(list_or_tuple)  # revealed: list[int] | tuple[int, ...]
     reveal_type(list_or_tuple_legacy)  # revealed: list[int] | tuple[int, ...]
-    # TODO: This should be `(str, bytes) -> int`
-    reveal_type(my_callable)  # revealed: @Todo(Callable[..] specialized with ParamSpec)
+    reveal_type(my_callable)  # revealed: (str, bytes, /) -> int
     reveal_type(annotated_int)  # revealed: int
     reveal_type(transparent_alias)  # revealed: int
     reveal_type(optional_int)  # revealed: int | None
@@ -463,7 +462,7 @@ reveal_type(ListOfPairs)  # revealed: <class 'list[tuple[str, str]]'>
 reveal_type(ListOrTupleOfInts)  # revealed: <types.UnionType special form 'list[int] | tuple[int, ...]'>
 reveal_type(AnnotatedInt)  # revealed: <special form 'typing.Annotated[int, <metadata>]'>
 reveal_type(SubclassOfInt)  # revealed: <special form 'type[int]'>
-reveal_type(CallableIntToStr)  # revealed: @Todo(Callable[..] specialized with ParamSpec)
+reveal_type(CallableIntToStr)  # revealed: <typing.Callable special form '(int, /) -> str'>
 
 def _(
     ints_or_none: IntsOrNone,
@@ -480,8 +479,7 @@ def _(
     reveal_type(list_or_tuple_of_ints)  # revealed: list[int] | tuple[int, ...]
     reveal_type(annotated_int)  # revealed: int
     reveal_type(subclass_of_int)  # revealed: type[int]
-    # TODO: This should be `(int, /) -> str`
-    reveal_type(callable_int_to_str)  # revealed: @Todo(Callable[..] specialized with ParamSpec)
+    reveal_type(callable_int_to_str)  # revealed: (int, /) -> str
 ```
 
 A generic implicit type alias can also be used in another generic implicit type alias:
@@ -534,8 +532,7 @@ def _(
     reveal_type(unknown_and_unknown)  # revealed: tuple[Unknown, Unknown]
     reveal_type(list_or_tuple)  # revealed: list[Unknown] | tuple[Unknown, ...]
     reveal_type(list_or_tuple_legacy)  # revealed: list[Unknown] | tuple[Unknown, ...]
-    # TODO: should be (...) -> Unknown
-    reveal_type(my_callable)  # revealed: @Todo(Callable[..] specialized with ParamSpec)
+    reveal_type(my_callable)  # revealed: (...) -> Unknown
     reveal_type(annotated_unknown)  # revealed: Unknown
     reveal_type(optional_unknown)  # revealed: Unknown | None
 ```

crates/ty_python_semantic/resources/mdtest/invalid_syntax.md

@@ -128,3 +128,16 @@ InvalidEmptyUnion = Union[]
 def _(u: InvalidEmptyUnion):
     reveal_type(u)  # revealed: Unknown
 ```
+
+### `typing.Annotated`
+
+```py
+from typing import Annotated
+
+# error: [invalid-syntax] "Expected index or slice expression"
+# error: [invalid-type-form] "Special form `typing.Annotated` expected at least 2 arguments (one type and at least one metadata element)"
+InvalidEmptyAnnotated = Annotated[]
+
+def _(a: InvalidEmptyAnnotated):
+    reveal_type(a)  # revealed: Unknown
+```

crates/ty_python_semantic/resources/mdtest/liskov.md

@@ -218,8 +218,8 @@ class E(A[int]):
     def method(self, x: object) -> None: ...  # fine
 
 class F[T](A[T]):
-    # TODO: we should emit `invalid-method-override` on this:
     # `str` is not necessarily a supertype of `T`!
+    # error: [invalid-method-override]
     def method(self, x: str) -> None: ...
 
 class G(A[int]):

crates/ty_python_semantic/resources/mdtest/protocols.md

@@ -3184,14 +3184,9 @@ from ty_extensions import reveal_protocol_interface
 reveal_protocol_interface(Foo)
 ```
 
-## Known panics
+## Protocols generic over TypeVars bound to forward references
 
-### Protocols generic over TypeVars bound to forward references
-
-This test currently panics because the `ClassLiteral::explicit_bases` query fails to converge. See
-issue <https://github.com/astral-sh/ty/issues/1587>.
-
-<!-- expect-panic: execute: too many cycle iterations -->
+Protocols can have TypeVars with forward reference bounds that form cycles.
 
 ```py
 from typing import Any, Protocol, TypeVar
@@ -3209,6 +3204,19 @@ class A2(Protocol[T2]):
 
 class B1(A1[T3], Protocol[T3]): ...
 class B2(A2[T4], Protocol[T4]): ...
+
+# TODO should just be `B2[Any]`
+reveal_type(T3.__bound__)  # revealed: B2[Any] | @Todo(specialized non-generic class)
+
+# TODO error: [invalid-type-arguments]
+def f(x: B1[int]):
+    pass
+
+reveal_type(T4.__bound__)  # revealed: B1[Any]
+
+# error: [invalid-type-arguments]
+def g(x: B2[int]):
+    pass
 ```
 
 ## TODO

crates/ty_python_semantic/resources/mdtest/regression/paramspec_on_python39.md

@@ -0,0 +1,19 @@
+# `ParamSpec` regression on 3.9
+
+```toml
+[environment]
+python-version = "3.9"
+```
+
+This used to panic when run on Python 3.9 because `ParamSpec` was introduced in Python 3.10 and the
+diagnostic message for `invalid-exception-caught` expects to construct `typing.ParamSpec`.
+
+```py
+# error: [invalid-syntax]
+def foo[**P]() -> None:
+    try:
+        pass
+    # error: [invalid-exception-caught] "Invalid object caught in an exception handler: Object has type `typing.ParamSpec`"
+    except P:
+        pass
+```

crates/ty_python_semantic/resources/mdtest/snapshots/assert_type.md_-_`assert_type`_-_Basic_(c507788da2659ec9).snap

@@ -14,10 +14,11 @@ mdtest path: crates/ty_python_semantic/resources/mdtest/directives/assert_type.m
 ```
 1 | from typing_extensions import assert_type
 2 | 
-3 | def _(x: int):
+3 | def _(x: int, y: bool):
 4 |     assert_type(x, int)  # fine
 5 |     assert_type(x, str)  # error: [type-assertion-failure]
 6 |     assert_type(assert_type(x, int), int)
+7 |     assert_type(y, int)  # error: [type-assertion-failure]
 ```
 
 # Diagnostics
@@ -26,15 +27,32 @@ mdtest path: crates/ty_python_semantic/resources/mdtest/directives/assert_type.m
 error[type-assertion-failure]: Argument does not have asserted type `str`
  --> src/mdtest_snippet.py:5:5
   |
-3 | def _(x: int):
+3 | def _(x: int, y: bool):
 4 |     assert_type(x, int)  # fine
 5 |     assert_type(x, str)  # error: [type-assertion-failure]
   |     ^^^^^^^^^^^^-^^^^^^
   |                 |
-  |                 Inferred type of argument is `int`
+  |                 Inferred type is `int`
 6 |     assert_type(assert_type(x, int), int)
+7 |     assert_type(y, int)  # error: [type-assertion-failure]
   |
 info: `str` and `int` are not equivalent types
 info: rule `type-assertion-failure` is enabled by default
 
 ```
+
+```
+error[type-assertion-failure]: Argument does not have asserted type `int`
+ --> src/mdtest_snippet.py:7:5
+  |
+5 |     assert_type(x, str)  # error: [type-assertion-failure]
+6 |     assert_type(assert_type(x, int), int)
+7 |     assert_type(y, int)  # error: [type-assertion-failure]
+  |     ^^^^^^^^^^^^-^^^^^^
+  |                 |
+  |                 Inferred type is `bool`
+  |
+info: `bool` is a subtype of `int`, but they are not equivalent
+info: rule `type-assertion-failure` is enabled by default
+
+```

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

@@ -537,6 +537,9 @@ static_assert(is_assignable_to(tuple[Any, ...], tuple[Any, Any]))
 static_assert(is_assignable_to(tuple[Any, ...], tuple[int, ...]))
 static_assert(is_assignable_to(tuple[Any, ...], tuple[int]))
 static_assert(is_assignable_to(tuple[Any, ...], tuple[int, int]))
+static_assert(is_assignable_to(tuple[Any, ...], tuple[int, *tuple[int, ...]]))
+static_assert(is_assignable_to(tuple[Any, ...], tuple[*tuple[int, ...], int]))
+static_assert(is_assignable_to(tuple[Any, ...], tuple[int, *tuple[int, ...], int]))
 ```
 
 This also applies when `tuple[Any, ...]` is unpacked into a mixed tuple.
@@ -560,6 +563,10 @@ static_assert(is_assignable_to(tuple[*tuple[Any, ...], int], tuple[int, ...]))
 static_assert(is_assignable_to(tuple[*tuple[Any, ...], int], tuple[int]))
 static_assert(is_assignable_to(tuple[*tuple[Any, ...], int], tuple[int, int]))
 
+# `*tuple[Any, ...]` can materialize to a tuple of any length as a special case,
+# so this passes:
+static_assert(is_assignable_to(tuple[*tuple[Any, ...], Any], tuple[*tuple[Any, ...], Any, Any]))
+
 static_assert(is_assignable_to(tuple[int, *tuple[Any, ...], int], tuple[int, *tuple[Any, ...], int]))
 static_assert(is_assignable_to(tuple[int, *tuple[Any, ...], int], tuple[Any, ...]))
 static_assert(not is_assignable_to(tuple[int, *tuple[Any, ...], int], tuple[Any]))
@@ -580,6 +587,9 @@ static_assert(not is_assignable_to(tuple[int, ...], tuple[Any, Any]))
 static_assert(is_assignable_to(tuple[int, ...], tuple[int, ...]))
 static_assert(not is_assignable_to(tuple[int, ...], tuple[int]))
 static_assert(not is_assignable_to(tuple[int, ...], tuple[int, int]))
+static_assert(not is_assignable_to(tuple[int, ...], tuple[int, *tuple[int, ...]]))
+static_assert(not is_assignable_to(tuple[int, ...], tuple[*tuple[int, ...], int]))
+static_assert(not is_assignable_to(tuple[int, ...], tuple[int, *tuple[int, ...], int]))
 
 static_assert(is_assignable_to(tuple[int, *tuple[int, ...]], tuple[int, *tuple[Any, ...]]))
 static_assert(is_assignable_to(tuple[int, *tuple[int, ...]], tuple[Any, ...]))
@@ -1344,6 +1354,38 @@ static_assert(not is_assignable_to(TypeGuard[Unknown], str))  # error: [static-a
 static_assert(not is_assignable_to(TypeIs[Any], str))
 ```
 
+## `ParamSpec`
+
+```py
+from ty_extensions import TypeOf, static_assert, is_assignable_to, Unknown
+from typing import ParamSpec, Mapping, Callable, Any
+
+P = ParamSpec("P")
+
+def f(func: Callable[P, int], *args: P.args, **kwargs: P.kwargs) -> None:
+    static_assert(is_assignable_to(TypeOf[args], tuple[Any, ...]))
+    static_assert(is_assignable_to(TypeOf[args], tuple[object, ...]))
+    static_assert(is_assignable_to(TypeOf[args], tuple[Unknown, ...]))
+    static_assert(not is_assignable_to(TypeOf[args], tuple[int, ...]))
+    static_assert(not is_assignable_to(TypeOf[args], tuple[int, str]))
+
+    static_assert(not is_assignable_to(tuple[Any, ...], TypeOf[args]))
+    static_assert(not is_assignable_to(tuple[object, ...], TypeOf[args]))
+    static_assert(not is_assignable_to(tuple[Unknown, ...], TypeOf[args]))
+
+    static_assert(is_assignable_to(TypeOf[kwargs], dict[str, Any]))
+    static_assert(is_assignable_to(TypeOf[kwargs], dict[str, Unknown]))
+    static_assert(not is_assignable_to(TypeOf[kwargs], dict[str, object]))
+    static_assert(not is_assignable_to(TypeOf[kwargs], dict[str, int]))
+    static_assert(is_assignable_to(TypeOf[kwargs], Mapping[str, Any]))
+    static_assert(is_assignable_to(TypeOf[kwargs], Mapping[str, object]))
+    static_assert(is_assignable_to(TypeOf[kwargs], Mapping[str, Unknown]))
+
+    static_assert(not is_assignable_to(dict[str, Any], TypeOf[kwargs]))
+    static_assert(not is_assignable_to(dict[str, object], TypeOf[kwargs]))
+    static_assert(not is_assignable_to(dict[str, Unknown], TypeOf[kwargs]))
+```
+
 [gradual form]: https://typing.python.org/en/latest/spec/glossary.html#term-gradual-form
 [gradual tuple]: https://typing.python.org/en/latest/spec/tuples.html#tuple-type-form
 [typing documentation]: https://typing.python.org/en/latest/spec/concepts.html#the-assignable-to-or-consistent-subtyping-relation

crates/ty_python_semantic/resources/mdtest/type_qualifiers/classvar.md

@@ -101,6 +101,37 @@ class C:
     x: ClassVar[int, str] = 1
 ```
 
+## Trailing comma creates a tuple
+
+A trailing comma in a subscript creates a single-element tuple. We need to handle this gracefully
+and emit a proper error rather than crashing (see
+[ty#1793](https://github.com/astral-sh/ty/issues/1793)).
+
+```py
+from typing import ClassVar
+
+class C:
+    # error: [invalid-type-form] "Tuple literals are not allowed in this context in a type expression: Did you mean `tuple[()]`?"
+    x: ClassVar[(),]
+
+# error: [invalid-attribute-access] "Cannot assign to ClassVar `x` from an instance of type `C`"
+C().x = 42
+reveal_type(C.x)  # revealed: Unknown
+```
+
+This also applies when the trailing comma is inside the brackets (see
+[ty#1768](https://github.com/astral-sh/ty/issues/1768)):
+
+```py
+from typing import ClassVar
+
+class D:
+    # A trailing comma here doesn't change the meaning; it's still one argument.
+    a: ClassVar[int,] = 1
+
+reveal_type(D.a)  # revealed: int
+```
+
 ## Illegal `ClassVar` in type expression
 
 ```py

crates/ty_python_semantic/resources/mdtest/type_qualifiers/final.md

@@ -340,6 +340,22 @@ class C:
     x: Final[int, str] = 1
 ```
 
+### Trailing comma creates a tuple
+
+A trailing comma in a subscript creates a single-element tuple. We need to handle this gracefully
+and emit a proper error rather than crashing (see
+[ty#1793](https://github.com/astral-sh/ty/issues/1793)).
+
+```py
+from typing import Final
+
+# error: [invalid-type-form] "Tuple literals are not allowed in this context in a type expression: Did you mean `tuple[()]`?"
+x: Final[(),] = 42
+
+# error: [invalid-assignment] "Reassignment of `Final` symbol `x` is not allowed"
+x = 56
+```
+
 ### Illegal `Final` in type expression
 
 ```py

crates/ty_python_semantic/resources/mdtest/type_qualifiers/initvar.md

@@ -112,6 +112,25 @@ class Wrong:
     x: InitVar[int, str]  # error: [invalid-type-form] "Type qualifier `InitVar` expected exactly 1 argument, got 2"
 ```
 
+A trailing comma in a subscript creates a single-element tuple. We need to handle this gracefully
+and emit a proper error rather than crashing (see
+[ty#1793](https://github.com/astral-sh/ty/issues/1793)).
+
+```py
+from dataclasses import InitVar, dataclass
+
+@dataclass
+class AlsoWrong:
+    # error: [invalid-type-form] "Tuple literals are not allowed in this context in a type expression: Did you mean `tuple[()]`?"
+    x: InitVar[(),]
+
+# revealed: (self: AlsoWrong, x: Unknown) -> None
+reveal_type(AlsoWrong.__init__)
+
+# error: [unresolved-attribute]
+reveal_type(AlsoWrong(42).x)  # revealed: Unknown
+```
+
 A bare `InitVar` is not allowed according to the [type annotation grammar]:
 
 ```py

crates/ty_python_semantic/resources/mdtest/with/async.md

@@ -213,7 +213,7 @@ async def connect() -> AsyncGenerator[Session]:
     yield Session()
 
 # TODO: this should be `() -> _AsyncGeneratorContextManager[Session, None]`
-reveal_type(connect)  # revealed: (...) -> _AsyncGeneratorContextManager[Unknown, None]
+reveal_type(connect)  # revealed: () -> _AsyncGeneratorContextManager[Unknown, None]
 
 async def main():
     async with connect() as session:

crates/ty_python_semantic/src/diagnostic.rs

@@ -58,9 +58,8 @@ pub fn add_inferred_python_version_hint_to_diagnostic(
                     SubDiagnosticSeverity::Info,
                     format_args!("Python {version} was assumed when {action}"),
                 );
-                sub_diagnostic.annotate(Annotation::primary(span).message(format_args!(
-                    "Python {version} assumed due to this configuration setting"
-                )));
+                sub_diagnostic
+                    .annotate(Annotation::primary(span).message("Python version configuration"));
                 diagnostic.sub(sub_diagnostic);
             } else {
                 diagnostic.info(format_args!(
@@ -76,10 +75,8 @@ pub fn add_inferred_python_version_hint_to_diagnostic(
                         "Python {version} was assumed when {action} because of your virtual environment"
                     ),
                 );
-                sub_diagnostic.annotate(
-                    Annotation::primary(span)
-                        .message("Python version inferred from virtual environment metadata file"),
-                );
+                sub_diagnostic
+                    .annotate(Annotation::primary(span).message("Virtual environment metadata"));
                 // TODO: it would also be nice to tell them how we resolved their virtual environment...
                 diagnostic.sub(sub_diagnostic);
             } else {

crates/ty_python_semantic/src/module_resolver/module.rs

@@ -335,6 +335,12 @@ pub enum KnownModule {
     #[cfg(test)]
     Uuid,
     Warnings,
+    #[strum(serialize = "sqlalchemy.sql.selectable")]
+    SqlalchemySqlSelectable,
+    #[strum(serialize = "sqlalchemy.sql._selectable_constructors")]
+    SqlalchemySqlSelectableConstructors,
+    #[strum(serialize = "sqlalchemy.orm.attributes")]
+    SqlalchemyOrmAttributes,
 }
 
 impl KnownModule {
@@ -363,6 +369,9 @@ impl KnownModule {
             #[cfg(test)]
             Self::Uuid => "uuid",
             Self::Templatelib => "string.templatelib",
+            Self::SqlalchemySqlSelectable => "sqlalchemy.sql.selectable",
+            Self::SqlalchemySqlSelectableConstructors => "sqlalchemy.sql._selectable_constructors",
+            Self::SqlalchemyOrmAttributes => "sqlalchemy.orm.attributes",
         }
     }
 
@@ -378,7 +387,20 @@ impl KnownModule {
         if search_path.is_standard_library() {
             Self::from_str(name.as_str()).ok()
         } else {
-            None
+            // For non-stdlib search paths, check for known third-party modules
+            Self::try_from_third_party_name(name)
+        }
+    }
+
+    /// Returns a known module for third-party packages, if applicable.
+    fn try_from_third_party_name(name: &ModuleName) -> Option<Self> {
+        match name.as_str() {
+            "sqlalchemy.sql.selectable" => Some(Self::SqlalchemySqlSelectable),
+            "sqlalchemy.sql._selectable_constructors" => {
+                Some(Self::SqlalchemySqlSelectableConstructors)
+            }
+            "sqlalchemy.orm.attributes" => Some(Self::SqlalchemyOrmAttributes),
+            _ => None,
         }
     }
 
@@ -419,6 +441,11 @@ mod tests {
         let stdlib_search_path = SearchPath::vendored_stdlib();
 
         for module in KnownModule::iter() {
+            // Third-party modules aren't available in the vendored stdlib
+            if module.is_third_party() {
+                continue;
+            }
+
             let module_name = module.name();
 
             assert_eq!(

crates/ty_python_semantic/src/module_resolver/path.rs

@@ -594,7 +594,7 @@ impl SearchPath {
         )
     }
 
-    pub(crate) fn is_first_party(&self) -> bool {
+    pub fn is_first_party(&self) -> bool {
         matches!(&*self.0, SearchPathInner::FirstParty(_))
     }
 

crates/ty_python_semantic/src/types/bound_super.rs

@@ -157,7 +157,7 @@ impl<'db> BoundSuperError<'db> {
                         .map(|c| c.display(db))
                         .join(", ")
                 ));
-                Type::Union(constraints)
+                constraints.as_type(db)
             }
             None => {
                 diagnostic.info(format_args!(
@@ -374,7 +374,7 @@ impl<'db> BoundSuperType<'db> {
                         delegate_with_error_mapped(bound, Some(type_var))
                     }
                     Some(TypeVarBoundOrConstraints::Constraints(constraints)) => {
-                        delegate_with_error_mapped(Type::Union(constraints), Some(type_var))
+                        delegate_with_error_mapped(constraints.as_type(db), Some(type_var))
                     }
                     None => delegate_with_error_mapped(Type::object(), Some(type_var)),
                 };

crates/ty_python_semantic/src/types/builder.rs

@@ -202,12 +202,30 @@ enum ReduceResult<'db> {
     Type(Type<'db>),
 }
 
-// TODO increase this once we extend `UnionElement` throughout all union/intersection
-// representations, so that we can make large unions of literals fast in all operations.
-//
-// For now (until we solve https://github.com/astral-sh/ty/issues/957), keep this number
-// below 200, which is the salsa fixpoint iteration limit.
-const MAX_UNION_LITERALS: usize = 190;
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, get_size2::GetSize)]
+pub enum RecursivelyDefined {
+    Yes,
+    No,
+}
+
+impl RecursivelyDefined {
+    const fn is_yes(self) -> bool {
+        matches!(self, RecursivelyDefined::Yes)
+    }
+
+    const fn or(self, other: RecursivelyDefined) -> RecursivelyDefined {
+        match (self, other) {
+            (RecursivelyDefined::Yes, _) | (_, RecursivelyDefined::Yes) => RecursivelyDefined::Yes,
+            _ => RecursivelyDefined::No,
+        }
+    }
+}
+
+/// If the value ​​is defined recursively, widening is performed from fewer literal elements, resulting in faster convergence of the fixed-point iteration.
+const MAX_RECURSIVE_UNION_LITERALS: usize = 10;
+/// If the value ​​is defined non-recursively, the fixed-point iteration will converge in one go,
+/// so in principle we can have as many literal elements as we want, but to avoid unintended huge computational loads, we limit it to 256.
+const MAX_NON_RECURSIVE_UNION_LITERALS: usize = 256;
 
 pub(crate) struct UnionBuilder<'db> {
     elements: Vec<UnionElement<'db>>,
@@ -217,6 +235,7 @@ pub(crate) struct UnionBuilder<'db> {
     // This is enabled when joining types in a `cycle_recovery` function.
     // Since a cycle cannot be created within a `cycle_recovery` function, execution of `is_redundant_with` is skipped.
     cycle_recovery: bool,
+    recursively_defined: RecursivelyDefined,
 }
 
 impl<'db> UnionBuilder<'db> {
@@ -227,6 +246,7 @@ impl<'db> UnionBuilder<'db> {
             unpack_aliases: true,
             order_elements: false,
             cycle_recovery: false,
+            recursively_defined: RecursivelyDefined::No,
         }
     }
 
@@ -248,6 +268,11 @@ impl<'db> UnionBuilder<'db> {
         self
     }
 
+    pub(crate) fn recursively_defined(mut self, val: RecursivelyDefined) -> Self {
+        self.recursively_defined = val;
+        self
+    }
+
     pub(crate) fn is_empty(&self) -> bool {
         self.elements.is_empty()
     }
@@ -258,6 +283,27 @@ impl<'db> UnionBuilder<'db> {
         self.elements.push(UnionElement::Type(Type::object()));
     }
 
+    fn widen_literal_types(&mut self, seen_aliases: &mut Vec<Type<'db>>) {
+        let mut replace_with = vec![];
+        for elem in &self.elements {
+            match elem {
+                UnionElement::IntLiterals(_) => {
+                    replace_with.push(KnownClass::Int.to_instance(self.db));
+                }
+                UnionElement::StringLiterals(_) => {
+                    replace_with.push(KnownClass::Str.to_instance(self.db));
+                }
+                UnionElement::BytesLiterals(_) => {
+                    replace_with.push(KnownClass::Bytes.to_instance(self.db));
+                }
+                UnionElement::Type(_) => {}
+            }
+        }
+        for ty in replace_with {
+            self.add_in_place_impl(ty, seen_aliases);
+        }
+    }
+
     /// Adds a type to this union.
     pub(crate) fn add(mut self, ty: Type<'db>) -> Self {
         self.add_in_place(ty);
@@ -270,6 +316,15 @@ impl<'db> UnionBuilder<'db> {
     }
 
     pub(crate) fn add_in_place_impl(&mut self, ty: Type<'db>, seen_aliases: &mut Vec<Type<'db>>) {
+        let cycle_recovery = self.cycle_recovery;
+        let should_widen = |literals, recursively_defined: RecursivelyDefined| {
+            if recursively_defined.is_yes() && cycle_recovery {
+                literals >= MAX_RECURSIVE_UNION_LITERALS
+            } else {
+                literals >= MAX_NON_RECURSIVE_UNION_LITERALS
+            }
+        };
+
         match ty {
             Type::Union(union) => {
                 let new_elements = union.elements(self.db);
@@ -277,6 +332,20 @@ impl<'db> UnionBuilder<'db> {
                 for element in new_elements {
                     self.add_in_place_impl(*element, seen_aliases);
                 }
+                self.recursively_defined = self
+                    .recursively_defined
+                    .or(union.recursively_defined(self.db));
+                if self.cycle_recovery && self.recursively_defined.is_yes() {
+                    let literals = self.elements.iter().fold(0, |acc, elem| match elem {
+                        UnionElement::IntLiterals(literals) => acc + literals.len(),
+                        UnionElement::StringLiterals(literals) => acc + literals.len(),
+                        UnionElement::BytesLiterals(literals) => acc + literals.len(),
+                        UnionElement::Type(_) => acc,
+                    });
+                    if should_widen(literals, self.recursively_defined) {
+                        self.widen_literal_types(seen_aliases);
+                    }
+                }
             }
             // Adding `Never` to a union is a no-op.
             Type::Never => {}
@@ -300,7 +369,7 @@ impl<'db> UnionBuilder<'db> {
                 for (index, element) in self.elements.iter_mut().enumerate() {
                     match element {
                         UnionElement::StringLiterals(literals) => {
-                            if literals.len() >= MAX_UNION_LITERALS {
+                            if should_widen(literals.len(), self.recursively_defined) {
                                 let replace_with = KnownClass::Str.to_instance(self.db);
                                 self.add_in_place_impl(replace_with, seen_aliases);
                                 return;
@@ -345,7 +414,7 @@ impl<'db> UnionBuilder<'db> {
                 for (index, element) in self.elements.iter_mut().enumerate() {
                     match element {
                         UnionElement::BytesLiterals(literals) => {
-                            if literals.len() >= MAX_UNION_LITERALS {
+                            if should_widen(literals.len(), self.recursively_defined) {
                                 let replace_with = KnownClass::Bytes.to_instance(self.db);
                                 self.add_in_place_impl(replace_with, seen_aliases);
                                 return;
@@ -390,7 +459,7 @@ impl<'db> UnionBuilder<'db> {
                 for (index, element) in self.elements.iter_mut().enumerate() {
                     match element {
                         UnionElement::IntLiterals(literals) => {
-                            if literals.len() >= MAX_UNION_LITERALS {
+                            if should_widen(literals.len(), self.recursively_defined) {
                                 let replace_with = KnownClass::Int.to_instance(self.db);
                                 self.add_in_place_impl(replace_with, seen_aliases);
                                 return;
@@ -585,6 +654,7 @@ impl<'db> UnionBuilder<'db> {
             _ => Some(Type::Union(UnionType::new(
                 self.db,
                 types.into_boxed_slice(),
+                self.recursively_defined,
             ))),
         }
     }
@@ -696,6 +766,7 @@ impl<'db> IntersectionBuilder<'db> {
                             enum_member_literals(db, instance.class_literal(db), None)
                                 .expect("Calling `enum_member_literals` on an enum class")
                                 .collect::<Box<[_]>>(),
+                            RecursivelyDefined::No,
                         )),
                         seen_aliases,
                     )
@@ -1184,7 +1255,7 @@ impl<'db> InnerIntersectionBuilder<'db> {
                                 speculative = speculative.add_positive(bound);
                             }
                             Some(TypeVarBoundOrConstraints::Constraints(constraints)) => {
-                                speculative = speculative.add_positive(Type::Union(constraints));
+                                speculative = speculative.add_positive(constraints.as_type(db));
                             }
                             // TypeVars without a bound or constraint implicitly have `object` as their
                             // upper bound, and it is always a no-op to add `object` to an intersection.

crates/ty_python_semantic/src/types/call/arguments.rs

@@ -150,6 +150,14 @@ impl<'a, 'db> CallArguments<'a, 'db> {
         (self.arguments.iter().copied()).zip(self.types.iter_mut())
     }
 
+    /// Create a new [`CallArguments`] starting from the specified index.
+    pub(super) fn start_from(&self, index: usize) -> Self {
+        Self {
+            arguments: self.arguments[index..].to_vec(),
+            types: self.types[index..].to_vec(),
+        }
+    }
+
     /// Returns an iterator on performing [argument type expansion].
     ///
     /// Each element of the iterator represents a set of argument lists, where each argument list

crates/ty_python_semantic/src/types/call/bind.rs

@@ -3,6 +3,7 @@
 //! [signatures][crate::types::signatures], we have to handle the fact that the callable might be a
 //! union of types, each of which might contain multiple overloads.
 
+use std::borrow::Cow;
 use std::collections::HashSet;
 use std::fmt;
 
@@ -33,13 +34,14 @@ use crate::types::generics::{
     InferableTypeVars, Specialization, SpecializationBuilder, SpecializationError,
 };
 use crate::types::signatures::{Parameter, ParameterForm, ParameterKind, Parameters};
-use crate::types::tuple::{TupleLength, TupleType};
+use crate::types::tuple::{TupleLength, TupleSpec, TupleType};
 use crate::types::{
-    BoundMethodType, BoundTypeVarIdentity, ClassLiteral, DATACLASS_FLAGS, DataclassFlags,
-    DataclassParams, FieldInstance, KnownBoundMethodType, KnownClass, KnownInstanceType,
-    MemberLookupPolicy, NominalInstanceType, PropertyInstanceType, SpecialFormType,
-    TrackedConstraintSet, TypeAliasType, TypeContext, TypeVarVariance, UnionBuilder, UnionType,
-    WrapperDescriptorKind, enums, list_members, todo_type,
+    BoundMethodType, BoundTypeVarIdentity, BoundTypeVarInstance, CallableSignature,
+    CallableTypeKind, ClassLiteral, DATACLASS_FLAGS, DataclassFlags, DataclassParams,
+    FieldInstance, KnownBoundMethodType, KnownClass, KnownInstanceType, MemberLookupPolicy,
+    NominalInstanceType, PropertyInstanceType, SpecialFormType, TrackedConstraintSet,
+    TypeAliasType, TypeContext, TypeVarVariance, UnionBuilder, UnionType, WrapperDescriptorKind,
+    enums, list_members, todo_type,
 };
 use ruff_db::diagnostic::{Annotation, Diagnostic, SubDiagnostic, SubDiagnosticSeverity};
 use ruff_python_ast::{self as ast, ArgOrKeyword, PythonVersion};
@@ -788,51 +790,67 @@ impl<'db> Bindings<'db> {
                                     ))
                                 };
 
-                                let function_generic_context = |function: FunctionType<'db>| {
-                                    let union = UnionType::from_elements(
-                                        db,
-                                        function
-                                            .signature(db)
-                                            .overloads
-                                            .iter()
-                                            .filter_map(|signature| signature.generic_context)
-                                            .map(wrap_generic_context),
-                                    );
-                                    if union.is_never() {
-                                        Type::none(db)
-                                    } else {
-                                        union
-                                    }
-                                };
+                                let signature_generic_context =
+                                    |signature: &CallableSignature<'db>| {
+                                        UnionType::try_from_elements(
+                                            db,
+                                            signature.overloads.iter().map(|signature| {
+                                                signature.generic_context.map(wrap_generic_context)
+                                            }),
+                                        )
+                                    };
 
-                                // TODO: Handle generic functions, and unions/intersections of
-                                // generic types
-                                overload.set_return_type(match ty {
-                                    Type::ClassLiteral(class) => class
-                                        .generic_context(db)
-                                        .map(wrap_generic_context)
-                                        .unwrap_or_else(|| Type::none(db)),
+                                let generic_context_for_simple_type = |ty: Type<'db>| match ty {
+                                    Type::ClassLiteral(class) => {
+                                        class.generic_context(db).map(wrap_generic_context)
+                                    }
 
                                     Type::FunctionLiteral(function) => {
-                                        function_generic_context(*function)
+                                        signature_generic_context(function.signature(db))
                                     }
 
-                                    Type::BoundMethod(bound_method) => {
-                                        function_generic_context(bound_method.function(db))
+                                    Type::BoundMethod(bound_method) => signature_generic_context(
+                                        bound_method.function(db).signature(db),
+                                    ),
+
+                                    Type::Callable(callable) => {
+                                        signature_generic_context(callable.signatures(db))
                                     }
 
                                     Type::KnownInstance(KnownInstanceType::TypeAliasType(
                                         TypeAliasType::PEP695(alias),
-                                    )) => alias
-                                        .generic_context(db)
-                                        .map(wrap_generic_context)
-                                        .unwrap_or_else(|| Type::none(db)),
+                                    )) => alias.generic_context(db).map(wrap_generic_context),
 
-                                    _ => Type::none(db),
-                                });
+                                    _ => None,
+                                };
+
+                                let generic_context = match ty {
+                                    Type::Union(union_type) => UnionType::try_from_elements(
+                                        db,
+                                        union_type
+                                            .elements(db)
+                                            .iter()
+                                            .map(|ty| generic_context_for_simple_type(*ty)),
+                                    ),
+                                    _ => generic_context_for_simple_type(*ty),
+                                };
+
+                                overload.set_return_type(
+                                    generic_context.unwrap_or_else(|| Type::none(db)),
+                                );
                             }
                         }
 
+                        Some(KnownFunction::IntoCallable) => {
+                            let [Some(ty)] = overload.parameter_types() else {
+                                continue;
+                            };
+                            let Some(callables) = ty.try_upcast_to_callable(db) else {
+                                continue;
+                            };
+                            overload.set_return_type(callables.into_type(db));
+                        }
+
                         Some(KnownFunction::DunderAllNames) => {
                             if let [Some(ty)] = overload.parameter_types() {
                                 overload.set_return_type(match ty {
@@ -2563,20 +2581,62 @@ impl<'a, 'db> ArgumentMatcher<'a, 'db> {
         argument: Argument<'a>,
         argument_type: Option<Type<'db>>,
     ) -> Result<(), ()> {
-        // TODO: `Type::iterate` internally handles unions, but in a lossy way.
-        // It might be superior here to manually map over the union and call `try_iterate`
-        // on each element, similar to the way that `unpacker.rs` does in the `unpack_inner` method.
-        // It might be a bit of a refactor, though.
-        // See <https://github.com/astral-sh/ruff/pull/20377#issuecomment-3401380305>
-        // for more details. --Alex
-        let tuple = argument_type.map(|ty| ty.iterate(db));
-        let (mut argument_types, length, variable_element) = match tuple.as_ref() {
-            Some(tuple) => (
+        enum VariadicArgumentType<'db> {
+            ParamSpec(Type<'db>),
+            Other(Cow<'db, TupleSpec<'db>>),
+            None,
+        }
+
+        let variadic_type = match argument_type {
+            Some(argument_type @ Type::Union(union)) => {
+                // When accessing an instance attribute that is a `P.args`, the type we infer is
+                // `Unknown | P.args`. This needs to be special cased here to avoid calling
+                // `iterate` on it which will lose the `ParamSpec` information as it will return
+                // `object` that comes from the upper bound of `P.args`. What we want is to always
+                // use the `P.args` type to perform type checking against the parameter type. This
+                // will allow us to error when `*args: P.args` is matched against, for example,
+                // `n: int` and correctly type check when `*args: P.args` is matched against
+                // `*args: P.args` (another ParamSpec).
+                match union.elements(db) {
+                    [paramspec @ Type::TypeVar(typevar), other]
+                    | [other, paramspec @ Type::TypeVar(typevar)]
+                        if typevar.is_paramspec(db) && other.is_unknown() =>
+                    {
+                        VariadicArgumentType::ParamSpec(*paramspec)
+                    }
+                    _ => {
+                        // TODO: Same todo comment as in the non-paramspec case below
+                        VariadicArgumentType::Other(argument_type.iterate(db))
+                    }
+                }
+            }
+            Some(paramspec @ Type::TypeVar(typevar)) if typevar.is_paramspec(db) => {
+                VariadicArgumentType::ParamSpec(paramspec)
+            }
+            Some(argument_type) => {
+                // TODO: `Type::iterate` internally handles unions, but in a lossy way.
+                // It might be superior here to manually map over the union and call `try_iterate`
+                // on each element, similar to the way that `unpacker.rs` does in the `unpack_inner` method.
+                // It might be a bit of a refactor, though.
+                // See <https://github.com/astral-sh/ruff/pull/20377#issuecomment-3401380305>
+                // for more details. --Alex
+                VariadicArgumentType::Other(argument_type.iterate(db))
+            }
+            None => VariadicArgumentType::None,
+        };
+
+        let (mut argument_types, length, variable_element) = match &variadic_type {
+            VariadicArgumentType::ParamSpec(paramspec) => (
+                Either::Right(std::iter::empty()),
+                TupleLength::unknown(),
+                Some(*paramspec),
+            ),
+            VariadicArgumentType::Other(tuple) => (
                 Either::Left(tuple.all_elements().copied()),
                 tuple.len(),
                 tuple.variable_element().copied(),
             ),
-            None => (
+            VariadicArgumentType::None => (
                 Either::Right(std::iter::empty()),
                 TupleLength::unknown(),
                 None,
@@ -2651,21 +2711,39 @@ impl<'a, 'db> ArgumentMatcher<'a, 'db> {
                 );
             }
         } else {
-            let value_type = match argument_type.map(|ty| {
-                ty.member_lookup_with_policy(
+            let dunder_getitem_return_type = |ty: Type<'db>| match ty
+                .member_lookup_with_policy(
                     db,
                     Name::new_static("__getitem__"),
                     MemberLookupPolicy::NO_INSTANCE_FALLBACK,
                 )
                 .place
-            }) {
-                Some(Place::Defined(keys_method, _, Definedness::AlwaysDefined)) => keys_method
+            {
+                Place::Defined(getitem_method, _, Definedness::AlwaysDefined) => getitem_method
                     .try_call(db, &CallArguments::positional([Type::unknown()]))
                     .ok()
                     .map_or_else(Type::unknown, |bindings| bindings.return_type(db)),
                 _ => Type::unknown(),
             };
 
+            let value_type = match argument_type {
+                Some(argument_type @ Type::Union(union)) => {
+                    // See the comment in `match_variadic` for why we special case this situation.
+                    match union.elements(db) {
+                        [paramspec @ Type::TypeVar(typevar), other]
+                        | [other, paramspec @ Type::TypeVar(typevar)]
+                            if typevar.is_paramspec(db) && other.is_unknown() =>
+                        {
+                            *paramspec
+                        }
+                        _ => dunder_getitem_return_type(argument_type),
+                    }
+                }
+                Some(paramspec @ Type::TypeVar(typevar)) if typevar.is_paramspec(db) => paramspec,
+                Some(argument_type) => dunder_getitem_return_type(argument_type),
+                None => Type::unknown(),
+            };
+
             for (parameter_index, parameter) in self.parameters.iter().enumerate() {
                 if self.parameter_info[parameter_index].matched && !parameter.is_keyword_variadic()
                 {
@@ -2735,6 +2813,7 @@ impl<'a, 'db> ArgumentMatcher<'a, 'db> {
 
 struct ArgumentTypeChecker<'a, 'db> {
     db: &'db dyn Db,
+    signature_type: Type<'db>,
     signature: &'a Signature<'db>,
     arguments: &'a CallArguments<'a, 'db>,
     argument_matches: &'a [MatchedArgument<'db>],
@@ -2752,6 +2831,7 @@ impl<'a, 'db> ArgumentTypeChecker<'a, 'db> {
     #[expect(clippy::too_many_arguments)]
     fn new(
         db: &'db dyn Db,
+        signature_type: Type<'db>,
         signature: &'a Signature<'db>,
         arguments: &'a CallArguments<'a, 'db>,
         argument_matches: &'a [MatchedArgument<'db>],
@@ -2763,6 +2843,7 @@ impl<'a, 'db> ArgumentTypeChecker<'a, 'db> {
     ) -> Self {
         Self {
             db,
+            signature_type,
             signature,
             arguments,
             argument_matches,
@@ -3011,9 +3092,23 @@ impl<'a, 'db> ArgumentTypeChecker<'a, 'db> {
     }
 
     fn check_argument_types(&mut self) {
+        let paramspec = self
+            .signature
+            .parameters()
+            .find_paramspec_from_args_kwargs(self.db);
+
         for (argument_index, adjusted_argument_index, argument, argument_type) in
             self.enumerate_argument_types()
         {
+            if let Some((_, paramspec)) = paramspec {
+                if self.try_paramspec_evaluation_at(argument_index, paramspec) {
+                    // Once we find an argument that matches the `ParamSpec`, we can stop checking
+                    // the remaining arguments since `ParamSpec` should always be the last
+                    // parameter.
+                    return;
+                }
+            }
+
             match argument {
                 Argument::Variadic => self.check_variadic_argument_type(
                     argument_index,
@@ -3039,6 +3134,131 @@ impl<'a, 'db> ArgumentTypeChecker<'a, 'db> {
                 }
             }
         }
+
+        if let Some((_, paramspec)) = paramspec {
+            // If we reach here, none of the arguments matched the `ParamSpec` parameter, but the
+            // `ParamSpec` could specialize to a parameter list containing some parameters. For
+            // example,
+            //
+            // ```py
+            // from typing import Callable
+            //
+            // def foo[**P](f: Callable[P, None], *args: P.args, **kwargs: P.kwargs) -> None: ...
+            //
+            // def f(x: int) -> None: ...
+            //
+            // foo(f)
+            // ```
+            //
+            // Here, no arguments match the `ParamSpec` parameter, but `P` specializes to `(x: int)`,
+            // so we need to perform a sub-call with no arguments.
+            self.evaluate_paramspec_sub_call(None, paramspec);
+        }
+    }
+
+    /// Try to evaluate a `ParamSpec` sub-call at the given argument index.
+    ///
+    /// The `ParamSpec` parameter is always going to be at the end of the parameter list but there
+    /// can be other parameter before it. If one of these prepended positional parameters contains
+    /// a free `ParamSpec`, we consider that variable in scope for the purposes of extracting the
+    /// components of that `ParamSpec`. For example:
+    ///
+    /// ```py
+    /// from typing import Callable
+    ///
+    /// def foo[**P](f: Callable[P, None], *args: P.args, **kwargs: P.kwargs) -> None: ...
+    ///
+    /// def f(x: int, y: str) -> None: ...
+    ///
+    /// foo(f, 1, "hello")  # P: (x: int, y: str)
+    /// ```
+    ///
+    /// Here, `P` specializes to `(x: int, y: str)` when `foo` is called with `f`, which means that
+    /// the parameters of `f` become a part of `foo`'s parameter list replacing the `ParamSpec`
+    /// parameter which is:
+    ///
+    /// ```py
+    /// def foo(f: Callable[[x: int, y: str], None], x: int, y: str) -> None: ...
+    /// ```
+    ///
+    /// This method will check whether the parameter matching the argument at `argument_index` is
+    /// annotated with the components of `ParamSpec`, and if so, will invoke a sub-call considering
+    /// the arguments starting from `argument_index` against the specialized parameter list.
+    ///
+    /// Returns `true` if the sub-call was invoked, `false` otherwise.
+    fn try_paramspec_evaluation_at(
+        &mut self,
+        argument_index: usize,
+        paramspec: BoundTypeVarInstance<'db>,
+    ) -> bool {
+        let [parameter_index] = self.argument_matches[argument_index].parameters.as_slice() else {
+            return false;
+        };
+
+        if !self.signature.parameters()[*parameter_index]
+            .annotated_type()
+            .is_some_and(|ty| matches!(ty, Type::TypeVar(typevar) if typevar.is_paramspec(self.db)))
+        {
+            return false;
+        }
+
+        self.evaluate_paramspec_sub_call(Some(argument_index), paramspec)
+    }
+
+    /// Invoke a sub-call for the given `ParamSpec` type variable, using the remaining arguments.
+    ///
+    /// The remaining arguments start from `argument_index` if provided, otherwise no arguments
+    /// are passed.
+    ///
+    /// This method returns `false` if the specialization does not contain a mapping for the given
+    /// `paramspec`, contains an invalid mapping (i.e., not a `Callable` of kind `ParamSpecValue`)
+    /// or if the value is an overloaded callable.
+    ///
+    /// For more details, refer to [`Self::try_paramspec_evaluation_at`].
+    fn evaluate_paramspec_sub_call(
+        &mut self,
+        argument_index: Option<usize>,
+        paramspec: BoundTypeVarInstance<'db>,
+    ) -> bool {
+        let Some(Type::Callable(callable)) = self
+            .specialization
+            .and_then(|specialization| specialization.get(self.db, paramspec))
+        else {
+            return false;
+        };
+
+        if callable.kind(self.db) != CallableTypeKind::ParamSpecValue {
+            return false;
+        }
+
+        // TODO: Support overloads?
+        let [signature] = callable.signatures(self.db).overloads.as_slice() else {
+            return false;
+        };
+
+        let sub_arguments = if let Some(argument_index) = argument_index {
+            self.arguments.start_from(argument_index)
+        } else {
+            CallArguments::none()
+        };
+
+        // TODO: What should be the `signature_type` here?
+        let bindings = match Bindings::from(Binding::single(self.signature_type, signature.clone()))
+            .match_parameters(self.db, &sub_arguments)
+            .check_types(self.db, &sub_arguments, self.call_expression_tcx, &[])
+        {
+            Ok(bindings) => Box::new(bindings),
+            Err(CallError(_, bindings)) => bindings,
+        };
+
+        // SAFETY: `bindings` was created from a single binding above.
+        let [binding] = bindings.single_element().unwrap().overloads.as_slice() else {
+            unreachable!("ParamSpec sub-call should only contain a single binding");
+        };
+
+        self.errors.extend(binding.errors.iter().cloned());
+
+        true
     }
 
     fn check_variadic_argument_type(
@@ -3081,69 +3301,94 @@ impl<'a, 'db> ArgumentTypeChecker<'a, 'db> {
                 );
             }
         } else {
-            // TODO: Instead of calling the `keys` and `__getitem__` methods, we should instead
-            // get the constraints which satisfies the `SupportsKeysAndGetItem` protocol i.e., the
-            // key and value type.
-            let key_type = match argument_type
-                .member_lookup_with_policy(
-                    self.db,
-                    Name::new_static("keys"),
-                    MemberLookupPolicy::NO_INSTANCE_FALLBACK,
-                )
-                .place
-            {
-                Place::Defined(keys_method, _, Definedness::AlwaysDefined) => keys_method
-                    .try_call(self.db, &CallArguments::none())
-                    .ok()
-                    .and_then(|bindings| {
-                        Some(
-                            bindings
-                                .return_type(self.db)
-                                .try_iterate(self.db)
-                                .ok()?
-                                .homogeneous_element_type(self.db),
+            let mut value_type_fallback = |argument_type: Type<'db>| {
+                // TODO: Instead of calling the `keys` and `__getitem__` methods, we should
+                // instead get the constraints which satisfies the `SupportsKeysAndGetItem`
+                // protocol i.e., the key and value type.
+                let key_type = match argument_type
+                    .member_lookup_with_policy(
+                        self.db,
+                        Name::new_static("keys"),
+                        MemberLookupPolicy::NO_INSTANCE_FALLBACK,
+                    )
+                    .place
+                {
+                    Place::Defined(keys_method, _, Definedness::AlwaysDefined) => keys_method
+                        .try_call(self.db, &CallArguments::none())
+                        .ok()
+                        .and_then(|bindings| {
+                            Some(
+                                bindings
+                                    .return_type(self.db)
+                                    .try_iterate(self.db)
+                                    .ok()?
+                                    .homogeneous_element_type(self.db),
+                            )
+                        }),
+                    _ => None,
+                };
+
+                let Some(key_type) = key_type else {
+                    self.errors.push(BindingError::KeywordsNotAMapping {
+                        argument_index: adjusted_argument_index,
+                        provided_ty: argument_type,
+                    });
+                    return None;
+                };
+
+                if !key_type
+                    .when_assignable_to(
+                        self.db,
+                        KnownClass::Str.to_instance(self.db),
+                        self.inferable_typevars,
+                    )
+                    .is_always_satisfied(self.db)
+                {
+                    self.errors.push(BindingError::InvalidKeyType {
+                        argument_index: adjusted_argument_index,
+                        provided_ty: key_type,
+                    });
+                }
+
+                Some(
+                    match argument_type
+                        .member_lookup_with_policy(
+                            self.db,
+                            Name::new_static("__getitem__"),
+                            MemberLookupPolicy::NO_INSTANCE_FALLBACK,
                         )
-                    }),
-                _ => None,
+                        .place
+                    {
+                        Place::Defined(keys_method, _, Definedness::AlwaysDefined) => keys_method
+                            .try_call(self.db, &CallArguments::positional([Type::unknown()]))
+                            .ok()
+                            .map_or_else(Type::unknown, |bindings| bindings.return_type(self.db)),
+                        _ => Type::unknown(),
+                    },
+                )
             };
 
-            let Some(key_type) = key_type else {
-                self.errors.push(BindingError::KeywordsNotAMapping {
-                    argument_index: adjusted_argument_index,
-                    provided_ty: argument_type,
-                });
+            let value_type = match argument_type {
+                Type::Union(union) => {
+                    // See the comment in `match_variadic` for why we special case this situation.
+                    match union.elements(self.db) {
+                        [paramspec @ Type::TypeVar(typevar), other]
+                        | [other, paramspec @ Type::TypeVar(typevar)]
+                            if typevar.is_paramspec(self.db) && other.is_unknown() =>
+                        {
+                            Some(*paramspec)
+                        }
+                        _ => value_type_fallback(argument_type),
+                    }
+                }
+                Type::TypeVar(typevar) if typevar.is_paramspec(self.db) => Some(argument_type),
+                _ => value_type_fallback(argument_type),
+            };
+
+            let Some(value_type) = value_type else {
                 return;
             };
 
-            if !key_type
-                .when_assignable_to(
-                    self.db,
-                    KnownClass::Str.to_instance(self.db),
-                    self.inferable_typevars,
-                )
-                .is_always_satisfied(self.db)
-            {
-                self.errors.push(BindingError::InvalidKeyType {
-                    argument_index: adjusted_argument_index,
-                    provided_ty: key_type,
-                });
-            }
-
-            let value_type = match argument_type
-                .member_lookup_with_policy(
-                    self.db,
-                    Name::new_static("__getitem__"),
-                    MemberLookupPolicy::NO_INSTANCE_FALLBACK,
-                )
-                .place
-            {
-                Place::Defined(keys_method, _, Definedness::AlwaysDefined) => keys_method
-                    .try_call(self.db, &CallArguments::positional([Type::unknown()]))
-                    .ok()
-                    .map_or_else(Type::unknown, |bindings| bindings.return_type(self.db)),
-                _ => Type::unknown(),
-            };
-
             for (argument_type, parameter_index) in
                 std::iter::repeat(value_type).zip(&self.argument_matches[argument_index].parameters)
             {
@@ -3321,6 +3566,7 @@ impl<'db> Binding<'db> {
     ) {
         let mut checker = ArgumentTypeChecker::new(
             db,
+            self.signature_type,
             &self.signature,
             arguments,
             &self.argument_matches,