Chapter 45: Reading Python
James watches Claude Code generate fifty lines of typed Python in under ten seconds. He is impressed by the speed. Emma glances at the screen and points to line twelve. "What does that line do?" James stares at it. He cannot answer. Emma does not look surprised. "Speed means nothing without understanding. If you cannot read the code your tools produce, you cannot verify it, debug it, or trust it."
In Chapter 44, you built the workbench: uv, pyright, ruff, pytest, and Git. Every tool is installed, every configuration file is in place, and your SmartNotes project has a clean foundation. Now you learn the language those tools process. Before you write Python, you read it. Before you generate code with Claude Code, you learn to predict what code does line by line, so that every variable, type annotation, and expression is something you understand rather than something you hope works.
This chapter teaches you to read typed Python using the PRIMM method: Predict, Run, Investigate. You will use Claude Code to generate code blocks, trace expressions by hand, predict output before running code, and catch a real bug in a SmartNotes module. By the end, you will have a formal method for reading any code you encounter, whether written by a human or generated by Claude Code. This is the verification skill that makes Spec-Driven Development work: you cannot verify what you cannot read.
What You Will Learn
By the end of this chapter, you will be able to:
- Apply the PRIMM method (Predict-Run-Investigate) to any code you encounter
- Recognize the four primitive types (
str,int,float,bool) and read type annotations - Predict what Python expressions evaluate to before running the code
- Build trace tables to track how variables change line by line
- Catch a type mismatch bug by reading code carefully, the same bug Pyright catches automatically
The Reading Method
Every lesson in this chapter follows the Predict-Run-Investigate method. You see a piece of code. You predict what it does (on paper or in your head) before you run it. Then you run it and compare your prediction to the actual result. When your prediction is wrong, you investigate why. This cycle builds the mental model that separates someone who reads code from someone who stares at it.
Chapter Lessons
| Lesson | Title | What You Do |
|---|---|---|
| 1 | The PRIMM Method -- Predict, Run, Investigate | Learn the formal method for reading code, practice on short examples |
| 2 | Trace Tables -- When Your Brain Takes Shortcuts | Track variable state line by line using trace tables |
| 3 | Your First Code Review -- Catching a Bug | Apply PRIMM and trace tables to find a bug in SmartNotes code |
| 4 | Reading a Test -- Two New Words | Recognize def and assert in test code, predict pass/fail |
PRIMM-AI+ in This Chapter
Every lesson in this chapter includes a PRIMM-AI+ Practice section where you apply the enhanced framework from Chapter 42. These exercises use real Python code (not conceptual scenarios), making this the first chapter where PRIMM-AI+ meets actual programming.
Each Practice section follows the five stages:
| Stage | What You Do | What It Builds |
|---|---|---|
| Predict [AI-FREE] | Read AI-generated code and predict output with a confidence score (1-5) | Calibrates your judgment: you learn to distinguish "I know this" from "I think I know this" |
| Run | Execute the code and compare to your prediction | Creates the feedback loop that turns predictions into learning |
| Investigate | Write a trace artifact (trace table or "why I got it wrong" note) before asking the AI | Makes your understanding visible so you can compare it to reality |
| Modify | Change one thing and predict the new output | Tests whether your understanding transfers to new situations |
| Make [Mastery Gate] | Complete a challenge that proves the skill is solid | Each lesson has a specific mastery gate, your checkpoint before moving on |
Lessons 2 and 4 include Parsons Problems (scrambled code lines you reconstruct into the correct order) that test structural comprehension before you modify code freely. The Error Taxonomy from Chapter 43 appears throughout, helping you classify bugs by type (type error, logic error, specification error) rather than just fixing them. The Verification Ladder builds across the chapter: Rung 1 (prediction) in Lesson 1, Rung 2 (types) in Lesson 3, and Rung 3 (tests) in Lesson 4.
What This Chapter Uses
This chapter introduces Python through reading, not writing. Every code example uses only these concepts:
- Variables with type annotations:
name: str = "Alice" - Four primitive types:
str,int,float,bool - Arithmetic operators:
+,-,*,/,// - String concatenation (
+), repetition (*), f-strings - Boolean logic:
and,or, comparisons print()for output
Functions, collections, imports, and control flow appear later in Phase 2 (the next section of this course). Lesson 4 adds two vocabulary words (def and assert) so you can read test code before writing your first test in the next chapter. This chapter gives you a taste of Python, enough to practice the PRIMM method and build confidence reading code.