Hands-on lab — Day 75: Static Typing with mypy

"""The fixed catalogue: identical behaviour on the tested paths, clean under
mypy --strict.

Compare this file with starter/catalog.py line by line. Four things changed:

  1. describe() now handles the None the lookup can return, so the checker
     can narrow `Model | None` down to `Model` before the attributes are read.
  2. split_cost() uses floor division, so the value handed to estimate_cost
     really is an int.
  3. format_price() is annotated, so strict mode accepts both the definition
     and the calls to it.
  4. load_settings() checks the loaded object at the boundary instead of
     passing Any through, so the returned dict genuinely is dict[str, float].

Note what did NOT change: the tests. Every test in test_catalog.py passes
before and after. The bugs were never on a tested path — which is exactly why
a checker is not a substitute for tests, and tests are not a substitute for a
checker.
"""

from __future__ import annotations

import json
from dataclasses import dataclass


@dataclass(frozen=True)
class Model:
    """One row of the catalogue."""

    name: str
    context_tokens: int
    price_per_million_input: float


CATALOG: dict[str, Model] = {
    "small": Model(name="small", context_tokens=8_000, price_per_million_input=0.25),
    "medium": Model(name="medium", context_tokens=128_000, price_per_million_input=3.0),
    "large": Model(name="large", context_tokens=200_000, price_per_million_input=15.0),
}


def find_model(name: str) -> Model | None:
    """Look a model up by name, or return None when the name is unknown."""
    return CATALOG.get(name)


def describe(name: str) -> str:
    """One-line human summary of a model.

    FIX A. The early return is the narrowing. After `if model is None:
    return ...`, mypy knows that on every remaining line `model` is a Model,
    not a `Model | None`, so reading .name and .context_tokens is safe. The
    guard is for the reader, the runtime and the checker at once.
    """
    model = find_model(name)
    if model is None:
        return f"{name}: unknown model"
    return f"{model.name}: {model.context_tokens:,} token context"


def estimate_cost(name: str, tokens: int) -> float:
    """Dollar cost of sending `tokens` input tokens to `name`."""
    model = find_model(name)
    if model is None:
        raise KeyError(name)
    return tokens / 1_000_000 * model.price_per_million_input


def split_cost(name: str, tokens: int, parts: int) -> float:
    """Cost of one part when a job of `tokens` tokens is split into `parts`.

    FIX B. Floor division keeps the value an int, which is what a token count
    is. `/` would have produced a float, and a fractional token is not a
    thing that exists.
    """
    per_part = tokens // parts
    return estimate_cost(name, per_part)


def format_price(value: float) -> str:
    """Format a price in dollars. FIX: annotated, so strict mode is happy."""
    return f"${value:.2f}"


def price_line(name: str) -> str:
    """Human-readable price for one model."""
    model = find_model(name)
    if model is None:
        return f"{name}: unknown model"
    return f"{name}: {format_price(model.price_per_million_input)} per million tokens"


def load_settings(path: str) -> dict[str, float]:
    """Read numeric settings from a JSON file.

    FIX: json.load returns Any, and returning Any from a function that
    promises dict[str, float] is a promise you have not kept. Binding the
    result to a name annotated `object` throws away the Any immediately, and
    then the isinstance check narrows it to a dict the checker will let you
    iterate. The conversion to float is the value check that no type system
    can do for you.
    """
    with open(path, encoding="utf-8") as handle:
        raw: object = json.load(handle)
    if not isinstance(raw, dict):
        raise ValueError(f"{path}: expected a JSON object at the top level")
    settings: dict[str, float] = {}
    for key, value in raw.items():
        if not isinstance(value, (int, float)) or isinstance(value, bool):
            raise ValueError(f"{path}: setting {key!r} is not a number")
        settings[str(key)] = float(value)
    return settings

"""A deterministic tour of the fixed catalogue.

    python3 examples/demo.py

Every line printed here is fixed text or arithmetic — no clocks, no random
numbers, no memory addresses — so it matches expected-output/sample-run.txt
character for character.
"""

from __future__ import annotations

from pathlib import Path

import catalog

HERE = Path(__file__).resolve().parent


def main() -> None:
    print("1. The lookup that can fail")
    print("---------------------------")
    print(f"find_model('small'):    {catalog.find_model('small')}")
    print(f"find_model('enormous'): {catalog.find_model('enormous')}")
    print()

    print("2. describe() — the function the tests never asked about")
    print("--------------------------------------------------------")
    print(f"describe('small'):    {catalog.describe('small')}")
    print(f"describe('large'):    {catalog.describe('large')}")
    print(f"describe('enormous'): {catalog.describe('enormous')}")
    print("  ^ the buggy version raised AttributeError on that last line")
    print()

    print("3. split_cost() — an int really is an int now")
    print("---------------------------------------------")
    print(f"split_cost('medium', 1000000, 2): {catalog.split_cost('medium', 1_000_000, 2)}")
    print(f"split_cost('medium', 1000000, 3): {catalog.split_cost('medium', 1_000_000, 3)}")
    print("  ^ 1000000 // 3 is 333333 tokens; 1000000 / 3 would have been 333333.33...")
    print()

    print("4. price_line() — an annotated helper, callable under strict")
    print("------------------------------------------------------------")
    for name in ("small", "medium", "large"):
        print(f"  {catalog.price_line(name)}")
    print(f"  {catalog.price_line('enormous')}")
    print()

    print("5. load_settings() — checked at the boundary, not merely annotated")
    print("------------------------------------------------------------------")
    settings = catalog.load_settings(str(HERE / "settings.json"))
    for key in sorted(settings):
        print(f"  {key} = {settings[key]!r}")
    print("  every value is a real float, because the loader converted it")


