Typing, modern tooling & testing

Python's type system arrived later than TypeScript's and works the same way in the part that matters. Annotations are erased at runtime and checked by a separate tool. What differs is that Python also has a first-class runtime validation story, and you will use both.

The rosetta

The important one is Protocol. It is structural, exactly like a TypeScript interface. A class satisfies it by having the right members, no inheritance, no registration.

from typing import Protocol
class Closeable(Protocol):
    def close(self) -> None: ...
class Socket:
    def close(self) -> None:
        print("socket closed")
def shutdown(resource: Closeable) -> None:
    resource.close()
shutdown(Socket())     # no inheritance, no registration — structural

Pydantic is Zod, not TypeScript

Static hints cover your own code. Anything crossing a trust boundary, an HTTP body, a config file, an LLM response, needs runtime validation. Pydantic v2 generates a validator from the same class you would have written anyway.

from pydantic import BaseModel, Field, ValidationError
class User(BaseModel):
    id: int
    name: str = Field(min_length=1)
    age: int = Field(ge=0)
    tags: list[str] = []
print(User(id="7", name="ada", age=36))    # "7" is coerced to 7
try:
    User(id=1, name="", age=-3)
except ValidationError as e:
    for err in e.errors():
        print(err["loc"], err["msg"])

The first run downloads the Pydantic wheel into the browser, so give it a moment.

The Zod Rosetta

The conceptual flip is this. In Zod you build a schema object, then z.infer pulls the static type out of it. In Pydantic the class is both the static type and the runtime validator. There is nothing to infer.

V2 gives you two things Zod does not. Validation compiled to Rust (pydantic-core), and coercion by default. "7" becomes 7. If you want Zod's strictness, opt in per model with model_config = ConfigDict(strict=True).

Discriminated unions are the pattern you will reach for most, every LLM tool-choice and webhook event envelope is one:

from typing import Annotated, Literal, Union
from pydantic import BaseModel, Field, ValidationError
# z.discriminatedUnion("kind", [Card, DirectDebit])
class Card(BaseModel):
    kind: Literal["card"]
    number: str = Field(pattern=r"^\d{16}$")
class DirectDebit(BaseModel):
    kind: Literal["direct_debit"]
    iban: str
Payment = Annotated[Union[Card, DirectDebit], Field(discriminator="kind")]
class Checkout(BaseModel):
    payment: Payment
# .parse(...) equivalent — throws on invalid input
ok = Checkout.model_validate({"payment": {"kind": "card", "number": "4242424242424242"}})
print(type(ok.payment).__name__, "→", ok.payment)
# .safeParse(...) equivalent — catch instead of checking a success flag
for raw in [{"payment": {"kind": "paypal"}}, {"payment": {"kind": "card", "number": "1234"}}]:
    try:
        Checkout.model_validate(raw)
        print("valid:", raw)
    except ValidationError as e:
        print("invalid:", raw, "→", e.errors()[0]["type"])

The toolchain

uv init myservice && cd myservice
uv add pydantic httpx
uv add --dev pytest ruff pyright
uv run pytest          # creates and syncs the venv on the way

There is no node_modules. uv builds a .venv from a global content-addressed cache, which is why it is fast and why the directory is disposable.

Single-file scripts with PEP 723

npx-style single-file scripts get their own format. A comment block at the top declares the script's dependencies, and uv run builds a throwaway environment for it, no venv to activate, nothing to install first:

# /// script
# requires-python = ">=3.13"
# dependencies = ["httpx"]
# ///
import httpx

print(httpx.get("https://example.com").status_code)

uv run scrape.py   # resolves deps, caches the env, runs, repeatable on any machine

This replaces the pip install -r requirements.txt && source .venv/bin/activate steps for one-off scripts.

Monorepos with uv workspaces

A uv workspace works like pnpm-workspace.yaml. One root manifest pins one lockfile over many packages, with local packages importable from each other by name.

# root pyproject.toml, the pnpm-workspace.yaml analogue
[tool.uv.workspace]
members = ["packages/*", "apps/*"]

[tool.uv.sources]
shared = { workspace = true }   # "link" protocol: resolve shared/ locally, never from PyPI

uv sync --all-packages            # one lockfile, every member installed editable
uv add --package apps/api fastapi # add a dep to one member without cd-ing there
uv run --package worker pytest    # run tests for just one member

Where Turborepo would orchestrate builds across your pnpm workspace, the common Python answer is simpler. Each package's tasks are plain [tool.hatch.envs...]/Makefile targets invoked via uv run --package <member>, the dependency graph comes from the workspace itself.

Ruff replaces ESLint, Prettier, Black and isort

One config block in pyproject.toml, one command in CI:

[tool.ruff]
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B"]   # pycodestyle, pyflakes, isort, pyupgrade, bugbear

[tool.ruff.format]
quote-style = "double"                 # prettier-style knobs live here

ruff check --fix .   # lint + autofix (includes import sorting)
ruff format .        # format, this replaces Black entirely

UP is the rule family worth knowing about. It rewrites pre-3.10 idioms to modern ones (Optional[X] → X | None, %-format → f-string), the equivalent of ESLint's plugin that upgrades your syntax to what your target runtime supports.

pytest

Two things replace most of what Jest gives you.

Fixtures replace beforeEach and manual mock wiring. A fixture is a function; requesting it by parameter name is the injection.

@pytest.mark.parametrize is test.each, with every case reported as its own test.

import pytest


@pytest.fixture
def db():
    conn = connect(":memory:")
    yield conn          # everything after yield is teardown
    conn.close()


def test_insert(db):    # requested by name
    assert insert(db, "ada") == 1


@pytest.mark.parametrize("value,expected", [(0, "zero"), (1, "one"), (-1, "negative")])
def test_describe(value, expected):
    assert describe(value) == expected

Assertions are plain assert. pytest rewrites the bytecode to produce the diff, so there is no expect(...).toEqual(...) vocabulary to learn.

Kata

Validate at the boundary, the way you would with a Zod schema.

from pydantic import BaseModel, ValidationError
class Order(BaseModel):
    sku: str
    quantity: int
    currency: str
    # TODO: quantity >= 1
    # TODO: normalise sku to uppercase
    # TODO: reject currencies outside {"USD", "EUR", "GBP"}