Categories
python scope variables

UnboundLocalError on local variable when reassigned after first use

263

The following code works as expected in both Python 2.5 and 3.0:

a, b, c = (1, 2, 3)

print(a, b, c)

def test():
    print(a)
    print(b)
    print(c)    # (A)
    #c+=1       # (B)
test()

However, when I uncomment line (B), I get an UnboundLocalError: 'c' not assigned at line (A). The values of a and b are printed correctly. This has me completely baffled for two reasons:

  1. Why is there a runtime error thrown at line (A) because of a later statement on line (B)?

  2. Why are variables a and b printed as expected, while c raises an error?

The only explanation I can come up with is that a local variable c is created by the assignment c+=1, which takes precedent over the “global” variable c even before the local variable is created. Of course, it doesn’t make sense for a variable to “steal” scope before it exists.

Could someone please explain this behavior?

2

275

Python treats variables in functions differently depending on whether you assign values to them from inside or outside the function. If a variable is assigned within a function, it is treated by default as a local variable. Therefore, when you uncomment the line, you are trying to reference the local variable c before any value has been assigned to it.

If you want the variable c to refer to the global c = 3 assigned before the function, put

global c

as the first line of the function.

As for python 3, there is now

nonlocal c

that you can use to refer to the nearest enclosing function scope that has a c variable.

6

  • 6

    Thanks. Quick question. Does this imply that Python decides the scope of each variable before running a program? Before running a function?

    – tba

    Dec 16, 2008 at 3:46

  • 11

    The variable scope decision is made by the compiler, which normally runs once when you first start the program. However it is worth keeping in mind that the compiler might also run later if you have “eval” or “exec” statements in your program.

    Dec 16, 2008 at 3:48

  • 3

    Okay thank you. I guess “interpreted language” doesn’t imply quite as much as I had thought.

    – tba

    Dec 16, 2008 at 3:53

  • 1

    Ah that ‘nonlocal’ keyword was exactly what I was looking for, it seemed Python was missing this. Presumably this ‘cascades’ through each enclosing scope that imports the variable using this keyword?

    – Brendan

    Nov 17, 2009 at 20:54

  • 8

    @brainfsck: it is easiest to understand if you make the distinction between “looking up” and “assigning” a variable. Lookup falls back to a higher scope if the name is not found in the current scope. Assignment is always done in the local scope (unless you use global or nonlocal to force global or nonlocal assignment)

    – Steven

    Sep 13, 2011 at 12:00

87

Python is a little weird in that it keeps everything in a dictionary for the various scopes. The original a,b,c are in the uppermost scope and so in that uppermost dictionary. The function has its own dictionary. When you reach the print(a) and print(b) statements, there’s nothing by that name in the dictionary, so Python looks up the list and finds them in the global dictionary.

Now we get to c+=1, which is, of course, equivalent to c=c+1. When Python scans that line, it says “aha, there’s a variable named c, I’ll put it into my local scope dictionary.” Then when it goes looking for a value for c for the c on the right hand side of the assignment, it finds its local variable named c, which has no value yet, and so throws the error.

The statement global c mentioned above simply tells the parser that it uses the c from the global scope and so doesn’t need a new one.

The reason it says there’s an issue on the line it does is because it is effectively looking for the names before it tries to generate code, and so in some sense doesn’t think it’s really doing that line yet. I’d argue that is a usability bug, but it’s generally a good practice to just learn not to take a compiler’s messages too seriously.

If it’s any comfort, I spent probably a day digging and experimenting with this same issue before I found something Guido had written about the dictionaries that Explained Everything.

Update, see comments:

It doesn’t scan the code twice, but it does scan the code in two phases, lexing and parsing.

Consider how the parse of this line of code works. The lexer reads the source text and breaks it into lexemes, the “smallest components” of the grammar. So when it hits the line

c+=1

it breaks it up into something like

SYMBOL(c) OPERATOR(+=) DIGIT(1)

The parser eventually wants to make this into a parse tree and execute it, but since it’s an assignment, before it does, it looks for the name c in the local dictionary, doesn’t see it, and inserts it in the dictionary, marking it as uninitialized. In a fully compiled language, it would just go into the symbol table and wait for the parse, but since it WON’T have the luxury of a second pass, the lexer does a little extra work to make life easier later on. Only, then it sees the OPERATOR, sees that the rules say “if you have an operator += the left hand side must have been initialized” and says “whoops!”

The point here is that it hasn’t really started the parse of the line yet. This is all happening sort of preparatory to the actual parse, so the line counter hasn’t advanced to the next line. Thus when it signals the error, it still thinks its on the previous line.

As I say, you could argue it’s a usability bug, but its actually a fairly common thing. Some compilers are more honest about it and say “error on or around line XXX”, but this one doesn’t.

3

  • 2

    Okay thank you for your response; it cleared some things up for me about scopes in python. However, I still don’t understand why the error is raised at line (A) rather than line (B). Does Python create its variable scope dictionary BEFORE running the program?

    – tba

    Dec 16, 2008 at 3:40

  • 1

    No, it’s on the expression level. I’ll add to the answer, I don’t think I can fit this in a comment.

    Dec 16, 2008 at 10:36

  • 5

    Note on implementation details: In CPython, the local scope isn’t usually handled as a dict, it’s internally just an array (locals() will populate a dict to return, but changes to it don’t create new locals). The parse phase is finding each assignment to a local and converting from name to position in that array, and using that position whenever the name is referenced. On entry to the function, non-argument locals are initialized to a placeholder, and UnboundLocalErrors happen when a variable is read and its associated index still has the placeholder value.

    Mar 25, 2016 at 19:49


51

Taking a look at the disassembly may clarify what is happening:

>>> def f():
...    print a
...    print b
...    a = 1

>>> import dis
>>> dis.dis(f)

  2           0 LOAD_FAST                0 (a)
              3 PRINT_ITEM
              4 PRINT_NEWLINE

  3           5 LOAD_GLOBAL              0 (b)
              8 PRINT_ITEM
              9 PRINT_NEWLINE

  4          10 LOAD_CONST               1 (1)
             13 STORE_FAST               0 (a)
             16 LOAD_CONST               0 (None)
             19 RETURN_VALUE

As you can see, the bytecode for accessing a is LOAD_FAST, and for b, LOAD_GLOBAL. This is because the compiler has identified that a is assigned to within the function, and classified it as a local variable. The access mechanism for locals is fundamentally different for globals – they are statically assigned an offset in the frame’s variables table, meaning lookup is a quick index, rather than the more expensive dict lookup as for globals. Because of this, Python is reading the print a line as “get the value of local variable ‘a’ held in slot 0, and print it”, and when it detects that this variable is still uninitialised, raises an exception.

0