if __name__ == "__main__":
    main()

# A real mypy configuration, and the file mypy looks for by default.
#
# Run it explicitly from the lab directory:
#
#     python3 -m mypy --config-file examples/pyproject.toml examples/catalog.py
#
# In a real project this file sits at the repository root and you simply run
# `mypy .`; mypy finds the [tool.mypy] table on its own. It lives in
# examples/ here so the lab can point at it without changing anything above
# this directory.

[tool.mypy]
# The one setting that matters most: what Python version's rules to apply.
python_version = "3.10"

# `strict` is a bundle. Turning it on enables about a dozen individual flags,
# including the three spelled out below. Those three are written out anyway
# because they are the ones worth understanding by name.
strict = true

# Every function must be annotated. This is the flag that stops a codebase
# from quietly drifting back to unchecked, because an unannotated function's
# body is not checked at all.
disallow_untyped_defs = true

# Returning Any from a function that promises a real type is a broken
# promise. This is what catches json.load() flowing straight out of a loader.
warn_return_any = true

# A `# type: ignore` that no longer suppresses anything becomes an error.
# Without this, ignores accumulate for years and nobody ever removes one.
warn_unused_ignores = true

# Report unreachable code — usually a sign a narrowing guard is wrong.
warn_unreachable = true

# Make error codes visible in every message. They are on by default in
# recent mypy; setting it explicitly means the output does not depend on the
# version somebody happens to have installed.
show_error_codes = true

# --- Per-module overrides ---------------------------------------------------
# This is how you adopt mypy in an existing codebase: strict everywhere, with
# named exceptions that shrink over time. The list is a work queue, and the
# fact that it is checked into the repository is what makes it one.
#
# The module below does not exist in this lab; it is here to show the shape.
# A real entry names a real package, and a comment says who will remove it.

[[tool.mypy.overrides]]
module = "legacy_importer.*"
disallow_untyped_defs = false
warn_return_any = false

# Third-party packages that ship no type information at all. Without an
# override, mypy reports [import-untyped] for each one. Silencing it is
# honest ONLY when you have checked that no stubs exist — see the lesson.

[[tool.mypy.overrides]]
module = "some_untyped_dependency.*"
ignore_missing_imports = true

{
  "temperature": 0.2,
  "top_p": 0.95,
  "max_output_tokens": 1024
}

"""The same suite, run against the fixed catalogue.

The first eight tests are character for character the ones in
starter/test_catalog.py, and that is the point: fixing both type errors
changed no observable behaviour on any path a test walks. They were green
before and are green after.

The ninth test is new. It asks the question the old suite never asked — what
does describe() do with a name that is not in the catalogue? — and it is the
test you would only think to write after a checker pointed at that line.
"""

import catalog


def test_find_known_model() -> None:
    model = catalog.find_model("small")
    assert model is not None
    assert model.context_tokens == 8_000


def test_find_unknown_model_returns_none() -> None:
    assert catalog.find_model("enormous") is None


def test_describe_known_model() -> None:
    assert catalog.describe("small") == "small: 8,000 token context"


def test_describe_large_model() -> None:
    assert catalog.describe("large") == "large: 200,000 token context"


def test_estimate_cost_of_one_million_tokens() -> None:
    assert catalog.estimate_cost("medium", 1_000_000) == 3.0


def test_estimate_cost_rejects_unknown_model() -> None:
    try:
        catalog.estimate_cost("enormous", 1_000)
    except KeyError:
        return
    raise AssertionError("expected a KeyError for an unknown model")


def test_split_cost_divides_evenly() -> None:
    assert catalog.split_cost("medium", 1_000_000, 2) == 1.5


def test_price_line() -> None:
    assert catalog.price_line("large") == "large: $15.00 per million tokens"


def test_describe_unknown_model_no_longer_crashes() -> None:
    assert catalog.describe("enormous") == "enormous: unknown model"

"""A tour of the type system, every line of which passes mypy --strict.

This file is a reference, not an exercise. Read it beside the lesson: each
section is one construct, written the way you would actually use it. Run it
to see the values, and check it to see that the annotations hold:

    python3 examples/typing_tour.py
    python3 -m mypy --strict examples/typing_tour.py
"""

from __future__ import annotations

from typing import Final, Literal, NewType, Protocol, TypedDict, TypeVar, cast

# --- Builtin generics -------------------------------------------------------
# list[int], dict[str, float], tuple[int, ...] are the modern spelling. The
# capitalised List/Dict imports from typing mean the same thing and belong to
# older code.

Scores = dict[str, list[float]]  # a type alias is just a name for a type


def mean(values: list[float]) -> float:
    """Arithmetic mean. Empty input is a value question, not a type question."""
    if not values:
        raise ValueError("mean of no values")
    return sum(values) / len(values)


def best_suite(scores: Scores) -> tuple[str, float]:
    """Return the suite with the highest mean score, and that mean."""
    ranked = sorted(((name, mean(vals)) for name, vals in scores.items()), key=lambda pair: -pair[1])
    return ranked[0]


