knaxuslearn · build · ship

Roadmaps / Python / Phase 2

Phase 2 of 4 · Study weeks 5-8

Types, tests and data models

This phase makes the second checkpoint possible: a core that the type checker, the tests and a property test all accept.

Topics every week

  1. Week 58 h
    • Type hints and mypy --strict
    • Protocols and generics
    • TypedDict, dataclass and models
    • Gradual typing in an old codebase

    Hand inThe core package typed under --strict

  2. Week 68 h
    • Validation at the boundary with Pydantic
    • Errors as data
    • Parsing against validating
    • Schema versions

    Hand inA validator with a clear error for each malformed event

  3. Week 78 h
    • pytest fixtures and parametrisation
    • Property tests with Hypothesis
    • Test doubles and fakes
    • Mutation of defaults and shared state

    Hand inA property test of 10,000 payloads and the seeded mutable-default bug

  4. Week 88 h
    • Ruff and the lint set
    • Pre-commit and CI
    • Reading a stack trace
    • Logging that helps at 3 a.m.

    Hand inCheckpoint 2, with the written note on which tool catches the seeded bug

Practice projects

  • Practice 1, typing an untyped module (Week 5): add hints to a 300-line module. Done when: mypy --strict passes and you list the three places a hint exposed a real bug or a wrong assumption.
  • Practice 2, the hostile payload (Week 6): send missing fields, wrong types, huge strings and nested depth 1,000. Done when: each returns a clear error, none crashes the service and a test exists for each.
  • Practice 3, the property test (Week 7): write properties for the validator (valid in, valid out; invalid never passes). Done when: Hypothesis runs 10,000 cases and a seeded bug in the validator is found and shrunk to a small example.
  • Optional, a fake database: replace Postgres in unit tests with a fake. Done when: the same test passes against the fake and the real container.

GitHub repos to study

Existence and last commit were checked on 22 Nov 2026 by shallow clone. Every repository below had a commit in the last 12 months.

RepoWhat to readWeek
python/mypyThe error codes and the configuration options5
pydantic/pydanticHow validation is designed and where the Rust core sits6
pytest-dev/pytestFixtures and the plugin hooks7
HypothesisWorks/hypothesisStrategies and shrinking7
astral-sh/ruffThe rule set and how a rule is configured8

Milestone checkpoint

Build Checkpoint 2. Type the core package first and fix what --strict reports. Write the validator and its error table. Seed the mutable-default bug and write down which tool (type checker, linter or test) caught it and which did not. Hand in the strict run, the property-test output, ADR-3 (the validation boundary) and ADR-4 (the typing policy).

Check yourself

Answer each question in your head first, then open it to check.

  1. What does mypy --strict catch, and what does it not?
    It catches wrong types, missing returns and unchecked None. It does not check values (a negative age), anything behind Any, or logic.
  2. Why validate at the boundary and trust types inside?
    Outside input can be anything. Once it is parsed into a typed model, the inner code can rely on the shape and stay simple.
  3. What does a property test find that example tests miss?
    It tries inputs across a large space, including ones you did not think of, and shrinks a failing case to a small one.
  4. Why is a mutable default argument a bug?
    The default is created once at definition time, so every call shares it and changes leak between calls.
  5. What should a log line carry so it helps at 3 a.m.?
    A request or event id, the component, the outcome and the numbers involved, without personal data.