Shelf · Python · Chapter 5

Chapter 5: Decorators & context managers

A decorator attaches reusable behaviour to any callable without touching its source; a context manager guarantees cleanup runs whether the body succeeds or explodes. Together they replace most hand-written try/finally blocks in production ETL code.

Difficulty
Priority
py-05-01Card 1 of 6

Write decorators that preserve function metadata

MediumP2 · Very likelyKnow cold11 min
decoratorsfunctoolsmetadatawrapswrapper
Needs: nothing. Start here.

Why you care

Every decorator tutorial shows you how to add timing or logging. What none of them warn you about is that a decorator without functools.wraps silently renames the function it wraps. Your audit log starts showing "wrapper" instead of "load_orders". Your docstrings disappear. Introspection tools, type checkers and monitoring dashboards all use __name__ and __doc__ — lose them and you spend twenty minutes per incident trying to figure out which "wrapper" in the stack trace crashed. Interviewers ask "what does functools.wraps do?" because it is the single line that separates a toy decorator from a production one, and forgetting it is a 3-year developer's most common decorator mistake.

Explain like I'm 5

Think of a decorator as a new coat of paint on a car. The car still drives the same, but if the painter forgets to keep the old number plate, the DMV has no idea whose car it is. functools.wraps is the instruction to the painter: keep the original plate, keep the VIN sticker, keep the service history. Without it you have a car nobody can identify.

Core concept

A decorator is any callable that takes a function and returns a callable. The minimal form is a three-layer stack: the outer function receives the target, defines a wrapper, and returns it.

  • functools.wraps(func) assigns __module__, __name__, __qualname__, __doc__, __annotations__ and __type_params__ (3.12+) from func onto the new wrapper, and updates the wrapper's __dict__ with the original's. It also sets __wrapped__ to point directly at the original.
  • __wrapped__ lets callers bypass all decoration layers: f.__wrapped__(*args) calls the bare function.
  • Stacking order: decorators apply bottom-up at definition, but execute outer-to-inner at call time. If @A sits above @B, A's wrapper runs first when you call the function.
  • When you stack two decorators, both must use functools.wraps or the outermost's name will win and the inner one's name is lost.

Decision rule: use functools.wraps on every wrapper you write, with no exceptions. The only time you intentionally skip it is when you are writing a decorator that changes the function's public identity (a rare rename-on-purpose pattern), and even then you set __wrapped__ manually.

Minimal example Metadata loss without wraps, and the fix

Pythonruns
import functools

