[ty] Implement goto-type for inlay type hints #21533

Gankra · 2025-11-20T05:07:46Z

This PR generalizes the signature_help system's SignatureWriter which could get the subspans of function parameters.
We now have TypeDetailsWriter which is threaded between type's display implementations via a new fmt_detailed method that many of the Display types now have.

With this information we can properly add goto-type targets to our inlay hints. This also lays groundwork for any future "I want to render a type but get spans" work.

Also a ton of lifetimes are introduced to avoid things getting conflated with 'db.

This PR is broken up into a series of commits:

Generalizing SignatureWriter to TypeDetailsWriter, but not using it anywhere else. This commit was confirmed to be a non-functional change (no test results changed)
Introducing fmt_detailed everywhere to thread through TypeDetailsWriter and annotate various spans as "being" a given Type -- this is also where I had to reckon with a ton of erroneous &'db self. This commit was also confirmed to be a non-functional change.
Finally, actually using the results for goto-type on inlay hints!
Regenerating snapshots, fixups, etc.

Gankra · 2025-11-20T05:08:22Z

Have had this bee in my bonnet all week the IDE feels SO much better with these being clickable!

astral-sh-bot · 2025-11-20T05:09:51Z

Diagnostic diff on typing conformance tests

No changes detected when running ty on typing conformance tests ✅

Gankra · 2025-11-20T05:10:20Z

crates/ty_python_semantic/src/types/display.rs

+        f.with_detail(TypeDetail::Type(Type::ClassLiteral(self.class)))
+            .write_str(self.class.name(self.db))?;


This is the single-most important type span we introduce, since it's nearly every nominal type's name.

astral-sh-bot · 2025-11-20T05:11:16Z

`mypy_primer` results

Changes were detected when running on open source projects

