How Python Executes Your Code

Part I · Module 1 · Chapter 1.4 · How Python Executes Your Code

1. Three Stages

When you ask Python to run a file, three things happen in order.

1. Read. The interpreter reads your file as text, from the first character to the last.
2. Compile. It translates the whole file into a simpler internal form called bytecode. Bytecode is a set of very small instructions that the interpreter is good at carrying out quickly. You never see it and never write it.
3. Run. It works through the bytecode, carrying out the instructions in order, producing output or stopping with an error.

2. Yes, Python Compiles

Chapter 1.2 flagged this and here is the detail.

Python compiles your code. It just does it for you, automatically, as part of running — you never invoke a compiler, and you never get an executable file to keep and run later.

The word "interpreted" that gets attached to Python refers to stage 3: the bytecode is carried out by the interpreter rather than by the processor directly. It does not mean stage 2 was skipped.

3. The First Observable Consequence: __pycache__

You will eventually notice a directory called __pycache__ appearing next to your files, containing files ending in .pyc.

That is stage 2 leaving its results on disk so it does not have to repeat the work next time. It is a cache, it is created automatically, and it is safe to delete — Python will simply rebuild it.

You do not need to do anything about it. You only need to not be alarmed by it, and to know it is not something you wrote.

4. The Second Consequence: Two Kinds of Failure

This is the part worth the chapter.

Because Python compiles the whole file before running any of it, the moment at which a mistake stops your program tells you what kind of mistake it is.

A mistake in the shape of the code

If the code is not valid Python — a missing quote, a missing bracket — stage 2 cannot finish. Nothing runs at all. Not even the first line.

print("first line")
print("second line)

Run this and neither line appears. Not the first one, even though the first line is perfectly correct and comes before the mistake.

That surprises people, and the three stages explain it exactly: the compile stage examines the entire file, finds the second line unintelligible, and refuses to produce bytecode. There is nothing to run, so nothing runs.

A mistake in what the code asks for

If the code is validly shaped but asks for something impossible, stage 2 succeeds — the shape was fine — and the failure only appears in stage 3, at the moment that line is reached.

print("first line")
prnt("second line")

Run this and you do see first line, and then the program stops. The first line ran normally, because there was nothing wrong with its shape or its request. The second line was well-formed enough to compile but asked for something called prnt, which does not exist.

Chapter 1.11 reads the actual messages these two produce.

5. Where This Chapter Stops

Python's execution model goes considerably deeper: how bytecode is represented, how the virtual machine that carries it out is built, what optimisations happen, how different Python implementations differ.

None of that helps you write correct Python, and this course will not cover it in Part I. If you later care about performance in detail, that is the point to go further.

6. What This Does Not Mean

Two corrections, because simplified models tend to over-extend.

It does not mean Python is slow because it is "interpreted". Speed comes from many things. Chapter 1.3's point stands: for automation the time goes on waiting for other tools, not on your script.

It does not mean the compile stage checks your logic. Stage 2 checks only that the code is well-formed — valid shapes, complete brackets, matched quotes. It does not check that your names exist, that your arithmetic is sensible, or that the file you are about to open is there. All of that is stage 3's problem, which is why programs can start successfully and fail later.

7. Exercise

Exercise 1 — predict before running. For each, say whether you expect no output at all or some output then a stop, and why: (a) a file whose third line is missing a closing bracket; (b) a file whose third line asks for a name that does not exist; (c) a file that is entirely correct.

Exercise 2 — explain the surprise. A colleague says: "My first line is definitely right, so why didn't it print anything?" Answer in two sentences using the word compile.

Exercise 3 — the cache. You delete __pycache__ and run your program again. Predict what happens, and whether your program behaves differently.

(You will be able to run all of these yourself from Chapter 1.7 onward. Write your predictions down now and check them then — that habit is worth more than the answers.)

8. Summary

• Three stages: read the file as text, compile the whole file to bytecode, then run the bytecode in order.
• Python does compile your code — automatically, every time, with no separate step for you to manage and no executable to keep. "Interpreted" describes stage 3, not the absence of stage 2.
• __pycache__ is stage 2's cache. Created automatically, safe to delete, not something you wrote.
• The whole file compiles before any of it runs, which is why a mistake in the shape of line 20 stops line 1 from ever appearing.
• The diagnostic question is: did any output appear? None means a shape problem; some means the shape was fine and a specific request failed.
• Anything deeper is deliberately deferred. The virtual machine's internals do not help you write correct Python.

You now have the complete execution model for Part I. The next chapter stops describing and starts doing: you will meet the interpreter directly and type Python at it.