{"course":{"slug":"python-for-ai","title":"Python, from Zero, for AI","url":"https://addaly.com/learn/python-for-ai","level":"beginner","track":"build"},"lesson":{"slug":"running-a-type-checker","title":"Running a type checker: the bugs it finds that tests do not","url":"https://addaly.com/learn/python-for-ai/running-a-type-checker","position":67,"of":89,"minutes":9,"answer":"A type checker follows every possible path through the code without running it, so it catches the None that only appears on the branch you never tested; Optional forces you to handle the missing case.","keyIdea":"A type checker follows every possible path through the code without running it, so it catches the None that only appears on the branch you never tested; Optional forces you to handle the missing case, and Protocol lets you describe an interface without inheritance."},"body":{"format":"markdown","text":"## What a test cannot see\n\nA test runs one path through the code with one set of inputs. If the path where a function returns `None` was never exercised, the test does not know it exists. A type checker reads the code instead of running it and follows every path the annotations allow. That is a different kind of evidence, and it is cheap: no test data, no fixtures, one command.\n\nModule 3 said hints are not enforced at runtime. This is where they get enforced.\n\n## Two checkers, one command\n\n`mypy` is the original; `pyright` is Microsoft's, faster, and the engine inside VS Code's Pylance, so you may already be seeing its output as red underlines. Either works. Both are free.\n\n```bash\npip install pyright        # or: pip install mypy\npyright src/               # or: mypy src/\n```\n\nRun it on the `src/` folder from module 3's project layout. The first run on unannotated code says very little, because a function with no hints is treated as accepting and returning `Any`, and `Any` is compatible with everything. The checker becomes useful in proportion to the annotations you add, and the payoff is front-loaded: annotate the functions at the boundaries of your program and most of the value arrives.\n\n## The None problem\n\n```python\ndef find(items: list[dict], key: str) -> dict | None:\n    for it in items:\n        if it[\"key\"] == key:\n            return it\n    return None\n\nrow = find(rows, \"abc\")\nprint(row[\"id\"])\n```\n\n```\nerror: \"__getitem__\" method not defined on type \"None\"\n```\n\nThe checker is saying: on one path this is `None`, and `None[\"id\"]` will raise. You wrote `dict | None` yourself: that is the point. Writing the honest return type forces every caller to handle the missing case:\n\n```python\nrow = find(rows, \"abc\")\nif row is None:\n    raise KeyError(\"abc\")\nprint(row[\"id\"])\n```\n\nAfter the `if`, the checker knows `row` is a `dict` (this is called **narrowing**), and the error disappears. `Optional[dict]` from `typing` means the same as `dict | None`; the bar form needs Python 3.10 or later.\n\nMost of what a type checker finds in ordinary code is this: a value that can be `None` used as though it cannot. It is also most of what crashes in production at 2 a.m.\n\n## Annotations that do work\n\n```python\nfrom typing import Literal, TypedDict, Any\n\nRole = Literal[\"system\", \"user\", \"assistant\"]\n\nclass Message(TypedDict):\n    role: Role\n    content: str\n\ndef add(messages: list[Message], role: Role, content: str) -> None:\n    messages.append({\"role\": role, \"content\": content})\n\nadd(msgs, \"usre\", \"hi\")     # error: \"usre\" is not a valid Role\n```\n\nA `Literal` turns a typo in a string constant into a checker error rather than a 400 from the API. A `TypedDict` describes the shape of a dict that has to stay a dict, the message format the SDKs want, so `m[\"contnet\"]` is caught. `Any` is the escape hatch: it means \"do not check this\", and every `Any` is a place the checker goes blind. Use it at the edge where JSON arrives, then narrow to real types as fast as you can.\n\n`dict[str, Any]` is honest for parsed JSON of unknown shape. `list[str]` beats `list`. A return type of `None` on a function that only has side effects catches the caller who assigns its result.\n\n## Protocol: an interface without inheritance\n\nModule 7 built `ChatProvider` as a base class. The checker can describe the same interface structurally:\n\n```python\nfrom typing import Protocol\n\nclass Completer(Protocol):\n    def complete(self, messages: list[Message], max_tokens: int = 500) -> str: ...\n\ndef run(provider: Completer, text: str) -> str:\n    return provider.complete([{\"role\": \"user\", \"content\": text}])\n```\n\nAny class with a matching `complete` method satisfies `Completer`, whether or not it inherits from anything. The fake in a test, the real Anthropic wrapper, a lambda-holding class: all pass, and a class whose `complete` returns a list instead of a string is flagged at the call site. This is duck typing with the checker watching, and it is usually the better choice when you control the callers but not the implementations.\n\n## What it will not catch\n\nA type checker knows types, not values. `price: float` accepts `-5.0`. `role: Role` cannot tell you the system message was put last instead of first. A function annotated `-> str` that returns the wrong string is fine by the checker. Validation of values is pydantic's job; correctness of logic is the tests' job; the checker sits between them, catching the category of error where a value of the wrong kind reaches a place that cannot handle it.\n\nIt also stops at library boundaries that ship no types. `requests` has stubs (`types-requests`); some smaller packages have nothing, and calls into them come back as `Any`. `# type: ignore` on a line silences one error; use it with a comment saying why, and treat a growing count of them as a smell.\n\n## Making it stick\n\nAdd it to the checks you already run:\n\n```bash\npyright src/ && pytest && python -m ruff check src/\n```\n\nand to the same CI job module 9 sets up. `pyright --strict` or `mypy --strict` turns on every check including \"this function has no annotations\"; start without strict, add annotations module by module, then turn it on for the modules that are done. Strict on day one produces a wall of errors that teaches nothing.\n\n## Try this now\n\nAnnotate `find` and its caller, run `pyright`, and read the error. Fix it with narrowing. Then change a role string to a typo and watch `Literal` catch it. Finally, write `Completer` as a `Protocol` and check that your `FakeProvider` from earlier satisfies it without inheriting."},"check":{"question":"`def find(items, key) -> dict | None` returns a dict or `None`. A caller writes `find(rows, k)[\"id\"]`. All tests pass. `pyright` reports: `\"__getitem__\" method not defined on type \"None\"`. What has the checker found that the tests did not?","options":[{"text":"That the function is missing a docstring, which the checker treats as an incomplete signature.","correct":false,"tempting":"Type checkers do not require docstrings; the report concerns a possible value, not documentation."},{"text":"That a path exists where `find` returns `None` which no test exercised, and it would raise `TypeError` the first time production takes it.","correct":true},{"text":"That `dict | None` is invalid syntax before Python 3.10 and the code will not import.","correct":false,"tempting":"On a supported version the syntax is fine, and the message says nothing about syntax; it names a method missing on `None`."},{"text":"That the dictionary key `\"id\"` is not guaranteed to exist, and the checker requires a `TypedDict` declaring every key before it will allow subscripting a dict at all.","correct":false,"tempting":"A plain `dict` may be subscripted with any key; the complaint is about the `None` half of the union, not the key."}]},"prev":{"slug":"decorators","title":"Decorators: wrapping a function with retry, timing or a cache","url":"https://addaly.com/learn/python-for-ai/decorators"},"next":{"slug":"packaging-with-pyproject","title":"pyproject.toml: making your project installable, and a command somebody can type","url":"https://addaly.com/learn/python-for-ai/packaging-with-pyproject"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Source and assessment review continues. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'Running a type checker: the bugs it finds that tests do not', in Python, from Zero, for AI. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/python-for-ai/running-a-type-checker (Accessed: 21 November 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"Running a type checker: the bugs it finds that tests do not","courseTitle":"Python, from Zero, for AI","module":{"index":7,"slug":"objects-and-the-shape-of-programs","title":"Objects, generators and the shape a larger program takes"},"answer":null,"keyIdea":"A type checker follows every possible path through the code without running it, so it catches the None that only appears on the branch you never tested; Optional forces you to handle the missing case, and Protocol lets you describe an interface without inheritance.","hero":{"kind":"plate","image":null,"alt":null,"caption":null},"blocks":[{"t":"h2","id":"what-a-test-cannot-see","runs":[{"text":"What a test cannot see"}]},{"t":"p","runs":[{"text":"A test runs one path through the code with one set of inputs. If the path where a function returns "},{"text":"None","code":true},{"text":" was never exercised, the test does not know it exists. A type checker reads the code instead of running it and follows every path the annotations allow. That is a different kind of evidence, and it is cheap: no test data, no fixtures, one command."}]},{"t":"p","runs":[{"text":"Module 3 said hints are not enforced at runtime. This is where they get enforced."}]},{"t":"h2","id":"two-checkers-one-command","runs":[{"text":"Two checkers, one command"}]},{"t":"p","runs":[{"text":"mypy","code":true},{"text":" is the original; "},{"text":"pyright","code":true},{"text":" is Microsoft’s, faster, and the engine inside VS Code’s Pylance, so you may already be seeing its output as red underlines. Either works. Both are free."}]},{"t":"code","lang":"bash","label":"Bash","text":"pip install pyright        # or: pip install mypy\npyright src/               # or: mypy src/"},{"t":"p","runs":[{"text":"Run it on the "},{"text":"src/","code":true},{"text":" folder from module 3’s project layout. The first run on unannotated code says very little, because a function with no hints is treated as accepting and returning "},{"text":"Any","code":true},{"text":", and "},{"text":"Any","code":true},{"text":" is compatible with everything. The checker becomes useful in proportion to the annotations you add, and the payoff is front-loaded: annotate the functions at the boundaries of your program and most of the value arrives."}]},{"t":"h2","id":"the-none-problem","runs":[{"text":"The None problem"}]},{"t":"code","lang":"python","label":"Python","text":"def find(items: list[dict], key: str) -> dict | None:\n    for it in items:\n        if it[\"key\"] == key:\n            return it\n    return None\n\nrow = find(rows, \"abc\")\nprint(row[\"id\"])"},{"t":"code","lang":"","label":"Text","text":"error: \"__getitem__\" method not defined on type \"None\""},{"t":"p","runs":[{"text":"The checker is saying: on one path this is "},{"text":"None","code":true},{"text":", and "},{"text":"None[\"id\"]","code":true},{"text":" will raise. You wrote "},{"text":"dict | None","code":true},{"text":" yourself: that is the point. Writing the honest return type forces every caller to handle the missing case:"}]},{"t":"code","lang":"python","label":"Python","text":"row = find(rows, \"abc\")\nif row is None:\n    raise KeyError(\"abc\")\nprint(row[\"id\"])"},{"t":"p","runs":[{"text":"After the "},{"text":"if","code":true},{"text":", the checker knows "},{"text":"row","code":true},{"text":" is a "},{"text":"dict","code":true},{"text":" (this is called "},{"text":"narrowing","b":true},{"text":"), and the error disappears. "},{"text":"Optional[dict]","code":true},{"text":" from "},{"text":"typing","code":true},{"text":" means the same as "},{"text":"dict | None","code":true},{"text":"; the bar form needs Python 3.10 or later."}]},{"t":"p","runs":[{"text":"Most of what a type checker finds in ordinary code is this: a value that can be "},{"text":"None","code":true},{"text":" used as though it cannot. It is also most of what crashes in production at 2 a.m."}]},{"t":"h2","id":"annotations-that-do-work","runs":[{"text":"Annotations that do work"}]},{"t":"code","lang":"python","label":"Python","text":"from typing import Literal, TypedDict, Any\n\nRole = Literal[\"system\", \"user\", \"assistant\"]\n\nclass Message(TypedDict):\n    role: Role\n    content: str\n\ndef add(messages: list[Message], role: Role, content: str) -> None:\n    messages.append({\"role\": role, \"content\": content})\n\nadd(msgs, \"usre\", \"hi\")     # error: \"usre\" is not a valid Role"},{"t":"p","runs":[{"text":"A "},{"text":"Literal","code":true},{"text":" turns a typo in a string constant into a checker error rather than a 400 from the API. A "},{"text":"TypedDict","code":true},{"text":" describes the shape of a dict that has to stay a dict, the message format the SDKs want, so "},{"text":"m[\"contnet\"]","code":true},{"text":" is caught. "},{"text":"Any","code":true},{"text":" is the escape hatch: it means “do not check this”, and every "},{"text":"Any","code":true},{"text":" is a place the checker goes blind. Use it at the edge where JSON arrives, then narrow to real types as fast as you can."}]},{"t":"p","runs":[{"text":"dict[str, Any]","code":true},{"text":" is honest for parsed JSON of unknown shape. "},{"text":"list[str]","code":true},{"text":" beats "},{"text":"list","code":true},{"text":". A return type of "},{"text":"None","code":true},{"text":" on a function that only has side effects catches the caller who assigns its result."}]},{"t":"h2","id":"protocol-an-interface-without-inheritance","runs":[{"text":"Protocol: an interface without inheritance"}]},{"t":"p","runs":[{"text":"Module 7 built "},{"text":"ChatProvider","code":true},{"text":" as a base class. The checker can describe the same interface structurally:"}]},{"t":"code","lang":"python","label":"Python","text":"from typing import Protocol\n\nclass Completer(Protocol):\n    def complete(self, messages: list[Message], max_tokens: int = 500) -> str: ...\n\ndef run(provider: Completer, text: str) -> str:\n    return provider.complete([{\"role\": \"user\", \"content\": text}])"},{"t":"p","runs":[{"text":"Any class with a matching "},{"text":"complete","code":true},{"text":" method satisfies "},{"text":"Completer","code":true},{"text":", whether or not it inherits from anything. The fake in a test, the real Anthropic wrapper, a lambda-holding class: all pass, and a class whose "},{"text":"complete","code":true},{"text":" returns a list instead of a string is flagged at the call site. This is duck typing with the checker watching, and it is usually the better choice when you control the callers but not the implementations."}]},{"t":"h2","id":"what-it-will-not-catch","runs":[{"text":"What it will not catch"}]},{"t":"p","runs":[{"text":"A type checker knows types, not values. "},{"text":"price: float","code":true},{"text":" accepts "},{"text":"-5.0","code":true},{"text":". "},{"text":"role: Role","code":true},{"text":" cannot tell you the system message was put last instead of first. A function annotated "},{"text":"-> str","code":true},{"text":" that returns the wrong string is fine by the checker. Validation of values is pydantic’s job; correctness of logic is the tests’ job; the checker sits between them, catching the category of error where a value of the wrong kind reaches a place that cannot handle it."}]},{"t":"p","runs":[{"text":"It also stops at library boundaries that ship no types. "},{"text":"requests","code":true},{"text":" has stubs ("},{"text":"types-requests","code":true},{"text":"); some smaller packages have nothing, and calls into them come back as "},{"text":"Any","code":true},{"text":". "},{"text":"# type: ignore","code":true},{"text":" on a line silences one error; use it with a comment saying why, and treat a growing count of them as a smell."}]},{"t":"h2","id":"making-it-stick","runs":[{"text":"Making it stick"}]},{"t":"p","runs":[{"text":"Add it to the checks you already run:"}]},{"t":"code","lang":"bash","label":"Bash","text":"pyright src/ && pytest && python -m ruff check src/"},{"t":"p","runs":[{"text":"and to the same CI job module 9 sets up. "},{"text":"pyright --strict","code":true},{"text":" or "},{"text":"mypy --strict","code":true},{"text":" turns on every check including “this function has no annotations”; start without strict, add annotations module by module, then turn it on for the modules that are done. Strict on day one produces a wall of errors that teaches nothing."}]},{"t":"h2","id":"try-this-now","runs":[{"text":"Try this now"}],"role":"try"},{"t":"p","runs":[{"text":"Annotate "},{"text":"find","code":true},{"text":" and its caller, run "},{"text":"pyright","code":true},{"text":", and read the error. Fix it with narrowing. Then change a role string to a typo and watch "},{"text":"Literal","code":true},{"text":" catch it. Finally, write "},{"text":"Completer","code":true},{"text":" as a "},{"text":"Protocol","code":true},{"text":" and check that your "},{"text":"FakeProvider","code":true},{"text":" from earlier satisfies it without inheriting."}]}],"check":{"question":[{"text":"def find(items, key) -> dict | None","code":true},{"text":" returns a dict or "},{"text":"None","code":true},{"text":". A caller writes "},{"text":"find(rows, k)[\"id\"]","code":true},{"text":". All tests pass. "},{"text":"pyright","code":true},{"text":" reports: "},{"text":"\"__getitem__\" method not defined on type \"None\"","code":true},{"text":". What has the checker found that the tests did not?"}],"options":[{"text":[{"text":"That the function is missing a docstring, which the checker treats as an incomplete signature."}],"correct":false,"tempting":[{"text":"Type checkers do not require docstrings; the report concerns a possible value, not documentation."}]},{"text":[{"text":"That a path exists where "},{"text":"find","code":true},{"text":" returns "},{"text":"None","code":true},{"text":" which no test exercised, and it would raise "},{"text":"TypeError","code":true},{"text":" the first time production takes it."}],"correct":true,"tempting":null},{"text":[{"text":"That "},{"text":"dict | None","code":true},{"text":" is invalid syntax before Python 3.10 and the code will not import."}],"correct":false,"tempting":[{"text":"On a supported version the syntax is fine, and the message says nothing about syntax; it names a method missing on "},{"text":"None","code":true},{"text":"."}]},{"text":[{"text":"That the dictionary key "},{"text":"\"id\"","code":true},{"text":" is not guaranteed to exist, and the checker requires a "},{"text":"TypedDict","code":true},{"text":" declaring every key before it will allow subscripting a dict at all."}],"correct":false,"tempting":[{"text":"A plain "},{"text":"dict","code":true},{"text":" may be subscripted with any key; the complaint is about the "},{"text":"None","code":true},{"text":" half of the union, not the key."}]}],"order":[0,2,3,1],"why":null},"prev":{"slug":"decorators","title":"Decorators: wrapping a function with retry, timing or a cache","minutes":9},"next":{"slug":"packaging-with-pyproject","title":"pyproject.toml: making your project installable, and a command somebody can type","minutes":9}}}