09Machines with names

In Chapter 8 we learned to pick the right container on sight. In this one we build the machines that work on them. I want to go slow, because there's a question most tutorials walk straight past. Here's the plan. We bundle a run of steps into a named unit and call it again and again. We hand it 'Blinding Lights' at 200s, then 'Titanium' at 245s — the same machine both times. Then we steer exactly how those arguments find their parameters, and tell whether a call hands back a value or a quiet None. The whole way through we keep asking the one thing that matters: what does def really build in memory, and what wakes it the moment a pair of parentheses finally runs? By the end we've watched frames push and pop on the call stack. We've climbed the LEGB ladder Python uses to resolve a name. And we've met the strange part: a function is itself a value, so you can pass the machine, not just its output.

01A machine with a name

Let's start with the pain, because it's the whole reason functions exist. Printing one song takes three lines. Printing forty songs, three lines each, would be a hundred and twenty. That's the same three lines copied out thirty-nine needless times, every copy a fresh chance to fumble one. Now watch the better move. Write the three lines once, hang a name on the bundle, and from then on just say the name. That's the whole of def — bundle the steps, name the bundle. You're building a small machine and writing its name on the side.

def describe(title, artist, seconds):
    line = title + " by " + artist
    print(line, "-", seconds, "s")

describe("Blinding Lights", "The Weeknd", 200)   # Blinding Lights by The Weeknd - 200 s

Look hard at the two moments in that snippet, because they are genuinely different things. The names in the def line — title, artist, seconds — are the parameters. They're labelled empty slots built into the machine's design, waiting. The values you drop in at the call — "Blinding Lights", "The Weeknd", 200 — are the arguments: what actually arrives when you press GO. Here's a mnemonic worth keeping. The parameter is part of the machine. The argument is what shows up at the door.

you type
def greet():
    print("Hey, how are you")

def describe(title, artist):
    print(title, "by", artist)

def total_seconds(a, b):
    """Add two song lengths and hand the sum back."""
    return a + b

greet()
describe("Titanium", "David Guetta ft. Sia")

total = total_seconds(200, 245)
print(total)

print(greet())
print(total_seconds(200, 245) + 100)

print(type(total_seconds).__name__, total_seconds.__name__)
print(total_seconds.__doc__)

you see
Hey, how are you
Titanium by David Guetta ft. Sia
445
Hey, how are you
None
545
function total_seconds
Add two song lengths and hand the sum back.

And in memory, def does something you have already met. It builds a function object on the heap — the machine itself, which is the compiled body plus the list of parameter names. Then it binds the name describe to it, exactly the way a = 10 bound a name to an int back in chapter 3. The object is compact, about 160 bytes on this machine. It mostly just points at the separate 240-byte block of compiled instructions that is the body. Then comes the part that surprises everyone: the body does not run. Not one line of it. def executes, the machine gets built and named, and the instructions inside sit shelved, untouched, waiting for a caller.

encore = describe            # a second name for the SAME machine
encore is describe           # True  -> one object, two names
encore("Titanium", "David Guetta ft. Sia", 245)
# Titanium by David Guetta ft. Sia - 245 s

del describe               # drop the original name...
encore("Blinding Lights", "The Weeknd", 200)
# ...still works: the machine outlived the label

Because the machine is just an object, a name is nothing precious to it. You can hang a second name on the very same machine, and both point at one object (encore is describe is True, same id). Delete the original name and the machine lives on, still answering to encore. Even its __name__ stays "describe", because that was baked in at build time, not carried by the label. This is what people mean when they call functions first-class. A function is a value like any other: free to be renamed, stored in a list, or handed to another function. It's a thread we pull hard on later in the chapter.

you type
def describe(title, artist, seconds):
    """Print one playlist line for a track.

    title   -- the song title, a str
    artist  -- who made it, a str
    seconds -- how long it runs, an int
    Returns None: this one prints, it does not hand anything back.
    """
    print(title, "by", artist, "-", seconds, "s")

def shout(title):
    "One-liner docstring: hand back the title in capitals."
    return title.upper()

describe("Titanium", "David Guetta ft. Sia", 245)
print(shout.__doc__)
print(describe.__doc__.splitlines()[0])
help(shout)

you see
Titanium by David Guetta ft. Sia - 245 s
One-liner docstring: hand back the title in capitals.
Print one playlist line for a track.
Help on function shout in module __main__:

shout(title)
    One-liner docstring: hand back the title in capitals.

