23The type system — runtime types vs static hints

In Chapter 22 we pinned the environment down — venv, pip, a lockfile — so the code on your machine is the code that runs everywhere else. In this one we turn on the code itself, and go after a small lie most of us half-believe. You wrote age: int = 5, asked type(age), got int back. Something in you concluded the : int is what made it an int. It didn't. So here's the plan. We watch Python run two type systems at once. One is a runtime system, where every object wears its type in its own header at a real RAM address. The other is a static system, where hints the interpreter never reads get studied by a separate program. That program reasons about your code without running a single line. And the whole way through we keep asking the one question that dissolves every confusion about types — when you write : int, what actually reads it, and why is that never the same thing type() reads? By the end we can see the seam plainly. Two mechanisms wear the same word, stored in two different places, with no wire connecting them. Once you feel that gap, annotations, Optional, generics, and protocols all stop looking like magic.

01Two type systems, coexisting

Let's start at the prompt, because the whole chapter cracks open in three lines. Type age: int = 5. Then — no error, no complaint, nothing — type age = 'oops'. Now ask type(age), and watch what it says: str. Sit with that for a second. You annotated the name as int, you stored a string in it, and Python shrugged. If the hint had actually made age an int, that second line would have been a crime — a type error, a refusal, something. It was not even noticed. So the : int did not make anything anything, which leaves us holding a sharp question. Plainly, type(age) is reading some other thing than the : int you wrote, so what is it reading? That gap is the seam, and we are going to walk straight into it.

Go back to Vol 1's opening truth. Every value in Python is a PyObject living at some address on the heap, and every object begins with a header. The very first useful field in that header is ob_type. It's a pointer to the object's type object, a PyTypeObject that itself lives somewhere in memory. When you call type(x), CPython does almost nothing. It runs the macro Py_TYPE(x), which is a single dereference of that header field. Not a search, not a comparison, not a lookup by name. It's an O(1) read of a pointer that travels with the object. So the type is a physical property of the thing on the heap. The name age is never consulted. The runtime type belongs to the object 5, or a line later to the object 'oops', not to the label you tied around it.

So where did the : int go? It compiled to something entirely separate, and the compiler will show you. An annotated assignment like age: int = 5 is really two unrelated acts glued into one line. The first is the ordinary assignment age = 5, which stores the value. The second is the annotation int, which at module or class scope gets filed as a key/value pair into a real, inspectable dictionary named __annotations__. Watch the bytecode prove they never touch:

import dis

def annotated():
    x: int = 5          # with the hint
    return x

def plain():
    x = 5               # without it
    return x

dis.dis(annotated)
#   LOAD_CONST   5
#   STORE_FAST   x        <- stores the value, no type check
#   LOAD_FAST    x
#   RETURN_VALUE
dis.dis(plain)
#   LOAD_CONST   5         identical. byte for byte.
#   STORE_FAST   x
#   LOAD_FAST    x
#   RETURN_VALUE

Byte for byte identical. Inside a function the annotation int is not even evaluated. PEP 526 says local annotations are recorded by the compiler as metadata and then thrown away. The frame never reads them, the name int is never looked up, and no __annotations__ entry is created for a function local at all. At module scope there's exactly one extra instruction, SETUP_ANNOTATIONS. It lazily creates the module's __annotations__ dict, so the compiler can drop the card 'age': int into it. That card is inert side-data. You can print it, mutate it, even del a key out of it. It is a filing cabinet, not a law. Function signatures work the same way. def f(n: int) -> str stores its hints in f.__annotations__, a plain dict hanging off the function object that f never once reads while it runs.

you type
# annotate_basics.py -- the four places a hint can go, and what it costs
x: int = 0                          # 1. annotated assignment: hint AND value
y: str                              # 2. declaration only: NOTHING is stored


def is_long(title: str, limit: int = 12) -> bool:   # 3. params, default, arrow
    return len(title) > limit


class Track:                        # 4. class-level field declarations
    title: str
    seconds: int = 0


x = "not an int"                    # the hint said int. nobody checks.
print("x is now       :", type(x).__name__, repr(x))
print("is_long('Levels'):", is_long("Levels"))
print("is_long('Blinding Lights'):", is_long("Blinding Lights"))
print("module hints   :", __annotations__)
print("is_long hints  :", is_long.__annotations__)
print("Track hints    :", Track.__annotations__)
try:
    print(y)
except NameError as exc:
    print("reading y      : NameError:", exc)


# ---------- the terminal ----------
$ python annotate_basics.py
$ python -m mypy annotate_basics.py

you see
$ python annotate_basics.py
x is now       : str 'not an int'
is_long('Levels'): False
is_long('Blinding Lights'): True
module hints   : {'x': <class 'int'>, 'y': <class 'str'>}
is_long hints  : {'title': <class 'str'>, 'limit': <class 'int'>,
                  'return': <class 'bool'>}
Track hints    : {'title': <class 'str'>, 'seconds': <class 'int'>}
reading y      : NameError: name 'y' is not defined

$ python -m mypy annotate_basics.py
annotate_basics.py:15: error: Incompatible types in assignment
    (expression has type "str", variable has type "int")  [assignment]
Found 1 error in 1 file (checked 1 source file)

There it is, laid bare. The runtime type is a live pointer in the object's header, read by type(). The static hint is a string-or-object filed in a side dictionary. At runtime it is read by nobody, and before runtime it is read by a separate checker. Two systems, two storage locations, and — this is the whole chapter in one sentence — zero interaction between them. The name type is doing double duty across a chasm.

"""hints_lie.py -- one file, two readers: the interpreter and the checker."""


def as_clock(seconds: int) -> str:
    minutes, secs = divmod(seconds, 60)
    return f"{minutes}:{secs:02d}"


total: int = "245"                     # the lie: a str where int was promised

print("the hint      :", __annotations__["total"])
print("what is stored:", type(total).__name__, repr(total))
print("as_clock hints:", as_clock.__annotations__)
print("honest call   :", as_clock(245))
print("now the lie   :", as_clock(total))


# ---------- the terminal, twice ----------
$ python hints_lie.py
$ python -m mypy hints_lie.py

$ python hints_lie.py
the hint      : <class 'int'>
what is stored: str '245'
as_clock hints: {'seconds': <class 'int'>, 'return': <class 'str'>}
honest call   : 4:05
Traceback (most recent call last):
  File "C:\tmp\ch23lang\hints_lie.py", line 15, in <module>
    print("now the lie   :", as_clock(total))
                             ^^^^^^^^^^^^^^^
  File "C:\tmp\ch23lang\hints_lie.py", line 5, in as_clock
    minutes, secs = divmod(seconds, 60)
                    ^^^^^^^^^^^^^^^^^^^
