Types and data modeling

None, on purpose

"No value" is None, like a box left empty on a form. It's the source of a famous class of crash: 'NoneType' object has no attribute .... The fix is to be explicit. Hint it as str | None, and handle the None case right where the value is used:

def greeting(name: str | None) -> str:
    if name is None:
        return "Hi there"
    return f"Hi {name.strip().title()}"

print(greeting(None), "|", greeting("  ada  "))

A type checker then warns you wherever you forget the check.

Parse, don't validate

Here's the most useful idea in this lesson. An airport checks your passport once, at the border. After that, nobody inside asks whether you're allowed to be there.

Untrusted data enters at the edges of your program: a request body, a CSV row, a model's JSON. At that edge, convert it into your typed objects once. Check everything and fail loudly with a clear message. Then the inside of your program only ever sees clean Order objects, and never has to wonder whether qty is a string.

This is called parse, don't validate. A validator answers "is this OK?" and hands back the same messy dict. A parser hands back a new, trustworthy object, or refuses.

In plain words: check once at the door, and turn what comes in into something the rest of your code can trust.

import json
from dataclasses import dataclass

@dataclass(frozen=True)
class Item:
    sku: str
    qty: int
    unit_price: float

def parse_item(raw: dict) -> Item:
    try:
        sku = str(raw["sku"]).strip()
        qty = int(raw["qty"])
        unit_price = float(raw["unit_price"])
    except KeyError as missing:
        raise ValueError(f"item is missing {missing}") from None
    except (TypeError, ValueError):
        raise ValueError(f"item has a bad number: {raw}") from None
    if not sku:
        raise ValueError("item sku is empty")
    if qty < 1:
        raise ValueError(f"item qty must be at least 1, got {qty}")
    return Item(sku, qty, unit_price)

model_reply = '{"sku": "TENT-2", "qty": "2", "unit_price": "249.00"}'
print(parse_item(json.loads(model_reply)))
for bad in [{"sku": "MUG", "qty": 0, "unit_price": 3}, {"sku": "MUG", "unit_price": 3}]:
    try:
        parse_item(bad)
    except ValueError as err:
        print("rejected:", err)

What type hints do and don't do

Here's a surprise for most people: Python ignores type hints when it runs your code.

def line_total(price: float, qty: int) -> float:
    return price * qty

print(line_total("ab", 3))

This runs without complaint and prints ababab, which is nonsense. Hints are checked by a separate tool, such as mypy or pyright, before the code runs. In your editor they catch the mistake as you type. In production they do nothing, so they can't protect you from bad data arriving at run time. That needs validation, which is where parsing comes in.

Why raw dictionaries spread problems

Suppose an API gives you a dictionary, and you pass it deep into your program. Every function now has to wonder: is "total" there? Is it a number or text? Soon you have the same checks everywhere, some of them missing, and a misspelled key that only fails at 2 a.m.

The fix is to convert once, at the edge of your program, into a dataclass. If the conversion succeeds, everything further in can trust what it holds, and your tools can check every use of it.

Make wrong choices impossible

Plain strings are easy to mistype. status = "shiped" raises no error and quietly never matches anything. An Enum limits the choices, so a typo fails at once.

None deserves the same care. When a value might be missing, say so in the type, as str | None. Then the checker makes you handle that case where it matters, not ten calls later, where the crash shows up far from its cause.

Adding types to old code

You don't need to do it all at once, any more than you'd label a whole garage in one afternoon. Start with the functions other code calls most, and the ones that have caused bugs. Run the checker in CI so that new code stays clean, and let the old code catch up as you touch it.

A good sign you've gone wrong is Any everywhere, since Any switches checking off. Another is a type so complicated nobody can read it. When that happens, a small dataclass usually says the same thing more clearly. Types are there to help the next reader, so keep them readable, and remove any that no longer tell the truth.