You have been feeding three arguments in strict left-to-right order, and the slots filled up quietly. But nothing yet forces the call to match the design — so how does each argument find its parameter when the counts line up, and what happens the moment they don't? →

02How arguments find their parameters

You already met the two sides of a call. The parameters are the named slots you wrote in the def line — empty boxes waiting to be filled. The arguments are the actual values you hand over at the call site. The moment you write add_song(...), Python has to decide which value drops into which slot. It does it by a small, fixed rulebook — not by guessing, not by type, but by three plain mechanisms you can learn in one sitting.

Positional is the default: values fill slots left to right, first argument into the first slot. Keyword lets a value name its own destination. Write seconds=200 and it flies straight to the seconds slot no matter where you put it, order be damned. And a default is a fallback value baked into the def line, used only for a slot the call leaves empty. One traffic rule binds them: positionals first, keywords after. Once you switch to naming, you can't switch back. A bare value sitting behind a named one is a hard error, caught before your code even runs.

you type
def add_song(title, artist="Unknown", seconds=180):
    return f"{title} by {artist} - {seconds} s"

print(add_song("Blinding Lights", "The Weeknd", 200))
print(add_song("Blinding Lights", seconds=200, artist="The Weeknd"))
print(add_song("Titanium"))
print(add_song(artist="Sia", title="Titanium"))

try:
    exec('add_song("Titanium", seconds=245, "Sia")')
except SyntaxError as e:
    print("SyntaxError:", e.msg)

def add(song, playlist=[]):        # the trap, run honestly
    playlist.append(song)
    return playlist

print(add("Blinding Lights"))
print(add("Titanium"))
print(add.__defaults__)

def add_safe(song, playlist=None):  # the fix
    if playlist is None:
        playlist = []
    playlist.append(song)
    return playlist

print(add_safe("Blinding Lights"))
print(add_safe("Titanium"))

you see
Blinding Lights by The Weeknd - 200 s
Blinding Lights by The Weeknd - 200 s
Titanium by Unknown - 180 s
Titanium by Sia - 180 s
SyntaxError: positional argument follows keyword argument
['Blinding Lights']
['Blinding Lights', 'Titanium']
(['Blinding Lights', 'Titanium'],)
['Blinding Lights']
['Titanium']

def add_song(title, artist="Unknown", seconds=180):
    return f"{title} by {artist} - {seconds} s"

add_song("Blinding Lights", "The Weeknd", 200)      # by position
add_song("Blinding Lights", seconds=200, artist="The Weeknd")  # by name, reordered
add_song("Titanium")     # Titanium by Unknown - 180 s  (both defaults kick in)

That is the whole rulebook, but rules are easier to trust once you've watched them run. Drag through five real calls below. The same three slots stay put. Only what lands in them changes, colour-coded by how it got there.

So far every value has been a lone thing dropped into a named slot. But a function can also open its arms and accept however many values you throw. Two star-markers in the def line turn overflow into a single collected object. *args scoops up every spare positional argument into a tuple. **kwargs scoops up every spare keyword argument into a dict. Those are the very structures you built by hand in chapters 6 and 7, packed for you now at the instant of the call. (The names args and kwargs are only convention. The stars do the actual work.)

you type
def playlist_length(*songs):
    print("packed:", songs, type(songs).__name__)
    total = 0
    for s in songs:
        total += s
    return total

def tag_song(title, **extras):
    print("packed:", extras, type(extras).__name__)
    for key, value in extras.items():
        print("   ", key, "=", value)

def add_song(title, artist="Unknown", seconds=180):
    return f"{title} by {artist} - {seconds} s"

print(playlist_length(200, 245, 354))
print(playlist_length())
tag_song("Blinding Lights", artist="The Weeknd", year=2019)

row = ("Titanium", "David Guetta ft. Sia", 245)
meta = {"artist": "Avicii", "seconds": 203}
lengths = [200, 245, 354]

print(add_song(*row))
print(add_song("Levels", **meta))
print(playlist_length(*lengths))

you see
packed: (200, 245, 354) tuple
799
packed: () tuple
0
packed: {'artist': 'The Weeknd', 'year': 2019} dict
    artist = The Weeknd
    year = 2019
Titanium by David Guetta ft. Sia - 245 s
Levels by Avicii - 203 s
packed: (200, 245, 354) tuple
799

def playlist_length(*songs):        # songs is a TUPLE Python packs for you
    total = 0
    for s in songs:                 # walk the tuple it just built
        total += s
    return total                    # 799 — full story on return next section