# --- Optional, and the narrowing that makes it usable -----------------------
# `X | None` is the modern spelling of Optional[X]. They are the same type.


def first_word(text: str | None) -> str:
    """The first word of `text`, or a placeholder when there is no text.

    The two guards are the whole idea. Before them mypy knows `text` is
    `str | None` and refuses `.split()`. After `if text is None: return ...`
    it knows `text` is `str` on every remaining line.
    """
    if text is None:
        return "(nothing)"
    words = text.split()
    if not words:
        return "(blank)"
    return words[0]


def parse_port(raw: object) -> int:
    """Narrowing with isinstance rather than a None check.

    `raw` arrives as `object`, which mypy will let you do almost nothing
    with. Each isinstance branch narrows it to something usable.
    """
    if isinstance(raw, int) and not isinstance(raw, bool):
        return raw
    if isinstance(raw, str):
        return int(raw)
    raise TypeError(f"cannot read a port from {type(raw).__name__}")


# --- Union of two real types ------------------------------------------------


def token_count(item: str | list[str]) -> int:
    """Accept either a string or a list of strings and count the words."""
    if isinstance(item, str):
        return len(item.split())
    return sum(len(part.split()) for part in item)


# --- Literal ----------------------------------------------------------------
# Literal pins a value to a fixed set. A typo in a call site becomes an error
# instead of a shrug at runtime.

Mode = Literal["semantic", "keyword"]


def search_label(mode: Mode) -> str:
    return f"search mode: {mode}"


# --- TypedDict --------------------------------------------------------------
# For JSON-shaped data you must keep as a dict, TypedDict says which keys
# exist and what each holds.


class RunRecord(TypedDict):
    suite: str
    passed: int
    failed: int


def pass_rate(record: RunRecord) -> float:
    total = record["passed"] + record["failed"]
    if total == 0:
        return 0.0
    return record["passed"] / total


# --- Final and NewType ------------------------------------------------------
# Final says "this name is never rebound". NewType makes a distinct type out
# of an existing one, so two things that are both strings stop being
# interchangeable.

MAX_RETRIES: Final = 3

UserId = NewType("UserId", str)
SessionId = NewType("SessionId", str)


def audit_line(user: UserId, session: SessionId) -> str:
    """Both parameters are strings at runtime, and distinct types to mypy.

    Call this with the arguments the wrong way round and mypy reports it,
    which a plain `(str, str)` signature could never do.
    """
    return f"user={user} session={session}"


# --- TypeVar and generic functions ------------------------------------------
# A TypeVar is a placeholder that means "whatever type came in, that same type
# goes out" — which `Any` cannot express, because Any forgets.

T = TypeVar("T")


def first_or(items: list[T], fallback: T) -> T:
    """Return the first item, or the fallback when the list is empty."""
    return items[0] if items else fallback


# --- Protocol: structural typing --------------------------------------------
# A Protocol describes a shape. Anything with matching methods satisfies it,
# with no inheritance and no registration — which is exactly what you want
# for an injected dependency.


class Clock(Protocol):
    """Anything that can tell you the time, in seconds, as a float."""

    def now(self) -> float: ...


class FrozenClock:
    """A test double. It inherits from nothing and mentions Clock nowhere."""

    def __init__(self, value: float) -> None:
        self.value = value

    def now(self) -> float:
        return self.value


def stamp(clock: Clock, message: str) -> str:
    """Depends on the shape, not on a base class."""
    return f"[{clock.now():.1f}] {message}"


# --- cast: the escape hatch, used sparingly ---------------------------------


def config_name(config: dict[str, object]) -> str:
    """cast asserts a type to the checker and does NOTHING at runtime.

    The values in this dict are `object`, so mypy will not let you return one
    as a str. `cast` tells it to believe you anyway. It generates no check and
    no conversion — if the value is really an int, the cast succeeds silently
    and the wrongness surfaces somewhere else entirely. Prefer isinstance,
    which narrows AND checks; reach for cast only where you know something
    the checker cannot, and say so in a comment.

    (If you write a cast that mypy could already prove — casting a value it
    has narrowed with isinstance — it tells you so, with [redundant-cast].)
    """
    return cast(str, config["name"])


def main() -> None:
    scores: Scores = {"arithmetic": [0.9, 0.8, 1.0], "geometry": [0.5, 0.6]}
    print(f"mean of arithmetic: {mean(scores['arithmetic']):.4f}")
    print(f"best suite: {best_suite(scores)[0]} at {best_suite(scores)[1]:.4f}")
    print(f"first_word(None): {first_word(None)}")
    print(f"first_word('  '): {first_word('  ')}")
    print(f"first_word('hello there'): {first_word('hello there')}")
    print(f"parse_port('8080'): {parse_port('8080')}")
    print(f"token_count('a b c'): {token_count('a b c')}")
    print(f"token_count(['a b', 'c']): {token_count(['a b', 'c'])}")
    print(f"search_label('keyword'): {search_label('keyword')}")
    record: RunRecord = {"suite": "arithmetic", "passed": 7, "failed": 3}
    print(f"pass_rate: {pass_rate(record):.4f}")
    print(f"MAX_RETRIES: {MAX_RETRIES}")
    print(audit_line(UserId("u-1"), SessionId("s-9")))
    print(f"first_or([], 'fallback'): {first_or([], 'fallback')}")
    print(f"first_or([4, 5], 0): {first_or([4, 5], 0)}")
    print(stamp(FrozenClock(1234.5), "structural typing works"))
    print(f"config_name: {config_name({'name': 'production', 'retries': 3})}")