def without_wraps(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

def with_wraps(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@without_wraps
def load_orders(path):
    """Load orders from CSV."""

@with_wraps
def load_settlements(path):
    """Load settlements from CSV."""

print(load_orders.__name__)
print(load_orders.__doc__)
print(load_settlements.__name__)
print(load_settlements.__doc__)
print(load_settlements.__wrapped__ is load_settlements)
Output
wrapper
None
load_settlements
Load settlements from CSV.
False

In production Audit decorator for ETL steps

Pythonruns
import functools

def audit(func):
    """Record name and row count for every ETL step."""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"[audit] {func.__name__} starting")
        result = func(*args, **kwargs)
        count = len(result) if isinstance(result, (list, tuple)) else "n/a"
        print(f"[audit] {func.__name__} done  rows={count}")
        return result
    return wrapper

@audit
def extract_orders(source: str) -> list:
    """Pull orders from an S3 key and return raw dicts."""
    return [{"id": i, "amount": i * 100} for i in range(1, 4)]

@audit
def extract_settlements(source: str) -> list:
    """Pull settlements; returns empty when source is missing."""
    return []

extract_orders("s3://bucket/orders.csv")
extract_settlements("s3://bucket/settlements.csv")
print(extract_orders.__name__)
print(extract_orders.__wrapped__.__name__)
Output
[audit] extract_orders starting
[audit] extract_orders done  rows=3
[audit] extract_settlements starting
[audit] extract_settlements done  rows=0
extract_orders
extract_orders

See it happen Decoration builds a chain; calls execute outer-to-inner

callcallscallsETL script@audit@tag_stepload_ordersbody
  1. Build time: @tag_step wraps the body first, becoming the innermost layer.
  2. Build time: @audit then wraps the @tag_step layer. The ETL script sees only @audit.
  3. Call time: the caller invokes @audit, the outermost wrapper.
  4. @audit runs its before-code, then hands control down to @tag_step.
  5. @tag_step runs, then calls the body. Return values travel back left through the same chain.
Notice: decoration applies bottom-up (inner first, outer last), but execution at call time runs outer-to-inner — the last decorator you write is the first to run.
Scenario A

In your world

The situation

Your nightly Jenkins job runs extract_orders(), which is wrapped in a home-grown @timed decorator that was copy-pasted from a blog post. After a production alert, you notice the monitoring dashboard shows all slow functions as "wrapper", not their real names, and the docstrings are gone from the auto-generated runbook.

What actually breaks

Every @timed-decorated function appears as "wrapper" in logs, stack traces and the runbook. The on-call engineer cannot tell from the log which step was slow. When the runbook tool reads func.__doc__, it gets None for every step.

What you'd do on Monday

Add @functools.wraps(func) inside every decorator that defines a wrapper. It is a one-line change per decorator and takes no time to test. Add a unit assertion to every decorator's test suite:

PythonAssert wrapper metadata is preserved (stdlib unittest)
import functools, unittest

def timed(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

class TestTimedDecorator(unittest.TestCase):
    def test_metadata_preserved(self):
        @timed
        def load(): """Load rows."""
        self.assertEqual(load.__name__, "load")
        self.assertEqual(load.__doc__, "Load rows.")
        self.assertIs(load.__wrapped__, load.__wrapped__)
Scenario B

Imagine you work at Uber

15M ride events/day

The numbers

Illustrative: 15M events/day ÷ 86,400 s ≈ 174 events/s average, spiking to ~1,000/s during peak hours. A decorator that builds a log string with f"[{func.__name__}]" costs roughly 0.5 µs per call. At 1,000 calls/s that is 0.5 ms/s, a rounding error. But if the decorator calls inspect.stack() to capture the caller's filename and line number, each call costs ~40 µs. At 1,000 calls/s that is 40 ms/s per worker process; across 20 workers that is 800 ms CPU spent on introspection every second.

What the Scenario-A answer does here

The Scenario A fix (adding functools.wraps) keeps decorator overhead at the µs level with no change to call cost. The metadata problem is purely a correctness fix, not a performance one.

What flips at this scale

The question at scale is not functools.wraps itself but what you put inside the wrapper. Any I/O, stack inspection or lock acquisition inside a hot-path decorator multiplies by call volume. At 1,000 calls/s per worker, every 1 ms of wrapper overhead costs 1 s of CPU per second per worker: a 100% overhead.

The trade-off you'd defend

I would defend a flat decorator that appends to a ring buffer and a background thread that flushes the buffer, trading some delay in log delivery for keeping wrapper overhead under 2 µs. Stack inspection stays behind a debug feature flag and is never on in production.

Illustrative figures chosen to make the arithmetic visible; not Uber-published data.

Gotchas

Monitoring dashboard shows "wrapper" for every function

Symptom

Log lines and traces all say func=wrapper instead of the function's real name. func.__doc__ is None.

Cause

The decorator uses a plain inner function without @functools.wraps(func).

Fix

Add @functools.wraps(func) as the first line inside every decorator that defines a wrapper closure.

A cached method holds its instance alive forever

Symptom

After del obj, the object is never garbage-collected; memory grows without bound.

Cause

@functools.lru_cache on an instance method uses self as part of the cache key, storing a strong reference to every instance that has called it.

Fix

Move the cached logic to a module-level function that accepts only plain hashable arguments, or use functools.cached_property (per-instance, collected with the instance) for simple attribute caching.

__wrapped__ skips all validation

Symptom

Calling func.__wrapped__(bad_arg) bypasses guards added by outer decorators such as input validation or rate limiting.

Cause

__wrapped__ is a direct reference to the original; it is intentional but easy to misuse.

Fix

Treat __wrapped__ as a test or introspection handle only, never as the runtime call path in production code.

Tricky questions

Does a decorated function still have its original docstring?
Most people say

Yes, the decorator wraps it so the docstring comes through.

Actually

Only if the decorator uses functools.wraps. Without it, func.__doc__ returns the wrapper's docstring, which is usually None. The wrapper is a distinct callable with no relationship to the original unless you explicitly copy attributes.

Is load_settlements.__wrapped__ is load_settlements true?
Most people say

Yes, __wrapped__ points back to itself because the wrapper knows its own name.

Actually

False. __wrapped__ points to the original unwrapped function, which is a different object. load_settlements is the wrapper; load_settlements.__wrapped__ is the pre-decoration callable. You can verify with type(load_settlements.__wrapped__).

Scenario question

You're handed a Python codebase where @functools.lru_cache is applied to an instance method. A profiler shows the process slowly consumes memory over a day until the container is OOM-killed. The method is only called with small integer arguments. What is happening and how do you fix it?

Model answer

I would check whether self is part of the cache key. lru_cache caches based on all arguments including self, so every distinct instance that calls the method gets its own cache entry and the instance is held alive as long as that entry lives. With maxsize=128, 128 instances are pinned at all times; if the cache fills and the evicted instance has no other references it is freed, but instances are created faster than the LRU evicts them. I would fix this by moving the computation to a module-level function that takes only the plain integer arguments, and have the method call that function. The trade-off is that the cache is now shared across all instances, which is almost always what you want for a pure lookup.

Interview corner

CommonWhat does functools.wraps do, and why does it matter?
“I'd say it copies metadata from the original function onto the wrapper: __name__, __doc__, __qualname__ and __wrapped__. Without it every decorated function looks like 'wrapper' to logging, monitoring and doctools. It's a one-liner that separates a toy decorator from a production one.”
TrickYou apply two decorators. Which one's __name__ do you see on the wrapped function?
“I'd say the outermost decorator's wrapper name wins unless both use functools.wraps — in which case the original function's name propagates all the way out. If the inner decorator skips wraps, the outer one copies 'wrapper' as the name, not the original.”
Experience checkWhen did missing functools.wraps hurt you in real code?
“I hit this in a Grafana dashboard where every ETL step showed 'wrapper' as the function label. We couldn't tell from the trace which step was slow. Adding functools.wraps to five decorators took ten minutes and fixed the entire dashboard.”
CommonWhat does func.__wrapped__ give you?
“I'd say it gives you a direct reference to the original, pre-decoration callable. It's useful for unit testing the raw function without going through the wrapper's side effects. I treat it as a test handle, not a production call path.”

Memory hook

A decorator without functools.wraps is a new coat of paint with the number plate scraped off. The car runs the same, but nobody can identify it in a crash.

If you remember only one thing:

Every wrapper must carry @functools.wraps(func) or your monitoring dashboard will lie to you.

Self-check

  1. What attribute does functools.wraps set to link the wrapper back to the original?

    __wrapped__. It points at the original undecorated callable.

  2. If @A sits above @B in the source, which wrapper runs first when the function is called?

    A runs first. Decorators apply bottom-up at definition but execute outer-to-inner at call time.

  3. What does func.__name__ return when the decorator omits functools.wraps?

    "wrapper" — the inner function's literal name, not the decorated function's name.

Prove it

Write a decorator @timed that records elapsed time but intentionally omits functools.wraps. Apply it to def load_csv(path): """Load a CSV file.""" return []. Print load_csv.__name__ and load_csv.__doc__. Then add @functools.wraps(func), repeat, and confirm the output changes from wrapper / None to load_csv / Load a CSV file.. Paste both outputs.

py-05-02Card 2 of 6

Build parameterised decorator factories

MediumP2 · Very likelyKnow cold11 min
decoratorsfactoryclosureparameterisedstacking

Why you care

A decorator with no parameters can do one thing. The moment a team wants @retry(times=3) on one function and @retry(times=5) on another, you need a factory: a function that takes configuration, returns a decorator, which returns a wrapper. This three-level nesting trips up almost every developer the first time — not because it is conceptually hard, but because it is one level deeper than expected. Interviewers ask "how do you add parameters to a decorator?" specifically to see whether you understand where configuration lives versus where per-call state lives, which is the same question that separates a caching decorator from a broken one.

Explain like I'm 5

Think of a decorator as a stamp. A plain stamp always prints the same pattern. A parameterised decorator factory is like a stamp-making machine: you feed it a pattern ("PAYMENTS") and it produces a new stamp configured for that pattern. You then press that stamp onto each function you want to mark. The machine runs once (at definition time); the stamp runs once per decoration; the ink-transfer runs once per call.

Core concept

The structure is: factory → decorator → wrapper.

Text
def factory(config):          # runs once per decoration definition
    def decorator(func):      # runs once per decorated function
        @functools.wraps(func)
        def wrapper(*args, **kwargs):   # runs on every call
            # use `config` from factory closure, `func` from decorator closure
            return func(*args, **kwargs)
        return wrapper
    return decorator
  • Configuration closure: values passed to the factory (like times=3) are captured in the decorator's closure. They are shared across all calls to the wrapper for that particular decorated function.
  • Per-call state: if you need state that changes between calls (a retry counter, an elapsed time), declare it inside wrapper or in a mutable container in the decorator closure.
  • Stacking order: @A above @B means A(B(func)). When the function is called, A's wrapper runs first. Both wrappers share access to the original function via func in their respective closures.

Decision rule: use a plain decorator when there is no configuration and never will be. Use a factory as soon as any parameter is needed — going back to convert a plain decorator to a factory later requires changing every call site.

Minimal example A row-count guard factory

Pythonruns
import functools

def requires_rows(min_rows=1):
    """Guard: raise if the function returns fewer than min_rows items."""
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            result = func(*args, **kwargs)
            if len(result) < min_rows:
                raise ValueError(
                    f"{func.__name__} returned {len(result)} rows, "
                    f"need >= {min_rows}"
                )
            return result
        return wrapper
    return decorator

@requires_rows(min_rows=1)
def load_reference(path):
    return [{"id": 1, "name": "ACME"}]

@requires_rows(min_rows=1)
def load_empty(path):
    return []

rows = load_reference("ref.csv")
print(f"loaded {len(rows)} rows")
try:
    load_empty("empty.csv")
except ValueError as e:
    print(f"ValueError: {e}")
Output
loaded 1 rows
ValueError: load_empty returned 0 rows, need >= 1

In production Stacking two factories to show execution order

Pythonruns
import functools

def tag_step(label: str):
    """Factory: print the step label before and after the call."""
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            print(f"tag({label}): before")
            result = func(*args, **kwargs)
            print(f"tag({label}): after")
            return result
        return wrapper
    return decorator

def measure(func):
    """Decorator: print row count before and after the call."""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print("measure: before")
        result = func(*args, **kwargs)
        print(f"measure: after  rows={len(result)}")
        return result
    return wrapper

# Applied bottom-up; @tag_step wraps the @measure wrapper.
@tag_step("EXTRACT")
@measure
def load_orders(path):
    return [{"id": 1}, {"id": 2}]

# Reversed: @measure wraps the @tag_step wrapper.
@measure
@tag_step("EXTRACT")
def load_settlements(path):
    return [{"id": 10}]

load_orders("orders.csv")
print("---")
load_settlements("settlements.csv")
Output
tag(EXTRACT): before
measure: before
measure: after  rows=2
tag(EXTRACT): after
---
measure: before
tag(EXTRACT): before
tag(EXTRACT): after
measure: after  rows=1
Scenario A

In your world

The situation

Your ETL job has a plain @audit decorator on every extract function. The data team now wants @audit(team="PAYMENTS") so log lines include the team prefix. You cannot change the decorated function signatures.

What actually breaks

The plain decorator def audit(func): cannot accept a team argument. If you write @audit(team="PAYMENTS"), Python calls audit(team="PAYMENTS"), which returns None (no team parameter), and then tries to call None(extract_orders), crashing with TypeError: 'NoneType' object is not callable.

What you'd do on Monday

Convert audit to a factory: add an outer function that accepts team, and move the existing decorator and wrapper one level in. Existing callers using @audit must become @audit() (bare call), or you can use a sentinel to detect both usage forms:

PythonFactory version with backwards-compatible bare-call detection
import functools

_SENTINEL = object()

def audit(func=_SENTINEL, *, team=""):
    def decorator(f):
        @functools.wraps(f)
        def wrapper(*args, **kwargs):
            prefix = f"[{team}]" if team else "[audit]"
            print(f"{prefix} {f.__name__}")
            return f(*args, **kwargs)
        return wrapper
    if func is _SENTINEL:
        return decorator          # called as @audit(team="PAYMENTS")
    return decorator(func)        # called as @audit (no parens)
Scenario B

Imagine you work at Netflix

200M API calls/day (India service estimate)

The numbers

Illustrative: 200M calls/day ÷ 86,400 s ≈ 2,315 calls/s average. A parameterised rate-limiting decorator that tracks call timestamps in an in-process list checks len(calls) on every call. At 2,315 calls/s with a 10-second window, the list holds ~23,150 entries at steady state. Scanning and cleaning the list costs O(w) per call; at 23,150 entries that is ~0.02 ms per call, which is 0.02 × 2,315 = 46 ms CPU/s per process: negligible for a single process.

What the Scenario-A answer does here

The Scenario A fix (a factory with a module-level list in the closure) runs correctly on one process. In a multi-process deployment, each process has its own list, so 10 replicas each allow 2,315/10 = 232 calls/s — but a single client can hit the same process repeatedly and bypass the limit entirely.

What flips at this scale

At this scale, per-process rate state must move to a shared store (Redis INCR with TTL). The decorator's inner logic changes from a list scan to a single network round-trip per call. The factory's maxsize parameter becomes a Redis key prefix, not a local variable.

The trade-off you'd defend

I would defend a two-tier approach: a cheap local token bucket for the first line of defence (no network), plus a Redis quota check for global enforcement, trading one extra latency hop on quota-boundary calls for true cross-replica correctness.

Illustrative figures; not Netflix-published data.

Gotchas

Using a factory without calling it: @requires_rows instead of @requires_rows()

Symptom

TypeError: requires_rows() missing 1 required positional argument: 'result' or the function body receives a function object as its first argument instead of data.

Cause

@requires_rows passes the decorated function directly to the factory as min_rows, not to the inner decorator. The factory returns the decorator function, which is then used as the wrapped callable — the type signature is completely wrong.

Fix

Always call the factory: @requires_rows() or @requires_rows(min_rows=2). Use the sentinel pattern if you want to support both @requires_rows and @requires_rows().

Per-call state in the decorator closure, not the wrapper

Symptom

All decorated functions share the same state. A call counter reaches 5 on one function and immediately triggers the limit on a different function.

Cause

The mutable container (a list, a dict) is created in the decorator closure, which runs once per decorated function. If you accidentally create it in the factory closure, every decorated function shares the same object.

Fix

Create mutable per-call state inside decorator, not inside the outer factory function.

Stacking a factory on top of functools.lru_cache loses cache_info

Symptom

func.cache_info() raises AttributeError after adding an outer decorator.

Cause

The outer decorator's wrapper does not expose the cache_info attribute of the inner lru_cache wrapper.

Fix

Copy the attribute explicitly in the wrapper, or put the custom decorator inside lru_cache: @functools.lru_cache(maxsize=256) on the outer and your decorator below it.

Tricky questions

Why does a parameterised decorator need three def levels instead of two?
Most people say

Two levels are enough: one for the configuration, one for the wrapper.

Actually

You need three: factory (receives config), decorator (receives the function), wrapper (receives call arguments). The factory must return a callable that accepts a function; that callable is the decorator. If you collapse factory and decorator into one function, you cannot tell whether you are being called with a function to decorate or with configuration values.

If you write @log(namespace="X") and log is a plain two-level decorator, what happens?
Most people say

Python uses the namespace keyword and the decorator works.

Actually

Python calls log(namespace="X"), which returns whatever log returns when called with a keyword argument instead of a function. If log is def log(func):, it raises TypeError because func gets the keyword argument instead of a callable. The call site must be written @log (no parens) for a plain decorator.

Scenario question

You're handed a decorator def log(func): that prints function names. A colleague wants to add a namespace parameter. They propose wrapping the existing log in another decorator. What do you tell them and what do you do instead?

Model answer

I'd tell them wrapping a decorator in another decorator produces four levels of nesting and a maintenance nightmare. The right move is to convert the existing decorator into a factory: rename the outer function to accept namespace, rename the inner function to decorator, and move the existing wrapper one level in. Existing callers go from @log to @log() because a factory must be called to return the decorator. If changing callers is not acceptable, use a sentinel default to detect both calling forms. The trade-off is a one-time migration of all call sites versus the complexity of supporting both forms indefinitely.

Interview corner

CommonHow do you add a configuration parameter to a decorator?
“I add a factory layer around the existing decorator: an outer function takes the config, a middle function takes the function to decorate, and the inner wrapper does the actual work. The config is captured in the factory's closure and is available to every wrapper call.”
TrickA decorator starts working incorrectly after you add a second decorator above it. What do you check first?
“I check the stacking order and whether the outer decorator uses functools.wraps. If the outer decorator doesn't preserve __wrapped__, the inner decorator's attributes are hidden. I also check whether the outer decorator accidentally passes the wrong arguments to the inner wrapper.”
Experience checkWhere have parameterised decorators appeared in your ETL work?
“I use them for row-count guards: @requires_rows(min_rows=1) on every extract function so a zero-row return raises immediately instead of loading silently. The config sits in the factory closure and is baked into the wrapper at decoration time, not evaluated on every call.”

Memory hook

A factory makes stamps; a decorator applies the stamp; a wrapper presses it on every call. Three levels, three jobs.

If you remember only one thing:

Configuration goes in the factory closure; per-call state goes in the wrapper. Mixing them produces shared mutable state across unrelated functions.

Self-check

  1. How many function definition levels does a parameterised decorator need?

    Three: factory (config), decorator (target function), wrapper (call arguments).

  2. Where is the configuration value captured in a factory?

    In the factory's closure, accessible to every invocation of the decorator and wrapper via Python's free-variable lookup.

  3. What error do you see if you apply @requires_rows (no parens) to a function when requires_rows is a factory?

    The factory receives the function as min_rows, not as func, and returns the inner decorator object. When the body runs, it calls decorator(*args, **kwargs) with the real arguments and raises TypeError because decorator expects a callable as its argument.

Prove it

Write @require_env(var): a factory decorator that raises RuntimeError(f"{var} not set") at call time if os.environ.get(var) is falsy. Apply it to def connect():. Call connect() without the env var (expect RuntimeError), then set os.environ["DB_URL"] = "sqlite:///test.db" and call again (expect no error). Paste both outputs.

py-05-03Card 3 of 6

Apply retry, timing and caching wrappers

HardP3 · Role-dependentTalk about it13 min
decoratorsretrycachinglru-cachetiminghard

Why you care

Flaky APIs, transient DB timeouts and repeated catalogue lookups are facts of ETL life. The naive fix is a loop with time.sleep inside every function that can fail, and a dict for every lookup that repeats. The production fix is one @retry and one @functools.lru_cache — each written once, applied everywhere. The reason this is a hard card is not that the patterns are complex; it is that stacking them in the wrong order silently breaks the contract. Interviewers ask about retry and caching together precisely because combining them requires you to reason about which wrapper runs first and what that implies for cache correctness.

Explain like I'm 5

Think of a retry decorator as a vending machine with a "try again" button. If the machine fails to dispense, you press the button up to N times before giving up. A cache decorator is like a coffee thermos: the first time you brew, it takes a few minutes; every time after that you pour from the thermos instantly. Stacking them in the wrong order is like pressing the thermos's "pour" button N times before deciding to brew — you get stale coffee faster instead of fresh coffee.

Core concept

Three reusable wrapper patterns cover the majority of ETL decorator needs:

  • @retry(times, delay): loops times times, sleeping delay seconds between attempts, and re-raises the last exception on budget exhaustion. The retry counter is per-call state inside the wrapper. Retry only transient exceptions; catching Exception without narrowing swallows logic bugs.
  • @timed: records start/end with time.perf_counter(), logs the delta. Elapsed time is deterministic per call but non-deterministic across runs; compare against a threshold (elapsed > SLOW_THRESHOLD) rather than printing raw milliseconds in output.
  • @functools.lru_cache(maxsize=N): caches calls keyed on all arguments. Arguments must be hashable. cache_info() returns CacheInfo(hits, misses, maxsize, currsize). cache_clear() resets it. maxsize=None is equivalent to functools.cache (3.9+): unbounded, no LRU eviction, slightly faster.

Stacking rule: put @lru_cache below a @retry so that only a successful result is cached. If you put @lru_cache above, the first successful result (after retries) is cached and subsequent calls skip retries entirely — which is usually what you want for a lookup, but means a temporary failure on the first call is never retried again.

Decision rule: retry for I/O (APIs, DB, S3); cache for pure lookups (product catalogue, config tables); time for SLO measurement. Never use all three on the same function without reading the stacking order first.

Under the hood

functools.lru_cache arrived in Python 3.2 as pure Python and has had a C implementation since 3.5: a dict (the cache store) plus a doubly-linked circular list for O(1) LRU updates. The cache key follows the rules of functools._make_key (the pure-Python fallback, mirrored in C), which combines positional args and keyword args in call order into a single tuple. It does NOT sort keyword args: f(a=1, b=2) and f(b=2, a=1) produce different keys and count as two separate cache misses. If any argument is unhashable (a list, a dict), the call raises TypeError: unhashable type. Setting maxsize=None removes the linked-list entirely: the wrapper stores results in a plain dict with no eviction and no list bookkeeping, so each call does slightly less work. cache_info() reads directly from the C struct and is cheap. cache_clear() reinitialises both the dict and the linked list in one C call.

The @retry wrapper does not interact with the cache internals. When @lru_cache is below @retry, a call flows as: retry wrapper → lru_cache wrapper. On a cache hit, lru_cache returns immediately without calling the body; the retry wrapper never sees a miss. On a cache miss, lru_cache calls the body; if the body raises, lru_cache does not store the exception (it only caches return values), and the exception propagates to the retry wrapper, which catches it and retries.

Minimal example Retry until success

Pythonruns
import functools

def retry(times=3):
    """Retry up to `times` attempts on any exception."""
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            last_exc = None
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except Exception as exc:
                    last_exc = exc
                    print(f"  attempt {attempt}/{times} failed: {exc}")
            raise last_exc
        return wrapper
    return decorator

_call_count = 0

@retry(times=3)
def flaky_api():
    global _call_count
    _call_count += 1
    if _call_count < 3:
        raise ConnectionError("upstream timeout")
    return "ok"

result = flaky_api()
print(result)
print(f"total calls: {_call_count}")
Output
  attempt 1/3 failed: upstream timeout
  attempt 2/3 failed: upstream timeout
ok
total calls: 3

In production LRU cache on a catalogue lookup (sqlite3 stands in for Postgres)

Pythonruns
import functools
import sqlite3

db = sqlite3.connect(":memory:")
db.execute("CREATE TABLE products (id INT, name TEXT)")
db.executemany("INSERT INTO products VALUES (?,?)", [
    (1, "Widget A"), (2, "Gadget B"), (3, "Widget C")
])
db.commit()

@functools.lru_cache(maxsize=4)
def lookup_product(product_id: int) -> dict:
    """Return the product dict for product_id; cached after first hit."""
    row = db.execute(
        "SELECT id, name FROM products WHERE id=?", (product_id,)
    ).fetchone()
    return {"id": row[0], "name": row[1]} if row else {}

lookup_product(1)
lookup_product(2)
lookup_product(1)   # cache hit — body not called again
lookup_product(3)

info = lookup_product.cache_info()
print(f"hits={info.hits} misses={info.misses} size={info.currsize}")
print(lookup_product(1))
Output
hits=1 misses=3 size=3
{'id': 1, 'name': 'Widget A'}
Scenario A

In your world

The situation

Your ETL job calls a vendor REST API to enrich order rows with product metadata. The API is flaky: roughly 1 in 20 calls returns a 503. You call the API once per row. The same 50 product IDs repeat across 10,000 order rows.

What actually breaks

Without retry, a single 503 fails the entire batch. Without caching, you call the API 10,000 times for 50 distinct products — the API enforces a 1,000-calls-per-minute rate limit and your batch takes 10 minutes longer than it should, hitting the daily quota and costing money.

What you'd do on Monday

Apply @retry(times=3) and @functools.lru_cache(maxsize=128) in the right stacking order — @retry above, @lru_cache below. After the first successful call for each product ID, subsequent calls return from the in-process cache with zero latency. The 10,000 rows reduce to 50 API calls maximum:

PythonStacking order: retry above, lru_cache below (needs requests + a real API)
import functools

def retry(times=3, delay=1):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            import time
            last_exc = None
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except Exception as exc:
                    last_exc = exc
                    if attempt < times:
                        time.sleep(delay)
            raise last_exc
        return wrapper
    return decorator

@retry(times=3, delay=1)
@functools.lru_cache(maxsize=128)
def get_product(product_id: int) -> dict:
    """Needs a real HTTP call; norun."""
    import requests
    r = requests.get(f"https://api.example.com/products/{product_id}", timeout=5)
    r.raise_for_status()
    return r.json()
Scenario B

Imagine you work at Hotstar

25M concurrent streams at peak

The numbers

Illustrative India IPL peak: ~25M concurrent streams × 1 metadata refresh every 30 s ÷ across the fleet ≈ 833,333 refreshes/s. A retry decorator with times=3 (3 attempts = 2 sleeps) and exponential backoff starting at 100 ms adds at worst 100 + 200 = 300 ms to tail latency for a retrying request. If 0.1 % of requests retry: 833,333 × 0.001 = 833 retrying calls/s × 300 ms ≈ 250 extra request-seconds/s across the fleet — a measurable but manageable tail.

What the Scenario-A answer does here

The Scenario A fix (retry up to 3 times, lru_cache on the hot path) works correctly at this scale for the cache hit case. The risk is that 833 simultaneous retries, each sleeping up to 700 ms, all wake up at the same time and send a coordinated wave of retries to the downstream: a thundering herd.

What flips at this scale

At this scale you add jitter to the backoff: delay = base * 2 ** attempt + random.uniform(0, base). You also add a circuit breaker: after N consecutive failures in a window, stop retrying and return a fast failure to callers, giving the downstream time to recover. The retry decorator becomes a configuration object, not a simple loop.

The trade-off you'd defend

I would defend jittered exponential backoff with a circuit-breaker gate over plain retry, trading a more complex decorator implementation for protecting downstream services from coordinated retry storms under peak load.

Illustrative figures; not Hotstar-published data.

Gotchas

Caching a mutable return value shares it across callers

Symptom

One caller modifies the returned dict and every subsequent cache hit for the same key reflects the mutation.

Cause

lru_cache stores a reference to the returned object, not a copy. All callers share the same dict.

Fix

Return a copy inside the cached function, or document the contract that callers must not mutate the result: return dict(row) instead of row.

Retrying non-transient exceptions hides bugs

Symptom

A KeyError or TypeError in the body retries three times, and the job fails after a 6-second delay instead of immediately.

Cause

The except Exception clause catches everything, including logic errors that will never succeed on retry.

Fix

Catch only the specific transient exception types: except (ConnectionError, TimeoutError). Let all other exceptions propagate immediately.

lru_cache on a method pins the instance in memory

Symptom

Instances are never garbage-collected; memory grows without bound.

Cause

self is part of the cache key; the cache holds a strong reference to every instance that has called the method.

Fix

Move the cached logic to a module-level function that accepts only hashable non-instance arguments, or use functools.cached_property for per-instance memoisation.

Keyword-argument order produces unexpected cache misses

Symptom

The hit rate is unexpectedly low; cache_info() shows far more misses than expected for what appear to be identical calls.

Cause

lru_cache keys on keyword args in call order, not sorted order. lookup(a=1, b=2) and lookup(b=2, a=1) are two different cache keys even though the function body receives identical values.

Fix

Always call the cached function with positional arguments, or write a thin wrapper that normalises the kwargs before forwarding: return _cached(a=kwargs["a"], b=kwargs["b"]) with a fixed call order.

Tricky questions

If you put @lru_cache above @retry, what happens on the first call?
Most people say

The cache caches the exception so retries return it instantly.

Actually

lru_cache only caches return values, not exceptions. If the body raises, lru_cache propagates the exception without storing it. But with @lru_cache above @retry, a successful result after retries is cached — subsequent calls return the cached result without going through the retry loop at all, which is usually correct for pure lookups. The subtle issue is that a transient failure on the very first call keeps retrying (correct), but once it succeeds the result is cached forever — there is no TTL unless you add one yourself.

Why must lru_cache arguments be hashable?
Most people say

Python can hash anything with id() as a fallback.

Actually

lru_cache builds the cache key from a tuple of all arguments using the same hash() protocol as dict keys. Lists, dicts and other mutables are not hashable, so passing them raises TypeError. The fix is to convert them to tuples or frozensets before the call, or to restructure the function to accept only hashable primitives.

Scenario question

You're handed an ETL job with @retry(times=5, delay=2) above @functools.lru_cache(maxsize=128) on a product-lookup function. A test shows that after one successful call, a subsequent call with the same argument skips the retry loop entirely, even if the downstream is now broken. Is this a bug?

Model answer

I would not call it a bug — it is the intended behaviour of the stacking order. Once a successful result is cached, the cache returns it directly, bypassing the retry wrapper and the body. That is the whole point of caching. The question is whether you want staleness protection: if the catalogue can change, a cached result is stale and the retry never has a chance to fetch a fresh value. I would add an explicit TTL wrapper or call cache_clear() at the start of each nightly batch to force re-population. The trade-off is that clearing the cache on every batch run sacrifices within-run performance on the first pass; a TTL-based eviction trades implementation complexity for automatic freshness.

Interview corner

CommonHow do you retry a flaky API call with a decorator?
“I write a factory decorator that loops up to N times, catches the specified transient exceptions, sleeps with backoff between attempts, and re-raises the last exception if the budget runs out. I catch only the transient types, not Exception, so logic errors propagate immediately.”
DesignRetry vs circuit breaker: when do you need the circuit breaker?
“I'd say retry is right when failures are rare and transient. A circuit breaker is right when a downstream is genuinely degraded and retries would make it worse — each retrying caller adds load, accelerating the failure. I add a circuit breaker when the retry rate in a window exceeds a threshold, so the service fails fast and gives the downstream time to recover.”
Experience checkWhere have you used lru_cache in ETL code?
“I cache product and supplier catalogue lookups that repeat across thousands of order rows. The catalogue changes once a day, so I clear the cache at job startup and let it fill naturally during the run. Without the cache, a 10k-row batch makes 10k identical DB queries; with it, it makes at most N queries where N is the number of distinct product IDs.”

Memory hook

A retry loop adds resilience; a cache adds speed. Stack them in the wrong order and you get neither: the cache stores a failure, or the retry hides a stale value.

If you remember only one thing:

Put @retry above @lru_cache: only a successful result gets cached, and a transient failure is always retried.

Self-check

  1. What does lru_cache.cache_info() return after two calls with the same argument?

    CacheInfo(hits=1, misses=1, maxsize=N, currsize=1).

  2. Why does lru_cache require hashable arguments?

    The cache is keyed on a tuple of arguments using Python's hash() protocol. Unhashable types (list, dict) cannot be tuple-hashed, so the call raises TypeError.

  3. What is the difference between lru_cache(maxsize=128) and lru_cache(maxsize=None)?

    With maxsize=None the cache is unbounded and no LRU eviction occurs; there is no linked-list overhead. It is equivalent to functools.cache (added in 3.9) and is ~20% faster per call.

Prove it

Apply @functools.lru_cache(maxsize=4) to a function that returns {"v": arg * 2}. Call it four times with distinct arguments. Print cache_info(). Call one of the same arguments again. Print cache_info() again. Confirm hits increases by 1 and misses and currsize stay the same. Paste both cache_info() outputs.

py-05-04Card 4 of 6

Context managers and deterministic cleanup

MediumP2 · Very likelyKnow cold10 min
context-managerswith-statemententerexitcleanupdeterministic

Why you care

Every time you open a file, acquire a DB connection or lock a shared resource, you are making a promise: "I will release this when I am done." The try/finally pattern keeps that promise, but it is verbose and easy to skip under time pressure. The with statement keeps the same promise, guaranteed, in three lines — and its protocol (__enter__, __exit__) is what open(), sqlite3.connect() and every Postgres connection pool in Python already implement. Interviewers ask "what does __exit__ receive?" because the answer — the full exception triple — reveals whether you understand that the context manager is the last line of defence before an exception escapes, and that swallowing it silently is a data-loss bug.

Explain like I'm 5

Imagine a hotel key card. When you check in, the receptionist hands you the card (__enter__ returns the resource). When you check out — whether because your stay ended normally or because you were escorted out by security — the card is deactivated (__exit__ runs). The hotel does not care why you left. The card always stops working.

Core concept

Two methods form the protocol:

  • __enter__(self): called when the with block opens. Sets up the resource (opens a file, begins a transaction). Its return value is bound to the as target. It may return None if no target is needed.
  • __exit__(self, exc_type, exc_val, exc_tb): called when the with block exits, regardless of how. On clean exit, all three arguments are None. On exception, they carry the type, value and traceback of the live exception.
  • Return value of __exit__: returning a truthy value suppresses the exception; the with block appears to exit normally and code after it continues. Returning a falsy value (including None) propagates the exception. In almost every case you want return False — or just omit the return statement.

Decision rule: use with whenever your code opens something that must be closed. Write a class-based context manager when cleanup needs to carry state between __enter__ and __exit__ (a cursor, a start timestamp, a lock handle). Use @contextmanager (Express cleanup with contextlib) when the setup and cleanup can be expressed as code before and after a single yield.

Minimal example Class-based context manager showing both exit paths

Pythonruns
class ManagedFile:
    def __init__(self, path, mode="w"):
        self.path = path
        self.mode = mode
        self._f = None

    def __enter__(self):
        print(f"open  {self.path}")
        self._f = open(self.path, self.mode)
        return self._f

    def __exit__(self, exc_type, exc_val, exc_tb):
        print(f"close {self.path}  exc={exc_type}")
        self._f.close()
        return False

with ManagedFile("orders.tmp") as f:
    f.write("id,amount\n1,100\n")

print("after with: closed?", f.closed)

try:
    with ManagedFile("bad.tmp") as f:
        raise ValueError("bad row")
except ValueError as e:
    print(f"ValueError: {e}")
Output
open  orders.tmp
close orders.tmp  exc=None
after with: closed? True
open  bad.tmp
close bad.tmp  exc=<class 'ValueError'>
ValueError: bad row

In production Transaction wrapper using sqlite3 (stands in for Postgres)

Pythonruns
import sqlite3

class Transaction:
    """Commit on clean exit; roll back on any exception."""

    def __init__(self, conn):
        self._conn = conn

    def __enter__(self):
        return self._conn.cursor()

    def __exit__(self, exc_type, exc_val, exc_tb):
        if exc_type is None:
            self._conn.commit()
            print("committed")
        else:
            self._conn.rollback()
            print(f"rolled back  ({exc_type.__name__})")
        return False

conn = sqlite3.connect(":memory:")
conn.execute("CREATE TABLE orders (id INT, amount INT)")

with Transaction(conn) as cur:
    cur.execute("INSERT INTO orders VALUES (1, 250)")
    cur.execute("INSERT INTO orders VALUES (2, 90)")

print("rows:", conn.execute("SELECT COUNT(*) FROM orders").fetchone()[0])

try:
    with Transaction(conn) as cur:
        cur.execute("INSERT INTO orders VALUES (3, 410)")
        raise ValueError("duplicate key")
except ValueError:
    pass

print("rows after rollback:", conn.execute("SELECT COUNT(*) FROM orders").fetchone()[0])
Output
committed
rows: 2
rolled back  (ValueError)
rows after rollback: 2

See it happen What happens inside a with statement

callerruntimecontext managerwith cm as x:__enter__()resource (or None)__exit__(None, None, None)__exit__(type, val, tb)False → propagate
  1. Python evaluates the context-manager expression and calls __enter__.
  2. __enter__ acquires the resource and returns it; the return value is bound to x.
  3. The body runs with the resource available as x.
  4. Clean exit: __exit__ receives three Nones. Commit, close or flush here.
  5. Exception exit: __exit__ receives the full exception triple. Rollback or log here.
  6. Returning a falsy value propagates the exception. Returning True suppresses it — only do this when suppression is intentional and documented.
Notice: both normal and exception exits call __exit__; the only difference is whether the arguments are (None, None, None) or the live exception triple.
Scenario A

In your world

The situation

Your ETL job opens a Postgres connection, runs a multi-statement load batch, and closes the connection manually at the end. The pattern is: conn = connect() at the top, conn.close() at the bottom.

What actually breaks

When the load raises halfway through — a null constraint violation, a network reset — the function exits via exception before reaching conn.close(). The connection is leaked. Postgres's connection pool fills up and new jobs start failing with "too many connections", which looks unrelated to the original error.

What you'd do on Monday

Wrap the connection in a context manager that closes (or rolls back and closes) in its __exit__. Every exit path calls __exit__, including exceptions, return statements and sys.exit():

PythonTransaction CM for Postgres (needs psycopg)
import psycopg

class Transaction:
    def __init__(self, dsn):
        self._dsn = dsn
        self._conn = None

    def __enter__(self):
        self._conn = psycopg.connect(self._dsn)
        return self._conn.cursor()

    def __exit__(self, exc_type, exc_val, exc_tb):
        if exc_type is None:
            self._conn.commit()
        else:
            self._conn.rollback()
        self._conn.close()
        return False
Scenario B

Imagine you work at BigBasket

500k orders/day

The numbers

Illustrative: 500k orders/day × 3 DB operations/order (insert order, insert items, update stock) = 1.5M DB calls/day ÷ 86,400 s ≈ 17 calls/s average, spiking to ~170 calls/s during 19:00–21:00. A class-based Transaction CM that opens a new socket connection on every __enter__ pays ~5 ms per connection. At 170 calls/s that is 170 × 5 ms = 850 ms CPU/s wasted on TCP handshakes.

What the Scenario-A answer does here

The Scenario A fix (a CM that opens and closes each connection correctly) eliminates leaks. It does not eliminate connection overhead; every with Transaction(dsn) call still pays the full connection cost.

What flips at this scale

At this scale the CM's __enter__ acquires from a connection pool (< 0.1 ms) and __exit__ releases back. The socket stays open between transactions; only the logical transaction boundaries are managed by the CM.

The trade-off you'd defend

I would defend a CM that wraps pool-acquire/release rather than socket-open/close, trading a pool-size configuration step for eliminating per-transaction TCP overhead entirely.

Illustrative figures; not BigBasket-published data.

Gotchas

Connection pool exhaustion with no explicit error

Symptom

New jobs fail with "connection pool exhausted" or "too many connections" hours after a batch that had no error on its own.

Cause

A leaked connection (the batch exited via exception before conn.close()) is not returned to the pool. Over time the pool fills.

Fix

Always use with conn: or a CM wrapper. Never call open()/connect() outside a with block.

Returning True from __exit__ hides all errors

Symptom

A batch reports "0 errors" but loaded 0 rows; Jenkins is green.

Cause

__exit__ returns True, suppressing the exception that caused the 0-row load.

Fix

Return False unconditionally unless suppression is the explicitly intended contract (use contextlib.suppress for that case; it is self-documenting).

__exit__ itself raising loses the original exception

Symptom

You see a RuntimeError: cleanup failed traceback instead of the ValueError that triggered the cleanup.

Cause

If __exit__ raises, the new exception replaces the active one; the original is chained as __context__ but the primary traceback is now the cleanup error.

Fix

Catch cleanup errors inside __exit__, log them, and re-raise only the original (or let the original propagate by not raising from __exit__). See Preserve errors while resources close for the full pattern.

Tricky questions

What three arguments does __exit__ receive when the body exits normally?
Most people say

It receives the return value of the body.

Actually

It receives (None, None, None): exception type, exception value, traceback — all None on clean exit. The body's return value is never passed to __exit__.

What happens if __exit__ returns None?
Most people say

An implicit None return is treated as True and suppresses the exception.

Actually

None is falsy, so it is treated as False. The exception propagates. Only an explicitly truthy return (such as return True) suppresses it.

Scenario question

You're handed a context manager that wraps a Postgres connection. The team reports the connection pool is being exhausted even though every with block exits normally. What do you check?

Model answer

My first check is whether __exit__ is actually being called for every code path. Specifically, I look for any case where the CM is used without a with statement: cm = Transaction(dsn); cm.__enter__() with no paired __exit__. My second check is whether __exit__ calls conn.close() or just conn.rollback(). In some drivers, rollback returns the connection to idle state but does not return it to the pool; only close() does. I add a print or log inside __exit__ to confirm it fires. The trade-off between holding a connection for the full duration of the with block versus acquiring per statement depends on transaction semantics; I default to the shorter hold and move to a pool if throughput demands it.

Interview corner

CommonWhat does __exit__ receive when the body raises an exception?
“I'd say it receives three arguments: the exception type, the exception value, and the traceback object. On clean exit all three are None. Returning False or None propagates the exception; returning True suppresses it.”
TrickYou write return True in __exit__ to keep the pipeline running. What is the risk?
“I'd say the exception is swallowed and any code after the with block runs as though nothing went wrong. If the exception was a data-load failure, the job reports success with 0 rows loaded and nobody notices until finance reconciles. I treat unconditional suppression as a correctness bug.”
Experience checkHow has resource leaking hurt you in real ETL code?
“I had a nightly job that leaked Postgres connections because an uncaught constraint violation bypassed conn.close(). The pool exhausted by 03:00 and every downstream job started failing. Wrapping the connection in a with block fixed it in two lines.”

Memory hook

The hotel key card always deactivates at checkout — whether you checked out normally or were carried out on a stretcher. __exit__ is checkout.

If you remember only one thing:

__exit__ receives (None, None, None) on clean exit and the live exception triple on error; return False (or nothing) to propagate, True to suppress.

Self-check

  1. What does __enter__ return and where does it go?

    It returns the resource (or None). The return value is bound to the as variable in with cm as x:.

  2. When does __exit__ receive (None, None, None)?

    When the body exits normally — no exception, no unhandled return, no sys.exit.

  3. What happens if __exit__ raises a new exception?

    The new exception replaces the active one. The original exception is chained as __context__ on the new exception, visible in the traceback as "During handling of the above exception, another exception occurred."

Prove it

Write a DBConnection class with __enter__ that increments a module-level open_count counter and __exit__ that decrements it. Run three with DBConnection() blocks: one clean, one that raises ValueError, one clean again. After each block, assert open_count == 0 and print it. Paste the output showing three zeros.

py-05-05Card 5 of 6

Express cleanup with contextlib

MediumP2 · Very likelyKnow cold10 min
contextlibcontextmanagergeneratorexitstackcleanup

Why you care

A class-based context manager works, but writing __enter__ and __exit__ for a one-use cleanup is ceremony you pay for every time. contextlib.contextmanager turns a generator function into a context manager with one decorator: everything before yield is __enter__, everything after is __exit__. When you have three or more resources to manage — or when the number is only known at runtime — contextlib.ExitStack lets you stack them dynamically and guarantees all of them close in LIFO order even if one raises. Interviewers ask about ExitStack specifically because it is the answer to "what do you do when you can't nest three with statements cleanly?", and most 3-year developers have never used it.

Explain like I'm 5

@contextmanager is like a two-part recipe: the "prep" section and the "cleanup" section, with a dividing line in the middle. You do your prep, hand the result to whoever is cooking, and when they're done you clean up — regardless of whether the dish came out well or burned. ExitStack is the catering company: you tell it "manage this fridge, that oven, and those knives" and when the event ends it shuts everything down in reverse order, even if putting away the knives goes wrong.

Core concept

Two tools from contextlib cover most use cases:

  • @contextmanager: decorate a generator function that yields exactly once. Code before yield is the setup (__enter__ equivalent). Code after yield (in a finally) is cleanup (__exit__ equivalent). The value passed to yield is the as target.
  • contextlib.ExitStack: a context manager that holds a stack of other context managers. stack.enter_context(cm) enters cm and pushes its __exit__ onto the stack. When the ExitStack exits (normally or on exception), it calls all __exit__ methods in LIFO order. This gives you nested-with semantics for a dynamic number of resources.

The finally clause around yield is not optional: without it, an exception in the body skips cleanup. The correct template is:

PythonCorrect @contextmanager template
from contextlib import contextmanager

@contextmanager
def manage_resource(name):
    resource = acquire(name)   # setup
    try:
        yield resource
    finally:
        release(resource)      # cleanup — runs even on exception

Decision rule: use @contextmanager when the CM is a function with no complex shared state between enter and exit. Use a class when you need to store multiple objects from __enter__ and reference them in __exit__. Use ExitStack when the set of resources is determined at runtime.

Minimal example @contextmanager showing setup, yield and cleanup

Pythonruns
from contextlib import contextmanager

@contextmanager
def managed_file(path, mode="w"):
    print(f"open  {path}")
    f = open(path, mode)
    try:
        yield f
    finally:
        f.close()
        print(f"close {path}")

with managed_file("output.tmp") as f:
    f.write("hello\n")
    print("inside with")
Output
open  output.tmp
inside with
close output.tmp

In production ExitStack for a dynamic set of stage tables

Pythonruns
from contextlib import contextmanager, ExitStack

@contextmanager
def stage_table(name):
    """Create a staging table; drop it on exit (sqlite3 in production)."""
    print(f"  create {name}")
    try:
        yield {"table": name}
    finally:
        print(f"  drop   {name}")

def run_etl(tables):
    with ExitStack() as stack:
        handles = [stack.enter_context(stage_table(t)) for t in tables]
        names = [h["table"] for h in handles]
        print(f"  processing {names}")
    print("all cleaned up")

run_etl(["orders_stage", "settlements_stage", "audit_stage"])
Output
  create orders_stage
  create settlements_stage
  create audit_stage
  processing ['orders_stage', 'settlements_stage', 'audit_stage']
  drop   audit_stage
  drop   settlements_stage
  drop   orders_stage
all cleaned up
Scenario A

In your world

The situation

Your ETL script opens a source file, a temp file and a DB connection in three nested with blocks. When a new requirement adds a fourth resource (an audit log handle), the nesting reaches four levels and the code is 40 columns indented before the first real line of logic.

What actually breaks

Deep nesting is not a runtime error, but it is a maintenance hazard. More importantly, if any of the with expressions raises during construction (before the block opens), the already-open inner resources are closed correctly by their own context managers, but the un-opened ones are not — which is exactly the guarantee you need.

What you'd do on Monday

Replace the nested with blocks with a single with ExitStack() as stack:. Each resource is entered with stack.enter_context(...). The number of resources becomes a variable, the indentation stays flat, and every successfully-entered context is cleaned up in LIFO order regardless of what goes wrong:

PythonFlat ExitStack replacing four nested with blocks (needs boto3 + psycopg)
from contextlib import ExitStack
import contextlib

def load_batch(s3_key, db_dsn, audit_path):
    with ExitStack() as stack:
        src = stack.enter_context(open_s3_object(s3_key))
        tmp = stack.enter_context(open_temp_file())
        cur = stack.enter_context(db_transaction(db_dsn))
        log = stack.enter_context(open(audit_path, "a"))
        # all four are open here; all four close on exit
        process(src, tmp, cur, log)
Scenario B

Imagine you work at Lenskart

50k prescription uploads/day

The numbers

Illustrative: 50k uploads/day × 4 resources/upload (S3 download, temp decrypt, DB write, audit log) = 200k resource open/close operations/day ÷ 86,400 s ≈ 2.3 open/close pairs/s at average load. Each ExitStack holds 4 CMs; cleanup of an encrypted 500 MB file takes ~2 s. If disk-full causes cleanup failure on 0.01 % of uploads: 50k × 0.0001 = 5 uploads/day hit a cleanup error. Without ExitStack, the first cleanup failure in a nested sequence abandons the remaining contexts — 3 of 4 resources stay open.

What the Scenario-A answer does here

The Scenario A fix (nested with blocks) closes resources correctly when all four succeed. When the third cleanup raises, the fourth context's __exit__ is never called.

What flips at this scale

ExitStack guarantees that all registered cleanup callbacks run even when one raises. The first raised exception becomes the active exception and subsequent cleanup errors are chained on it (see Preserve errors while resources close). This means you see all cleanup failures, not just the first one.

The trade-off you'd defend

I would defend ExitStack over nested with statements for any ETL job managing more than two resources, trading a slightly more verbose setup for a guarantee that no resource is abandoned on cleanup failure.

Illustrative figures; not Lenskart-published data.

Gotchas

Forgetting finally in an @contextmanager generator

Symptom

When the with body raises, cleanup code after yield is skipped. Temp files are left on disk, connections stay open.

Cause

Without a try/finally around yield, a body exception propagates through the generator frame and past the cleanup code without executing it.

Fix

Always write try: yield finally: cleanup() in every @contextmanager generator.

Yielding more than once in @contextmanager

Symptom

RuntimeError: generator didn't stop after throw() when the with body raises.

Cause

The generator yielded twice. After the body exception is thrown in, the generator must either handle it and stop, or raise StopIteration. A second yield violates that contract.

Fix

Ensure the generator yields exactly once; multiple yields require a loop and careful exception handling.

ExitStack in a module-level variable shared across calls

Symptom

Resources from a previous call are still registered; the stack closes them during the next call's exit, producing double-close errors.

Cause

The ExitStack object is reused across calls instead of being created fresh inside each with block.

Fix

Always create ExitStack inside a with statement; never store it as a reusable module-level object.

Tricky questions

Is @contextmanager a replacement for class-based context managers?
Most people say

Yes, it is simpler and you should always prefer it.

Actually

It depends. @contextmanager is simpler when setup and cleanup fit in a single function. A class is clearer when you need to store multiple objects between __enter__ and __exit__, or when the CM itself has configuration that should be set at instantiation time. Using a class also allows subclassing and clearer type annotations.

In what order does ExitStack close its contexts?
Most people say

The order in which they were entered.

Actually

LIFO (last-in, first-out) — the reverse of the entry order. This mirrors the behaviour of nested with statements, where the innermost block always exits first.

Scenario question

You're handed a script that opens three files inside nested with statements. When the middle file does not exist, the outer file stays open until the exception unwinds through two context managers. A new requirement adds a fourth file whose path is computed at runtime. What pattern do you use?

Model answer

I switch to ExitStack. I create a single with ExitStack() as stack: block, enter each file with stack.enter_context(open(path)), and build the list of paths dynamically. ExitStack closes all successfully-opened files in LIFO order if any entry raises. If the third file does not exist, the first and second are closed cleanly. The trade-off over nested with is that the cleanup order is less visually explicit — you need to know ExitStack is LIFO. For two resources I keep nested with; for three or more, or when the count is dynamic, ExitStack is the right tool.

Interview corner

CommonWhen do you use @contextmanager instead of a class-based CM?
“I use @contextmanager when setup and cleanup fit in one function with a single yield in the middle. I use a class when I need to store several objects between enter and exit, or when the CM will be subclassed or type-annotated precisely.”
TrickWhat happens if a @contextmanager generator yields twice?
“I'd say the runtime throws the body exception back into the generator to trigger cleanup. If the generator yields a second time instead of raising or returning, contextmanager raises RuntimeError: 'generator didn't stop after throw'. The fix is a single yield inside a try/finally.”
DesignHow does ExitStack handle a cleanup that raises inside __exit__?
“I'd say ExitStack runs all registered __exit__ methods regardless of whether one raises. If one raises, it chains subsequent errors and re-raises the first one at the end. No cleanup is skipped. You see all failures in the traceback chain, not just the first.”

Memory hook

@contextmanager: prep, yield, clean up. ExitStack: enter as many as you need, and every one of them closes in reverse order, no matter what.

If you remember only one thing:

Always put cleanup after yield inside a finally block; without it, a body exception skips cleanup silently.

Self-check

  1. Where exactly must yield appear in a @contextmanager generator?

    Inside a try/finally (or bare yield if there is no cleanup). The generator must yield exactly once; the yield value becomes the as target.

  2. In what order does ExitStack close its contexts?

    LIFO — last entered, first closed. The same order as nested with statements.

  3. What error do you get if a @contextmanager generator yields twice?

    RuntimeError: generator didn't stop after throw().

Prove it

Using @contextmanager, write managed_dir(name) that creates a directory on enter, yields its Path, and removes it in finally. Call run_etl(["reports", "staging"]) which uses ExitStack to enter both dirs, print their paths while inside, then confirm both dirs are gone outside the block. Paste the output showing creation, paths and removal in LIFO order.

py-05-06Card 6 of 6

Preserve errors while resources close

HardP2 · Very likelyKnow cold11 min
context-managersexception-safetyexit-stacksuppressioncleanuphard

Why you care

The context manager protocol promises that __exit__ always runs. It does not promise that __exit__ runs safely, or that the exception your body raised is the one that makes it to your except clause. When cleanup code itself raises — a connection flush fails, a temp file cannot be deleted, a log write times out — Python chains the two exceptions, and the cleanup error often buries the original. Meanwhile, a single return True in __exit__ silently swallows everything: a failed 0-row batch looks exactly like a successful one. Both patterns cost real data in production ETL. Interviewers ask "what does returning True from __exit__ do?" because the answer reveals whether you have ever chased a green-build-with-no-data incident.

Explain like I'm 5

Think of __exit__ as a hotel fire exit. It opens no matter what — whether you left normally, or a fire alarm forced you out. Returning True from __exit__ is the equivalent of sealing the fire exit shut so nobody reports the alarm: you get out fine, but the building records "no incident" and the next guest has no idea there was a fire. Letting the exception propagate (return False) is keeping the fire exit unlocked so the alarm reaches everyone who needs to hear it.

Core concept

Three failure modes and their fixes:

  • Silent suppression: __exit__ returns True. The with block appears to exit normally. Any exception from the body is gone. This is almost always a bug in ETL code. The only deliberate suppression idiom is contextlib.suppress(*exc_types), which is self-documenting.
  • Cleanup raises, original lost: if __exit__ raises a new exception, Python chains the original as __context__ on the new one. Callers see the cleanup error; the original is visible only in the traceback chain via .__context__. If cleanup must log and re-raise, inspect exc_type to distinguish a clean exit from an error exit.
  • Multiple cleanups, some fail: contextlib.ExitStack guarantees all registered __exit__ methods run. If one raises, subsequent ones still run. ExitStack re-raises the first cleanup exception after all others have run; the others are chained as __context__. No cleanup is skipped.

Decision rule: return False (or nothing) from every __exit__ you write. Use contextlib.suppress(ExcType) when you intend to ignore a specific exception type. Never return True unconditionally.

Under the hood

When __exit__ raises and an exception was already active, CPython calls _PyErr_ChainExceptions internally. This sets new_exc.__context__ = original_exc and new_exc.__suppress_context__ = False, so traceback.print_exc() shows "During handling of the above exception, another exception occurred". The original exception is not lost — it is chained — but the primary traceback is now the cleanup error, which is why operators are confused. ExitStack implements its own exception-chaining loop in pure Python (_push_exit_callback) that mirrors this exactly: it records the first raised exception, continues running remaining callbacks, and at the end re-raises with the others chained. contextlib.suppress(*exc_types) is implemented in about 10 lines: it calls issubclass(exc_type, exc_types) in __exit__ and returns True only for those types.

In Python 3.11+ you can inspect __context__ and __cause__ programmatically to separate the body exception from the cleanup exception. ExceptionGroup (3.11+) is not used by ExitStack; ExitStack chains sequentially, not as a group.

Minimal example Suppression vs propagation

Pythonruns
class Loud:
    def __enter__(self): return self
    def __exit__(self, exc_type, exc_val, exc_tb):
        print(f"__exit__  exc={exc_type}  returning False")
        return False

class Silent:
    def __enter__(self): return self
    def __exit__(self, exc_type, exc_val, exc_tb):
        print(f"__exit__  exc={exc_type}  returning True")
        return True

try:
    with Loud():
        raise ValueError("bad row")
except ValueError as e:
    print(f"caught: {e}")

print("---")

with Silent():
    raise ValueError("bad row")

print("after silent: no exception raised")
Output
__exit__  exc=<class 'ValueError'>  returning False
caught: bad row
---
__exit__  exc=<class 'ValueError'>  returning True
after silent: no exception raised

In production ExitStack with a cleanup that raises

Pythonruns
from contextlib import ExitStack

resources = []

class Resource:
    def __init__(self, name, fail_close=False):
        self.name = name
        self.fail_close = fail_close

    def __enter__(self):
        resources.append(self.name)
        print(f"  open  {self.name}")
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        resources.remove(self.name)
        if self.fail_close:
            print(f"  close {self.name}  FAIL")
            raise RuntimeError(f"flush failed: {self.name}")
        print(f"  close {self.name}  ok")
        return False

try:
    with ExitStack() as stack:
        stack.enter_context(Resource("orders_stage"))
        stack.enter_context(Resource("audit_log", fail_close=True))
        print("  body done")
except RuntimeError as e:
    print(f"RuntimeError: {e}")

print(f"open resources: {resources}")
Output
  open  orders_stage
  open  audit_log
  body done
  close audit_log  FAIL
  close orders_stage  ok
RuntimeError: flush failed: audit_log
open resources: []
Scenario A

In your world

The situation

Your ETL job uses a context manager to wrap a DB connection. The CM's __exit__ calls conn.flush() before closing. When the pipeline runs in CI, occasional network blips cause flush() to raise OSError. The team adds return True to __exit__ to keep the pipeline from failing.

What actually breaks

Now every exception is suppressed — not just the OSError from flush(). A load failure that would have been ValueError: null constraint or KeyError: missing column is silently swallowed. Jenkins shows green. The audit table shows rows_loaded=0. Finance emails Monday morning.

What you'd do on Monday

Catch only the specific exception you intend to suppress, log it, and then exit normally. Let all other exceptions propagate:

PythonCatch only OSError from cleanup; propagate everything else
def __exit__(self, exc_type, exc_val, exc_tb):
    try:
        self._conn.flush()
    except OSError as flush_err:
        import logging
        logging.warning("flush failed: %s", flush_err)
    finally:
        self._conn.close()
    return False   # never suppress the body exception
Scenario B

Imagine you work at Upstox

10M trade events/day

The numbers

Illustrative: 10M trade events/day across 6.5 Indian trading hours (09:15–15:45 IST) ÷ 6.5 × 3,600 s ≈ 428 events/s average. Each trade runs inside a CM that acquires a DB connection and an audit log handle. If the audit log CM's __exit__ returns True (suppresses all errors) and the audit flush fails on 0.01 % of events: 428 × 0.0001 = 0.04 silently-lost audit records/s. Over a full trading day: 0.04 × 23,400 s ≈ 936 audit events gone with no alert surfaced.

What the Scenario-A answer does here

The Scenario A fix (returning False from __exit__) propagates errors correctly for simple cases. It does not handle the case where cleanup itself raises and you want to distinguish body exceptions from cleanup exceptions.

What flips at this scale

At this scale, the compliance team requires that every audit record is either written or explicitly flagged as failed. Silent suppression is not an option. The CM's __exit__ inspects exc_type: if the body raised, it logs both the body error and any cleanup error separately before re-raising the body exception. If only cleanup raised, it logs and re-raises.

The trade-off you'd defend

I would defend always returning False from __exit__ and handling cleanup errors in a try/except inside __exit__ itself, trading some added code for a guarantee that no exception is ever silently swallowed.

Illustrative figures; not Upstox-published data.

Gotchas

return True in __exit__ turns a data-load failure into a silent green build

Symptom

Jenkins green, rows_loaded=0, no exception in logs.

Cause

__exit__ returns True, suppressing the exception that caused the 0-row load. All subsequent code runs as though the batch succeeded.

Fix

Remove return True. Use contextlib.suppress(SpecificError) only when you have a documented, intentional reason to swallow exactly that error type.

Cleanup exception buries the original body exception

Symptom

You see RuntimeError: cleanup failed in the traceback, but the original ValueError that triggered cleanup is nowhere visible in the primary trace.

Cause

__exit__ raises a new exception while an exception was already active. Python chains them, but the cleanup error becomes the primary traceback.

Fix

Inside __exit__, wrap cleanup in try/except, log cleanup failures, and let the original exception (the one in exc_val) remain the active one by not raising from __exit__.

ExitStack stops at the first cleanup exception

Symptom

Only the first cleanup failure is reported; later resources are not closed.

Cause

A manual loop of context manager exits (not using ExitStack) aborts when the first __exit__ raises.

Fix

Use contextlib.ExitStack; it guarantees all __exit__ methods run even when one raises, chaining all errors.

Tricky questions

What does return True in __exit__ actually do?
Most people say

It signals that cleanup succeeded, so Python knows the resource is safely released.

Actually

It tells Python to suppress the current exception: the with block exits as though the body ran without error, and the exception is discarded. It has nothing to do with whether cleanup succeeded or failed; it is purely about exception propagation.

If the body raises ValueError and __exit__ raises RuntimeError, which exception do you catch?
Most people say

ValueError, because that is the original.

Actually

RuntimeError — the cleanup exception replaces the active exception. The ValueError is chained as RuntimeError.__context__ and visible in the traceback, but an except ValueError clause will not catch the RuntimeError. To inspect both, catch Exception and examine .__context__.

Scenario question

You're handed an ETL context manager whose __exit__ catches all exceptions, logs them, and returns True to keep the pipeline running after any error. A batch job reports "0 errors, 0 rows loaded". What is your diagnosis and what do you change?

Model answer

The return True is suppressing the exception that prevented rows from loading. The pipeline proceeded as though nothing went wrong. My fix is to remove the unconditional return True and replace it with targeted handling: catch the specific cleanup error types in a nested try/except inside __exit__, log those, and return False so body exceptions propagate. If the team needs "log and continue" behaviour, the decision should sit in the orchestrator loop, not inside a context manager — the orchestrator can catch the propagated exception, increment a failure counter, and move to the next batch. The CM's job is to clean up, not to decide whether the pipeline should continue.

Interview corner

CommonWhat does returning True from __exit__ do?
“I'd say it suppresses the exception. The with block appears to exit normally, and any exception from the body is gone. I treat this as a data-loss bug unless it's the explicit suppress-a-specific-type idiom using contextlib.suppress.”
TrickThe body raises ValueError. Inside __exit__, your cleanup code raises RuntimeError. What does the caller catch?
“I'd say the RuntimeError — it replaces the active exception. The ValueError is chained as RuntimeError.__context__ and visible in the traceback, but an except ValueError clause won't catch it. To handle both, I catch Exception and inspect __context__.”
Experience checkWhen did a silently-suppressing context manager hurt you in production?
“I worked on a DB-writer CM that had return True to keep a pipeline moving after network errors. After a schema migration the body raised KeyError on every row, but the CM swallowed it. The job ran for two hours, loaded 0 rows, and Jenkins stayed green. We found it when the downstream report came back empty.”

Memory hook

return True in __exit__ is a delete key for exceptions. You will press it once by accident and spend a week finding the rows that never loaded.

If you remember only one thing:

Return False from every __exit__ you write. Use contextlib.suppress(SpecificType) when suppression is intentional.

Self-check

  1. What does returning True from __exit__ do to the active exception?

    It suppresses it entirely. The with block exits as though the body ran without error.

  2. How does Python link a body exception to a subsequent cleanup exception?

    It sets cleanup_exc.__context__ = body_exc and __suppress_context__ = False, so the traceback shows "During handling of the above exception, another exception occurred."

  3. Name the contextlib tool for intentional, type-specific suppression.

    contextlib.suppress(*exc_types) — it returns True from __exit__ only for the listed exception types.

Prove it

Write a context manager whose __exit__ always raises RuntimeError("cleanup failed"). Inside a try/except Exception as e:, use with to run a body that raises ValueError("original error"). After catching, print both str(e) (the RuntimeError) and str(e.__context__) (the ValueError). Confirm the two messages. Paste the output.