playlist_length(200, 245, 354)      # songs == (200, 245, 354)

def tag_song(title, **extras):      # extras is a DICT
    for key, value in extras.items():
        print(title, key, value)

tag_song("Blinding Lights", artist="The Weeknd", year=2019)

# make_track.py -- one constructor-style function, called four ways

def make_track(title, seconds, artist="Unknown", *, explicit=False):
    """Build one track record.

    title, seconds -- required, usually passed by position
    artist         -- optional, defaults to "Unknown"
    explicit       -- keyword-only: after the bare *, it MUST be named
    """
    return {"title": title, "seconds": seconds,
            "artist": artist, "explicit": explicit}

def show(track):
    mark = "E" if track["explicit"] else " "
    minutes, seconds = divmod(track["seconds"], 60)
    print(f" {mark} {track['title']:<16}{minutes}:{seconds:02d}   {track['artist']}")

# 1 - everything by position, artist falls back to its default
one = make_track("Titanium", 245)

# 2 - all by keyword, in whatever order reads best
two = make_track(seconds=200, title="Blinding Lights", artist="The Weeknd")

# 3 - position for the required pair, name for the keyword-only flag
three = make_track("bad guy", 194, "Billie Eilish", explicit=True)

# 4 - built straight out of a dict the caller already had
row = {"title": "Levels", "seconds": 203, "artist": "Avicii"}
four = make_track(**row)

for track in (one, two, three, four):
    show(track)

print()
print("defaults on the function:", make_track.__defaults__)
print("keyword-only defaults   :", make_track.__kwdefaults__)

try:
    make_track("One Dance", 173, "Drake", True)
except TypeError as e:
    print("TypeError:", e)

   Titanium        4:05   Unknown
   Blinding Lights 3:20   The Weeknd
 E bad guy         3:14   Billie Eilish
   Levels          3:23   Avicii

defaults on the function: ('Unknown',)
keyword-only defaults   : {'explicit': False}
TypeError: make_track() takes from 2 to 3 positional arguments but 4 were given

One question is easy to get wrong, and getting it wrong causes real bugs. When a value slides into a slot, is the function handed a copy, or the original itself?

def add(song, playlist=None):
    if playlist is None:      # a brand-new list per call that needs one
        playlist = []
    playlist.append(song)
    return playlist

def add_song(title, /, artist, *, seconds=180):
    return (title, artist, seconds)

add_song("Blinding Lights", "The Weeknd", seconds=200)   # ok
add_song(title="Blinding Lights", artist="The Weeknd")     # TypeError: title is positional-only
add_song("Blinding Lights", "The Weeknd", 200)          # TypeError: seconds is keyword-only

So arguments flow in and settle into their slots. What flows back out when the work is done — and what does Python quietly hand you when a function never says a word? →

# the bug, run honestly
def queue_song(song, queue=[]):
    queue.append(song)
    return queue

print("call 1:", queue_song("Blinding Lights"))
print("call 2:", queue_song("Titanium"))
print("call 3:", queue_song("bad guy"))
print("stored on the function:", queue_song.__defaults__)

# the fix: None is the sentinel, the real list is built inside the call
def queue_song_fixed(song, queue=None):
    if queue is None:
        queue = []
    queue.append(song)
    return queue

print()
print("call 1:", queue_song_fixed("Blinding Lights"))
print("call 2:", queue_song_fixed("Titanium"))
print("call 3:", queue_song_fixed("bad guy"))
print("stored on the function:", queue_song_fixed.__defaults__)

# and it still lets a caller pass their own list in
mine = ["Levels"]
print("passed in :", queue_song_fixed("Faded", mine))
print("caller's  :", mine)

# ------------- what it prints -------------
call 1: ['Blinding Lights']
call 2: ['Blinding Lights', 'Titanium']
call 3: ['Blinding Lights', 'Titanium', 'bad guy']
stored on the function: (['Blinding Lights', 'Titanium', 'bad guy'],)

call 1: ['Blinding Lights']
call 2: ['Titanium']
call 3: ['bad guy']
stored on the function: (None,)
passed in : ['Levels', 'Faded']
caller's  : ['Levels', 'Faded']

03What comes back: return, or None

A function runs, and then it answers. return is how it answers, and it does two things in the same breath. It stops the call on the spot, and it hands exactly one object back to whoever asked. That second part is the quiet magic. The call expression doesn't merely trigger the work, it becomes the result. Write total = playlist_length(200, 245) and, the instant the call returns, total is simply another name for 445. The parentheses did their job and dissolved. What's left standing where the call used to be is one plain value.