TypeError: unsupported operand type(s) for divmod(): 'str' and 'int'

$ python -m mypy hints_lie.py
hints_lie.py:9: error: Incompatible types in assignment (expression has
    type "str", variable has type "int")  [assignment]
Found 1 error in 1 file (checked 1 source file)

So the hint is a note nobody reads at runtime. But somebody does read it — a separate program that never runs your code and yet catches bugs your tests never reach. Next: how a checker reasons about every possible run at once. →

02A checker reasons without running code

You have run mypy and watched it print errors, and it probably felt like a spellchecker — a linter grepping your text for suspicious shapes. It is doing something far stronger than that, and far stranger. A type checker never executes your program. It reads the source the way you would if you traced it in your head. From that reading it constructs a proof about every possible run, including the runs your tests will never trigger. Testing samples reality. Checking reasons about all of it. To trust the tool you have to see the machine, so let's build its shape.

Recall from Vol 1 how the interpreter itself works. It keeps a namespace, a map from each name in scope to the object it currently points at. It walks your statements one at a time, mutating that map as it goes. A checker is the same walk with one substitution. It parses your source into an AST — the tree of statements and expressions — and walks it in control-flow order. As it walks it maintains a typing environment: a map from each in-scope name to its currently-inferred type, not its value. It binds name → type where the interpreter binds name → object, and it never runs anything. This technique has a name: abstract interpretation. Instead of computing with concrete values, the checker computes with the lattice of types. Those are the abstract stand-ins for whole sets of values at once.

Watch it thread a type through an expression it has never evaluated:

x = 5            # literal 5 has type int  -> env: x: int
y = x + 1.0      # int.__add__(float)? typeshed says the result is float
                 #                          -> env: y: float
z = str(y)       # str(float) returns str    -> env: z: str
z + 1            # str.__add__(int)? no such overload -> ERROR, before it runs

At no point did 5, 1.0, or str(y) actually get computed. The checker inferred x: int from the literal. Then it asked a question it cannot answer by introspection — what does int + float return? — and looked the answer up in typeshed. Typeshed is the corpus of .pyi stub files. These are signatures-only declarations for the entire standard library and every C-implemented builtin, which have no Python source for the checker to read. The stub for int.__add__ declares that adding a float yields a float, so the environment records y: float. That fact came purely from reading two files, never from running one line. The last line is a proof of a contradiction. str has no __add__ taking an int, so the checker reports an error for code the interpreter never reached.

This is why checking is categorically stronger than testing. A dynamic test only ever observes the exact path it executed. A branch guarded by if rare_condition: that your test suite never enters is invisible to every test you will ever write. The checker reads that branch anyway. It reasons about the program text, which contains all branches, rather than one execution, which contains one path. So a green test suite says "the runs I sampled worked." A green checker says "no run can do the thing I forbid." Those are different promises, and the second is a proof.

Be honest about the cost of that strength, because it explains the checker's most annoying moments. Its model is an over-approximation. It must assume every branch could run, since it can't know your runtime invariants. So it will flag a possible None dereference on a path that is really unreachable, for reasons buried in data the checker cannot see. That's not a bug in the tool — it's the price of a proof that holds for all inputs. And there is not one checker but several. mypy and pyright are independent implementations of roughly the same PEP 484 rules. They read the same annotations and the same typeshed, and they can quietly disagree at the edges where the spec is loose. Two engines, one rulebook, occasionally two verdicts.

you type
# duration.py -- runs clean today. one branch has never executed.
def as_clock(seconds: int) -> str:
    minutes, secs = divmod(seconds, 60)
    return f"{minutes}:{secs:02d}"


def report(seconds: int, fancy: bool = False) -> str:
    if fancy:
        return "~ " + as_clock(str(seconds)) + " ~"
    return as_clock(seconds)


print(report(340))
print(report(200))


# ---------- the terminal, in the Ch 22 venv ----------
$ python -m venv .venv
$ source .venv/Scripts/activate      # unix: source .venv/bin/activate
$ python -m pip install mypy
$ python -m mypy --version
$ python duration.py
$ python -m mypy duration.py
$ echo $?

you see
$ python -m pip install mypy
Collecting mypy
  Using cached mypy-2.3.1-cp312-cp312-win_amd64.whl.metadata (2.4 kB)
Collecting typing_extensions>=4.6.0 (from mypy)
Collecting mypy_extensions>=1.0.0 (from mypy)
Collecting pathspec>=1.0.0 (from mypy)
Collecting librt>=0.13.0 (from mypy)
Collecting ast-serialize<1.0.0,>=0.6.0 (from mypy)
Using cached mypy-2.3.1-cp312-cp312-win_amd64.whl (11.2 MB)
Installing collected packages: typing_extensions, pathspec,
    mypy_extensions, librt, ast-serialize, mypy
Successfully installed ast-serialize-0.8.0 librt-0.15.0 mypy-2.3.1
    mypy_extensions-1.1.0 pathspec-1.1.1 typing_extensions-4.16.0

$ python -m mypy --version
mypy 2.3.1 (compiled: yes)

$ python duration.py
5:40
3:20

$ python -m mypy duration.py
duration.py:9: error: Argument 1 to "as_clock" has incompatible type
    "str"; expected "int"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

$ echo $?
1

But a single type per name is a straitjacket — real code guards, branches, and re-checks. How does the checker learn that x is one type here and another type three lines down? Narrowing. →

03Narrowing: how control flow teaches the checker

Here is the moment that first makes the checker feel like it's reading your mind. You have a name that might be None. You write the obvious guard — if x is None: return — and then, below it, you call x.upper(). The annotation still says x could be None, so by the letter of it, x.upper() should be forbidden. Yet mypy accepts it without a word. It didn't ignore the rule — it learned something from your guard, and the mechanism it used is the single most important idea in practical typing: narrowing.

The key realization is that the typing environment is not one fixed type per name. It is a type per program point. As the checker walks the control-flow graph, the type it holds for x is a function of where in the code you are. At certain expressions, recognized as type guards, it splits that type. When the checker meets if x is None: with an incoming x: str | None, it partitions the possibilities across the two out-edges. On the edge into the if body it binds x: None. On the fall-through/else edge it binds x: str. That's because if x is not None, the only remaining member of the union is str. Two edges, two facts.

def greet(name: str | None) -> None:
    # here the checker holds  name: str | None
    if name is None:
        # on THIS edge  name: None
        return                 # edge dead-ends; reachability analysis notes it
    # the only edge that reaches here is the else-edge:  name: str
    print(name.upper())    # str.upper() exists -> accepted, no cast, no ignore

