Build 4 — Type Retrofit (Add Types to Untyped Code)

# Build 4 — Type Retrofit ## The brief Take an existing untyped Python project (yours or one provided) and add type annotations. Goal: Pyright strict mode passes. This is a real production task: most codebases have stretches of untyped code that need retrofitting. ## Choose code to retrofit Options: - A small open-source library you use (Click, requests, etc., or smaller). - Your own pre-existing project. - We'll provide a sample untyped project (~500 lines). For practice, start with 200-1000 lines. Larger codebases take days. ## Step 1: Baseline (10 min) Install Pyright: ```bash uv add --dev pyright ``` Run in strict mode: ```bash uv run pyright --typecheckingmode strict ``` You'll get hundreds of errors. Record the count. ## Step 2: Add types to public API first (20 min) Start with the most-used public functions / classes. Their signatures matter most. ```python # Before def fetch_user(user_id): return db.query(user_id) # After def fetch_user(user_id: int) -> User | None: return db.query(user_id) ``` Focus on: - Function parameters and return types. - Class attributes and methods. - Public constants. Skip: - Internal helper functions (do them in a later pass). - Test functions (lower priority). ## Step 3: Type-check incrementally (15 min) After each significant chunk, re-run Pyright. Watch error count drop. If a function uses a type from elsewhere not yet typed: define it with `Any` as a placeholder: ```python from typing import Any def process(data: Any) -> Any: return data ``` Refine later. `Any` is a temporary escape; mark it for revisit. ## Step 4: Add types to internal code (15 min) Now do internal helpers. Often, types are obvious from how they're used. For collections, prefer specific types over generic ones: - `list[int]` not `list` - `dict[str, User]` not `dict` - `tuple[int, str]` not `tuple` ## Step 5: Fix specific Pyright errors ### "Function has no return type annotation" ```python def hello(): # error in strict mode return "hi" ``` Add explicit return type: ```python def hello() -> str: return "hi" ``` ### "Type 'None' is not assignable" ```python def get_user(id: int) -> User: return db.find(id) # might return None ``` Fix the type: ```python def get_user(id: int) -> User | None: return db.find(id) ``` ### "Unbound variable" ```python def f(x): if x: result = "yes" print(result) # error: result may be undefined ``` Initialize: ```python def f(x): result = "default" if x: result = "yes" print(result) ``` ### "Type 'object' has no attribute" Often from `Any` or unhinted variables. Add specific type: ```python data: dict[str, int] = {} data["x"] = 1 # now Pyright knows it's int ``` ### "Argument missing" / "Too many arguments" Type mismatch in callers — usually a real bug. Fix the call. ## Step 6: Handle edge cases (10 min) ### Optional pattern ```python def f(x: int | None = None) -> str: if x is None: x = 0 return str(x) ``` Pyright narrows the type after the check. ### isinstance narrowing ```python def f(x: int | str) -> int: if isinstance(x, int): return x + 1 # x is int here return len(x) # x is str here ``` ### Cast for cases the checker can't infer ```python from typing import cast result = some_untyped_function() typed_result = cast(MyType, result) ``` Use sparingly; means "trust me, this is the right type". ## Step 7: Re-run and verify ```bash uv run pyright --typecheckingmode strict ``` Goal: 0 errors. Some may remain (warnings about libraries without stubs); record them and decide whether to handle. For third-party libraries without types: ```python # pyproject.toml [tool.pyright] ignoreMissingImports = true # if you really must ``` Or add `# type: ignore` per line as a last resort. Prefer fixing. ## Deliverables - Before/after error counts. - The retrofitted code with proper types. - A short reflection (RETROFIT.md): - How many errors at start vs end. - Time taken. - Bugs you found (often hidden bugs surface during typing). - Where types were ambiguous and how you resolved. ## What you'll learn - Real typing strategies for legacy code. - How types reveal hidden bugs (mismatched returns, missing None checks). - The Pyright strict-mode error vocabulary. - When to use `Any` (temporarily) vs `cast` (deliberately) vs `# type: ignore` (last resort). - Incremental refactoring workflow. ## Reflection prompts - Which types were easy? Which hard? - Did you find any actual bugs while adding types? - Was strict mode worth it, or would basic mode suffice for this code? - What changes would you make to the code itself to make typing cleaner? ## Stretch - Set up CI to run Pyright on every PR. - Migrate from `# type: ignore` to proper types over multiple passes. - Add a strict pyproject.toml config that other contributors will follow.