Lean on that word exactly. Not "up to one," not "as many as you like" — one object crosses back, always. And because return also ends the call the moment it fires, any line written after it in the same path is dead on arrival. The function has already left the building. That's not a rule to memorise so much as a consequence of the first job: you can't run more code after you've handed back your answer and gone.

you type
def total(a, b):
    return a + b

def clean(title):
    if not title:
        return                 # bare: nothing worth handing back
    return title.strip().title()

def shout(title):
    print(title.upper())       # prints, returns nothing

def longest():
    return "Titanium", 245     # the comma packs ONE tuple

print(total(200, 245))
print(total(200, 245) + 100)

print(clean("  blinding lights  "))
print(clean(""))

echoed = shout("levels")
print(echoed)

surprise = print("hi")
print(surprise)

pair = longest()
print(pair, type(pair).__name__)
title, seconds = longest()
print(title, seconds)

print(clean("") is None, shout("faded") is None)

you see
445
545
Blinding Lights
None
LEVELS
None
hi
None
('Titanium', 245) tuple
Titanium 245
FADED
True True

So what does a function hand back when it doesn't say return at all? It still answers — with None, Python's built-in nothing-object. Not a crash, not a blank, not the absence of a value. It's a specific, real object whose entire job is to mean "nothing worth returning happened here." You can catch it in your hands and print it:

def shout(title):
    print(title.upper())      # shows on screen — but hands nothing back

echoed = shout("Titanium")    # TITANIUM appears here…
print(echoed)                 # None — the silence has a name

surprise = print("hi")        # careful: print is NOT return
print(surprise)               # None — print SHOWS a value, it never hands one back

That last pair is the trap that snares nearly everyone once. print and return feel like cousins, but they live on opposite sides of a wall. print draws characters on your screen for a human to read, then quietly returns None. return hands an object back to the program so more code can use it. A function that prints its answer but forgets to return it looks perfect on screen. Then it gives you None the moment you try to do anything with the result.

# playlist_report.py -- BEFORE: one flat run of steps, nothing named
playlist = [("Blinding Lights", 200), ("Titanium", 245), ("bad guy", 194),
            ("Levels", 203), ("Faded", 212), ("One Dance", 173)]

total = 0
for title, seconds in playlist:
    total = total + seconds

best_title = playlist[0][0]
best_seconds = playlist[0][1]
for title, seconds in playlist:
    if seconds > best_seconds:
        best_title = title
        best_seconds = seconds

lines = []
lines.append("tracks : " + str(len(playlist)))
lines.append("total  : " + str(total) + " s")
lines.append("longest: " + best_title + " (" + str(best_seconds) + " s)")
print("\n".join(lines))

# playlist_report.py -- AFTER: three named machines, each handing a value back
playlist = [("Blinding Lights", 200), ("Titanium", 245), ("bad guy", 194),
            ("Levels", 203), ("Faded", 212), ("One Dance", 173)]

def total_seconds(tracks):
    """Add every track length and hand the sum back."""
    total = 0
    for title, seconds in tracks:
        total += seconds
    return total

def longest(tracks):
    """Hand back the (title, seconds) pair with the biggest length."""
    best = tracks[0]
    for track in tracks:
        if track[1] > best[1]:
            best = track
    return best

def report(tracks):
    """Build the three lines as one string -- print nothing."""
    title, seconds = longest(tracks)
    return "\n".join([
        f"tracks : {len(tracks)}",
        f"total  : {total_seconds(tracks)} s",
        f"longest: {title} ({seconds} s)",
    ])

print(report(playlist))

tracks : 6
total  : 1227 s
longest: Titanium (245 s)

Watch all of this move. Slide through four functions below: one that returns a number, one with a bare return, one with no return at all, and one that hands back a pair. In every case, whatever crosses the bridge is one object. And the name at the call site simply becomes it.

Which raises the obvious objection. What if you genuinely need two things back — a title and its length? You don't get to break the one-object rule. You bend it. Write return title, seconds and the comma quietly packs both into a single tuple. Remember, it's the comma that builds the tuple, not the parentheses. So still exactly one object makes the crossing. At the other end, chapter 6's unpacking splits it back apart in one clean move:

def longest_song():
    return "Titanium", 245        # the comma packs ONE tuple

pair = longest_song()             # pair  → ('Titanium', 245)  — a single tuple
title, seconds = longest_song()   # unpacked back into two names
print(seconds)                    # 245

