{"title":"Closures","description":"","content":"A closure is an inner function that remembers the variables from the function that built it, even after that outer function has returned. The remembered names aren't copied into the inner function; they're kept alive by reference, in a small piece of bookkeeping Python attaches to the function object. This lesson covers what a closure is, how to spot the free variables that get captured, how to build per-customer pricing functions with a function factory, how to inspect the captured state with `__closure__`, how `nonlocal` lets the inner function update that state, and the late-binding pitfall that catches almost everyone the first time they build closures inside a loop.\n\n---\n\n# What a Closure Is\n\nA function defined inside another function can use the names of the enclosing function. That part is normal scoping. The interesting part is that the inner function keeps working even after the outer function has finished and returned, and it still sees those enclosing names. That's a closure: an inner function plus the environment it captured from its birthplace.\n\n\n```python\ndef make_greeter(customer_name):\n def greet():\n return f\"Welcome back, {customer_name}!\"\n return greet\n\ngreet_alice = make_greeter(\"Alice\")\ngreet_bob = make_greeter(\"Bob\")\n\nprint(greet_alice())\nprint(greet_bob())\n```\n\n\n`make_greeter` runs, builds a `greet` function, and returns it. By the time `greet_alice()` is called on the next line, the call to `make_greeter(\"Alice\")` is long over. The `customer_name` parameter should be gone with it. But it isn't. The returned function still knows `customer_name == \"Alice\"`, because the function object carries a reference to that variable's cell with it.\n\nThe same factory called with `\"Bob\"` produces a different function with a different captured `customer_name`. Two greeters, two captured strings, no interference. Each closure has its own private environment.\n\nThe shape that makes this a closure (and not just a regular nested function) is three things together:\n\n1. A function defined inside another function.\n2. The inner function uses a name from the outer function's scope.\n3. The outer function returns the inner function (or stores it somewhere that outlives the outer call).\n\nIf any of those is missing, you have a nested function but not really a closure in the useful sense. The captured environment only matters if the inner function survives long enough to be called after its creator returns.\n\n\n```mermaid\nflowchart LR\n OUTER[\"make_greeter('Alice')
customer_name = 'Alice'\"]:::cyan\n CELL[\"cell
'Alice'\"]:::orange\n INNER[\"greet (returned)
uses customer_name\"]:::green\n CALLER[\"greet_alice()
called later\"]:::teal\n\n OUTER -->|\"binds\"| CELL\n INNER -->|\"references\"| CELL\n OUTER -->|\"returns\"| INNER\n CALLER -->|\"invokes\"| INNER\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe cyan box is the outer call; it disappears once it returns. The orange box is the cell, a small container Python uses to hold a name that's referenced from a nested scope. The green box is the inner function that gets returned. The cell stays alive because the returned function keeps a reference to it, which is why `greet_alice()` still sees `\"Alice\"` long after `make_greeter` has finished.\n\n---\n\n# Free Variables\n\nInside the inner function, the name `customer_name` is a **free variable**: a name that's used in the function but not defined by it and not a parameter of it. Python resolves free variables by looking at the enclosing function's scope (and then the module scope, and then builtins, in the usual LEGB order).\n\nThe thing that makes a free variable special, compared to just any unknown name, is that Python knows about it at compile time. When the function is built, Python sees that `customer_name` is referenced but not assigned and not a parameter, and it wires up a closure cell for it. That's why the inner function can find the value later, even after the outer call has returned.\n\n\n```python\ndef make_discount(percent):\n def apply(price):\n # `percent` is a free variable. `price` is a parameter.\n return price * (1 - percent / 100)\n return apply\n\nten_off = make_discount(10)\ntwenty_off = make_discount(20)\n\nprint(ten_off(50.00))\nprint(twenty_off(50.00))\n```\n\n\nInside `apply`, `price` is a parameter (bound when `apply` is called), and `percent` is a free variable (captured from `make_discount`'s scope). Each call to `make_discount` produces a new `apply` function with its own captured `percent`. `ten_off` remembers `10`; `twenty_off` remembers `20`. Calling either one only needs `price`.\n\nA free variable isn't the same as a global. The free variable is captured from an **enclosing function's** local scope, not from the module. If you replace the outer function's local with a module-level name, the inner function would read the module-level name instead, and you'd lose the per-call isolation.\n\n\n```python\npercent = 10\n\ndef apply(price):\n return price * (1 - percent / 100)\n\nprint(apply(50.00))\n\npercent = 20\nprint(apply(50.00))\n```\n\n\nThis version isn't a closure. There's only one `percent`, and it lives at the module level. Both calls read whatever the current module-level value happens to be. Closures matter because the captured value is private to that specific inner function and survives across other code changing module state.\n\n\n> **INFO**\n>\n> **Cost:** A closure cell is small (about the size of one reference) per captured name. The cost is the same whether you capture one name or several. If you find yourself capturing five or more names, a small class with attributes is usually clearer to read, not because of performance but because of clarity.\n\n\n---\n\n# Building a Function Factory\n\nThe `make_discount` example is the classic function factory: a function whose only job is to return a customized version of another function. Function factories are where closures earn their keep, because they let you parameterize behavior once and reuse the resulting function many times without re-passing the same arguments.\n\nA multiplier factory makes the shape obvious:\n\n\n```python\ndef make_multiplier(factor):\n def multiply(value):\n return value * factor\n return multiply\n\ndouble = make_multiplier(2)\ntriple = make_multiplier(3)\n\nprint(double(10))\nprint(triple(10))\nprint(double(triple(5)))\n```\n\n\nThree different multipliers built from the same factory, each with its own captured `factor`. The factory itself is six lines; everything else is reuse.\n\nIn an E-Commerce setting, the same shape gives you per-discount-tier pricing functions you can hand around to whichever piece of code needs them:\n\n\n```python\ndef make_discount(percent):\n def apply(price):\n return round(price * (1 - percent / 100), 2)\n return apply\n\n# Build the discount tier functions once, at startup.\nmember_price = make_discount(10)\nloyalty_price = make_discount(15)\nclearance_price = make_discount(40)\n\ncart = [29.99, 14.99, 9.99, 49.99]\n\nprint([member_price(p) for p in cart])\nprint([loyalty_price(p) for p in cart])\nprint([clearance_price(p) for p in cart])\n```\n\n\nThree pricing functions, each carrying its own discount percent. The caller never has to remember which percent goes with which tier; the function knows.\n\nThe same shape works when the captured value is structured. Suppose each customer has a personal discount profile (a base percent plus a loyalty bonus). A factory takes the profile and returns a price function tied to that one customer:\n\n\n```python\ndef build_customer_pricer(base_percent, loyalty_bonus):\n total = base_percent + loyalty_bonus\n\n def price_for(amount):\n return round(amount * (1 - total / 100), 2)\n\n return price_for\n\nalice_price = build_customer_pricer(base_percent=10, loyalty_bonus=5)\nbob_price = build_customer_pricer(base_percent=0, loyalty_bonus=0)\ncarol_price = build_customer_pricer(base_percent=20, loyalty_bonus=10)\n\nprint(alice_price(100.00))\nprint(bob_price(100.00))\nprint(carol_price(100.00))\n```\n\n\nAlice gets 15% off (10 base + 5 loyalty), Bob gets nothing, Carol gets 30% off. Each price function captures `total` from the call to `build_customer_pricer` and uses it forever after. The factory is also doing a little setup (computing `total` once) that the inner function gets for free on every call.\n\nFunction factories are the underlying idea behind decorators, but you don't need decorators to use them. Any time you find yourself writing `def f(x): return some_operation(x, fixed_arg)` for several different `fixed_arg`s, a factory will save you the repetition.\n\n---\n\n# Inspecting the Closure\n\nPython doesn't hide the closure machinery; it puts it right on the function object. Every function has a `__closure__` attribute, and every function has a `__code__` attribute that knows which names are free.\n\nFor a function with no closure, `__closure__` is `None`:\n\n\n```python\ndef plain():\n return 1\n\nprint(plain.__closure__)\nprint(plain.__code__.co_freevars)\n```\n\n\nNo captured names, no closure cells. The `co_freevars` tuple is empty.\n\nFor a function returned from a factory, `__closure__` is a tuple of **cell objects**, one per free variable. Each cell holds the captured value, and you read it with `.cell_contents`.\n\n\n```python\ndef make_discount(percent):\n def apply(price):\n return price * (1 - percent / 100)\n return apply\n\nten_off = make_discount(10)\n\nprint(ten_off.__code__.co_freevars)\nprint(ten_off.__closure__)\nprint(ten_off.__closure__[0].cell_contents)\n```\n\n\nThe `co_freevars` tuple lists the names that were captured (just `percent` here). The `__closure__` tuple has one cell, and its `cell_contents` is the captured value, `10`. The exact memory address in the cell repr varies between runs; the shape is what matters.\n\nWhen a closure captures more than one name, the order of `co_freevars` matches the order of `__closure__`:\n\n\n```python\ndef build_customer_pricer(base_percent, loyalty_bonus):\n total = base_percent + loyalty_bonus\n\n def price_for(amount):\n return amount * (1 - total / 100)\n\n return price_for\n\nf = build_customer_pricer(10, 5)\n\nprint(f.__code__.co_freevars)\nfor name, cell in zip(f.__code__.co_freevars, f.__closure__):\n print(f\" {name} = {cell.cell_contents}\")\n```\n\n\nNotice that `base_percent` and `loyalty_bonus` are **not** captured. The inner function never references them; it only references `total`. The compiler only allocates closure cells for the names that are actually used, which is one reason captures stay cheap.\n\nInspecting `__closure__` is mostly a debugging and learning tool. In day-to-day code you write closures without thinking about the cells. But when something behaves unexpectedly (a closure that keeps returning the same value, for example), a quick look at `__closure__` will often tell you what the function is actually carrying.\n\n\n> **INFO**\n>\n> **Cost:** Reading `__closure__` and `cell_contents` is constant time. There's no special cost. The main use is debugging, not hot-path inspection.\n\n\n---\n\n# Mutating Closed-Over State with `nonlocal`\n\nThe closures shown so far all **read** their captured names. Reading is enough for most function factories. But sometimes you want the inner function to update the captured value across calls, the way a counter or a running total would.\n\nBy default, an assignment inside the inner function creates a new local variable; it doesn't touch the captured one. `nonlocal` is the keyword that tells Python \"this name belongs to the nearest enclosing function, not to me, so writes should go there\".\n\nHere, we just need the one piece: `nonlocal name` lets the inner function rebind a name from the enclosing function.\n\nA counter is the simplest demonstration:\n\n\n```python\ndef make_counter():\n count = 0\n\n def next_value():\n nonlocal count\n count += 1\n return count\n\n return next_value\n\nticker = make_counter()\nprint(ticker())\nprint(ticker())\nprint(ticker())\n```\n\n\nEach call to `ticker()` reads the current `count`, adds one, rebinds the same name in the enclosing scope, and returns the new value. The state lives in the closure cell, not in the inner function. Three calls, three different return values, because the cell keeps updating in place.\n\nRemove the `nonlocal` and the same code breaks:\n\n\n```python\ndef make_counter_broken():\n count = 0\n\n def next_value():\n count += 1\n return count\n\n return next_value\n\nticker = make_counter_broken()\nprint(ticker())\n```\n\n\nWithout `nonlocal`, the `count += 1` makes Python treat `count` as a local in `next_value`. The local has no initial value when the line runs, so reading it raises `UnboundLocalError`. The fix is to add `nonlocal count` at the top of the inner function.\n\nAn invoice-number factory is the same shape with a less abstract use:\n\n\n```python\ndef make_invoice_counter(start=1000):\n next_id = start\n\n def next_invoice():\n nonlocal next_id\n result = next_id\n next_id += 1\n return result\n\n return next_invoice\n\ninvoice = make_invoice_counter(start=1001)\n\nprint(invoice())\nprint(invoice())\nprint(invoice())\n```\n\n\nEvery call to `invoice()` hands back the next number and advances the captured state. Two invoice counters built from the same factory don't share state; each has its own `next_id` cell.\n\n\n```python\ninvoice_a = make_invoice_counter(start=1)\ninvoice_b = make_invoice_counter(start=5000)\n\nprint(invoice_a(), invoice_a(), invoice_a())\nprint(invoice_b(), invoice_b(), invoice_b())\nprint(invoice_a())\n```\n\n\n`invoice_a` and `invoice_b` are independent. Counter `a` advances 1, 2, 3, then 4. Counter `b` advances 5000, 5001, 5002. The two cells are unrelated; the factory creates a fresh one per call.\n\nA running total is the same shape with addition instead of incrementing:\n\n\n```python\ndef make_running_total():\n total = 0.0\n\n def add(amount):\n nonlocal total\n total += amount\n return total\n\n return add\n\ncart_total = add_to_cart = make_running_total()\n\nprint(cart_total(29.99))\nprint(cart_total(14.99))\nprint(cart_total(9.99))\n```\n\n\nThe captured `total` accumulates across calls. Whatever the caller passes in gets added; the new running total is what comes back.\n\nThere's a small but useful escape hatch: if the captured value is a mutable container (a list, dict, or set), you can mutate it through the closure without `nonlocal`, because mutating isn't rebinding.\n\n\n```python\ndef make_event_log():\n events = []\n\n def log(event):\n events.append(event) # mutating, not reassigning\n return list(events)\n\n return log\n\nlog = make_event_log()\nprint(log(\"placed\"))\nprint(log(\"shipped\"))\nprint(log(\"delivered\"))\n```\n\n\nNo `nonlocal` needed. The `events` name still points at the same list object across calls; we're calling `.append` on that list, not rebinding `events`. This is a common pattern, but it's worth being aware that it only works because the value is mutable. The moment you write `events = events + [event]`, you'd be rebinding, and you'd need `nonlocal` again (or the code would silently create a fresh local).\n\n---\n\n# The Late-Binding Pitfall\n\nHere's the bug that almost everyone hits the first time they build closures in a loop. The closure remembers the **variable**, not the value at the time the inner function was defined. When all the closures end up sharing the same variable, they all end up returning the same final value.\n\nThe canonical demonstration uses `lambda`, but the bug is about closures, not about lambdas; a `def` version has the same problem. Here's both, side by side.\n\n\n```python\n# With lambda\nfuncs = [lambda: i for i in range(3)]\nprint([f() for f in funcs])\n```\n\n\n\n```python\n# With def: same bug.\ndef build():\n funcs = []\n for i in range(3):\n def grab():\n return i\n funcs.append(grab)\n return funcs\n\nfuncs = build()\nprint([f() for f in funcs])\n```\n\n\nYou'd expect `[0, 1, 2]`. You get `[2, 2, 2]`. Three separate closures, all built inside the same loop, all returning the same value.\n\nThe reason is that `i` is one variable, shared across every iteration of the loop. The loop rebinds `i` to a new value each pass, but it doesn't create a new variable. Every inner function captured a reference to that same `i`. By the time you call any of the saved functions, the loop has finished, and `i` is sitting at its final value, `2`. All three closures read the same cell and see the same `2`.\n\n\n```mermaid\nflowchart LR\n LOOP[\"for i in range(3)\"]:::cyan\n CELL[\"cell
i = 2 (final)\"]:::red\n F0[\"funcs[0]
returns i\"]:::orange\n F1[\"funcs[1]
returns i\"]:::orange\n F2[\"funcs[2]
returns i\"]:::orange\n\n LOOP -->|\"binds\"| CELL\n F0 -->|\"reads\"| CELL\n F1 -->|\"reads\"| CELL\n F2 -->|\"reads\"| CELL\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThe red cell is the shared `i`. All three closures point at it. When the loop ends, `i` is `2`, so every closure that reads `i` sees `2`.\n\nThis is called **late binding** because the value of the free variable is resolved late, at call time, not at the time the inner function was defined. Most of the time, late binding is what you want (a closure should reflect the current state of the cell it captured). Inside a loop where the captured name is the loop variable, it's almost never what you want.\n\n### Fix 1: Default Argument Capture\n\nThe most common fix is to turn the loop variable into a default argument of the inner function. Default arguments are evaluated **once**, at the time the inner function is defined, so each iteration produces a function with its own captured value.\n\n\n```python\nfuncs = [lambda i=i: i for i in range(3)]\nprint([f() for f in funcs])\n```\n\n\nThe `i=i` looks weird but it's a normal default argument. The left `i` is the parameter name of the lambda; the right `i` is the current value of the loop variable, evaluated when the lambda is built. By the time the loop ends and you call `funcs[0]()`, that lambda's `i` parameter still defaults to `0`, because that was the value of the outer `i` when the lambda was defined.\n\nThe `def` version of the same fix:\n\n\n```python\ndef build():\n funcs = []\n for i in range(3):\n def grab(i=i):\n return i\n funcs.append(grab)\n return funcs\n\nprint([f() for f in build()])\n```\n\n\nSame trick: `i=i` makes `i` a parameter of `grab`, with a default that's the loop variable's current value. The inner function no longer has `i` as a free variable; it's a parameter now, so it doesn't go through the closure cell at all.\n\n### Fix 2: Capture Through a Helper Factory\n\nThe other fix is to introduce an extra function whose job is to take the loop variable as an argument and return a closure over **that argument**, not over the loop variable directly. Because function parameters are local, each call to the helper produces a separate binding.\n\n\n```python\ndef make_grabber(value):\n def grab():\n return value\n return grab\n\nfuncs = [make_grabber(i) for i in range(3)]\nprint([f() for f in funcs])\n```\n\n\nEach call to `make_grabber(i)` evaluates `i` once (passing its current value as the argument `value`), then returns a closure that captures `value`. Three calls, three separate `value` parameters, three separate closures. The shared loop variable never gets captured by any inner function.\n\nOf the two fixes, the default-argument trick is shorter for a one-liner. The factory approach is clearer for more complex inner functions, because it doesn't mix the closure variable with the parameter list of the inner function. Either one solves the bug; both are common in real code.\n\n\n```python\n# Real-world version with a discount factory in a loop.\n\ndef make_discount(percent):\n def apply(price):\n return round(price * (1 - percent / 100), 2)\n return apply\n\n# Build a discount function for each tier.\ntiers = [5, 10, 15, 25]\ndiscounts = [make_discount(t) for t in tiers]\n\nfor tier, fn in zip(tiers, discounts):\n print(f\"{tier}% off 50.00 -> {fn(50.00)}\")\n```\n\n\nThis is the factory pattern from earlier, used inside a loop. It doesn't trip the late-binding bug because `make_discount` takes its argument as a parameter (`percent`), so each call gets its own fresh binding. The pitfall only shows up when the inner function captures the loop variable directly.\n\n\n> **INFO**\n>\n> **Cost:** All three patterns (broken, default-argument fix, helper factory) have the same runtime cost per call. The broken version isn't faster; it's just wrong. Pick the fix based on readability for the situation.\n\n\n---\n\n# Closures vs Classes\n\nA closure carries state. A class carries state too. Once you've seen both, the question \"which one should I use?\" comes up naturally, because either can do the job.\n\nA class version of the counter factory:\n\n\n```python\nclass Counter:\n def __init__(self, start=0):\n self.count = start\n\n def next(self):\n self.count += 1\n return self.count\n\nc = Counter()\nprint(c.next())\nprint(c.next())\nprint(c.next())\n```\n\n\nA closure version of the same thing:\n\n\n```python\ndef make_counter(start=0):\n count = start\n\n def next_value():\n nonlocal count\n count += 1\n return count\n\n return next_value\n\nc = make_counter()\nprint(c())\nprint(c())\nprint(c())\n```\n\n\nBoth work, both keep state, both isolate state per instance. Which one fits depends on what else you need:\n\n\n| Need | Closure | Class |\n| --- | --- | --- |\n| One operation, simple state | Cleaner | Fine |\n| Several related operations on shared state | Awkward (one function returns) | Cleaner (methods) |\n| Easy serialization (pickle, JSON) | Harder | Easier |\n| Inspect or change state from outside | Harder (need to expose getters) | Direct attribute access |\n| Inheritance, subtyping | Not really | Yes |\n| Function-shaped API (callbacks, handlers) | Natural | Have to define `__call__` |\n| Type hints for the produced thing | `Callable[..., T]` | The class itself |\n\n\nA rule of thumb that holds up well: if the state has **one operation**, a closure is usually the cleaner choice. The factory function describes the setup, and the returned function describes the operation. The reader doesn't have to learn a class to understand what's going on.\n\nIf the state has **multiple operations** (an invoice counter that can both issue a new ID and let you reset it and query the current value), a class is usually clearer. You'd have to return a tuple of functions, or a dict of functions, to do the same thing with closures, and at that point you've reinvented a worse version of a class.\n\n\n```python\n# Multiple operations: class is clearer.\n\nclass InvoiceCounter:\n def __init__(self, start=1000):\n self._next_id = start\n\n def next(self):\n result = self._next_id\n self._next_id += 1\n return result\n\n def peek(self):\n return self._next_id\n\n def reset(self, start=1000):\n self._next_id = start\n\ninv = InvoiceCounter(start=2001)\nprint(inv.next())\nprint(inv.next())\nprint(inv.peek())\ninv.reset(start=5000)\nprint(inv.next())\n```\n\n\nThree operations on the same state. A closure version would either return three functions (returned together as a tuple) or pack them into a dict, both of which are clunkier than just having three methods on a class.\n\nThe other thing closures do naturally is fit into APIs that want a **function**: a sort key, a callback, a key extractor, a filter predicate. You hand the closure to the API, and the API calls it the way it would call any function. A class instance can also be used in those spots if it defines `__call__`, but that's more ceremony than most cases need.\n\n\n```python\nproducts = [\n {\"name\": \"Wireless Mouse\", \"price\": 29.99},\n {\"name\": \"USB Cable\", \"price\": 4.99},\n {\"name\": \"HDMI Cable\", \"price\": 14.99},\n {\"name\": \"Webcam\", \"price\": 89.99},\n]\n\ndef make_price_filter(max_price):\n def under_budget(product):\n return product[\"price\"] <= max_price\n return under_budget\n\ncheap = list(filter(make_price_filter(15.00), products))\nfor p in cheap:\n print(f\"{p['name']}: ${p['price']}\")\n```\n\n\n`make_price_filter(15.00)` returns a closure that captures the budget. `filter` calls it once per product. The whole filter rule fits in a six-line factory, and the caller passes it to `filter` like any function. A class version would work but would add three lines for `__init__` and `__call__` without changing what the code does.","pageType":"python"}

Closures

Get Premium