Why does incorrect assignment to a global variable raise exception early?

Question

a = 10
def f():
  print(1)
  print(a) # UnboundLocalError raised here
  a = 20
f()

This code of course raises UnboundLocalError: local variable 'a' referenced before assignment. But why is this exception raised at the print(a) line?

If the interpreter executed code line by line (like I thought it did), it wouldn't know anything was wrong when print(a) was reached; it would just think that a referred to the global variable.

So it appears the interpreter reads the entire function in advance to figure out whether a is used for assignment. Is this documented anywhere? Is there any other occasion where the interpreter looks ahead (apart from checking for syntax errors)?

To clarify, the exception itself is perfectly clear: global variables can be read without global declaration, but not written (this design prevents bugs due to unintentionally modifying global variables; those bugs are especially hard to debug because they lead to errors that occur far from the location of the erroneous code). I'm just curious why the exception is raised early.

Answer 1

According to Python's documentation, the interpreter will first notice an assignment for a variable named a in the scope of f() (no matter the position of the assignment in the function) and then as a consequence only recognize the variable a as a local variable in this scope. This behavior effectively shadows the global variable a.

The exception is then raised "early", because the interpreter which executes the code "line by line", will encounter the print statement referencing a local variable, which is not yet bound at this point (remember, Python is looking for a local variable here).

As you mentioned in your question, one has to use the global keyword to explicitly tell the compiler that the assignment in this scope is done to the global variable the correct code would be:

a = 10
def f():
  global a
  print(1)
  print(a) # Prints 10 as expected
  a = 20
f()

As @2rs2ts said in a now-deleted answer, this is easily explained by the fact that "Python is not merely interpreted, it is compiled into a bytecode and not just interpreted line by line".

Answer 2

In the Resolution of Names section of the Python Reference Manual this is stated:

[..] If the current scope is a function scope, and the name refers to a local variable that has not yet been bound to a value at the point where the name is used, an UnboundLocalError exception is raised [..]

that's the official word on when UnboundLocalError occurs. If you take a look at the bytecode CPython generates for your function f with dis you can see it trying to load the name from a local scope when its value hasn't even been set yet:

>>> dis.dis(f)
  3           0 LOAD_GLOBAL              0 (print)
              3 LOAD_CONST               1 (1)
              6 CALL_FUNCTION            1 (1 positional, 0 keyword pair)
              9 POP_TOP

  4          10 LOAD_GLOBAL              0 (print)
             13 LOAD_FAST                0 (a)      # <-- this command
             16 CALL_FUNCTION            1 (1 positional, 0 keyword pair)
             19 POP_TOP

  5          20 LOAD_CONST               2 (20)
             23 STORE_FAST               0 (a)
             26 LOAD_CONST               0 (None)
             29 RETURN_VALUE

As you can see, the name 'a' is loaded onto the stack by means of the LOAD_FAST command:

             13 LOAD_FAST                0 (a)

This is the command that is used to grab local variables in a function (named FAST due to it being quite faster than loading from the global scope with LOAD_GLOBAL).

This really has nothing to do with the global name a that has been defined previously. It has to do with the fact that CPython will assume you're playing nice and generate a LOAD_FAST for references to 'a' since 'a' is being assigned to (i.e made a local name) inside the function body.

For a function with a single name access and no corresponding assignment, CPython does not generate a LOAD_FAST and instead goes and looks at the global scope with LOAD_GLOBAL:

>>> def g():
...    print(b)
>>> dis.dis(g)
  2           0 LOAD_GLOBAL              0 (print)
              3 LOAD_GLOBAL              1 (b)
              6 CALL_FUNCTION            1 (1 positional, 0 keyword pair)
              9 POP_TOP
             10 LOAD_CONST               0 (None)
             13 RETURN_VALUE

_{So it appears the interpreter reads the entire function in advance to figure out whether a is used for assignment. Is this documented anywhere? Is there any other occasion where the interpreter looks ahead (apart from checking for syntax errors)?}

In the Compound Statements section of the reference manual the following is stated for function definitions:

A function definition is an executable statement. Its execution binds the function name in the current local namespace to a function object (a wrapper around the executable code for the function).

Specifically, it binds the name f to a function object that holds the compiled code, f.__code__, that dis prettifies for us.