The local title lived in a private scratch record that Python built for that one call and destroyed the instant it returned — a frame. Frames stack up as calls nest inside calls and vanish in strict last-opened-first-closed order. Next: the call stack — frames that push and pop →

def mm_ss(seconds):
    """Format a whole number of seconds as M:SS."""
    minutes = seconds // 60
    rest = seconds % 60
    return f"{minutes}:{rest:02d}"

print(mm_ss(1227))
print(mm_ss(245))
print(mm_ss(5))
print(mm_ss(0))
print(mm_ss(60))
print(mm_ss(3600))

playlist = [("Blinding Lights", 200), ("Titanium", 245), ("bad guy", 194),
            ("Levels", 203), ("Faded", 212), ("One Dance", 173)]

total = 0
for title, seconds in playlist:
    total += seconds

print("total  :", mm_ss(total))
for title, seconds in playlist:
    print(f"  {title:<16}{mm_ss(seconds)}")

# ------------- what it prints -------------
20:27
4:05
0:05
0:00
1:00
60:00
total  : 20:27
  Blinding Lights 3:20
  Titanium        4:05
  bad guy         3:14
  Levels          3:23
  Faded           3:32
  One Dance       2:53

04The call stack: frames that push and pop

Chapter 8 had you build a stack by hand — a pile of plates where you only ever touch the top one. Here is the secret. Your interpreter has been running one of those the entire time, underneath every function you have ever called. It is called the call stack. Once you can see it breathe, functions stop being magic boxes and become exactly what they are: a tidy, self-cleaning pile of paperwork.

Every time you call a function, Python tears off a fresh sheet of scratch paper for that one call: a frame. The frame holds this call's local names — its parameters, and any variable it assigns — plus a bookmark remembering which line to come back to. Calling a function pushes its frame onto the top of the stack. Hitting return pops that frame straight back off. Its local names are wiped, and the value it returned flows down into the frame that was waiting below. Last sheet on is the first sheet off. That's the very same LIFO discipline as the plate-stack from chapter 8, because it is one, wired directly into the interpreter.

That one mechanism quietly answers a question you may not have known to ask. If I call the same function twice, why don't the two calls trip over each other's variables? Because each call got its own sheet of paper. Two frames, two private sets of locals, sitting on the stack at the same time and unable to see across the gap. The n inside one call is simply not the n inside another.

Take the smallest honest example from our playlist. One function turns minutes-and-seconds into a plain count of seconds; another adds two songs together. "Blinding Lights" is 3 min 20 s, so song_seconds(3, 20) is 200; "Titanium" is 4 min 5 s, so song_seconds(4, 5) is 245; together, 445. Watch the three shapes the stack passes through as that runs.

A snapshot is a still photograph, though, and a stack is a motion picture. Drag the step below through the whole run — eight beats from the first line to the last. Watch each call push a frame. Watch each return pop one and hand its answer down. And watch the highlighted line track exactly which sheet of paper is doing the work.

One precise thing about what a frame actually stores. It does not hold the objects 200 and 245 themselves — it holds the names that point at them. The objects live out on the heap, the open warehouse we met in chapter 0. A frame's locals are just labelled arrows aimed at that warehouse. So when a frame pops, the arrows vanish, but an object only disappears once nothing anywhere still points at it. Chapter 11 draws that border between stack and heap in full. For now, keep the two jobs apart: the stack tracks who is calling whom, the heap holds the things themselves.

"Eventually says stop" is not a figure of speech. Each frame costs real memory. A runaway recursion — a function that forgets its base case and calls itself forever — would eat the machine alive. So Python draws a hard line: ask sys.getrecursionlimit() and it answers 1000. Let a function call itself with no exit and the tower climbs fast. Then it slams into that ceiling just shy of the thousandth frame, where Python refuses to push another and raises RecursionError. It is not your program crashing randomly. It is the interpreter's seat belt, catching an infinite climb before it takes the whole process down.

Here is the part that pays for the whole section. You have watched the call stack print itself hundreds of times already — every time your code blew up. That wall of "File ..., line ..., in ..." is not noise. It is a photograph of the live stack at the instant something broke, frame by frame, oldest call first. The traceback is the call stack, made visible. (The raise ValueError("no such song") in the next block is how you throw an error on purpose. Here it's just a reliable way to break something so the stack prints. You'll build exceptions and raise properly in a later chapter.)

def a_call():  return b_call()
def b_call():  return c_call()
def c_call(): raise ValueError("no such song")

