knaxuslearn · build · ship

Roadmaps / Python / Phase 1

Phase 1 of 4 · Study weeks 1-4

The interpreter and how to measure it

This phase makes the first checkpoint possible: a baseline you can profile and a clear answer on threads, processes and free threading.

Topics every week

  1. Week 18 h
    • Objects and references
    • The bytecode and the dis module
    • The specialising interpreter
    • Memory, reference counts and the garbage collector

    Hand inA note that predicts the bytecode of three functions, checked with dis

  2. Week 28 h
    • The GIL and what it protects
    • Threads, processes and concurrent.futures
    • The free-threaded build and its trade-offs
    • Lazy imports and startup time

    Hand inThe baseline ingestd and the three-way comparison with predictions

  3. Week 38 h
    • Profiling with cProfile and the sampling profiler
    • Flame graphs
    • Memory profiling with tracemalloc
    • Benchmarks with pyperf

    Hand inA profile of the baseline and a fix for the seeded quadratic bug

  4. Week 48 h
    • Reading CPython source
    • The JIT and what it does and does not do
    • Writing a fair benchmark
    • Predicted against measured

    Hand inCheckpoint 1: the table, the profile and the before and after numbers

Practice projects

  • Practice 1, the bytecode note (Week 1): predict the bytecode for a loop, a comprehension and a method call. Done when: dis output matches your prediction or you explain each difference.
  • Practice 2, the GIL demo (Week 2): run a CPU-bound function on 1, 2 and 4 threads. Done when: a table shows throughput for each, and a second run with processes shows the difference.
  • Practice 3, the seeded slowdown (Week 3): build a string in a loop with += inside a hot path. Done when: a profile points at the function, the fix is measured and the improvement is a number.
  • Optional, a startup budget: measure python -X importtime for the service. Done when: the three slowest imports are listed and one is deferred with a measured gain.

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. Look at the README for archive notices before you rely on one.

RepoWhat to readWeek
python/cpythonPython/ceval.c, the specialising interpreter and the PEPs behind it1
python/pyperformanceHow the benchmark suite runs and reports3
numpy/numpyThe array object and strides, as an example of work done outside the interpreter4

Milestone checkpoint

Build Checkpoint 1. Write the baseline, run it on 1 KB events and profile it before changing anything. Write your prediction for threads, processes and free threading first. Run the three variants. Seed the quadratic bug, find it from the profile and fix it. Hand in the table with your own numbers, the profile, ADR-1 (the baseline) and ADR-2 (the concurrency model).

Check yourself

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

  1. What does the GIL protect, and what does it not make safe?
    It protects the interpreter's own data, such as reference counts. It does not make your code thread-safe: counter += 1 across threads can still lose updates.
  2. When do threads help in Python, and when do they not?
    They help when the work waits on I/O, because the lock is released while waiting. They do not help CPU-bound pure Python on the standard build.
  3. What does the free-threaded build change, and what does it cost?
    Several threads can run Python code at once. It costs some single-thread speed and some memory, and every extension must support it.
  4. Why profile before optimising?
    The slow part is rarely where you guess. A profile shows the three functions that account for most of the time.
  5. What makes a Python benchmark unfair?
    Different Python versions, a cold cache against a warm one, too few runs and no spread, and timing that includes setup.