Use type keyword when defining types

[hoodmane]

This makes type introspection a bit more complicated but it has the advantage that the name of the type is preserved so in errors you'll see the type name instead of the expansion of the type. It also handles forward references automatically and has several other small ergonomics benefits.

[github-actions]

Documentation Preview
Preview documentation for PR #647.
Last Updated: 2026-08-09 16:23 UTC

[antocuni]

This is the summary of a private conversation which I had with @hoodmane .
I'm not convinced about the utility of using the type statement: it seems to add a (tiny) bit of complexity for no clear gains.
The most compelling argument for it is "better error messages", however for the trivial types that we use, it doesn't seem to be the case.
E.g.:

from typing import Literal

A = Literal['a', 'b', 'c']
type B = Literal['a', 'b', 'c']

def foo() -> A:
    return 'd'

def bar() -> B:
    return 'd'

gives:

a.py:7: error: Incompatible return value type (got "Literal['d']", expected "Literal['a', 'b', 'c']")  [return-value]
a.py:10: error: Incompatible return value type (got "Literal['d']", expected "Literal['a', 'b', 'c']")  [return-value]

i.e., exact same error in both cases.

Another thing to keep in mind is that eventually we want to compile this source code with spy itself, and it's unclear if/what the type statement should do in spy.

At the same time, the PR is not doing anything harmful and it's "correct".
So, I'm -0.5 to merge, but I can be convinced otherwise if anybody has a strong "+1" for it.

I'll leave it open for a while to give people time to comment if they want.