a_call()
# Traceback (most recent call last):
#   File "boom.py", line 5, in <module>   a_call()      ← bottom of the stack
#   File "boom.py", line 1, in a_call     return b_call()
#   File "boom.py", line 2, in b_call     return c_call()
#   File "boom.py", line 3, in c_call     raise ValueError(...)   ← top, where it broke
# ValueError: no such song

Every frame carries its own private names — so when the same word means one thing inside a function and another thing outside it, which one does Python actually reach for? Next: LEGB, the four-ring search Python runs to look up a name. →

05LEGB: where Python looks up a name

You type a name — plays, len, playlist — and in that instant Python has to decide which of the thousands of things in a running program you actually meant. It does not guess, and it does not rummage everywhere at once. It walks a fixed list of exactly four places, always in the same order, and stops dead the moment it finds a match. That list has a name you'll keep for life: LEGB.

Local — the frame of the function running right now. Enclosing — the names an outer def captured for a def nested inside it. Those live not in the outer frame, which may be long gone by the time the inner one runs, but in a shared cell the inner one can still reach. Global — the module: names defined at the top level of the file, like our playlist. Built-in — the names Python ships and you never had to write: len, print, range, sum. Four rooms, one order, first hit wins. Search all four and come up empty, and Python stops apologising and raises a NameError.

>>> mood = "calm"
>>> def report():
...     print("mood is", mood)
...
>>> def party():
...     mood = "hype"      # the caller's own mood, alive on the stack
...     report()           # GO is pressed from INSIDE party
...
>>> party()
>>> del mood               # now remove the module's mood entirely...
>>> party()                # ...party's "hype" is STILL one sheet below

mood is calm
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 3, in party
  File "<stdin>", line 2, in report
NameError: name 'mood' is not defined

Reading names this way is quiet and intuitive. Right up until the one sharp edge that catches every Python programmer exactly once. Here it is. The instant you assign to a name anywhere inside a function — the first line, the last line, a line that never even runs — that name becomes Local for the entire function, top to bottom. Watch it bite:

plays = 0                      # a global name — the whole app's play count

def play_song(title):
    plays = plays + 1          # UnboundLocalError — not the error you expected
    print("now playing", title)

Read that and your gut says: "but plays is right there, it's 0, just add one." Python disagrees, and the reason is beautiful once you see it. Python sorts every name into local-or-not when it compiles the def, before a single line has run. It scans the whole body, spots plays = …, and stamps plays as Local then and there. So at run time the read half of plays = plays + 1 doesn't fall through to the global. It looks in the function's own local slot — which is real, reserved, and still empty. Reaching into an empty local slot is exactly the UnboundLocalError you get. The global plays = 0 was never even consulted. The name had already been claimed by the local room.

Once you know the cause, the two cures are obvious. If you genuinely mean to rewrite the module's plays, say so out loud with global. That keyword tells the compiler "don't stamp this local — the real one lives in the module." And when the name you mean to rewrite lives in an enclosing function rather than the module, there's a matching keyword for that too. You won't feel the need for it until closures start remembering things, two sections down, so we'll meet it there. But most of the time the cleanest fix is to touch no outer name at all: take the value in, hand a new value back.

you type
plays = 0

def show_plays():
    print("read only, no assignment:", plays)

def bump_broken():
    plays = plays + 1          # claims `plays` as local, so the read fails

def bump_global():
    global plays
    plays = plays + 1

def next_count(plays):         # the clean fix: in through a slot, out via return
    return plays + 1

def make_counter():
    count = 0
    def bump():
        nonlocal count
        count += 1
        return count
    return bump

show_plays()

try:
    bump_broken()
except UnboundLocalError as e:
    print("UnboundLocalError:", e)

bump_global()
bump_global()
print("after two bumps, plays =", plays)

print("next_count(7) =", next_count(7), "| global plays still", plays)

tick = make_counter()
print(tick(), tick(), tick())

print(len("Titanium"))

you see
read only, no assignment: 0
UnboundLocalError: cannot access local variable 'plays' where it is not associated with a value
after two bumps, plays = 2
next_count(7) = 8 | global plays still 2
1 2 3
8

plays = 0

# option A — opt in to the global, and mean it
def bump_global():
    global plays
    plays = plays + 1          # after two calls, plays == 2

# option B — never touch the global; take it in, give it back
def next_count(plays):
    return plays + 1          # the caller decides where the result goes