if __name__ == "__main__":
    main()

lesson_id: D075
day: 75
kind: python-program
languages: [python, bash]
setup_commands:
  - cd labs/sections/programming-with-python/day-075-static-typing-with-mypy
  - python3 -m venv .venv
  - .venv/bin/pip install -r requirements/requirements.txt
  - .venv/bin/mypy --version
  - .venv/bin/pytest --version
run_commands:
  - PYTHONPATH=starter .venv/bin/pytest -q starter/test_catalog.py
  - .venv/bin/mypy starter/catalog.py
  - .venv/bin/mypy --strict starter/catalog.py
  - .venv/bin/mypy starter/untyped_first_run.py
  - .venv/bin/mypy --strict starter/untyped_first_run.py
  - .venv/bin/mypy starter/any_demo.py
  - PYTHONPATH=examples python3 examples/demo.py
  - PYTHONPATH=examples python3 examples/typing_tour.py
  - .venv/bin/mypy --strict examples/catalog.py examples/typing_tour.py
  - .venv/bin/mypy --config-file examples/pyproject.toml examples/catalog.py
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - rm -rf .mypy_cache examples/.mypy_cache starter/.mypy_cache
  - rm -rf .pytest_cache examples/__pycache__ starter/__pycache__
  - 'rm -rf .venv  # optional: removes the lab virtual environment'
  - 'git checkout -- starter/  # optional: reset your work'
requires_network: true
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-19'
executed_on: 'macOS 26.5.1 (Apple Silicon), Python 3.14.0, mypy 2.3.0 (compiled: yes), pytest 9.1.1, bash 3.2.57 — bash tests/run_tests.sh -> 33 checks, 0 failure(s), exit 0. Network is needed once to install mypy and pytest; every command in the lab runs offline afterwards.'

# Dependencies for the Day 075 lab

This lab needs two third-party tools. Both are free and open source, both
install from the Python Package Index with `pip`, and both run entirely on
your machine — nothing here sends code anywhere.

| Package | Pinned version | Why this lab needs it |
| --- | --- | --- |
| `mypy` | `2.3.0` | The static type checker the whole lesson is about. It reads your annotated source without executing it and reports where a value flows somewhere its annotation does not allow. |
| `pytest` | `9.1.1` | The test runner from Days 071–074. This lab needs it because the entire point is the contrast: a green pytest suite over a module mypy immediately rejects. |

Versions are pinned exactly so that error messages, error codes and exit
statuses match the captured output in `expected-output/`. A newer mypy may
reword a message; the bracketed error codes are far more stable, which is why
the test suite greps for the codes rather than the prose.

## Licences

mypy and pytest are both distributed under the MIT licence, stated on each
project's own documentation site (linked from the lesson's source list). Both
are maintained in the open and cost nothing to use, personally or
commercially.

## One-time install

From the lab directory:

```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements/requirements.txt
.venv/bin/mypy --version
.venv/bin/pytest --version
```

Day 43 covered `python3 -m venv` in full; this is the same pattern. The
virtual environment lives in `.venv/` inside the lab, is already excluded
from version control, and can be deleted at any time with `rm -rf .venv`.

## Network

Installing needs the network, once. After that the lab runs completely
offline: mypy analyses local files, pytest runs local tests, and no script
here opens a socket.

## Running without a lab-local environment

If you already have mypy and pytest available — a project virtual environment
you have activated, or a system installation — the test runner will find them
on your `PATH`. You can also point it at specific binaries:

```bash
MYPY=/path/to/mypy PYTEST=/path/to/pytest bash tests/run_tests.sh
```

## Cache directories

mypy writes an incremental cache so repeated runs are fast. Run it by hand and
you get a `.mypy_cache/` directory in whatever folder you ran it from; it is
excluded from version control and safe to delete. The test suite avoids the
question entirely by pointing mypy at a temporary cache directory that is
removed when the run finishes, so `bash tests/run_tests.sh` leaves nothing
behind.

mypy==2.3.0
pytest==9.1.1

"""Exercise 7 — watch `Any` switch the checker off.

Run mypy on this file as it stands:

    python3 -m mypy starter/any_demo.py

You get one error, with the code [union-attr]: `lookup` may return None, and
`shout` calls .upper() on the result without checking.

Now change ONE character sequence. Replace the return annotation of `lookup`

    def lookup(name: str) -> str | None:

with

    def lookup(name: str) -> Any:

and run mypy again. The error is gone. Nothing about the code got safer —
`lookup` still returns None for an unknown name, and `shout` will still raise
AttributeError at runtime. All that changed is that you told the checker to
stop looking.

That is what `Any` means: not "some type", but "stop checking here". Every
Any you write is a hole, and the hole is not local — it spreads to every
value that flows out of it.

Change it back when you are done.
"""

from typing import Any

WORDS: dict[str, str] = {"a": "alpha", "b": "bravo"}

# `Any` is imported ready for the exercise; it is unused until you make the
# edit described above. mypy does not complain about unused imports — that is
# a linter's job, and it is tomorrow's lesson.


