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 here, because most tutorials walk straight past one question. 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 actually 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, climbed the LEGB ladder Python uses to resolve a name, and 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 lines: the same three lines copied out thirty-nine needless times, and every copy is 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: labelled empty slots built into the machine's design, waiting to be filled. 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.

In memory, def does something you have already met. It builds a function object on the heap — the machine itself, holding the compiled body plus the list of parameter names. Then it binds the name describe to that object, 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, and 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 and 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. We pull hard on that thread later in the chapter.

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 this 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 — seconds=200 flies straight to the seconds slot no matter where you write it, whatever the order. 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.

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 the overflow into a single collected object. *args scoops up every spare positional argument into a tuple, and **kwargs scoops up every spare keyword argument into a dict. These 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.)

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)

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? →

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 key idea. 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 have done their job; 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 never runs: the function has already left. That's less a rule to memorise than a consequence of the first job. You can't run more code after you've handed back your answer and gone.

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, yet gives you None the moment you try to do anything with the result.

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, but you can 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 →

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 how it works, 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. It'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 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, that's 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, each return pop one and hand its answer down, and the highlighted line show 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, and 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, and the heap holds the things themselves.

"Eventually says stop" is not a figure of speech. Each frame costs real memory, and 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 slams into that ceiling just shy of the thousandth frame. At that point Python refuses to push another frame 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 search everywhere at once. It walks a fixed list of exactly four places, always in the same order, and stops 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, held not in that 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.

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, even a line that never 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 makes sense 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 clear. If you genuinely mean to rewrite the module's plays, say so 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. Most of the time, though, the cleanest fix is to touch no outer name at all: take the value in, hand a new value back.

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, which is 200 + 5 + 2. Drag the control below and follow Python 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. →

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 for the shift. 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 pass 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 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, and 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: there are no parentheses after by_seconds. That absence is the entire idea, and it trips almost everyone the first time.

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 works 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 problem. 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 and 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 →