Add static type information

[Technologicat]

While useful, this is difficult to do for features like curry and with continuations.

Some selected parts of unpythonic could be eventually gradually typed using mypy, but this is not being worked on at the moment.

See #8 for context.

If anyone feels like working on this, in principle I'm open to suitably scoped PRs adding type signatures to parts of the library (using Python's type annotations) - but perhaps post a comment here for discussion first, to converge on a definition for "suitably scoped".

[Technologicat]

Now that we have @typed to perform dispatching and yell if the argument types are wrong, that could synergize:

• Get runtime type checking with compact syntax, allowing us to delete some if not isinstance() ... raise TypeError ... boilerplate.
• That compact syntax is the type annotation syntax used by mypy, so allow static type checking for no extra effort.

Investigate in 0.14.3. Maybe do it for a few select modules such as unpythonic.it and unpythonic.fold.

[Technologicat]

Forgot to mention, this allows us to delete not only the isinstance boilerplate that performs runtime type checking, but also the automated tests for individual instances of that boilerplate. The @typed machinery is tested centrally, so we can rely on it.

This is one reason it's useful to have a gradual typing mechanism (using some kind of type annotations) as a language feature in a dynamically typed language... sure, one can achieve the same effect in any Turing-complete language even without such a mechanism, as Python programs often do, but having a mechanism to compactly express this very common intent makes programs shorter, and more readable.

(Having language support reduces the impedance mismatch between what the source code says and what the programmer means. Arguably, the types are part of the call signature, so the logical place to express the type check is as part of the function's API; not hidden inside the function body so one has to look at the implementation (or at the docstring).)

[Technologicat]

Status update (2026-04-24, post-2.1.0):

Type annotations have been added across 32 of 34 pure-Python modules during the 2.1.0 modernization. The remaining gap is roughly the deeply Lispy parts (curry, TCO, conditions/restarts) where the typing question is more subtle than elsewhere.

The project position isn't that curry is unannotable — more that its correct signature depends on the partially-applied state of the call, which standard type systems don't easily express. Worth revisiting with ParamSpec / Concatenate / overloads when we next touch that area.

Keeping this open at ∞ to track the remaining parts and related work (e.g. ties to the @generic dispatch machinery, cf. #99).

— Claude (Opus 4.7)