The return is doing quiet, essential work. The checker's reachability analysis understands that return terminates the block, so the None edge simply stops there. The only edge that flows down to name.upper() is the else-edge, and on that edge the environment says name: str. The method exists on str, so the call type-checks. Not because the checker got lax, but because at that line it has proven name cannot be None. Tie it straight back to Vol 1. The interpreter's namespace maps a name to different objects over time. The checker's environment maps a name to different, narrower types over the control-flow graph. Same shape of idea, one axis swapped from time to place.

The recognized guard forms are a specific, learnable vocabulary. This is not fuzzy pattern-matching, it's a fixed list. x is None and x is not None split off None. isinstance(x, C) narrows to C on the true edge. type(x) is C narrows to exactly C. A plain truthiness test if x: narrows away None and other falsy members for types where that's sound. Comparing == against a literal or an enum value narrows to that literal's type. And you can extend the vocabulary yourself. A TypeGuard (PEP 647) or TypeIs (PEP 742) function is a predicate whose return annotation tells the checker "if this returned True, narrow the argument to this." Each of these is a rule the checker applies at an edge to shrink a name's type set.

shuffle.py:21: error: Incompatible default for parameter "avoid" (default
    has type "None", parameter has type "str")  [assignment]
shuffle.py:21: note: PEP 484 prohibits implicit Optional. Accordingly, mypy
    has changed its default to no_implicit_optional=True
shuffle.py:28: error: Value of type "tuple[str, int] | None" is not
    indexable  [index]
shuffle.py:31: error: Argument 1 to "append" of "list" has incompatible
    type "tuple[str, str]"; expected "tuple[str, int]"  [arg-type]
Found 3 errors in 1 file (checked 1 source file)

# ---------- shuffle.py  (the one you type: it RUNS) ----------
"""shuffle.py -- it runs today and prints something sensible. mypy disagrees."""
import random

Track = tuple[str, int]

LIBRARY: list[Track] = [("Blinding Lights", 200), ("Titanium", 245), ("Levels", 340)]


def as_clock(seconds: int) -> str:
    minutes, secs = divmod(seconds, 60)
    return f"{minutes}:{secs:02d}"


def find(title: str, library: list[Track]) -> Track | None:
    for row in library:
        if row[0] == title:
            return row
    return None


def pick(library: list[Track], avoid: str = None) -> Track:
    choices = [row for row in library if row[0] != avoid]
    return random.choice(choices)


def banner(title: str, library: list[Track]) -> str:
    row = find(title, library)
    return f"Now playing: {row[0]} ({as_clock(row[1])})"


LIBRARY.append(("Nightcall", "348"))

print(banner("Levels", LIBRARY))
print("avoided Levels:", pick(LIBRARY, avoid="Levels")[0] != "Levels")


$ python shuffle.py
Now playing: Levels (5:40)
avoided Levels: True


# The three answers, before the edits.
#
# 1. line 21 -- `avoid: str = None`. The default IS the counter-example. Call
#    pick(LIBRARY) with no `avoid` at all and the parameter holds None, which
#    is not a str. The declaration was already false on the most common call.
#
# 2. line 28 -- `row[0]`. Pass any title that is not in the library, say
#    banner("Enter Sandman", LIBRARY), and find() returns None. Subscripting
#    None raises TypeError. Today every call happens to use a title that hits.
#
# 3. line 31 -- ("Nightcall", "348") puts a str where the row promised an int.
#    Nothing breaks yet because appending never inspects the value. It breaks
#    the moment as_clock() reaches that row: divmod("348", 60) is a TypeError.
#    The bug and the crash are in different files, minutes apart.


# ---------- shuffle_fixed.py  (three edits, nothing else) ----------
"""shuffle_fixed.py -- three edits, each one the type telling you what it needed."""
import random

Track = tuple[str, int]

LIBRARY: list[Track] = [("Blinding Lights", 200), ("Titanium", 245), ("Levels", 340)]


def as_clock(seconds: int) -> str:
    minutes, secs = divmod(seconds, 60)
    return f"{minutes}:{secs:02d}"


def find(title: str, library: list[Track]) -> Track | None:
    for row in library:
        if row[0] == title:
            return row
    return None


def pick(library: list[Track], avoid: str | None = None) -> Track:   # FIX 1
    choices = [row for row in library if row[0] != avoid]
    return random.choice(choices)


def banner(title: str, library: list[Track]) -> str:
    row = find(title, library)
    if row is None:                                                  # FIX 2
        return f"Not in the library: {title}"
    return f"Now playing: {row[0]} ({as_clock(row[1])})"


LIBRARY.append(("Nightcall", 348))                                   # FIX 3

print(banner("Levels", LIBRARY))
print(banner("Nightcall", LIBRARY))
print(banner("Enter Sandman", LIBRARY))
print("avoided Levels:", pick(LIBRARY, avoid="Levels")[0] != "Levels")


$ python -m mypy shuffle_fixed.py
Success: no issues found in 1 source file

$ python shuffle_fixed.py
Now playing: Levels (5:40)
Now playing: Nightcall (5:48)
Not in the library: Enter Sandman
avoided Levels: True


# Why each fix is the one the type asked for.
#
# FIX 1 -- WIDEN the type, do not change the default. `str | None` states the
#   truth: this parameter really can be None, and every use of `avoid` inside
#   pick() must survive that. The comparison row[0] != avoid already does.
#   Writing `avoid: str = ""` would also silence mypy -- and would quietly
#   change behaviour for a caller who passes "" on purpose.
#
# FIX 2 -- ADD the guard. There is no annotation that makes `row[0]` safe,
#   because the danger is real: find() genuinely returns None on a miss. The
#   only honest fix is to handle the miss, which is what the checker was
#   asking for. Note the shape: after `if row is None: return ...`, the None
#   edge dead-ends, so below the guard row is a plain tuple[str, int] again.
#
# FIX 3 -- FIX THE VALUE, not the hint. The row was simply wrong: 348 seconds
#   is a number. Widening Track to tuple[str, int | str] would "fix" the error
#   and poison every function that reads a duration. When the data is wrong,
#   the type is the messenger -- do not shoot it.

def length_of(x: int | str) -> int:
    if isinstance(x, int):
        return x + 1      # this arm: x: int  -> int arithmetic is fine
    else:
        return len(x.upper())  # this arm: x: str  -> .upper() is fine

Now the honest edge, because it's a real bug class. Narrowing is a fact at a point in flow, and it can be destroyed. Say you narrow x to non-None, then reassign it from a function returning str | None. The checker must throw the old fact away. The name widens back to its declared type, because the new value could once again be None. Likewise, calling a function that the checker must assume could mutate a narrowed attribute can invalidate the narrowing. This is not the tool being fussy. It is the tool refusing to keep believing something you just made untrue. When mypy suddenly "forgets" that x was safe, look for the reassignment between the guard and the use.