scikit-build-core (https://github.com/scikit-build/scikit-build-core)
- src/scikit_build_core/build/wheel.py:98:20: error[no-matching-overload] No overload of bound method `__init__` matches arguments
- Found 44 diagnostics
+ Found 43 diagnostics

No memory usage changes detected ✅

crates/ty_python_semantic/src/types/display.rs

Gankra · 2025-11-20T05:13:01Z

crates/ty_python_semantic/src/types/display.rs

-                        write!(
-                            f,
-                            "bound method {instance}.{method}{type_parameters}{signature}",
-                            method = function.name(self.db),
-                            instance = self_ty.display_with(self.db, self.settings.singleline()),
-                            type_parameters = type_parameters,
-                            signature = signature
-                                .bind_self(self.db, Some(typing_self_ty))
-                                .display_with(self.db, self.settings.clone())
-                        )
+                        f.write_str("bound method ")?;
+                        self_ty
+                            .display_with(self.db, self.settings.singleline())
+                            .fmt_detailed(f)?;
+                        f.write_char('.')?;
+                        f.with_detail(TypeDetail::Type(self.ty))
+                            .write_str(function.name(self.db))?;
+                        type_parameters.fmt_detailed(f)?;
+                        signature
+                            .bind_self(self.db, Some(typing_self_ty))
+                            .display_with(self.db, self.settings.clone())
+                            .fmt_detailed(f)


A lot of the PR is me breaking up a nice pretty write! into individual parts to invoke fmt_detailed where appropriate.

Gankra · 2025-11-20T05:14:05Z

crates/ty_python_semantic/src/types/display.rs

 impl<'db> TupleSpec<'db> {
-    pub(crate) fn display_with(
-        &'db self,
+    pub(crate) fn display_with<'a>(
+        &'a self,
        db: &'db dyn Db,
        settings: DisplaySettings<'db>,
-    ) -> DisplayTuple<'db> {
+    ) -> DisplayTuple<'a, 'db> {


Deconflating these lifetimes was unfortunately loadbearing. I had to do that a lot.

Gankra · 2025-11-20T05:16:44Z

crates/ty_python_semantic/src/types/display.rs


-    /// Internal method to write signature with the signature writer
-    fn write_signature(&self, writer: &mut SignatureWriter) -> fmt::Result {
+    fn fmt_detailed(&self, f: &mut TypeWriter<'_, '_, 'db>) -> fmt::Result {
+        // Immediately write a marker signaling we're starting a signature
+        let _ = f.with_detail(TypeDetail::SignatureStart);
+        // When we exit this function, write a marker signaling we're ending a signature
+        let mut f = f.with_detail(TypeDetail::SignatureEnd);


An incredible victory for not wanting to have to reverse-engineer what parameters belong to nested signatures.

MichaReiser

The implementation looks good to me. I've one suggestion that should help to reduce the necessary changes because of Join.

I do find the test very confusing as we now see go to targets in places where we don't show any inlay hints. I think we should change this before landing this PR

crates/ty_ide/src/inlay_hints.rs

MichaReiser · 2025-11-20T08:29:57Z

crates/ty_python_semantic/src/types/display.rs

+
+impl Drop for TypeDetailGuard<'_, '_, '_, '_> {
+    fn drop(&mut self) {
+        // The fallibility here is primarily retrieving `TypeWriter::Details`


Should we bail early if std::thread::panicking?

I don't think that's necessary?

crates/ty_python_semantic/src/types/display.rs

MichaReiser · 2025-11-20T13:45:36Z

crates/ty_ide/src/inlay_hints.rs

            let hints = inlay_hints(&self.db, self.file, self.range, settings);

            let mut buf = source_text(&self.db, self.file).as_str().to_string();

-            let mut diagnostics = Vec::new();
+            let mut tbd_diagnostics = Vec::new();


Are those to be defined diagnostics?

I have to gather them up transiently while we create the annotated file, and then create the annotated file, and then create them properly.

Gankra · 2025-11-20T13:55:06Z

Micha you're god damn incredible, the join impl Just Worked.

AlexWaygood

Very cool!

AlexWaygood · 2025-11-20T12:51:51Z

crates/ty_python_semantic/src/types/display.rs

            | Type::BytesLiteral(_)
            | Type::EnumLiteral(_) => {
-                write!(f, "Literal[{representation}]")
+                f.write_str("Literal[")?;


It would be cool if we could also have goto-definition for the Literal part of e.g. Literal[42]. We don't have any documentation for typing.Literal in our vendored typeshed stubs right now (because we currently only add docstrings for classes, functions and modules), but it would be nice to add that capability to docstring-adder at some point. Then when you goto definition for the symbol Literal you'd see all of this lovely explanation in the stub file to tell you how Literal types work (this is the docstring for the symbol at runtime):

% uvx python -m pydoc typing.Literal Help on _TypedCacheSpecialForm in typing: typing.Literal = typing.Literal Special typing form to define literal types (a.k.a. value types). This form can be used to indicate to type checkers that the corresponding variable or function parameter has a value equivalent to the provided literal (or one of several literals):: def validate_simple(data: Any) -> Literal[True]: # always returns True ... MODE = Literal['r', 'rb', 'w', 'wb'] def open_helper(file: str, mode: MODE) -> str: ... open_helper('/some/path', 'r') # Passes type check open_helper('/other/path', 'typo') # Error in type checker Literal[...] cannot be subclassed. At runtime, an arbitrary value is allowed as type argument to Literal[...], but type checkers may impose restrictions.

The symbol typing.Literal itself has type Type::SpecialForm(SpecialFormType::Literal) in our model, so would you do that like this?

Suggested change

f.write_str("Literal[")?;

f.with_detail(TypeDetail::Type(Type::SpecialForm(SpecialFormType::Literal))).write_str("Literal")?;

f.write_char('[')?;

I know you literally gave me the implementation but I'd like to keep these things to followups (I'm terrified of this PR getting merge conflicted to hell).

AlexWaygood · 2025-11-20T13:50:08Z

crates/ty_python_semantic/src/types/display.rs

        match self.ty {
-            Type::Dynamic(dynamic) => dynamic.fmt(f),
-            Type::Never => f.write_str("Never"),
+            Type::Dynamic(dynamic) => write!(f, "{dynamic}"),


if the type is Type::Dynamic(DynamicType::Any), it would be cool if we could goto the definition for the Any symbol (with has type Type::SpecialForm(SpecialFormType::Any) in our model)

(similarly leaving as a followup)

AlexWaygood · 2025-11-20T14:02:53Z

crates/ty_ide/src/inlay_hints.rs

Could you also add tests for generic-alias types, e.g.

class Foo[T]: ... a [: <class 'Foo[int]'>] = Foo[int]

and subclass-of types, e.g.

def f(x: list[str]): y [: type[list[str]]] = type(x)

For the first one I'd expect goto targets for both Foo and int in <class 'Foo[int]>. For the second one I'd expect goto targets for both list and str in type[list[str]]

Cool with this also being a followup?

AlexWaygood · 2025-11-20T14:04:31Z

looks like you'll need to add some snapshot filters to get snapshots that include filepaths working on Windows 🙃

Gankra · 2025-11-20T14:28:39Z

Ughhhh

      299   299 │ info[inlay-hint-location]: Inlay Hint Target
      300       │-  --> stdlib/string/templatelib.pyi:10:7
            300 │+  --> stdlib\string\templatelib.pyi:10:7

This is really annoying because \ can appear in like \x08 and I think I'm just gonna ask everyone to agree to not Notice I'm clobbering those in the inlay hint tests.

Gankra · 2025-11-20T14:35:36Z

Actually I'm extremely confused why this isn't a problem in any of the goto tests

Gankra · 2025-11-20T14:39:56Z

(More followups for the followup pile I guess)

MatthewMckee4 · 2025-11-20T14:46:02Z

@Gankra, Sick!

Gankra added 5 commits November 19, 2025 20:17

replace SignatureWriter with more generic TypeDetailsWriter

e63a14a

introduce fmt_detailed everywhere

3b7006e

introduce goto-type for inlay hints

9554c0f

resolve snapshots

813ba0d

fixup

13fecff

Gankra added the server Related to the LSP server label Nov 20, 2025

Gankra requested a review from carljm as a code owner November 20, 2025 05:07

Gankra added the ty Multi-file analysis & type inference label Nov 20, 2025

Gankra requested review from AlexWaygood, MichaReiser, dcreager and sharkdp as code owners November 20, 2025 05:07

Gankra commented Nov 20, 2025

View reviewed changes

crates/ty_python_semantic/src/types/display.rs Outdated Show resolved Hide resolved

Gankra commented Nov 20, 2025

View reviewed changes

MichaReiser reviewed Nov 20, 2025

View reviewed changes

Show better details in inlay hint tests

89ca8c3

MichaReiser approved these changes Nov 20, 2025

View reviewed changes

AlexWaygood reviewed Nov 20, 2025

View reviewed changes

proper typeshed filter

e4695a2

help

6bbea1a

Gankra merged commit 416e226 into main Nov 20, 2025
40 checks passed

Gankra deleted the gankra/type-print branch November 20, 2025 14:40

This was referenced Nov 20, 2025

[ty] Support inlay hint type hint location #21505

Closed

Support goto definition on inlay hints astral-sh/ty#1078

Closed

AlexWaygood mentioned this pull request Nov 20, 2025

[ty] Add more TypeDetails to the display code #21541

Merged

		f.with_detail(TypeDetail::Type(Type::ClassLiteral(self.class)))
		.write_str(self.class.name(self.db))?;

	f.write_str("Literal[")?;
	f.with_detail(TypeDetail::Type(Type::SpecialForm(SpecialFormType::Literal))).write_str("Literal")?;
	f.write_char('[')?;

[ty] Implement goto-type for inlay type hints #21533

[ty] Implement goto-type for inlay type hints #21533

Conversation

Gankra commented Nov 20, 2025

Uh oh!

Gankra commented Nov 20, 2025

Uh oh!

astral-sh-bot bot commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Diagnostic diff on typing conformance tests

Uh oh!

Gankra Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

astral-sh-bot bot commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

mypy_primer results

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MichaReiser left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Gankra commented Nov 20, 2025

Uh oh!

AlexWaygood left a comment

Choose a reason for hiding this comment

Uh oh!

AlexWaygood Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlexWaygood Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlexWaygood commented Nov 20, 2025

Uh oh!

Gankra commented Nov 20, 2025

Uh oh!

Gankra commented Nov 20, 2025

Uh oh!

Gankra commented Nov 20, 2025

Uh oh!

Uh oh!

MatthewMckee4 commented Nov 20, 2025

Uh oh!

Reviewers

Assignees

Labels

astral-sh-bot bot commented Nov 20, 2025 •

edited

Loading

Gankra Nov 20, 2025 •

edited

Loading

astral-sh-bot bot commented Nov 20, 2025 •

edited

Loading

`mypy_primer` results

AlexWaygood Nov 20, 2025 •

edited

Loading

AlexWaygood Nov 20, 2025 •

edited

Loading