Designing Data Contracts

This is the Layer 4 gate. We formalize the informal "contract" from Session 27 using type hints and dataclasses, catching shape mismatches automatically instead of hoping.

1. Learning Objective

2. Pre-Coding Quiz

Answer these before reading the concept explanation or writing any code. It is fine to get these wrong — that is the point. You need 4/5 to proceed to the lab.

3. The Concept — Data Contracts with Type Hints and Dataclasses

Type hints — documentation, not enforcement

A type hint tells readers (and tools like editors and type checkers) what type a value is expected to be. Python itself does not check this at runtime — it is a critical fact to internalize, since it is easy to assume otherwise.

def summary(country: dict) -> str:
    return f"{country['name']} ({country['region']})"

# This "should" be wrong according to the type hint, but Python runs it anyway:
print(summary(42))
# TypeError happens INSIDE the function body (42 is not subscriptable),
# not because the type hint was checked and enforced upfront

@dataclass — less boilerplate, same underlying class

A dataclass declares its fields with type hints, and Python auto-generates __init__ (and by default, __eq__) from those declarations — directly replacing Session 13's hand-written boilerplate.

from dataclasses import dataclass

@dataclass
class Country:
    name: str
    region: str
    population: int

kenya = Country(name="Kenya", region="Africa", population=54000000)
print(kenya.name)        # "Kenya" — same as before
print(kenya.population)  # 54000000

peru1 = Country(name="Peru", region="Americas", population=33000000)
peru2 = Country(name="Peru", region="Americas", population=33000000)
print(peru1 == peru2)  # True — free, field-by-field equality (Session 19's manual __eq__, generated automatically)

Type hints still don't stop bad values at construction

A dataclass will happily accept a value of the wrong type — the hint is not checked. This is why explicit validation, at the boundary where raw external data enters the program, is still necessary.

bad = Country(name="Kenya", region="Africa", population="fifty-four-million")
print(bad.population)  # "fifty-four-million" — a string, accepted without complaint!
# This will fail confusingly later, wherever population is actually used as a number

Validating the contract before construction

Combining Session 24's validation discipline with the dataclass gives us both convenience AND safety: check the raw dict's shape and types explicitly, THEN construct.

def validate_country_record(data):
    required = {"name": str, "region": str, "population": int}
    for key, expected_type in required.items():
        if key not in data:
            raise ValueError(f"missing required field: {key}")
        if not isinstance(data[key], expected_type):
            raise TypeError(f"{key} must be {expected_type.__name__}, got {type(data[key]).__name__}")
    return data

def build_country(data):
    validate_country_record(data)
    return Country(**data)

4. Lab

What you will build

A file called contracts_lab.py.

Step-by-step instructions

# contracts_lab.py
from dataclasses import dataclass

@dataclass
class Country:
    name: str
    region: str
    population: int

    def summary(self):
        return f"{self.name} ({self.region}): pop. {self.population:,}"

a = Country(name="Kenya", region="Africa", population=54000000)
b = Country(name="Kenya", region="Africa", population=54000000)
print("a == b:", a == b)   # True — generated automatically
print("a is b:", a is b)   # False — still separate objects

bad = Country(name="Kenya", region="Africa", population="not a number")
print(bad.population)              # accepted anyway!
print(type(bad.population))        # <class 'str'> — the hint did nothing to stop this

def validate_country_record(data):
    required = {"name": str, "region": str, "population": int}
    for key, expected_type in required.items():
        if key not in data:
            raise ValueError(f"missing required field: {key}")
        if not isinstance(data[key], expected_type):
            raise TypeError(f"{key} must be {expected_type.__name__}, got {type(data[key]).__name__}")
    return data

raw_records = [
    {"name": "Kenya", "region": "Africa", "population": 54000000},
    {"name": "Bad Data", "region": "Africa", "population": "fifty"},  # wrong type
    {"name": "Also Bad", "region": "Africa"},                          # missing key
]

good_countries = []
for r in raw_records:
    try:
        validate_country_record(r)
        good_countries.append(Country(**r))
    except (ValueError, TypeError) as e:
        print(f"Rejected {r!r}: {e}")

print("Valid countries:", len(good_countries))

5. Expected Files Changed

6. Commit Checkpoint

Once the lab is complete and you can explain every line, make this exact commit:

git add contracts_lab.py docs/sessions/session-30/index.html
git commit -m "session-30: formalize the country data contract with dataclasses and explicit validation"

7. Code Review Checklist

Go through your code line by line and check each item:

8. Post-Coding Quiz

Same 5 questions. Take it again now that you have written and run the code. You need 4/5 to mark this session complete.

9. Reflection Questions

Think through these after the post-quiz. No right answer — they are for discussion.

10. What Breaks If This Knowledge Is Missing?

11. What We Learned