Scope: Where Names Live 🔭

What happens inside stays inside

def make_grog():
    strength = 11          # created inside the function
    print(f"inside: {strength}")


make_grog()
# print(strength)          # NameError: name 'strength' is not defined
print("outside: cannot see it")

inside: 11
outside: cannot see it

Names created inside a function are local to it. They come into existence when the call starts and disappear when it ends. This is a feature: it means you can name a variable total inside a function without wondering whether some other function forty lines away is also using total.

Reading outwards is allowed

ship_name = "Sea Monkey"          # global


def announce():
    print(f"Now boarding the {ship_name}")


announce()

Now boarding the Sea Monkey

A function can read names from outside. Python looks in ever-widening circles, which has a name you will see in every Python book: LEGB.

Python checks them in that order and stops at the first match.

Writing outwards is not

count = 0


def increment():
    count = count + 1       # UnboundLocalError


try:
    increment()
except UnboundLocalError as err:
    print("Error:", err)

Error: cannot access local variable 'count' where it is not associated with a value

You can override it, and you usually should not:

count = 0


def increment():
    global count
    count += 1


increment()
increment()
print(count)

2

Why global is usually the wrong answer

global works. It also means any function anywhere can change that value, so when it holds something wrong you have the entire file as your list of suspects. Prefer passing values in and returning them out:

def increment(count):
    """Return the next count. Changes nothing outside."""
    return count + 1


count = 0
count = increment(count)
count = increment(count)
print(count)

2

Now the function is testable, reusable, and impossible to blame for an action at a distance. This is the shape of a pure function: it takes values, returns a value, and touches nothing else. Not everything can be pure, but the parts that can, should be.

Shadowing: same name, different scope

name = "global Guybrush"


def outer():
    name = "outer Elaine"

    def inner():
        name = "inner Otis"
        print("inner sees: ", name)

    inner()
    print("outer sees: ", name)


outer()
print("module sees:", name)

inner sees:  inner Otis
outer sees:  outer Elaine
module sees: global Guybrush

Three separate variables that happen to share a name. Each function sees its own. Legal, occasionally useful, and a reliable way to confuse yourself if you do it on purpose.

nonlocal: reaching one level out

def counter():
    count = 0

    def increment():
        nonlocal count
        count += 1
        return count

    return increment


tally = counter()
print(tally(), tally(), tally())

1 2 3

nonlocal means "the one in the enclosing function, not a new local and not the global". The pattern above is a closure: increment remembers count even after counter has finished. It is the foundation of decorators (Lesson 35) and one of the genuinely beautiful ideas in programming.

Shadowing built-ins: the sneaky one

list = [1, 2, 3]           # now `list` is your list, not the type
print(list)

del list                    # undo the damage
print(list((1, 2, 3)))      # the built-in is back

[1, 2, 3]
[1, 2, 3]

x = 10


def show():
    x = 20
    print("inside:", x)


show()
print("outside:", x)

total = 0


def add(n):
    total += n


add(5)

total = 0


def add(n):
    global total
    total += n


add(5)
add(10)
print(total)

15

def add(total, n):
    """Return the new total."""
    return total + n


total = 0
total = add(total, 5)
total = add(total, 10)
print(total)

# or simply
print(sum([5, 10]))

15
15

def open_account(starting=0):
    """Return (deposit, balance) functions sharing a private balance."""
    balance = starting

    def deposit(amount):
        nonlocal balance
        balance += amount
        return balance

    def check():
        return balance

    return deposit, check


deposit, check = open_account(100)

print(check())
deposit(50)
deposit(25)
print(check())

100
175