def lookup(name: str) -> str | None:
    """Return the word for a letter, or None when the letter is unknown."""
    return WORDS.get(name)


def shout(name: str) -> str:
    """Upper-case the word for a letter."""
    return lookup(name).upper()

"""A small model catalogue — annotated, tested, and quietly wrong.

This module is the subject of the whole lab. Every function carries type
annotations, and the pytest suite in `test_catalog.py` passes green. It still
contains real bugs, because a passing test suite only proves that the paths
the tests walk behave as expected. mypy reads every path.

Your exercises are numbered below. Do NOT fix anything before you have run
both tools once and seen the difference for yourself.

  Exercise 1 — run the tests and watch them pass:
      python3 -m pytest starter/test_catalog.py
  Exercise 2 — run mypy on this file and read the report:
      python3 -m mypy starter/catalog.py
  Exercise 3 — write down each error's file, line, message and error code.
  Exercise 4 — fix bug A (marked below) so [union-attr] disappears.
  Exercise 5 — fix bug B (marked below) so [arg-type] disappears.
  Exercise 6 — run mypy in strict mode and handle what it adds:
      python3 -m mypy --strict starter/catalog.py
  Exercise 7 — prove the Any cautionary point with starter/any_demo.py.

The finished, strict-clean version is in examples/catalog.py. Compare only
after you have tried.
"""

from __future__ import annotations

import json
from dataclasses import dataclass


@dataclass(frozen=True)
class Model:
    """One row of the catalogue."""

    name: str
    context_tokens: int
    price_per_million_input: float


CATALOG: dict[str, Model] = {
    "small": Model(name="small", context_tokens=8_000, price_per_million_input=0.25),
    "medium": Model(name="medium", context_tokens=128_000, price_per_million_input=3.0),
    "large": Model(name="large", context_tokens=200_000, price_per_million_input=15.0),
}


def find_model(name: str) -> Model | None:
    """Look a model up by name, or return None when the name is unknown."""
    return CATALOG.get(name)


def describe(name: str) -> str:
    """One-line human summary of a model.

    BUG A. find_model returns `Model | None`, and this function reads
    attributes off the result without ever asking whether it is None. Every
    test calls describe() with a name that exists, so the suite never walks
    the None path. Exercise 4: teach the checker (and the reader) that the
    None case is handled, by returning early when the lookup fails.
    """
    model = find_model(name)
    return f"{model.name}: {model.context_tokens:,} token context"


def estimate_cost(name: str, tokens: int) -> float:
    """Dollar cost of sending `tokens` input tokens to `name`."""
    model = find_model(name)
    if model is None:
        raise KeyError(name)
    return tokens / 1_000_000 * model.price_per_million_input


def split_cost(name: str, tokens: int, parts: int) -> float:
    """Cost of one part when a job of `tokens` tokens is split into `parts`.

    BUG B. In Python 3 the `/` operator always produces a float, even when
    both operands are integers and the division is exact. estimate_cost is
    annotated to take an int. The test happens to use numbers that divide
    evenly, so the arithmetic is right and the test is green — but the type
    is wrong, and the day it stops dividing evenly you get a fractional token
    count nobody asked for. Exercise 5: use floor division instead.
    """
    per_part = tokens / parts
    return estimate_cost(name, per_part)


def format_price(value):
    """Format a price in dollars.

    Exercise 6: this function has no annotations at all. Under default
    settings mypy simply skips it. Under --strict it is an error, and so is
    calling it from an annotated function. Annotate it.
    """
    return f"${value:.2f}"


def price_line(name: str) -> str:
    """Human-readable price for one model."""
    model = find_model(name)
    if model is None:
        return f"{name}: unknown model"
    return f"{name}: {format_price(model.price_per_million_input)} per million tokens"


def load_settings(path: str) -> dict[str, float]:
    """Read numeric settings from a JSON file.

    Exercise 6 (continued): json.load is annotated to return Any, so this
    function hands back Any while promising dict[str, float]. Default mypy
    says nothing. --strict turns on warn_return_any and reports it. The fix
    is not to silence the warning but to check the value at the boundary:
    narrow the loaded object with isinstance, then build the dict you
    promised.
    """
    with open(path, encoding="utf-8") as handle:
        return json.load(handle)

{
  "temperature": 0.2,
  "top_p": 0.95,
  "max_output_tokens": 1024
}

"""The green suite. Every one of these tests passes on the buggy catalog.py.

That is the point of the lab, so do not "improve" this file until the very
last exercise. Read it and ask, for each test, which line of catalog.py it
never reaches. The two bugs live on exactly those lines.
"""

import catalog


def test_find_known_model() -> None:
    model = catalog.find_model("small")
    assert model is not None
    assert model.context_tokens == 8_000


def test_find_unknown_model_returns_none() -> None:
    assert catalog.find_model("enormous") is None


def test_describe_known_model() -> None:
    assert catalog.describe("small") == "small: 8,000 token context"


def test_describe_large_model() -> None:
    assert catalog.describe("large") == "large: 200,000 token context"


def test_estimate_cost_of_one_million_tokens() -> None:
    assert catalog.estimate_cost("medium", 1_000_000) == 3.0


def test_estimate_cost_rejects_unknown_model() -> None:
    try:
        catalog.estimate_cost("enormous", 1_000)
    except KeyError:
        return
    raise AssertionError("expected a KeyError for an unknown model")