Narrowing only matters because a name can carry several types at once. Time to name that thing directly — Optional and Union, and why they turn the most common crash in Python into a compile-time error. →

04Optional and Union: a name with several types

Count the times production has bitten you with AttributeError: 'NoneType' object has no attribute .... A function returned None — the lookup missed, the list was empty, the key wasn't there — and you, three files away, dotted into the result as if it were always a real object. This is not an exotic bug. By volume it is close to the Python bug. What makes it lethal is that nothing marks the moment None entered. Optional and Union are the fix, and they are not decoration. They are the checker's way of forcing you to face the None case at the exact seam where it's born. That turns a category of 3 a.m. crashes into errors you clear before you ship.

A Union is a static set of types. When the checker holds x: int | str (the | spelling, PEP 604, since 3.10), it is recording that at this point x may hold any member of that set. So it permits only operations valid for every member. You may call a method only if it exists on the int interface and the str interface. Anything present on just one is rejected, because the checker cannot prove which member you actually have. This is the meet of the interfaces, the common ground. And Optional[T] is nothing but Union[T, None]. It is pure sugar, the same object underneath.

from typing import Optional, Union

print(Optional[int] is Union[int, None])   # True — the same normalized object
print(Optional[int])                     # typing.Optional[int]  == Union[int, None]

Now the crux of why Optional protects you. The static type of None is NoneType, whose interface is very nearly empty — it has essentially no useful methods. So while None is still a possible member of the set, the meet of "whatever T offers" and "almost nothing" is almost nothing, and the checker rejects x.anything(). The only way to earn access to T's methods is to remove None from the set, which is precisely the narrowing of the previous section. So Optional mechanically compels a None-check before use. It is not asking politely, and the type algebra leaves you no other door.

you type
# optional_writer.py -- the None-default pattern, and the mistake it prevents
def add_track(title: str, bucket: list[str] | None = None) -> list[str]:
    if bucket is None:              # the sentinel check AND the narrowing, one line
        bucket = []
    bucket.append(title)
    return bucket


def first_title(bucket: list[str] | None) -> str:
    return bucket[0]                # no guard -- the checker refuses this


print("fresh call 1 :", add_track("Levels"))
print("fresh call 2 :", add_track("Titanium"))
mine = add_track("Levels")
print("passed in    :", add_track("Blinding Lights", mine))
print("with a list  :", first_title(["Levels"]))
print("with None    :", first_title(None))


# ---------- the terminal ----------
$ python optional_writer.py
$ python -m mypy optional_writer.py

you see
$ python optional_writer.py
fresh call 1 : ['Levels']
fresh call 2 : ['Titanium']
passed in    : ['Levels', 'Blinding Lights']
with a list  : Levels
Traceback (most recent call last):
  File "C:\tmp\ch23lang\optional_writer.py", line 18, in <module>
    print("with None    :", first_title(None))
                            ^^^^^^^^^^^^^^^^^
  File "C:\tmp\ch23lang\optional_writer.py", line 10, in first_title
    return bucket[0]
           ~~~~~~^^^
TypeError: 'NoneType' object is not subscriptable

$ python -m mypy optional_writer.py
optional_writer.py:10: error: Value of type "list[str] | None" is not
    indexable  [index]
Found 1 error in 1 file (checked 1 source file)

Keep the metal-up honesty sharp, because | means two different things depending on where it appears. As a runtime expression, int | str actually constructs a value. It builds a types.UnionType object you can inspect, and since 3.10 isinstance(3, int | str) genuinely works at runtime. But Union[...] and Optional[...] from typing construct typing.Union special forms instead. Both are real objects the annotation machinery evaluates and files away. And both do no checking whatsoever on assignment. Storing a str into a name annotated int | None raises nothing. The union is meaningful only to the checker reading the annotation, never to the STORE that runs.

U = int | str
print(type(U))              # <class 'types.UnionType'> — a real, live object
print(isinstance(3, U))     # True   (3.10+)
print(isinstance(3.0, U))   # False — but no assignment was ever checked

Here is the part that makes unions a superpower rather than a chore: the asymmetry of the seam. A union is introduced at a boundary. A function declares def find_user(id) -> User | None, and from that one honest signature, the obligation to handle None propagates outward to every caller, forever. The checker turns a single truthful return type into enforced discipline everywhere the value flows downstream. Compare the pre-hints world. A None-returning function was a landmine, documented at best in a docstring nobody opened, and the crash surfaced far from the function that planted it. With -> User | None, the person who knows the function can miss states it once, at the source. The type system then carries that warning to everyone who ever touches the result.

A union is a name that might be one of several types. But how does a list[int] remember its elements are int deep in code that never saw a single literal? Types that carry other types: generics. →

05Generics: types parameterized by types

You have already leaned on this without naming it. You pulled a value out of a list[int] and the checker knew it was an int. It let you write x + 1 with no cast, no question. Then you pulled from a bare list, unparameterized, and everything came out untyped, so nothing downstream was checked. Somewhere a container is carrying its element type through code that never saw the elements. That carrying is what makes types survive being stored in and fetched from collections — exactly where types otherwise go to die. It's called a generic.

A generic is a type with a hole in it. list is really list[T], where T is a type parameter — a placeholder. Writing list[int] substitutes int for T and yields a concrete static type. The checker implements the hole with a TypeVar, and the magic is that the same variable can appear in more than one spot, tying them together:

from typing import TypeVar
T = TypeVar('T')

def first(xs: list[T]) -> T:      # same T in and out: element type == return type
    return xs[0]

n = first([1, 2, 3])   # arg is list[int] -> unify T := int -> n: int
s = first(["a", "b"])     # arg is list[str] -> unify T := str -> s: str

Follow the checker's move on first([1, 2, 3]). It reads the argument's static type, list[int], and sets it against the parameter's declared type, list[T]. Then it solves for the placeholder: T := int. That step is called unification — matching a pattern with a hole against a concrete type and reading off what the hole must be. Having bound T = int, it substitutes into the return type T and concludes the result is int. This is parametric polymorphism: one definition serving every element type. The machinery is type inference by unification, the same core idea as Hindley-Milner, bent to fit Python. And every bit of it is symbol manipulation at check time, with zero runtime cost.

Now the case you actually hit daily — dict, generic in two parameters, dict[K, V]. Take our running example, a table of durations:

durations: dict[str, int] = {"Blinding Lights": 200, "Titanium": 245}
total = durations["Blinding Lights"] + durations["Titanium"]
# dict.__getitem__ stub:  (self: dict[K, V], key: K) -> V
# with K=str, V=int the lookup's result type is V = int, so total: int

