type-python 1.0.0rc1

A statically-typed authoring language that compiles to standard Python

TypePython

Write richer types in .tpy. Ship plain .py + .pyi.

---

TypePython is a typed dialect of Python that compiles to standard .py + .pyi. It brings author-time TypeScript-class ergonomics — sealed classes, exhaustive match, strict null checks, unknown, interface, data class — to a language whose output runs anywhere CPython runs.

Those stronger checks are enforced while authoring .tpy; emitted artifacts remain standard Python and do not transfer every TypePython-only constraint to downstream checkers.

No custom runtime. No required per-checker plugin for emitted output. No vendor lock-in.

Status: Core v1.0 RC (v1.0.0-rc.1). Core syntax, config, init/check/ build/clean/verify, Core checker semantics, diagnostic code identity, and emitted .py/.pyi compatibility are the release-candidate surfaces. Supported DX, Experimental opt-in, and Roadmap / prototype features remain outside the Core v1.0 RC compatibility promise and are tracked separately in the Experimental Feature Registry. This is not a full product-wide v1.0 RC: editor UX, VS Code packaging, watch, migration heuristics, and research slices remain outside the stable v1.0 promise until their own gates are complete. Bug reports and contributions are very welcome.

Install

pip install type-python
typepython init --dir hello && cd hello
typepython check --project .
typepython build --project .

You now have .typepython/build/ with .py + .pyi + py.typed ready for any Python interpreter, IDE, or downstream type checker.

• Wheels are prebuilt for Windows AMD64, macOS x86_64, macOS arm64, and Linux x86_64. Other platforms fall back to source and need Rust + cargo. Wheels are tagged py3-none-<platform> because the bundled Rust CLI is platform-specific while the Python wrapper is ABI-independent.
• Python: the package bridge supports 3.9+; generated projects target Python 3.10 through 3.14.

See it in 15 lines

# src/app/expr.tpy

sealed class Expr:
    pass

class Num(Expr):  value: int
class Add(Expr):  left: Expr; right: Expr
class Neg(Expr):  operand: Expr

def evaluate(expr: Expr) -> int:
    match expr:
        case Num(value=v):           return v
        case Add(left=l, right=r):   return evaluate(l) + evaluate(r)
        case Neg(operand=o):         return -evaluate(o)
    # No default branch needed — the compiler proves the match is exhaustive.
    # Add a fourth subclass and TypePython tells you exactly where to update.

typepython build lowers that to ordinary Python and writes a matching .pyi that any modern type checker can consume — no TypePython runtime required. The exhaustiveness proof happens before emit; downstream tools see a normal Python class hierarchy.

What you write vs. what ships

You write (.tpy)	TypePython emits (.py / .pyi)
interface Drawable:	class Drawable(Protocol):
data class User:	@dataclass class User:
sealed class Expr:	ordinary class + tpy:sealed marker
overload def parse(...)	@overload def parse(...)
typealias Pair[T] = tuple[T, T]	T = TypeVar("T") + Pair: TypeAlias = tuple[T, T]
def first[T](xs: list[T]) -> T:	inline generic on 3.13+, TypeVar-based on 3.10 – 3.12
unsafe: eval(expr)	valid Python, marker erased — runtime behavior preserved
unknown (must narrow before use)	object in .pyi
Partial[Config] / Pick[Config, …]	expanded TypedDict shapes (PEP 655 / 705)

Why not just mypy / pyright / PEP 695?

The comparison below is about .tpy authoring inside the package checked by TypePython. Emitted .py / .pyi remain standard Python typing, so external consumers do not automatically inherit TypePython-only constraints such as sealed exhaustiveness or unknown strictness.

Capability	mypy strict	pyright strict	PEP 695 .py	TypePython .tpy authoring
sealed class + compiler-proved exhaustiveness	—	—	—	✅
unknown — safe dynamic boundary, must narrow	—	—	—	✅
unsafe: audit fence for eval / exec / setattr	—	—	—	✅
First-class interface / data class / typealias	via	via	via	keyword
Inline generics def f[T] on any target ≥ 3.10	3.12+	3.12+	3.12+	✅
TypedDict transforms (Partial, Pick, Readonly…)	—	—	—	✅
Output consumed by mypy / pyright / basedpyright / ty unmodified	N/A	N/A	✅	✅

TypePython doesn't replace those checkers. It sits one step earlier: you author in .tpy, the compiler emits standard typed Python that those tools then consume normally.

The strongest TypePython guarantees are author-time checks. Emitted artifacts remain standard Python: sealed exhaustiveness, unknown strictness, and unsafe: fences are enforced by TypePython during authoring, but external checkers see the portable .py / .pyi boundary. Carrying TypePython-only semantics across that boundary requires an opt-in sidecar, checker plugin, or TypePython-aware consumer.

What you also get

• Rust-native, incremental compiler — public-API fingerprints skip downstream rechecks when only a body changes.
• Full toolchain — init, check, build, watch, clean, verify, compat, api-diff, type-health, migrate, lsp.
• Supported DX LSP server — hover, go to definition, references, rename, completions, signature help, real-time diagnostics, and code-action quick fixes. The repository includes a source-installable VS Code extension plus copy-paste setup for Neovim, Helix, Sublime Text, and Emacs. Editor UX and extension packaging are still outside the Core v1.0 RC compatibility promise.
• Standard, portable output — emitted .py + .pyi work with mypy, pyright, and ty out of the box. PEP 561 py.typed is written automatically.
• Mixed projects — .tpy, .py, and .pyi live in the same source tree. .py is pass-through; .pyi is stub-authoritative.

For library authors

Five commands aimed at people who publish typed Python:

typepython build       --project .
typepython verify      --project . --checker-preset all
typepython compat      --project . --profile library-portable
typepython api-diff    dist/previous.whl .typepython/build
typepython type-health --project . --fail-under 85

These catch missing/stale py.typed, wheel ↔ build-tree drift, multi-checker portability gaps, public-API drift between releases, and runtime-annotation hazards for frameworks that introspect annotations. They validate the standard published surface; they do not make ordinary downstream .py checkers enforce TypePython-only facts.

Documentation

• Getting Started
• Syntax Guide
• Type System
• Configuration
• CLI Reference
• Diagnostics (TPYxxxx codes)
• LSP Integration
• Interoperability
• Migration Guide
• Framework Adapters
• Beta Readiness
• Feature Status
• Experimental Feature Registry
• Language Spec v1

Links

• Repository
• Issues / bug reports
• Contributing
• License (MIT)