def test_split_cost_divides_evenly() -> None:
    assert catalog.split_cost("medium", 1_000_000, 2) == 1.5


def test_price_line() -> None:
    assert catalog.price_line("large") == "large: $15.00 per million tokens"

"""Exercise 0 — what mypy says about code that carries no annotations at all.

This module is correct, ordinary, working Python. It has no type hints. Run
mypy over it twice and compare:

    python3 -m mypy starter/untyped_first_run.py
    python3 -m mypy --strict starter/untyped_first_run.py

The first run reports success. That is not praise. A function with no
annotations is a function mypy declines to check — it has nothing to compare
anything against, so it checks nothing and says so by saying nothing. This is
gradual typing working exactly as designed, and it is the single most
misleading result a newcomer can get: "mypy passes" on an unannotated
codebase means "mypy did not look".

The second run refuses to be quiet about it. Under --strict, an unannotated
function is itself an error, and so is calling one from typed code.

That contrast is the whole argument for turning strictness up: without it,
the checker's silence tells you nothing about your code and everything about
your annotations.
"""


def load_prices(rows):
    prices = {}
    for row in rows:
        name, value = row.split("=")
        prices[name] = float(value)
    return prices


def total(prices, names):
    return sum(prices[name] for name in names)


def main():
    prices = load_prices(["small=0.25", "large=15.0"])
    print(f"total: {total(prices, ['small', 'large'])}")


if __name__ == "__main__":
    main()

#!/usr/bin/env bash
# Tests for the Day 075 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# These checks are the argument of the lesson, made mechanical:
#
#   * the pytest suite passes on the BUGGY starter code — proving that a
#     green suite is not proof of correctness;
#   * mypy exits non-zero on the same file and names specific error CODES;
#   * every assertion greps for the bracketed code, never the prose, so the
#     suite survives a wording change in a future mypy release;
#   * the fixed reference in examples/ is clean under --strict, and clean
#     again when driven by the real [tool.mypy] table in examples/pyproject.toml;
#   * adding Any to one signature makes a caught error vanish while the code
#     stays exactly as broken — the Any warning, proved rather than asserted;
#   * a `type: ignore` carrying the wrong error code does not suppress
#     anything, which is why you always write the code.
#
# No network at test time. mypy writes its cache into a temporary directory
# that is removed on exit, so nothing appears in the lab.
# Exits 0 only if every check passes.
set -u

export PYTHONDONTWRITEBYTECODE=1

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "${lab_dir}" || exit 1

failures=0
checks=0

work_dir="$(mktemp -d)"
cache_dir="${work_dir}/cache"
cleanup() { rm -rf "${work_dir}"; }
trap cleanup EXIT

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

# Resolve a tool: an explicit override, then this lab's .venv, then whatever
# is on PATH. Fails loudly with instructions rather than silently skipping.
resolve_tool() {
  local tool="$1" override="$2"
  if [ -n "${override}" ] && [ -x "${override}" ]; then echo "${override}"; return 0; fi
  if [ -x "${lab_dir}/.venv/bin/${tool}" ]; then echo "${lab_dir}/.venv/bin/${tool}"; return 0; fi
  if command -v "${tool}" >/dev/null 2>&1; then command -v "${tool}"; return 0; fi
  return 1
}

install_hint() {
  local tool="$1"
  echo "  Install it with:" >&2
  echo "    python3 -m venv .venv" >&2
  echo "    .venv/bin/pip install -r requirements/requirements.txt" >&2
  echo "  Or point this suite at an existing ${tool}: ${2}=/path/to/${tool} bash tests/run_tests.sh" >&2
}

pytest_bin="$(resolve_tool pytest "${PYTEST:-}")" || {
  echo "FAIL: pytest not found." >&2
  install_hint pytest PYTEST
  exit 1
}

mypy_bin="$(resolve_tool mypy "${MYPY:-}")" || {
  echo "FAIL: mypy not found." >&2
  install_hint mypy MYPY
  exit 1
}

echo "Day 075 lab tests"
echo "================="
echo "pytest: $("${pytest_bin}" --version 2>&1 | head -1)"
echo "mypy:   $("${mypy_bin}" --version 2>&1 | head -1)"
echo

# run_mypy <output-file> <extra args...>
# Runs mypy with colour and the cache pinned so output is stable and nothing
# is written into the lab. Records the exit status in mypy_status.
mypy_status=0
run_mypy() {
  local out="$1"
  shift
  "${mypy_bin}" --no-color-output --no-error-summary --cache-dir "${cache_dir}" "$@" >"${out}" 2>&1
  mypy_status=$?
}

# ---------------------------------------------------------------------------
echo "1. The tests pass on the buggy code (this is the whole point)"
# ---------------------------------------------------------------------------

pytest_out="${work_dir}/pytest-starter.txt"
if PYTHONPATH="${lab_dir}/starter" "${pytest_bin}" -q -p no:cacheprovider \
    starter/test_catalog.py >"${pytest_out}" 2>&1; then
  check "pytest exits 0 on the buggy starter/catalog.py" "yes"
else
  check "pytest exits 0 on the buggy starter/catalog.py" "no"
  sed -n '$p' "${pytest_out}"
fi

if grep -q "8 passed" "${pytest_out}"; then
  check "all 8 starter tests pass — a green suite over a broken module" "yes"
