Chapter 32: 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 31, 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 |
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 = "Zia" - 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. Lesson 4 adds two vocabulary words -- def and assert -- so you can read test code before writing your first test in Chapter 33. This chapter gives you a taste of Python -- enough to practice the PRIMM method and build confidence reading code.
Prerequisites
- Chapter 31: The Development Environment -- You must have the discipline stack installed (uv, pyright, ruff, pytest, Git) and a working SmartNotes project. Every lesson in this chapter runs code inside that project.
- Chapter 5: Spec-Driven Development with Claude Code -- You must understand why specifications come before code and how Claude Code serves as the AI coding agent that generates implementations. In this chapter, Claude Code generates the Python code blocks you read and verify -- the same workflow you will use throughout Part 4.