Typing in depth

Precise shapes: Literal, TypedDict and Protocol

Plain str and dict say too little. A few typing tools describe data more exactly:

from typing import Literal, Protocol, TypedDict

Store = Literal["portland", "seattle", "denver", "online"]      # only these four strings

class OrderRow(TypedDict):        # a dictionary with exactly these keys and value types
    sku: str
    qty: int
    store: Store

class Notifier(Protocol):         # anything with a send(text) method fits
    def send(self, text: str) -> None: ...

• Literal limits a value to a fixed set. Passing "Portland" (capital P) is now a type error, caught before it ever reaches the database.
• TypedDict describes a dictionary's keys and their types: the shape of a JSON record. row["quantity"] is reported as an unknown key, and row["qty"] is known to be an int.
• Protocol describes behavior instead of ancestry. Any class with a matching send method counts as a Notifier, without inheriting from anything. It's how Python's "duck typing" ("if it quacks like a duck") gets checked: the email sender, the SMS sender and a test fake all fit, and none needs to know about the others.

Generics: one function, many types

Some functions work the same way for any type, but their output type depends on their input: the first item of a list of strings is a string, and of a list of orders, an order. A type variable says so. Python 3.12 added a short syntax with square brackets after the name:

from mypy import api

def check_types(code):
    open("check.py", "w").write(code)
    return api.run(["check.py", "--strict", "--no-incremental", "--cache-dir=/dev/null"])[0].strip()

print(check_types('''
def first[T](items: list[T], default: T) -> T:
    return items[0] if items else default

class Box[T]:
    def __init__(self, item: T) -> None:
        self.item = item
    def get(self) -> T:
        return self.item

sku: str = first(["TE-101", "PA-108"], "")
qty: int = first([3, 5], 0)
bad: int = first(["TE-101"], "")
crate = Box(12)
reveal_type(crate.get())
'''))

T stands for "whatever type the caller uses". Called with a list of strings, first returns a string, so assigning it to an int is an error. Box[T] is a generic class, like list[int] and dict[str, float] in the standard library, and mypy works out Box[int] from the argument. Older code spells the same idea T = TypeVar("T"); you'll see both.

from typing import Protocol


class Email:
    def __init__(self) -> None:
        self.sent: list[str] = []

    def send(self, text: str) -> None:
        self.sent.append("email: " + text)


class Sms:
    def __init__(self) -> None:
        self.sent: list[str] = []

    def send(self, text: str) -> None:
        self.sent.append("sms: " + text[:160])


def alert_all(channels, text):
    for channel in channels:
        channel.send(text)


alert_all([Email(), Sms()], "Rain at 8:00")

Adding types to an existing codebase

You rarely start with fully typed code. Typing is gradual: unannotated code is treated as Any, a type that fits everything, so mypy stays quiet about it. You add types where they pay off most, and tighten the settings as you go:

1. Start with mypy's default settings, which check only annotated functions, and fix what it finds.
2. Annotate the edges first: functions other modules call, data that comes from files and APIs.
3. Turn on stricter options file by file, until --strict passes for the whole project.
4. Run mypy in CI, so new code can't slip back.

Each newly annotated function tends to expose a real bug or two. That's the point: the bugs were always there, waiting for the unlucky input. When a library you use has no type information, mypy treats it as Any; many popular libraries ship hints, and others have a separate types-... package.

Use Any and # type: ignore[code] sparingly, and always with the error code, like noqa in linting. Each one switches the safety net off for that spot. And never let types replace tests: a function can be perfectly typed and still compute the wrong total.

from mypy import api

MODULE = '''
from typing import Literal, TypedDict

Tier = Literal["basic", "club"]

class Line(TypedDict):
    sku: str
    price: float
    qty: int

DISCOUNT: dict[Tier, float] = {"basic": 0.0, "club": 0.1}

def line_total(line: Line) -> float:
    return line["price"] * line["quantity"]

def order_total(lines: list[Line], tier: Tier) -> float:
    subtotal = sum(line_total(l) for l in lines)
    return round(subtotal * (1 - DISCOUNT[tier]), 2)

print(order_total([{"sku": "TE-101", "price": 200.0, "qty": 1}], "Club"))
'''

open("pricing.py", "w").write(MODULE)
report, _, status = api.run(["pricing.py", "--strict", "--no-incremental", "--cache-dir=/dev/null"])
print(report)