Now let's watch the search itself run. Here's a tiny nested program: a play function tucked inside a make_player function, over a module-level playlist. Four different rooms hold the four names its body uses. Calling make_player(5) then play(200) returns 207 — that's 200 + 5 + 2. Drag the control below and follow Python's eyes as it walks L → E → G → B, crossing off each room that misses until one hits.

playlist = [200, 245]             # G — "Blinding Lights", "Titanium"

def make_player(bonus):           # bonus lives in the ENCLOSING frame
    def play(seconds):            # seconds is LOCAL to play
        return seconds + bonus + len(playlist)
    return play

We keep saying "def just builds an object and binds a name." So play is a value like any other — you can hand the whole machine to someone else, not just the number it spits out. Next: functions are values you can pass around. →

3 min 20 s
4 min 5 s
Traceback (most recent call last):
  File "C:\tmp\minutes.py", line 4, in <module>
    total = song_minutes(200) + song_minutes(245)
            ~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~
TypeError: unsupported operand type(s) for +: 'NoneType' and 'NoneType'

Traceback (most recent call last):
  File "C:\tmp\lineup.py", line 4, in <module>
    line = add_song("Blinding Lights")
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: add_song() missing 2 required positional arguments: 'artist' and 'seconds'

Traceback (most recent call last):
  File "C:\tmp\leftover.py", line 6, in <module>
    print(total)
          ^^^^^
NameError: name 'total' is not defined

bonus = 10
playlist = ["Titanium"]

# A - reads a global it never assigns: the LEGB walk finds it, no keyword needed
def a():
    return bonus + 1

# B - assigns bonus ANYWHERE, so bonus is local for the WHOLE body.
#     The read on the line above the assignment hits an empty local slot.
def b():
    total = bonus + 1
    bonus = 99
    return total

# C - a local named bonus, born and dead inside the call. The module's 10 never moves.
def c():
    bonus = 99
    return bonus

# D - no assignment at all: it MUTATES the object both names share.
def d():
    playlist.append("Levels")
    return len(playlist)

print("A:", a())

try:
    print("B:", b())
except UnboundLocalError as e:
    print("B: UnboundLocalError:", e)

print("C:", c(), "| module bonus still", bonus)
print("D:", d(), "| module playlist now", playlist)

# ------------- what it prints -------------
A: 11
B: UnboundLocalError: cannot access local variable 'bonus' where it is not associated with a value
C: 99 | module bonus still 10
D: 2 | module playlist now ['Titanium', 'Levels']

# The word that separates C from D is ASSIGNMENT.
#   C assigns: the name is claimed as local, and the module's name is untouched.
#   D mutates: no name is claimed, so it edits the one object the caller can see.
# To make B work, choose one: `global bonus` (and mean it), or pass bonus in
# as a parameter and return the new value. The second has no hidden state.

06Functions are values: pass the machine, not its output

Everything you've handed a function so far has been data — a number, a string, a tuple of a song and its length. Now watch the floor tilt. In Python a function is itself just another value: an object like any other, with a type, an identity, and an address in RAM. You can drop it in a list, pin a second name on it, stash it as a value in a dict, or post it to another function as an argument. Python's word for this is first-class. A function gets the exact same rights as a plain 200. And that one fact quietly explains the mysterious key= you first met when you sorted a playlist back in chapter 6.

Say you want the playlist ordered by length, shortest first. You write the rule for what to sort by as an ordinary function. Then you hand that function to sort. The function itself, mind you, not a call to it:

playlist = [("Blinding Lights", 200), ("Titanium", 245), ("bad guy", 194)]

def by_seconds(song):
    return song[1]                # pull out the length field

playlist.sort(key=by_seconds)      # hand over the machine — no parentheses
# playlist is now ordered shortest-first:
# [("bad guy", 194), ("Blinding Lights", 200), ("Titanium", 245)]

Notice what's missing: no parentheses after by_seconds. That absence is the entire idea, and it trips almost everyone the first time.

you type
playlist = [("Blinding Lights", 200), ("Titanium", 245), ("bad guy", 194)]

def by_seconds(song):
    return song[1]

print(sorted(playlist, key=by_seconds))
print(sorted(playlist, key=lambda song: song[1]))
print(sorted(playlist, key=lambda song: song[0]))
print(sorted(playlist, key=lambda song: song[0].lower()))
print(sorted(playlist, key=lambda song: -song[1]))
print(max(playlist, key=lambda song: song[1]))
print(sorted(["Levels", "bad guy", "One Dance"], key=len))

f = lambda song: song[1]
print(type(f).__name__, f.__name__, by_seconds.__name__)
print(f(("Faded", 212)))