The checker knew durations["Blinding Lights"] was an int without seeing 200. Indexing invokes dict.__getitem__, whose typeshed stub reads (self: dict[K, V], key: K) -> V. With K = str and V = int bound from the annotation, the return type resolves to V = int. The parameter threaded straight through the lookup. That is the entire reason a value can be fetched from deep inside a collection and still arrive with a known type.

you type
# generic_errors.py -- four honest mistakes. python runs it without a word.
titles: list[str] = ["Blinding Lights", 340]        # an int in a list of str
durations: dict[str, float] = {"Levels": "340"}     # a str where float was promised
pair: tuple[str, int] = ("Levels", 340, 1)          # three slots, two declared
counts: tuple[int, ...] = (1, 2, 3, 4, 5)           # any length is fine here
titles.append(340)                                  # the same mistake, later


# ---------- the terminal ----------
$ python generic_errors.py
$ echo $?
$ python -m mypy generic_errors.py

you see
$ python generic_errors.py

$ echo $?
0

$ python -m mypy generic_errors.py
generic_errors.py:1: error: List item 1 has incompatible type "int";
    expected "str"  [list-item]
generic_errors.py:2: error: Dict entry 0 has incompatible type "str":
    "str"; expected "str": "float"  [dict-item]
generic_errors.py:3: error: Incompatible types in assignment (expression
    has type "tuple[str, int, int]", variable has type "tuple[str, int]")
    [assignment]
generic_errors.py:5: error: Argument 1 to "append" of "list" has
    incompatible type "int"; expected "str"  [arg-type]
Found 4 errors in 1 file (checked 1 source file)

And now the metal-up truth that keeps you honest, because it is genuinely surprising. list[int] at runtime is a real object, a types.GenericAlias, built by list.__class_getitem__(int). You can print it, and it has fields: list[int].__origin__ is list, and list[int].__args__ == (int,). But the interpreter erases the parameter for actual objects. The list [1, 2, 3] keeps no memory of int. Ask type([1, 2, 3]) and you get plain list. The [int] exists only as annotation metadata, never as a property of the container that holds the values.

GA = dict[str, int]
print(type(GA))        # <class 'types.GenericAlias'> — the parameterization is a real object
print(GA.__origin__)   # <class 'dict'>
print(GA.__args__)     # (<class 'str'>, <class 'int'>)
print(type({"a": 1}))  # <class 'dict'> — the actual object erased K and V

So generics are check-time substitution over runtime-erased parameters — fiercely powerful in the static world, invisible in the dynamic one. The modern spelling drops the boilerplate: PEP 695 (3.12) lets you write def first[T](xs: list[T]) -> T and class Box[T]: with the type parameter declared inline, no separate TypeVar and no Generic[T] base. Same unification underneath, less ceremony on top.

you type
# shapes_errors.py -- four wrong shapes. python builds every one of them.
from dataclasses import dataclass
from typing import TypedDict

Seconds = int                           # the plain alias -- no version worries


class TrackDict(TypedDict):
    title: str
    seconds: Seconds


@dataclass
class Track:
    title: str
    seconds: Seconds


ok: TrackDict = {"title": "Levels", "seconds": 340}
typo: TrackDict = {"title": "Levels", "secs": 340}      # key misspelled
short: TrackDict = {"title": "Levels"}                  # a key is missing
bad = Track("Levels", "340")                            # a str into an int field

print(ok["seconds"], bad)
print(bad.seconds + 1)


# ---------- the terminal ----------
$ python -m mypy shapes_errors.py
$ python shapes_errors.py

you see
$ python -m mypy shapes_errors.py
shapes_errors.py:19: error: Missing key "seconds" for TypedDict
    "TrackDict"  [typeddict-item]
shapes_errors.py:19: error: Extra key "secs" for TypedDict
    "TrackDict"  [typeddict-unknown-key]
shapes_errors.py:20: error: Missing key "seconds" for TypedDict
    "TrackDict"  [typeddict-item]
shapes_errors.py:21: error: Argument 2 to "Track" has incompatible
    type "str"; expected "int"  [arg-type]
Found 4 errors in 1 file (checked 1 source file)

$ python shapes_errors.py
340 Track(title='Levels', seconds='340')
Traceback (most recent call last):
  File "C:\tmp\ch23lang\shapes_errors.py", line 24, in <module>
    print(bad.seconds + 1)
          ~~~~~~~~~~~~^~~
TypeError: can only concatenate str (not "int") to str

# ---------- annotate_this.py  (what you were given) ----------
"""annotate_this.py -- three defs, no hints. Annotate every seam."""


def as_clock(seconds):
    minutes, secs = divmod(seconds, 60)
    return f"{minutes}:{secs:02d}"


def longest(library):
    best = None
    for title, secs in library:
        if best is None or secs > best[1]:
            best = (title, secs)
    return best


def clock_table(library):
    return {title: as_clock(secs) for title, secs in library}


$ python -m mypy annotate_this.py
Success: no issues found in 1 source file

# Read that again. Three unannotated defs, and mypy has NOTHING to say --
# because by default it does not check the body of a function with no
# annotations. "Success" here means "I did not look."


# ---------- annotate_this_solved.py ----------
"""annotate_this_solved.py -- the same three defs, annotated at the seams."""

Track = tuple[str, int]                 # a row is (title, seconds)


def as_clock(seconds: int) -> str:
    minutes, secs = divmod(seconds, 60)
    return f"{minutes}:{secs:02d}"


def longest(library: list[Track]) -> Track | None:
    best: Track | None = None           # the ONE hint a body needs
    for title, secs in library:
        if best is None or secs > best[1]:
            best = (title, secs)
    return best


def clock_table(library: list[Track]) -> dict[str, str]:
    return {title: as_clock(secs) for title, secs in library}


LIBRARY: list[Track] = [("Blinding Lights", 200), ("Titanium", 245), ("Levels", 340)]

top = longest(LIBRARY)
if top is None:
    print("empty library")
else:
    print("longest:", top[0], as_clock(top[1]))
print(clock_table(LIBRARY))
print(longest([]))


$ python -m mypy annotate_this_solved.py
Success: no issues found in 1 source file

$ python annotate_this_solved.py
longest: Levels 5:40
{'Blinding Lights': '3:20', 'Titanium': '4:05', 'Levels': '5:40'}
None


