Python Type Checking and Type Hinting

Annotations state what a function expects and returns:

def parcel_cost(weight_kg: float, express: bool = False) -> float:
    rate = 4.5 if express else 2.0
    return round(weight_kg * rate, 2)

Install and run a checker on your project:

python -m pip install mypy
mypy depot/

mypy reports each problem with a file, line and explanation, and exits with a non-zero status, which makes it easy to run in continuous integration. Functions without annotations are skipped by default, so you can add hints gradually, module by module; --strict turns on the full set of checks once a codebase is ready.

Annotations remain hints: parcel_cost("3") still runs until the multiplication fails, because Python doesn't check them when the program runs. If you need run-time validation of external data, use explicit checks or a library such as Pydantic.

A value that may be absent is written X | None (or Optional[X] before Python 3.10). The checker then insists that you handle the None case before using the value:

def find_weight(parcels: dict[str, float], code: str) -> float | None:
    return parcels.get(code)

weight = find_weight({"P1": 2.5}, "P9")
print(weight * 2)          # mypy: Unsupported operand types for * ("None" and "int")

Fix it by narrowing: a check that rules out None, after which the checker knows the type is float:

if weight is None:
    print("Unknown parcel")
else:
    print(weight * 2)      # weight is float here

isinstance() checks, early returns and assert weight is not None narrow types in the same way. This catches the most common Python crash, 'NoneType' object has no attribute... or unsupported operand errors, at the desk instead of in production.

Collection annotations describe the contents as well as the container:

For function parameters, accepting the most general type you need makes functions more reusable: def total(weights: Iterable[float]) works with lists, tuples and generators. Return the specific type you build.

For dictionaries with fixed keys, such as a parsed JSON record, TypedDict describes each key's type:

from typing import TypedDict

class Parcel(TypedDict):
    code: str
    weight: float

Annotations never convert data: ["2.5", "1.0"] annotated as list[float] is still a list of strings at run time.

A Protocol describes the methods an object must have, without requiring a common base class. It's static duck typing:

from typing import Protocol

class Weighable(Protocol):
    def weight_kg(self) -> float: ...

class Box:
    def weight_kg(self) -> float:
        return 3.2

class Envelope:
    def weight_kg(self) -> float:
        return 0.1

def total_weight(items: list[Weighable]) -> float:
    return sum(item.weight_kg() for item in items)

Box and Envelope don't inherit from Weighable, yet the checker accepts them because their methods match. A class whose weight_kg returned a string, or that lacked the method, would be reported. Protocols are how type checkers describe built-in behaviours like "anything with __len__" (Sized), and they keep code flexible while still catching mistakes.

Task: annotate package data, narrow an optional value and run a configured static checker on an incompatible call.

# depot.py
def find_weight(parcels: dict[str, float], code: str) -> float | None:
    return parcels.get(code)

def postage(weight: float) -> float:
    return round(weight * 2.0, 2)

parcels = {"P1": 2.5, "P2": 0.4}
w = find_weight(parcels, "P2")
if w is not None:
    print(postage(w))       # 0.8
postage("heavy")            # mypy reports this line

Running mypy depot.py reports Argument 1 to "postage" has incompatible type "str"; expected "float" for the last line, while the narrowed call passes. For the worked check: do annotations alone enforce parameter types at run time? No. The program runs until the bad value actually causes an error.

The mypy documentation has a cheat sheet and guides for gradual adoption, and the typing module reference covers Protocol, TypedDict and more. Continue with dependency management and revisit PEP 8 style. Practise with the Python exercises and Python quiz.