Lesson 15. Annotations Are Claims

Mission link: A type hint is a claim a separate tool can prove or refute. Understanding that the interpreter has no opinion about it is what stops annotations from being decoration and starts them being verification.
Primary source: The Python Standard Library, typing
Prerequisites: Lesson 6, Lesson 12

Warm-up

1. ▢ Lesson 12: what does @dataclass do with the annotation in amount: float?

2. ▢ What do you expect this to do?

   def double(n: int) -> int:
       return n * 2
   
   print(double("ab"))
   

Know this

An annotation is syntax that records a claim. The interpreter stores it and enforces nothing:

def double(n: int) -> int:
    return n * 2

double("ab")                     # runs, returns "abab"

That is not a flaw, it is the design. Python's type system is gradual: annotations are written where they pay, checked by a separate tool, and absent everywhere else. Nothing about the language changes when you add them.

What they buy, in order of value:

1. A checker rejects programs that were going to fail, before they run.
2. An editor knows what a name is, so completion and rename work.
3. The signature documents itself, and the documentation cannot drift, because the checker fails when it does.

The current spellings

def summarise(
    orders: list[Order],                 # not List, since 3.9
    country: str | None = None,          # not Optional[str], since 3.10
    limits: dict[str, int] | None = None,
) -> tuple[int, float]:
    ...

The old spellings still work and still appear everywhere in existing code. Read them, write the new ones.

When the annotation is evaluated

This is the one part with a real version boundary, and it changed recently.

class Node:
    def child(self) -> Node:             # refers to Node inside its own body
        ...

From Python 3.14, annotations are evaluated lazily (PEP 649). The line above is fine, and a NameError for a genuinely missing name surfaces only when something reads the annotation.

Before 3.14, annotations were evaluated at definition time, so that code raised NameError, and the two workarounds were quoting the name, -> "Node", or putting from __future__ import annotations at the top of the file, which turned every annotation in the module into a string. Both are still valid, both are still all over real codebases, and a library supporting older versions still needs one of them.

Practical consequence: annotations are for a checker, and a checker never evaluates them. Anything that reads them at run time, such as a dataclass-like decorator or a validation library, does the evaluation itself, which is why those libraries care about this and ordinary code does not.

Any is a hole, not a type

def parse(raw: str) -> Any:
    ...

user = parse(payload)
user.nmae                            # no error, from any checker, ever

Any means "stop checking here", and it propagates: everything derived from an Any is also unchecked. An unannotated function is an implicit Any in both directions, which is why a codebase can be half-annotated and get almost none of the benefit, and why stage-3 tooling has a flag for exactly that.

When the type is genuinely unknown, object is usually the honest answer. object accepts anything and permits almost nothing without narrowing, so the checker keeps working.

What to annotate, and what not to

Annotate:

• every parameter and return of a public function, -> None included
• dataclass fields and class attributes
• a container whose element type is not obvious from one line away
• anything the checker gets wrong, or wrong enough that you had to think

Do not annotate:

• local variables the checker can infer: count = 0 needs nothing
• self and cls
• a private one-line helper, unless the checker asks

-> None deserves its own line. A function with no annotations at all is invisible to a default checker configuration, so the single most valuable annotation in a codebase is often the return type on a procedure that returns nothing.

Take the general type, return the specific one

def total(orders: Iterable[Order]) -> float:      # accepts list, tuple, generator
    return sum(o.amount for o in orders)

def recent(orders: Iterable[Order]) -> list[Order]:   # callers get a real list
    ...

Iterable, Sequence, Mapping and Collection in parameters accept more callers, which lesson 8 already argued for on other grounds. Concrete list and dict in return types tell callers what they can do with the result. Declaring -> Iterable[Order] promises less, and is right when the function is a generator whose laziness is the point.

Two annotations that state intent

from typing import Final, ClassVar

MAX_RETRIES: Final = 3               # rebinding is an error a checker reports

class Session:
    registry: ClassVar[dict[str, "Session"]] = {}   # on the class, not per instance
    token: str

Final catches the accidental reassignment of a constant. ClassVar is the one that prevents a real bug: a dataclass would otherwise treat registry as a field with a shared mutable default, and lesson 12 covered what that costs.

Practice

1. ▢ Rewrite with current spellings.

   from typing import Dict, List, Optional, Union
   
   def group(rows: List[Dict[str, str]], key: Optional[str] = None) -> Dict[str, List[Union[int, str]]]:
       ...
   

def group(rows: list[dict[str, str]], key: str | None = None) -> dict[str, list[int | str]]:
    ...

2. ▢ This passes a strict checker. Explain why that is worthless.

   def load_config(path: str) -> Any:
       return json.loads(Path(path).read_text(encoding="utf-8"))
   
   config = load_config("app.json")
   timeout = config["timout"]["seconds"] * "3"
   

3. ▢ Which of these annotations is wrong or misleading?

   • a) def send(self, msg: str) -> None: on a method that returns nothing
   • b) def parse(raw: bytes) -> dict:
   • c) def total(orders: list[Order]) -> float: called with a generator
   • d) def find(id: int) -> Order: on a function that returns None when absent
   • e) count: int = 0 as a local variable

4. ▢ Why does this fail before Python 3.14, and give the two fixes that work on any version.

   class Tree:
       def leftmost(self) -> Tree:
           ...
   

5. ▢ A colleague adds annotations to one module and reports the checker found nothing. The module has forty functions, of which two are annotated. Explain.

6. ▢ What bug does ClassVar prevent here?

   @dataclass
   class Session:
       registry: dict[str, "Session"] = field(default_factory=dict)
   

Real-world reps

• [ ] Annotate one complete module, not one function. Every public signature, -> None included, and nothing else. That is the unit at which a checker starts finding things.
• [ ] Grep for -> Any and : Any in code you own. For each, decide whether the honest type is object, a TypedDict, or a real class.
• [ ] Find a function annotated -> X that can return None, and fix the annotation rather than the function. Then look at what the checker says about its callers.
• [ ] Search for List[, Dict[ and Optional[ and modernise one file. Note how many typing imports disappear.
• [ ] Tomorrow: add Final to one module-level constant and ClassVar to one class attribute, and read what the checker says.

Going further

• typing: the current spellings, and which older ones are deprecated
• Static Typing with Python: the specification and the practical guides, maintained with the type system
• PEP 484, Type Hints: the original design, and the explicit decision that annotations do not affect runtime behaviour
• PEP 585 and PEP 604: list[int] and int | None
• PEP 649, Deferred Evaluation of Annotations: what changed in Python 3.14, and why the old workarounds existed
• annotationlib: reading annotations at run time, for the libraries that must
• Resources

Not landing? Reread the primary source at the top, since this lesson compresses it and compression is where understanding leaks. Check the glossary for any term that felt slippery.

If the lesson itself is unclear rather than the material, that is a defect: open an issue.