# The reasoning, seam by seam.
#
# as_clock(seconds: int) -> str
#   divmod(seconds, 60) and the :02d format both demand a number, and an
#   f-string always produces str. Both hints were already true; writing them
#   down just moves the truth to where a caller can read it.
#
# longest(library: list[Track]) -> Track | None
#   THE one that matters. Read the body: `best` starts as None, and if the
#   loop never runs, None is what comes back. So `-> Track` would be a lie
#   for exactly one input -- the empty list -- which is the input nobody
#   tests. `Track | None` states it, and then forces every caller to say
#   what an empty library should mean.
#
# best: Track | None = None
#   The one hint inside a body. Without it, mypy infers `best: None` from the
#   first assignment and then rejects the tuple on the next line. Annotate the
#   variable that is DECLARED empty and later filled -- that is the general rule.
#
# clock_table(library: list[Track]) -> dict[str, str]
#   Both parameters matter. Keys are titles (str) and values come out of
#   as_clock, which returns str. dict[str, str], not dict[str, int] -- the
#   whole point of the function is that the seconds became a clock.


# ---------- probes.py: the three probes, and their verdicts ----------
# (the same Track, as_clock and longest as above, then:)
LIBRARY: list[Track] = [("Blinding Lights", 200), ("Levels", 340)]
print(longest(LIBRARY)[0])              # flagged -- and it WORKS at runtime
print(longest([])[0])                   # flagged -- and it really crashes
print(as_clock("245"))                  # flagged -- str where int promised


$ python -m mypy probes.py
probes.py:19: error: Value of type "tuple[str, int] | None" is not
    indexable  [index]
probes.py:20: error: Value of type "tuple[str, int] | None" is not
    indexable  [index]
probes.py:21: error: Argument 1 to "as_clock" has incompatible type
    "str"; expected "int"  [arg-type]
Found 3 errors in 1 file (checked 1 source file)

$ python probes.py
Levels
Traceback (most recent call last):
  File "C:\tmp\ch23lang\ex\probes.py", line 20, in <module>
    print(longest([])[0])                   # flagged -- and it really crashes
          ~~~~~~~~~~~^^^
TypeError: 'NoneType' object is not subscriptable


# Why the checker is right about line 19, which works.
#
# Line 19 and line 20 are the SAME expression. The only difference is the
# list you happened to pass, and the checker does not get to see your data --
# it reasons about every list you could ever pass. `longest(...)` returns
# `Track | None` for all of them, so the subscript is unsafe for all of them.
# Line 19 passing today is luck about an argument, not a property of the code.
# The guard is four words:
#
#     top = longest(LIBRARY)
#     if top is not None:
#         print(top[0])

Generics let types ride inside containers. But Vol 1's real dispatch was duck typing — "if it quacks" — and nominal hints betray that. Next: how to type-check duck typing itself. →

06Protocols: structural typing the checker can verify

Vol 1 sold you on Python's real nature: dispatch is duck typing. for x in thing works on anything with an __iter__. len(x) works on anything with a __len__. No inheritance, no declared kinship, no permission asked. The interpreter looks up a method slot on the object's type and calls it. Lineage never enters the room. And then the first hints you wrote quietly betrayed all of it. def f(x: Animal) demands that x descend from a specific class, an ancestry the duck-typed runtime never cared about. You need a way to write hints that say "anything shaped like this," so the static world finally matches the dynamic world's "if it quacks." That is a Protocol.

There are two flavors of subtyping, and naming them clears the fog. Nominal subtyping is the default in Java, C++, and Python's own isinstance-against-a-base. It says X is a subtype of Y exactly when X explicitly inherits from Y, so it's about declared ancestry. Structural subtyping says X is a subtype of Y exactly when X has the members Y requires, so it's about shape and ignores lineage entirely. Now the observation that reframes the whole language: Python's runtime dispatch is structural to the bone. len(x) calls x.__len__() and for calls x.__iter__(), so the interpreter checks for the slot on the object's type, never for a base class. The runtime has always been structural, and it was only the hints that pretended otherwise.

typing.Protocol brings that same structural rule to the checker. You declare a shape, and any class with matching members satisfies it — no inheritance, verified purely by member presence and signature compatibility:

from typing import Protocol

class Quacker(Protocol):        # a SHAPE, not a base class to inherit
    def quack(self) -> str: ...

class Duck:                     # does NOT inherit Quacker
    def quack(self) -> str: return "quack"

class Person:                   # also unrelated
    def quack(self) -> str: return "i am quacking"

def make_noise(q: Quacker) -> str:   # accepts anything shaped like Quacker
    return q.quack()

make_noise(Duck())      # checks: Duck HAS quack() -> str  -> OK
make_noise(Person())    # checks: Person HAS quack() -> str -> OK, no shared base

Neither Duck nor Person inherits from Quacker, and both type-check. The checker asked one question — does it have a quack returning str? — and both answered yes. This is the checker's version of "if it quacks, it's a duck," verified statically by member matching. You are no longer choosing between duck typing and type checking — you are type-checking duck typing.

Now the honest caveat, and it matters. Protocols are checked structurally at static time, and at runtime they normally do nothing at all. But mark one @runtime_checkable and you may write isinstance(duck, Quacker). Here is the trap: that runtime isinstance only checks that the attribute names exist, and it does not verify signatures or return types. It's a shallow hasattr-style sweep. A class with a quack attribute of the wrong signature, even a quack that's an integer, will pass isinstance(x, Quacker) while failing the static check. The static verification is strictly deeper than the runtime one:

from typing import Protocol, runtime_checkable

@runtime_checkable
class Quacker(Protocol):
    def quack(self) -> str: ...

class Fake:
    quack = 42              # an int, not even a method

print(isinstance(Fake(), Quacker))  # True! name exists -> shallow check passes
# a static checker would REJECT Fake as a Quacker: 42 is not () -> str

Contrast this with the ABCs in collections.abc, which are the nominal path. You register or inherit to belong, though several use __subclasshook__ to add duck-style checks on top. And notice how much of the standard library was Protocol-shaped all along — Iterable, Iterator, Sized, SupportsInt. These are the checker's formal names for the dunder contracts Vol 1 leaned on the whole time. Sized is just "has __len__." Iterable is just "has __iter__." The duck contracts were real. Protocols finally gave them a spelling the static world can verify.

# ---------- config_before.py  (what you start with) ----------
"""config_before.py -- a settings dict passed everywhere, shaped by nothing."""
CONFIG = {
    "name": "kitchen jukebox",
    "volume": 7,
    "shuffle": True,
    "device": None,
}


def describe(cfg):
    line = cfg["name"] + " at volume " + str(cfg["volume"])
    if cfg["shuffle"]:
        line += " (shuffling)"
    if cfg["device"] is not None:
        line += " -> " + cfg["device"]
    return line


print(describe(CONFIG))
print(describe({"name": "loft", "volume": "9", "shuffle": False, "device": None}))