try:
    sorted(playlist, key=by_seconds())
except TypeError as e:
    print("TypeError:", e)

you see
[('bad guy', 194), ('Blinding Lights', 200), ('Titanium', 245)]
[('bad guy', 194), ('Blinding Lights', 200), ('Titanium', 245)]
[('Blinding Lights', 200), ('Titanium', 245), ('bad guy', 194)]
[('bad guy', 194), ('Blinding Lights', 200), ('Titanium', 245)]
[('Titanium', 245), ('Blinding Lights', 200), ('bad guy', 194)]
('Titanium', 245)
['Levels', 'bad guy', 'One Dance']
function <lambda> by_seconds
212
TypeError: by_seconds() missing 1 required positional argument: 'song'

When the machine is a single expression and needs no name of its own, you can build it right at the call site with lambda. Read lambda song: song[1] straight across. lambda announces a tiny function, song is its one parameter, and whatever the expression after the colon comes out to is returned automatically — no def, no return, no name. It's the very same kind of object by_seconds is, just born anonymous and thrown away after one use:

# same order, machine built inline and forgotten after
playlist.sort(key=lambda song: song[1])

# a lambda is the SAME kind of object as a def'd function
f = lambda song: song[1]
type(f)              # <class 'function'>   — identical type
f.__name__           # '<lambda>'           — just born nameless
by_seconds.__name__  # 'by_seconds'

# because functions are values, a dict can be a menu of them
order_by = {"length": by_seconds, "title": lambda s: s[0]}
playlist.sort(key=order_by["length"])   # look up a machine by name, then hand it over

Here's a concrete itch. You want a plays() that returns 1, then 2, then 3 — a counter that remembers across calls. A plain local won't do it: every call gets a fresh frame, so the count resets to 0 each time. A module global works but leaks — every caller now shares one hidden number, spooky action at a distance. A whole class (chapter 12) is a lot of ceremony for a single integer. What you actually want is private state that lives between calls and belongs to no one else. Here is the move that gives it to you. Define a function inside another function and return the inner one. The inner function keeps using a name from the outer function's frame, even after that frame has finished and popped. The compiler sees this coming at compile time. It marks that name for capture, so instead of a plain frame slot the value is born in a small heap-allocated box called a cell, which the inner function grips for as long as it lives. An inner function carrying captured variables like this is a closure. And nonlocal is the keyword that lets it rebind a captured name instead of accidentally shadowing it with a fresh local:

def make_counter():
    count = 0                  # lives in make_counter's frame
    def bump():
        nonlocal count         # rebind the ENCLOSING count, don't make a new local
        count += 1
        return count
    return bump                # hand the inner machine out; the frame then pops

plays = make_counter()
plays()   # 1
plays()   # 2
plays()   # 3   — the count survived, with no global and no class

You can now hand a machine to sort. Next chapter you hand machines to map and filter, collapse whole loops into a single-line comprehension, and wire up sequences so lazy they compute each value only at the instant you ask for it — and barely touch memory doing it →

# dice_roll.py -- Ajai's Dice Roll Simulation, rebuilt so the functions are the star
import random

def roll(sides=6):
    """One roll of one die: a whole number from 1 to sides, inclusive."""
    return random.randint(1, sides)

def simulate(rolls, sides=6):
    """Roll `rolls` times. Hand back a dict of face -> how often it came up."""
    counts = {face: 0 for face in range(1, sides + 1)}
    for _ in range(rolls):
        counts[roll(sides)] += 1
    return counts

def summarize(counts):
    """Turn the counts into report lines. Prints nothing -- it returns."""
    rolls = sum(counts.values())
    lines = []
    for face, times in counts.items():
        bar = "#" * round(times / rolls * 60)
        lines.append(f"  {face}  {bar:<14}{times:>4}  {times / rolls:6.1%}")
    top = max(counts, key=counts.get)
    lines.append(f"  {rolls} rolls | most common face: {top} ({counts[top]} times)")
    return lines

random.seed(9)          # same seed, same run -- so your screen matches this page

print("one roll :", roll())
print("one roll :", roll())
print("one d20  :", roll(20))
print()

counts = simulate(600)
for line in summarize(counts):
    print(line)

one roll : 4
one roll : 5
one d20  : 12

  1  ############   125   20.8%
  2  ##########     103   17.2%
  3  #########       90   15.0%
  4  #########       92   15.3%
  5  ###########    106   17.7%
  6  ########        84   14.0%
  600 rolls | most common face: 1 (125 times)