Modern Python tooling

Working code is only useful when another person—or a deployment server—can run it reliably.

Modern Python tools make the project repeatable. They record its dependencies, check common mistakes, run tests, and stop broken changes before they enter the repository.

Why this matters

An AI application may work on your laptop and fail in continuous integration or production because a package version changed, a type was wrong, or a previously working behaviour broke.

These tools catch different parts of that problem early, when a fix is cheaper and easier to understand.

The intuition

None of these tools make an idea smarter. They catch mechanical mistakes you can describe in advance: an unused import, a mismatched type, a broken assertion, or an environment that cannot be reproduced.

How it works

uv manages your project’s Python version, its isolated virtual environmentVirtual environmentAn isolated set of installed Python packages, separate from your system Python and from any other project's environment, so two projects that need different versions of the same library never conflict. uv creates and manages one per project automatically., and its dependencies — the jobs that used to need four or five separate tools:

uv init my-project        # creates pyproject.toml, a .venv, and a first commit-ready layout
uv add requests           # adds requests to pyproject.toml, resolves it, updates uv.lock
uv run python pipeline.py # runs inside the project's own isolated environment, no "activate" step

The file that matters most here is uv.lock. pyproject.toml says “I need requests, roughly this version range” — that’s still an intentional range, so you can pick up compatible patches. uv.lock says exactly which version, and every one of its dependencies’ exact versions, were actually resolved. Commit both. uv sync (or uv run, which syncs first) installs from the lockfile, not the range — so a fresh checkout on any machine gets the identical set of packages the lockfile recorded, which is precisely what the hook’s bug was missing.

ruff reads your code and reports style and correctness issues without running any of it — that’s what makes it a linterLinterA tool that checks source code for style violations, common bugs, and dead code — like an unused import — by reading and analysing the code, without running it. ruff is a linter (and formatter) for Python; it does not check whether your types line up (mypy's job) or whether your code produces the right result (a test's job). rather than a test:

import os          # never used below
import requests

def fetch(url):
    resp = requests.get(url)
    return resp.json()

$ ruff check pipeline.py
pipeline.py:1:8: F401 [*] `os` imported but unused
Found 1 error.
[*] 1 fixable with the `--fix` option.

F401 is ruff’s actual rule code for an unused import — not a generic warning, a specific, addressable finding. ruff format pipeline.py handles the layout side separately (spacing, quote style, line length) the same way black used to, in the same tool.

mypy checks that the types you promised in your type hintsType hintsOptional annotations that declare the expected types of variables, arguments and return values (e.g. `def f(x: int) -> str`). Python does not enforce them at runtime, but tools like mypy, your editor, and libraries like Pydantic read them to catch bugs before the code ever runs. actually line up, without running the code either:

def apply_discount(price: float, pct: float) -> float:
    return price - pct

apply_discount(100, "10")   # a string where a float was promised

$ mypy pricing.py
pricing.py:4: error: Argument 2 to "apply_discount" has incompatible type "str"; expected "float"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

This is exactly the shape of bug type hints exist to catch (Chapter 00-01) — except now something actually checks it for you, instead of it only being a note for a human reader.

pytest is the one tool here that actually runs your code, to check it produces what you said it would. You’ll run it for real in a moment.

A small test you can copy

def estimate_cost(tokens: int, price_per_token: float) -> float:
    return tokens * price_per_token


def test_estimate_cost():
    result = estimate_cost(1_000, 0.000_002)
    assert result == 0.002

Try changing the expected result to 0.02. A useful test should now fail and show the two different values.

pre-commit ties all of this together. A .pre-commit-config.yaml lists the hooks a project runs automatically, right before git creates a commit:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.4
    hooks:
      - id: ruff
      - id: ruff-format
  - repo: local
    hooks:
      - id: pytest
        name: pytest
        entry: uv run pytest
        language: system
        pass_filenames: false

pre-commit install (run once per clone) wires this into git itself — after that, git commit runs every listed hook first:

$ git commit -m "add discount logic"
ruff.....................................................................Passed
ruff-format...............................................................Passed
pytest....................................................................Failed
- hook id: pytest
- exit code: 1

FAILED test_pricing.py::test_apply_discount - assert 90.0 == 91.0

The commit did not happen. Nothing reached the repository’s history. You fix the failing assertion or the code it’s checking, and try again — this is the loop the diagram above is showing.

A worked example

Trace one small change through the whole gate. You write:

import os
def apply_discount(price: float, pct: float) -> float:
    return price - pct

with a test file asserting apply_discount(100, 10) == 90, and you run git commit. Walk it stage by stage:

You delete the unused import os and commit again. This time ruff passes, mypy passes (the types genuinely line up), and pytest actually executes apply_discount(100, 10) and gets 90 — matching the assertion. All three stages pass, in increasing order of cost, and only then does the commit happen. Notice what each stage could and couldn’t have caught: if the test had asserted == 91 by mistake, ruff and mypy would both have passed cleanly — neither of them runs the code, so neither could have known the expected number was wrong. Only pytest, the one stage that executes anything, would have caught it.

Try it

pytest and mypy are themselves just Python packages, so — unlike uv, ruff, and pre-commit, which are project-management tools that need a real project on a real filesystem — you can run them for real, right here, in the browser.

First, a genuine pytest run against a bug, then fix it and rerun:

Next, a genuine mypy run against a real type mistake:

Production reality

The course you are reading right now runs exactly this pattern: a Quality CI workflow runs a typecheck, a manifest check, and a full Playwright/axe/Lighthouse suite on every push — and, as of the previous chapter, the site’s own deploy is gated on that workflow passing. Nothing about that is special to this project; it is the same gate this chapter describes, just running in CI instead of (or in addition to) on your own machine.

A few things worth knowing before you rely on this in a real team:

• Lockfiles matter most exactly when you need to move fast. A security patch to a dependency needs to reach every environment — laptops, CI, production — identically and quickly. Without a lockfile, “it’s fixed in CI” and “it’s fixed in production” can silently mean two different sets of installed packages.
• ruff is fast enough that teams run it on save, not just before commit — it reads code, it doesn’t execute it, so there’s very little to wait for. That speed is why it replaced several older, slower tools that did similar jobs one at a time.
• Retrofitting mypy onto an old, untyped codebase is a real project, not a switch you flip. Most teams start it on new code only, or run it in a mode that doesn’t yet demand every function be annotated, and tighten the rules gradually. Trying to type an entire large existing codebase in one pass is usually a mistake — it stalls, and nobody finishes it.
• A green pipeline is not the same as correct code. ruff, mypy, and pytest can all pass while the code still does the wrong thing — pytest only checks what you actually wrote a test for, and mypy only checks where you actually wrote a type hint. These tools raise the floor under mistakes you can name in advance; they do not check whether you understood the problem correctly.

Common mistakes

Exercises

requests==2.32.3

def test_divide_by_zero():
    assert divide(10, 0) == 0   # or whatever behaviour you decide is correct

def divide(a, b):
    if b == 0:
        return 0
    return a / b

Knowledge check

Practice activity

def estimate_cost(tokens, price_per_token):
    return tokens * price_per_token

def estimate_cost(tokens: int, price_per_token: float) -> float:
    return tokens * price_per_token


def test_estimate_cost():
    assert estimate_cost(1_000, 0.000_002) == 0.002


def test_zero_tokens_cost_nothing():
    assert estimate_cost(0, 0.000_002) == 0.0

Key takeaways

Flashcards

One-page sketchnote summary

uv sync
uv run ruff check .
uv run mypy src
uv run pytest

Resources