else
  check "all 8 starter tests pass — a green suite over a broken module" "no"
fi

# ---------------------------------------------------------------------------
echo
echo "2. mypy finds what the tests missed, and names the codes"
# ---------------------------------------------------------------------------

mypy_starter="${work_dir}/mypy-starter.txt"
run_mypy "${mypy_starter}" starter/catalog.py
if [ "${mypy_status}" -ne 0 ]; then
  check "mypy exits non-zero on starter/catalog.py" "yes"
else
  check "mypy exits non-zero on starter/catalog.py" "no"
fi

# Grep for the bracketed CODE, not the prose. Messages get reworded between
# releases; the codes are the stable interface.
for code in union-attr arg-type; do
  if grep -q "\[${code}\]" "${mypy_starter}"; then
    check "default mypy reports [${code}] on starter/catalog.py" "yes"
  else
    check "default mypy reports [${code}] on starter/catalog.py" "no"
  fi
done

if grep -q "^starter/catalog.py:63: error:.*\[union-attr\]" "${mypy_starter}"; then
  check "[union-attr] is reported on line 63 — the unguarded lookup in describe()" "yes"
else
  check "[union-attr] is reported on line 63 — the unguarded lookup in describe()" "no"
fi

# ---------------------------------------------------------------------------
echo
echo "3. Strict mode adds the errors default settings let through"
# ---------------------------------------------------------------------------

mypy_strict="${work_dir}/mypy-starter-strict.txt"
run_mypy "${mypy_strict}" --strict starter/catalog.py
if [ "${mypy_status}" -ne 0 ]; then
  check "mypy --strict exits non-zero on starter/catalog.py" "yes"
else
  check "mypy --strict exits non-zero on starter/catalog.py" "no"
fi

for code in no-untyped-def no-untyped-call no-any-return; do
  if grep -q "\[${code}\]" "${mypy_strict}"; then
    check "strict mode reports [${code}]" "yes"
  else
    check "strict mode reports [${code}]" "no"
  fi
  if grep -q "\[${code}\]" "${mypy_starter}"; then
    check "default settings do NOT report [${code}]" "no"
  else
    check "default settings do NOT report [${code}]" "yes"
  fi
done

# A file with no annotations at all: mypy's silence means "nothing to check",
# not "nothing wrong". Strict mode says so out loud.
mypy_untyped="${work_dir}/mypy-untyped.txt"
run_mypy "${mypy_untyped}" starter/untyped_first_run.py
if [ "${mypy_status}" -eq 0 ]; then
  check "default mypy is SILENT on a fully unannotated file" "yes"
else
  check "default mypy is SILENT on a fully unannotated file" "no"
fi

run_mypy "${mypy_untyped}" --strict starter/untyped_first_run.py
if [ "${mypy_status}" -ne 0 ] && grep -q "\[no-untyped-def\]" "${mypy_untyped}"; then
  check "--strict on the same file reports [no-untyped-def]" "yes"
else
  check "--strict on the same file reports [no-untyped-def]" "no"
fi

# ---------------------------------------------------------------------------
echo
echo "4. The fixed reference is clean, and the behaviour really was broken"
# ---------------------------------------------------------------------------

mypy_examples="${work_dir}/mypy-examples.txt"
run_mypy "${mypy_examples}" --strict \
  examples/catalog.py examples/typing_tour.py examples/demo.py examples/test_catalog.py
if [ "${mypy_status}" -eq 0 ]; then
  check "mypy --strict exits 0 on every file in examples/" "yes"
else
  check "mypy --strict exits 0 on every file in examples/" "no"
  cat "${mypy_examples}"
fi

mypy_config="${work_dir}/mypy-config.txt"
run_mypy "${mypy_config}" --config-file examples/pyproject.toml examples/catalog.py
if [ "${mypy_status}" -eq 0 ]; then
  check "the real [tool.mypy] table in examples/pyproject.toml also passes" "yes"
else
  check "the real [tool.mypy] table in examples/pyproject.toml also passes" "no"
  cat "${mypy_config}"
fi

pytest_examples="${work_dir}/pytest-examples.txt"
if PYTHONPATH="${lab_dir}/examples" "${pytest_bin}" -q -p no:cacheprovider \
    examples/test_catalog.py >"${pytest_examples}" 2>&1 && grep -q "9 passed" "${pytest_examples}"; then
  check "the fixed module passes all 9 tests, including the new None case" "yes"
else
  check "the fixed module passes all 9 tests, including the new None case" "no"
  sed -n '$p' "${pytest_examples}"
fi

# The type error was a real bug, not a bookkeeping complaint: prove it.
if PYTHONPATH="${lab_dir}/starter" python3 -c \
    "import catalog; catalog.describe('enormous')" >/dev/null 2>&1; then
  check "buggy describe('enormous') raises at runtime" "no"
else
  check "buggy describe('enormous') raises at runtime" "yes"
fi

fixed_describe="$(PYTHONPATH="${lab_dir}/examples" python3 -c \
  "import catalog; print(catalog.describe('enormous'))" 2>&1)"
if [ "${fixed_describe}" = "enormous: unknown model" ]; then
  check "fixed describe('enormous') returns a sensible string" "yes"
else
  check "fixed describe('enormous') returns a sensible string" "no"
  echo "    got: ${fixed_describe}"
fi