$ python config_before.py
kitchen jukebox at volume 7 (shuffling)
loft at volume 9

$ python -m mypy config_before.py
Success: no issues found in 1 source file

# Why "Success" -- describe() has no annotations, so mypy skips its body
# entirely and treats every call to it as returning Any. The dict was never
# described, and the function was never checked. Two holes, one silence.


# ---------- config_after.py  (the shape, written once) ----------
"""config_after.py -- the same dict, with its shape written down once."""
from typing import NotRequired, TypedDict


class Config(TypedDict):
    name: str
    volume: int
    shuffle: bool
    device: str | None
    theme: NotRequired[str]              # may be absent; must be str if present


CONFIG: Config = {
    "name": "kitchen jukebox",
    "volume": 7,
    "shuffle": True,
    "device": None,
}


def describe(cfg: Config) -> str:
    line = f"{cfg['name']} at volume {cfg['volume']}"
    if cfg["shuffle"]:
        line += " (shuffling)"
    if cfg["device"] is not None:        # narrows str | None to str
        line += " -> " + cfg["device"]
    return line


print(describe(CONFIG))
print(describe({"name": "loft", "volume": 9, "shuffle": False,
                "device": "speaker-2", "theme": "dark"}))


$ python -m mypy config_after.py
Success: no issues found in 1 source file

$ python config_after.py
kitchen jukebox at volume 7 (shuffling)
loft at volume 9 -> speaker-2


# ---------- config_broken.py  (six ways to break it) ----------
from config_after import CONFIG, Config, describe

bad: Config = {"name": "loft", "volume": "9", "shuffle": False, "device": None}
missing: Config = {"name": "loft", "volume": 9, "shuffle": False}
typo: Config = {"name": "loft", "volume": 9, "shufle": False, "device": None}

print(CONFIG["volme"])
CONFIG["volume"] = "9"
print(describe(bad))


$ python -m mypy config_broken.py
config_broken.py:3: error: Incompatible types (expression has type "str",
    TypedDict item "volume" has type "int")  [typeddict-item]
config_broken.py:4: error: Missing key "device" for TypedDict "Config"
    [typeddict-item]
config_broken.py:5: error: Missing key "shuffle" for TypedDict "Config"
    [typeddict-item]
config_broken.py:5: error: Extra key "shufle" for TypedDict "Config"
    [typeddict-unknown-key]
config_broken.py:7: error: TypedDict "Config" has no key "volme"
    [typeddict-item]
config_broken.py:7: note: Did you mean "volume"?
config_broken.py:8: error: Value of "volume" has incompatible type "str";
    expected "int"  [typeddict-item]
Found 6 errors in 1 file (checked 1 source file)


# The answers.
#
# 1. device: str | None  vs  theme: NotRequired[str]
#    Two different questions. `device` is always PRESENT and may hold None --
#    every reader must handle the empty case. `theme` may be ABSENT: the key
#    might not exist at all, so `cfg["theme"]` is what has to be guarded, with
#    cfg.get("theme") or an "in" check. Marking device NotRequired would be
#    wrong: it is always there. Marking theme  str | None  would be wrong too:
#    it would force every config to carry a theme key holding None.
#
# 2. The narrowing in describe() is the Section 3 machinery, applied to a
#    dict value. After `if cfg["device"] is not None:`, mypy holds cfg["device"]
#    as plain str on that edge -- which is exactly what `" -> " + ...` needs.
#    The sentinel check and the type proof are the same three words.
#
# 3. Which would a test have caught, and when?
#    The typo on line 5 and the misread on line 7 produce KeyError only if
#    that key is ever touched at runtime -- so a test catches them only if it
#    exercises that branch, on that config, in that environment. The "9" on
#    line 3 catches nothing at all: it prints happily, exactly as the original
#    program did, and surfaces months later as `TypeError: '>' not supported
#    between instances of 'str' and 'int'` inside some volume comparison.
#    mypy found all six in 200 milliseconds without running a line, and the
#    "Did you mean volume?" note is the giveaway: it is not grepping for
#    suspicious text, it holds the actual set of keys this dict is allowed
#    to have and compared yours against it.

You now hold power tools — unions, generics, protocols, narrowing. The temptation is to annotate everything. Where do hints actually buy safety, and where are they noise? Hint the seams. →

07Hint the seams, infer the rest

Now the overcorrection, because you can feel it coming. You have generics, unions, protocols, narrowing, and the instinct is to annotate everything, stapling : int onto every throwaway loop counter until readable code turns into a thicket of ceremony. That is not rigor — it's noise, and it buries the hints that actually matter under the ones that don't. You need a defensible policy: where do annotations buy safety, and where would the checker have known anyway? The answer isn't taste but structure, and it names the thing this entire volume has been about: the seams.

Start from what the checker already knows for free. Inference is strong within a function body, because there it can see every assignment. count = 0 needs no : int — the checker read the literal and knows. names = [] and total = a + b are all inferred with full confidence from their initializers. Inside a single function, the checker is watching every line, so it needs no help. Then ask the sharp question: where does inference go blind? It goes blind exactly at the boundaries it cannot see across. A function parameter has no initializer the callee can inspect — the value arrives from an unknown caller the checker isn't currently reading. A return type is what every caller must trust without reading the body. A dataclass field is the shape other code constructs and reads across the codebase. A module-level export is what other files consume sight-unseen. These boundaries — signatures, fields, exports — are the seams, and a hint at a seam is a contract.

you type
# gradual.py -- Any is a hole you can see through; object is a door you must open
from typing import Any

SOURCE: str = "gradual.py"


def load_any() -> Any:                  # "trust me" -- checking switches OFF
    return {"title": "Levels", "seconds": 340}


def load_obj() -> object:               # "unknown" -- checking stays ON
    return {"title": "Levels", "seconds": 340}


a = load_any()
o = load_obj()

print("Any, indexed     :", a["title"])
print("object, indexed  :", o["title"])     # checker: ERROR. runtime: fine.
print("hints on load_any:", load_any.__annotations__)
print("hints on load_obj:", load_obj.__annotations__)
print("module hints     :", __annotations__)
try:
    a.whatever_i_like                       # checker: SILENT
except AttributeError as exc:
    print("Any let it past  :", exc)


# ---------- the terminal ----------
$ python gradual.py
$ python -m mypy gradual.py

you see
$ python gradual.py
Any, indexed     : Levels
object, indexed  : Levels
hints on load_any: {'return': typing.Any}
hints on load_obj: {'return': <class 'object'>}
module hints     : {'SOURCE': <class 'str'>}
Any let it past  : 'dict' object has no attribute 'whatever_i_like'

