python-type-safety

Python Type Safety (3.13+ / 3.14+)

Modern Python type safety using the Astral toolchain: ty for type checking and language server, ruff for linting (including annotation enforcement), and uv for package management. All examples target Python 3.13+ with 3.14 deferred annotations as the default.

Toolchain

Tool	Role	Install
ty	Type checker + LSP (10-100x faster than mypy)	uv tool install ty@latest
ruff	Linter + formatter (replaces flake8, black, isort)	uv tool install ruff
uv	Package manager + env management	astral.sh/uv

ty is the type checker from Astral (the creators of ruff and uv). It is written in Rust, provides a full language server (LSP) with code navigation, completions, and inlay hints, and supports advanced features like intersection types, reachability analysis, and gradual typing guarantees.

Key Python Version Features

Python 3.12

• PEP 695 — Type parameter syntax: def first[T](items: list[T]) -> T:
• PEP 695 — type statement for aliases: type Point = tuple[float, float]

Python 3.13

• PEP 696 — TypeVar/ParamSpec/TypeVarTuple defaults: class Box[T = int]:
• PEP 742 — TypeIs for proper bidirectional type narrowing
• PEP 705 — ReadOnly for TypedDict items
• PEP 702 — warnings.deprecated() decorator with type system support

Python 3.14

• PEP 649/749 — Deferred evaluation of annotations (no more from __future__ import annotations, no more forward reference strings)
• PEP 758 — except and except* expressions may omit brackets

Fundamental Patterns

Pattern 1: Annotate All Public Signatures

Every public function, method, and class should have type annotations. Use native generics everywhere (no typing.List, typing.Dict, etc. — those are ancient history).

from pydantic import BaseModel


class User(BaseModel):
    id: str
    name: str
    email: str | None = None


class UserRepository:
    def __init__(self, db: Database) -> None:
        self._db = db

    async def find_by_id(self, user_id: str) -> User | None:
        ...

    async def find_by_email(self, email: str) -> User | None:
        ...

    async def save(self, user: User) -> User:
        ...