# ---------------------------------------------------------------------------
echo
echo "5. Any switches the checker off — proved, not asserted"
# ---------------------------------------------------------------------------

any_dir="${work_dir}/any"
mkdir -p "${any_dir}"
cp starter/any_demo.py "${any_dir}/before.py"
sed 's/-> str | None:/-> Any:/' "${any_dir}/before.py" >"${any_dir}/after.py"

if ! cmp -s "${any_dir}/before.py" "${any_dir}/after.py"; then
  check "the Any edit changed exactly one annotation" "yes"
else
  check "the Any edit changed exactly one annotation" "no"
fi

any_before="${work_dir}/any-before.txt"
run_mypy "${any_before}" "${any_dir}/before.py"
if [ "${mypy_status}" -ne 0 ] && grep -q "\[union-attr\]" "${any_before}"; then
  check "before: mypy reports [union-attr] on the unguarded call" "yes"
else
  check "before: mypy reports [union-attr] on the unguarded call" "no"
fi

any_after="${work_dir}/any-after.txt"
run_mypy "${any_after}" "${any_dir}/after.py"
if [ "${mypy_status}" -eq 0 ]; then
  check "after: the same code with Any reports NOTHING and exits 0" "yes"
else
  check "after: the same code with Any reports NOTHING and exits 0" "no"
  cat "${any_after}"
fi

# The code is exactly as broken as it was. Only the checking changed.
if PYTHONPATH="${any_dir}" python3 -c \
    "import after; after.shout('zzz')" >/dev/null 2>&1; then
  check "the Any version still crashes at runtime — nothing got safer" "no"
else
  check "the Any version still crashes at runtime — nothing got safer" "yes"
fi

# ---------------------------------------------------------------------------
echo
echo "6. A type: ignore with the wrong code suppresses nothing"
# ---------------------------------------------------------------------------

ignore_dir="${work_dir}/ignore"
mkdir -p "${ignore_dir}"
sed 's|return lookup(name).upper()|return lookup(name).upper()  # type: ignore[arg-type]|' \
  "${any_dir}/before.py" >"${ignore_dir}/wrong_code.py"
sed 's|return lookup(name).upper()|return lookup(name).upper()  # type: ignore[union-attr]|' \
  "${any_dir}/before.py" >"${ignore_dir}/right_code.py"

ignore_wrong="${work_dir}/ignore-wrong.txt"
run_mypy "${ignore_wrong}" "${ignore_dir}/wrong_code.py"
if [ "${mypy_status}" -ne 0 ] && grep -q "\[union-attr\]" "${ignore_wrong}"; then
  check "ignore[arg-type] does NOT suppress a [union-attr] error" "yes"
else
  check "ignore[arg-type] does NOT suppress a [union-attr] error" "no"
fi

ignore_right="${work_dir}/ignore-right.txt"
run_mypy "${ignore_right}" "${ignore_dir}/right_code.py"
if [ "${mypy_status}" -eq 0 ]; then
  check "ignore[union-attr] suppresses exactly that error and nothing else" "yes"
else
  check "ignore[union-attr] suppresses exactly that error and nothing else" "no"
  cat "${ignore_right}"
fi

# warn_unused_ignores turns a stale ignore into an error of its own.
cp examples/catalog.py "${ignore_dir}/stale.py"
printf '\n\nSTALE: int = 1  # type: ignore[assignment]\n' >>"${ignore_dir}/stale.py"
ignore_stale="${work_dir}/ignore-stale.txt"
run_mypy "${ignore_stale}" --strict "${ignore_dir}/stale.py"
if [ "${mypy_status}" -ne 0 ] && grep -q "\[unused-ignore\]" "${ignore_stale}"; then
  check "warn_unused_ignores reports a stale ignore as [unused-ignore]" "yes"
else
  check "warn_unused_ignores reports a stale ignore as [unused-ignore]" "no"
  cat "${ignore_stale}"
fi

# ---------------------------------------------------------------------------
echo
echo "7. The reference scripts run and produce their documented output"
# ---------------------------------------------------------------------------

demo_out="${work_dir}/demo.txt"
if PYTHONPATH="${lab_dir}/examples" python3 examples/demo.py >"${demo_out}" 2>&1; then
  check "python3 examples/demo.py exits 0" "yes"
else
  check "python3 examples/demo.py exits 0" "no"
fi

if grep -q "describe('enormous'): enormous: unknown model" "${demo_out}"; then
  check "demo shows the None path handled" "yes"
else
  check "demo shows the None path handled" "no"
fi

tour_out="${work_dir}/tour.txt"
if PYTHONPATH="${lab_dir}/examples" python3 examples/typing_tour.py >"${tour_out}" 2>&1; then
  check "python3 examples/typing_tour.py exits 0" "yes"
else
  check "python3 examples/typing_tour.py exits 0" "no"
fi

for expected in "first_word(None): (nothing)" "structural typing works" "first_or([], 'fallback'): fallback"; do
  if grep -qF "${expected}" "${tour_out}"; then
    check "typing tour prints: ${expected}" "yes"
  else
    check "typing tour prints: ${expected}" "no"
  fi
done

# ---------------------------------------------------------------------------
echo
echo "-----------------------------------------------------------"
echo "${checks} checks, ${failures} failure(s)."
if [ "${failures}" -ne 0 ]; then
  exit 1
fi
exit 0