$ python -m mypy gradual.py
gradual.py:19: error: Value of type "object" is not indexable  [index]
Found 1 error in 1 file (checked 1 source file)

Why a contract and not just an annotation? Because a hint at a seam lets the checker verify the two sides independently. The callee is checked against its own body, every caller is checked against the signature, and neither has to re-derive the whole program. That is precisely the modularity that lets a compiler check files separately. You state the interface once, and both sides are held to it in isolation. So the policy falls out cleanly: hint every signature (params and return), every dataclass field, every module boundary; let inference handle short-lived locals. Hint the arrows between the boxes. Leave the insides to the checker.

def total_seconds(tracks: dict[str, int]) -> int:   # SEAM: hint params + return
    running = 0                    # local: inferred int, no hint needed
    for secs in tracks.values():   # local: inferred int, no hint needed
        running += secs
    return running

def total_seconds(tracks):        # NO seam hints -> to mypy, an unchecked hole:
    running = 0                    # body skipped by default (untyped def)
    return running

And here the failure modes get teeth. First: an unannotated function is, to many checkers, invisible. By default mypy does not type-check the body of a function with no annotations, so a missing signature silently switches checking off for that whole region. (--check-untyped-defs makes it check those bodies anyway. --disallow-untyped-defs makes it complain about the missing hints in the first place.) So the second total_seconds above isn't merely under-documented — it's a hole where bugs pass unexamined. Second: Any is the escape hatch that poisons. Any is compatible with everything in both directions — it accepts anything and is accepted as anything. So a single Any at a seam propagates downstream and erases checking everywhere the value flows:

from typing import Any

def load() -> Any:              # the poison enters at the seam
    return {"secs": 200}

x = load()
x.no_such_method()          # checker: silent. runtime: AttributeError

def load2() -> object:          # 'unknown' done right
    return {"secs": 200}

y = load2()
y.no_such_method()          # checker: ERROR — object has no such method; narrow first

When you mean "I don't know the type," reach for object, not Any. object is the safe top of the hierarchy. It accepts any value but demands you narrow before you use it, so it preserves checking instead of dissolving it. Any says "stop checking." object says "prove what it is first." And third, the softest but most durable point: at a seam, the signature is the interface. It's the contract readers and tools consume, the living documentation that can't drift out of date because the checker enforces it. This echoes the thread from Vol 1's very first object header: the type is metadata the system reads. A local's type is read by the checker for a few lines and forgotten. A seam's type is read by every caller, every reader, and every tool, forever.

# ================= BEFORE: before/tracks.py =================
"""tracks.py -- the jukebox module from Ch 19 and 21. Not one annotation."""

LIBRARY = [("Blinding Lights", 200), ("Titanium", 245), ("Levels", 340)]


def as_clock(seconds):
    minutes, secs = divmod(seconds, 60)
    return f"{minutes}:{secs:02d}"


def total_seconds(library):
    return sum(secs for _title, secs in library)


def find(title, library):
    for row in library:
        if row[0] == title:
            return row
    return None


def summary(library):
    return f"{len(library)} tracks, {as_clock(total_seconds(library))}"


# ================= BEFORE: before/report.py =================
"""report.py -- the caller, with two bugs planted in plain sight."""
from tracks import LIBRARY, as_clock, find, summary

print(summary(LIBRARY))

typed_in = "245"                        # BUG 1: came off input(), still a str
print(as_clock(typed_in))

missing = find("Nope", LIBRARY)         # BUG 2: a miss returns None
print(missing[0])


# ================= AFTER: after/tracks.py =================
"""tracks.py -- the same module, annotated at every seam."""

Track = tuple[str, int]                 # one alias: a row is (title, seconds)

LIBRARY: list[Track] = [
    ("Blinding Lights", 200),
    ("Titanium", 245),
    ("Levels", 340),
]


def as_clock(seconds: int) -> str:
    minutes, secs = divmod(seconds, 60)
    return f"{minutes}:{secs:02d}"


def total_seconds(library: list[Track]) -> int:
    return sum(secs for _title, secs in library)


def find(title: str, library: list[Track]) -> Track | None:
    for row in library:
        if row[0] == title:
            return row
    return None


def summary(library: list[Track]) -> str:
    return f"{len(library)} tracks, {as_clock(total_seconds(library))}"


# after/report.py is byte-for-byte the BEFORE one. Do not change it yet.


# ================= THE FIX: fixed/report.py =================
"""report.py -- both bugs fixed the way the types asked for."""
from tracks import LIBRARY, as_clock, find, summary

print(summary(LIBRARY))

typed_in = "245"
print(as_clock(int(typed_in)))          # FIX 1: convert at the seam

missing = find("Nope", LIBRARY)
if missing is None:                     # FIX 2: the guard the type demanded
    print("not in the library")
else:
    print(missing[0])


# ---------- the terminal ----------
$ cd before && python -m mypy tracks.py report.py
$ python report.py
$ cd ../after && python -m mypy tracks.py report.py
$ cd ../fixed && python -m mypy tracks.py report.py
$ python report.py

$ cd before && python -m mypy tracks.py report.py
Success: no issues found in 2 source files

$ python report.py
3 tracks, 13:05
Traceback (most recent call last):
  File "C:\tmp\ch23lang\before\report.py", line 7, in <module>
    print(as_clock(typed_in))
          ^^^^^^^^^^^^^^^^^^
  File "C:\tmp\ch23lang\before\tracks.py", line 7, in as_clock
    minutes, secs = divmod(seconds, 60)
                    ^^^^^^^^^^^^^^^^^^^
TypeError: unsupported operand type(s) for divmod(): 'str' and 'int'

$ cd ../after && python -m mypy tracks.py report.py
report.py:7: error: Argument 1 to "as_clock" has incompatible type "str";
    expected "int"  [arg-type]
report.py:10: error: Value of type "tuple[str, int] | None" is not
    indexable  [index]
Found 2 errors in 1 file (checked 2 source files)

$ cd ../fixed && python -m mypy tracks.py report.py
Success: no issues found in 2 source files

$ python report.py
3 tracks, 13:05
4:05
not in the library

That closes the arc. Volume 2 has been the physics of boundaries — the disk, other encodings, other people's code, future-you, other cores, other processes — and the one law under all of them: what crosses a boundary is bytes and contracts, never the live thing itself. Types matter most at exactly those boundaries. That is where the object leaves the reach of the code that made it and arrives somewhere that must trust a promise. Hint the seams — the arrows between functions and files — and let inference handle the insides. The seams are what this book has been about since the pointer in the object header.

You've reached the seam between Python's two type systems and learned to stand on the right side of it. The runtime carries the object; the checker carries the contract; and the whole discipline is knowing which line reads which. →