Build, Break, Learn

Generator Functions in Python: How to Pause a Function Mid-Execution

Moussa Kalam AMZAT — Thu, 02 Apr 2026 09:04:10 GMT

Here's something Python can do that JavaScript can't, at least not natively, without async/await:

def count_up():
    yield 1
    yield 2
    yield 3

Call that function and you don't get 1. You also don't get [1, 2, 3]. You get a generator object; a paused function waiting to be resumed.

gen = count_up()
print(next(gen))  # 1
print(next(gen))  # 2
print(next(gen))  # 3

That's the core idea of generators: functions that can be paused at a specific point and resumed later, picking up exactly where they left off (local variables, execution position, everything...)

This article is about understanding generators from the ground up. And there's a practical reason to care beyond generators themselves: Python's @contextmanager decorator, the cleanest way to build context managers, is powered entirely by this mechanism. Once you understand generators, @contextmanager stops feeling like magic and start feeling obvious. We'll get there in Part 4.

The Problem Generators Solve

Before we get into the mechanics, let's understand why generators exist.

Imagine you write a function that generates the first n Fibonacci numbers. The naive approach returns a list:

def fibonacci(n):
    numbers = []
    a, b = 0, 1
    for _ in range(n):
        numbers.append(a)
        a, b = b, a + b
    return numbers

for num in fibonacci(10):
    print(num)

This works, but it has a problem: it builds the entire list in memory before returning. If n is 10 million, you're holding 10 million numbers in RAM before you've processed a single one.

What if you only need to process them one at a time? What if you only need the first few? You're paying the full memory cost upfront for no reason.

The generator function would look like this:

def fibonacci(n):
    a, b = 0, 1
    for _ in range(n):
        yield a
        a, b = b, a + b

for num in fibonacci(10):
    print(num)

This produces the same output, but never holds more than two numbers in memory at once. Each time the for loop asks for the next value, the function runs until it hits yield, hands the value over, and pauses. On the next iteration, it picks up right after the yield.

This is the key insight: a generator computes values on demand, not all at once.

What `yield` Actually Does

yield is the keyword that turns a regular function into a generator function. But it does more than just return a value: it suspends the entire execution state of the function.

Let's trace through a simple example step by step:

def simple_gen():
    print("before first yield")
    yield 1
    print("before second yield")
    yield 2
    print("after last yield")

gen = simple_gen()   # function body doesn't run yet — returns a generator object

val = next(gen)
# prints: "before first yield"
# pauses at `yield 1`
# val = 1

val = next(gen)
# resumes after `yield 1`
# prints: "before second yield"
# pauses at `yield 2`
# val = 2

val = next(gen)
# resumes after `yield 2`
# prints: "after last yield"
# function body finishes - raises StopIteration

Notice: calling simple_gen() doesn't execute a single line of the function body. It just create the generator object. The body only starts running when you call next() for the first time.

`StopIteration` - How Generators Signal "Done"

When a generator's function body finishes, either by reaching the end of hitting a return statement, it raises StopIteration. This is Python's built-in signal that an iterator has no more values.

def two_values():
    yield "first"
    yield "second"
    # function ends here — StopIteration raised automatically

gen = two_values()
print(next(gen))  # "first"
print(next(gen))  # "second"
print(next(gen))  # raises StopIteration 💥

In practice, you almost never call next() manually and catch StopIteration yourself. The for loop handles it automatically:

for value in two_values():
    print(value)
# "first"
# "second"
# loop exits cleanly when StopIteration is raised

This is why generators work seamlessly in for loops. The loop protocol calls next() under the hood and catches StopIteration to know when to stop.

Generators Are Lazy

This is the core behavioral difference from a regular function returning a list: generators are lazy. They don't compute values until they're asked for.

def big_range(n):
    i = 0
    while i < n:
        yield i
        i += 1

# This creates a generator instantly — no computation yet
gen = big_range(1_000_000_000)

# Only NOW does computation happen — and only for one value
print(next(gen))  # 0
print(next(gen)) # 1

Compare that to list(range(1_000_000_000)), which would try to allocate roughly 8GB of memory immediately.

Laziness makes generators ideal for:

Large datasets: Process a file line by line without loading it all into memory
Infinite sequences: A generator can produce values forever; a list can't.
Pipelines: Chain generators together so that data flows through transformations one value at a time

Generators Remember Their State

This is what makes generators genuinely different from callbacks or regular functions. Every local variable, every loop counter, the exact position in the code, all of it is preserved between calls to next().

def stateful_counter(start, step):
    current = start
    while True:
        yield current
        current += step   # this runs after each yield, before the next one

counter = stateful_counter(10, 3)
print(next(counter))  # 10
print(next(counter))  # 13
print(next(counter))  # 16
print(next(counter))  # 19

current persists between calls. No class, no instance variables, no global state. The generator object itself carries the state.

Generator Expressions

Just like list comprehensions give you a concise way to build lists, generator expressions give you a concise way to build generators, with the same lazy evaluation.

The syntax is identical to a list comprehension, but with parentheses instead of square brackets:

# List comprehension — builds entire list in memory immediately
squares_list = [x ** 2 for x in range(10)]

# Generator expression — lazy, computes one value at a time
squares_gen = (x ** 2 for x in range(10))

print(squares_list)  # [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
print(squares_gen)   #  at 0x...>
print(next(squares_gen))  # 0
print(next(squares_gen)) # 1

They work identically in for loops:

for sq in (x ** 2 for x in range(5)):
    print(sq)

And they shine when passed directly to functions that consume iterables:

# List comprehension — computes all squares, builds list, then sums
total = sum([x ** 2 for x in range(1_000_000)])

# Generator expression — sums one value at a time, never holds the full list
total = sum(x ** 2 for x in range(1_000_000))

The second version uses a fraction of the memory. Notice that you can drop the extra parentheses when a generator expression is the only argument to a function call.

When to Use Each

Situation	Use
Need all values at once, or index into them	List comprehension or `list()`
Processing values one at a time	Generator expression
Complex stateful logic between values	Generator function with `yield`
Potentially infinite sequence	Generator function
Passing to `sum()`, `max()`, `min()`, `any()`, `all()`	Generator expression

A good rule of thumb: If you're building a collection to iterate over it once, a generator is probably the right tool.

Real-World Usage 1: Reading Large Files

The most practical everyday use of generators is reading files line by line without loading the whole file into memory:

def read_large_file(filepath):
    with open(filepath, "r", encoding="utf-8") as f:
        for line in f:
            yield line.strip()

for line in read_large_file("access.log"):
    if "ERROR" in line:
        print(line)

The file is read one line at a time. If the log file is 10GB, this uses essentially no extra memory, compared to f.readlines() which would load all 10GB into RAM.

Real-World Usage 2: Infinite Sequences

Generators are the natural tool for sequences that have no defined end:

def unique_ids(prefix="user"):
    count = 0
    while True:
        yield f"{prefix}_{count}"
        count += 1

id_gen = unique_ids()
print(next(id_gen))  # user_0
print(next(id_gen))  # user_1
print(next(id_gen))  # user_2

You'd never build an infinite list. But an infinite generator is perfectly reasonable. You just take as many values as you need.

The JavaScript Parallel

If you're coming from JavaScript, generators will look familiar. Javascript has them too, with the function* syntax, and the same yield keyword:

// JavaScript generator
function* fibonacci() {
    let a = 0, b = 1;
    while (true) {
        yield a;
        [a, b] = [b, a + b];
    }
}

const gen = fibonacci();
console.log(gen.next().value);  // 0
console.log(gen.next().value);  // 1
console.log(gen.next().value);  // 1

Python's generators came first, introduced by PEP 255 in Python 2.2 and JavaScript borrowed the concept later. The mechanics are nearly identical, with one key difference: in Python, next(gen) is a built-function, while in JavaScript it's gen.next(), a method on the generator object.

What You Can't Do with a Generator

A few important constraints worth knowing:

You can only iterate once. A generator is exhausted after you've consumed all its values. You can't reset it or iterate it again, you have to create a new one.

gen = (x ** 2 for x in range(3))
print(list(gen))  # [0, 1, 4]
print(list(gen))  # [] — already exhausted

You can't index into a generator. Unlike lists, generators don't support gen[2]. They only know "next".

gen = (x for x in range(10))
print(gen[3])  # TypeError: 'generator' object is not subscriptable

If you need random access, convert to a list first: list(gen)[3].

The Bridge to Context Managers

Here's why generators matter for this series.

When Python see yield inside a function, it treats the function completely differently. It becomes a generator function.

The @contextmanager decorator from contextlib takes exactly this mechanism and wires to __enter__ and __exit__:

from contextlib import contextmanager

@contextmanager
def managed_resource():
    print("setup")    # __enter__ — runs up to yield
    yield             # your with block runs here
    print("teardown") # __exit__ — runs after yield

The yield is literally a pause point. @contextmanager calls next() to run setup, then calls next() again after your with block finishes to run teardown.

You don't need to understand the full wiring yet, that's Article 4. But now you know the mechanism it relies on, and it's not magic. It's just a generator being driven by a decorator.

The Mental Model to Take Away

A generator function is a resumable function. Every time you ask for the next value, it runs until the next yield, hands the value, and freezes, preserving every local variable and its position in the code exactly as they were.

Three things to remember:

yield pauses the function and send a value out
next() resumes it from exactly where it paused
StopIteration signals the generator is exhausted and for loops handle this automatically

Acronyms Used in This Article

PEP - Python Enhancement Proposal: It's a design document used by the Python community to propose and discuss new language features. PEP 255 introduced generators and PEP 289 introduced generator expressions.
RAM - Random Access Memory: It's the working memory your computer uses to store data while a program is running.

This is part 3 of 5 in the Python Context Managers Series.

Next up: Part 4 - Building Context Managers: __enter__, __exit__ and @contextmanager

The with Statement and open() in Depth

Moussa Kalam AMZAT — Mon, 30 Mar 2026 07:53:20 GMT

In Part 1, we established the problem: resources need to be returned, code between acquiring and releasing can fail, and try/finally is the manual safety net. Now let's look at the cleaner solution Python provides, and go deep on the most common context manager you'll ever use.

The `with` Statement: Clean Resource Management

Here's the try/finally pattern from Part 1:

file = open("notes.txt", "w")
try:
    file.write("Hello from Python")
finally:
    file.close()

And here's the same thing with with:

with open("notes.txt", "w") as file:
    file.write("Hello from Python")
# file is automatically closed here — no matter what

Same guarantee, half the code, and crucially, no way to forget the cleanup. The with statement handles it for you.

Anatomy of the `with` Statement

Let's name every piece:

with open("notes.txt", "w") as file:
    file.write("Hello from Python")

with  EXPRESSION  as  NAME:
         │              │
         │         the object you use inside the block
         │
something that returns a context manager

with: the keyword that opens a managed block
open("notes.txt", "w"): returns a file object that knows how to manage itself
as file: binds the file object to the name file so you can use it
the indented block: you code runs here
after the block: cleanup happens automatically, whether you left normally or via an exception

The as clause is optional. Some context managers do their job without needing to reference the object:

import threading

lock = threading.Lock()

with lock:  # no `as` needed — you just want acquire/release behavior
    print("only one thread runs this at a time")

Proving the Guarantee Holds on Error

Don't take the guarantee on faith. Let's verify it:

try:
    with open("notes.txt", "w") as file:
        file.write("first line\n")
        raise ValueError("something exploded")
        file.write("second line\n")  # never runs
except ValueError:
    pass

print(file.closed)  # True — closed despite the error

Compare that to the broken version without with:

try:
    file = open("notes.txt", "w")
    file.write("first line\n")
    raise ValueError("something exploded")
    file.close()  # never runs
except ValueError:
    pass

print(file.closed) # False - still open, leaked

Run both. The difference is clear. file.closed is your proof.

The JavaScript Parallel

Coming from Javascript, this pattern should feel familiar. The with statement is conceptually identical to try/finally, which you've probably written in Node.js. There's also the TC39 Explicit Resource Management proposal (already in TypeScript 5.2+) that introduces a using keyword with the same intent:

// TypeScript 5.2+ — using keyword
await using file = await fs.open("notes.txt", "w");
// file auto-disposes when block exits

Python has had this built in since 2.5 (2006, via PEP 343). The JavaScript ecosystem is just now catching up, which says something about how useful the pattern is.

Deep Dive: `open()`

open() is the context manager you'll reach for most often. Let's understand it fully, not just the happy path.

What `open()` Actually Does

When you call open(), Python asks the OS to:

Find the file at the given path
Reserve a file descriptor for your process
Return a file object that wraps that descriptor

That file object is what as file binds. It's not the file's contents, it's a handle you use to interact with the file. Think of it like a TV remote: the remote isn't the TV, but it's what lets you control it.

The Full Signature

open(file, mode='r', encoding=None, buffering=-1, errors=None)

The two parameters you'll use constantly are file and mode.

Parameter 1: `file` - What to Open

open("notes.txt")                       # looks in current working directory
open("data/notes.txt")                  # relative path
open("/home/moussa/projects/notes.txt") # absolute path

If the file doesn't exist and you're trying to read it.

with open("ghost.txt", "r") as f:
    content = f.read()
# FileNotFoundError: [Errno 2] No such file or directory: 'ghost.txt'

If you're writing, Python creates the file automatically.

Parameter 2: `mode` - What You Intend to Do

The mode tells Python (and the OS) how you want to interact with the file. It matters as the OS grants different permissions based on intent.

Mode	Name	Behavior
`"r"`	read	Default. The file must exist and the cursor is at the file start.
`"w"`	write	It creates the file if it doesn't exist yet and writes to it. If the file exists, it wipes existing content.
`"a"`	append	It creates the file if it doesn't exist yet, writes to it and add to its ends. It basically appends and never wipes.
`"x"`	exclusive create	It creates the file and fails if the file already exists.
`"r+"`	read + write	The file must exist. It allows you to both read and write.

You combine modes with a type modifier:

Modifier	Meaning
`"b"`	Binary mode: raw bytes, no encoding
`"t"`	Text mode: It's the default and it handles encoding.

open("image.png", "rb")   # read binary — for images, PDFs, etc.
open("data.bin", "wb")    # write binary
open("notes.txt", "rt")   # read text — same as just "r"

The Mode That Silently Destroys Your Data

"w" is the mode most beginners get burned by. It doesn't append, it destroys the existing content the moment you open the file, before you've written a single byte:

# First write
with open("log.txt", "w") as f:
    f.write("Entry 1\n")

# This WIPES "Entry 1" completely
with open("log.txt", "w") as f:
    f.write("Entry 2\n")

# log.txt now contains only "Entry 2" — Entry 1 is gone

If you want to keep existing content and add to it, use "a":

with open("log.txt", "a") as f:
    f.write("Entry 2\n")  # Entry 1 is still there

Parameter 3: `encoding` - Always Specify It

This is the one that causes bugs across operating systems. When you don't specify encoding, Python uses the system default, which differs by platform:

Linux / macOS: UTF-8 (almost always)
Windows: A legacy encoding like cp1252, which cannot represent most Unicode characters.

According to PEP 597, of the 4,000 most downloaded packages on PyPI, 82 fail to install from source on Windows due to missing encoding specification, and that's just the ones with non-ASCII characters in their README.

# Risky — encoding depends on the OS
with open("notes.txt", "r") as f:
    content = f.read()

# Explicit — works the same everywhere
with open("notes.txt", "r", encoding="utf-8") as f:
    content = f.read()

One character can prevent a whole class of cross-platform bugs. Always specify encoding="utf-8".

Note: Python 3.15 will make UTF-8 the default via PEP 686. Until then, specify it explicitly.

Reading and Writing: The Core Methods

Once you have a file object, these are the methods you'll use day to day.

Reading

# Read the entire file as one string
with open("notes.txt", "r", encoding="utf-8") as f:
    content = f.read()
    print(content)

# Read one line at a time
with open("notes.txt", "r", encoding="utf-8") as f:
    first_line = f.readline()
    print(first_line)
    second_line = f.readline()
    print(second_line)
    

# Read all lines into a list
with open("notes.txt", "r", encoding="utf-8") as f:
    lines = f.readlines()
    print(lines)  # ["line 1\n", "line 2\n", ...]

The most Pythonic way to read line by line is to iterate directly over the file object. It's memory-efficient as it doesn't load the entire file at once, which matters when you're processing large files:

with open("notes.txt", "r", encoding="utf-8") as f:
    for line in f:            # file objects are iterable
        print(line.strip())   # strip() removes the trailing \n

Writing

# Write a string — \n is your responsibility
with open("notes.txt", "w", encoding="utf-8") as f:
    f.write("Hello, Moussa\n")
    f.write("Second line\n")

# Write a list of strings at once
with open("notes.txt", "w", encoding="utf-8") as f:
    lines = ["line 1\n", "line 2\n", "line 3\n"]
    f.writelines(lines)

Note: write() does not add a newline automatically. You have to include \n yourself. This catches people coming from print(), which adds it for you.

The File Cursor

Every file object tracks your current position using an internal cursor. This trips people up when they try to read a file they just wrote:

with open("notes.txt", "r", encoding="utf-8") as f:
    first_five = f.read(5)   # reads first 5 characters
    print(first_five)        # "Hello"

    rest = f.read()          # cursor is now at position 5
    print(rest)              # reads everything after position 5

You can move the cursor manually with seek():

with open("notes.txt", "r", encoding="utf-8") as f:
    f.read()         # reads everything — cursor now at end
    print(f.read())  # empty string — nothing left

    f.seek(0)        # reset cursor to the beginning
    print(f.read())  # reads everything again

Why `open()` Is a Context Manager

Here is the connection back to where we started. File objects implement two special methods: __enter__ and __exit__ which is what makes them work with with.

Simplified, this is what they do:

class FileObject:
    def __enter__(self):
        return self     # return the file object itself

    def __exit__(self, exc_type, exc_value, traceback):
        self.close()    # always close the file
        return False    # never suppress exceptions

That's it. When Python sees with open(...) as f, it calls __enter__ to get the file object and __exit__ to close it. Everything else follows from that.

We'll look at how __enter__ and __exit__ actually work, and how to implement them yourself in Part 3.

Quick Reference

# Read entire file
with open("data.txt", "r", encoding="utf-8") as f:
    content = f.read()

# Write (creates or overwrites)
with open("data.txt", "w", encoding="utf-8") as f:
    f.write("some content\n")

# Append (never overwrites)
with open("data.txt", "a", encoding="utf-8") as f:
    f.write("new line\n")

# Read line by line (memory efficient)
with open("data.txt", "r", encoding="utf-8") as f:
    for line in f:
        print(line.strip())

# Read binary (images, PDFs, etc.)
with open("image.png", "rb") as f:
    data = f.read()

The Mental Model to Take Away

The with statement activates a contract: setup on entry, guaranteed teardown on exit. open() is the most common thing that honors that contract. It opens a file descriptor on entry and closes it on exit, no matter what happens in between.

Two rules to carry forward:

Always use with when opening files. Never rely on .close() or the garbage collector.
Always specify encoding=utf-8. Never rely on the OS default.

In part 3, we'll pull back the curtain on how the with statement works under the hood and build your own context manager from scratch.

Thank you for reading! 🙂

This is Part 2 of 5 in the Python Context Managers series.

New here? Read Part 1

Next up: Part 3 - Generator Functions in Python

Why Python Makes you "Close" Things (And What Happens When You Don't)

Moussa Kalam AMZAT — Fri, 27 Mar 2026 06:58:55 GMT

Coming from JavaScript/TypeScript, I thought I understood resource management. You fetch(), you await, you move on. Node.js handles the rest, right?

Then I started writing Python seriously, and I kept on seeing this part everywhere:

with open("data.txt", "r") as file:
    content = file.read()

I knew how to use it. Always writing the same bit of syntax, it works. But I had no idea why it existed, or what happened if I skipped it.
It turns out a lot can go wrong. And the worst part is that it won't blow up immediately. It will fail silently, in production, at 2am on a Saturday.

This article is about understanding the problem that Python's with statement was built to solve. We'll get to with in the next article. First, let's talk about what happens when things go wrong.

Your Program Borrows Things from the OS

When your Python program wants to read a file, it can't just reach into the filesystem directly. It has to ask the operating system nicely.
The OS responds by opening the file and handing your program a file descriptor, a small non-negative integer that acts as a reservation ticket. Think of it like the numbered ticket you get at a deli counter. The ticket isn't the sandwich. It's just proof that you're in the queue and the deli is holding your order.

file = open("notes.txt", "w")
print(file.fileno()) # prints something like 3, 4, or 5

Numbers 0, 1, and 2 are permanently reserved by the OS for every process:

Descriptor	Name	What it is
`0`	`stdin`	Keyboard input
`1`	`stdout`	Normal print output
`2`	`stderr`	Error output

So the first file you open typically gets descriptor 3, the next gets 4, and so on.

Here is the critical part: the OS keeps a table of open file descriptors per process, and that table has a fixed size. On most Linux systems, the default limit is 1024.

import resource

soft_limit, _ = resource.getrlimit(resource.RLIMIT_NOFILE)
print(f"Max open files: {soft_limit}") # typically 1024

Once all 1024 slots are taken, any new open() call raises:

OSError: [Errno 24] Too many open files

That ticket counter fills up, and the deli stops taking orders.

The Leak You Don't See Coming

Here's where it gets sneaky. A resource leak doesn't announce itself. It builds up quietly until the system hits its limit, then it explodes.
Consider this function that processes a batch of files:

def process_files(filenames):
    for name in filenames:
        file = open(name, "r")
        data = file.read()
        process(data)
        # oops — forgot file.close()

This works perfectly for the first 1,021 files. Then on file 1022, crash 💥. And the error message points at the open() call, not at the missing close() three lines earlier. Good luck debugging that at 2am!

Let's make it concrete. Here's a script that deliberately leaks file descriptors:

import os

files = []
count = 0

try:
    while True:
        f = open("test.txt", "w")
        files.append(f)  # keep a reference so it's not garbage collected
        count += 1
except OSError as e:
    print(f"Failed after {count} open files: {e}")

⚠

Please don't run this in production.

It's Not Just Files

File descriptors are the most visible example, but the same problem applies to any resource with a limited supply:

Network connections: databases, APIs, and servers all have connection limits. Leave connections open and you'll eventually see Too many connections errors from your database, with perfectly healthy-looking application code.

Locks: This one is nastier that a file leak. If your code requires a threading lock and then throws an exception before releasing it, the lock stays held forever. Every other thread waiting on it will wait forever too. Your application freezes. No error message, just silence.

import threading

lock = threading.Lock()

def transfer_funds(amount):
    lock.acquire()

    if amount > get_balance():
        raise ValueError("Insufficient funds")  # 💥 lock never released

    deduct(amount)
    lock.release()  # never reached if the check above raises

Call transfer_funds() with an invalid amount once, and your entire application deadlocks. Every subsequent call to any function that tries to acquire that lock will hang. Congratulations, you've built a very expensive paperweight 😄.

The Data Corruption You Don't Expect

There's another flavor of resource leak that's even more surprising: unflushed writes.

When you write to a file, Python doesn't immediately send those bytes to disk. It buffers them in memory first for performance. The buffer gets flushed to disk with it fills up, when you call .flush(), or crucially, when you call .close().
If your program crashes before .close() is called, the buffer is discarded. The data never makes it to disk.

file = open("important_data.txt", "w")
file.write("Transfer $10,000 to account 9982")
raise Exception("something went wrong")
file.close()  # never reached

Open important_data.txt after running this. Empty!!!
Those bytes were sitting in a memory buffer, and when the process died, they went with it.

Let's make it even more dramatic:

import os

file = open("test.txt", "w")
file.write("This will never make it to disk")

os._exit(1)  # hard kill — skips all cleanup

Check test.txt after running that. Empty file. Zero bytes written.

Won't the Garbage Collector Handle It?

Coming from JavaScript, this was my first instinct too. GC handles memory, but does it handle files too?

Sometimes. CPython (the standard Python implementation) uses reference counting: when an object's reference count drops to zero, it gets cleaned up immediately, which includes closing the file:

def read_data():
    file = open("notes.txt", "r")
    return file.read()
    # file goes out of scope here
    # CPython closes it immediately — but only because of reference counting

But here's the problem: this is an implementation detail of CPython, not a guarantee of the Python language. PyPy, Jython, and other Python implementations use different garbage collectors that don't clean up immediately. Even in CPython, circular references can delay cleanup indefinitely.

The Python documentation is explicit about this:

"It is good practice to use the with keyword when dealing with file objects. The advantage is that the file is properly closed after its suite finishes, even if an exception is raised at some point."

Don't rely on GC to close your files. It's like assuming someone else will wash your dishes. Maybe they will. Maybe they won't. You'll find out at the worst possible time.

The Manual Fix, And Why It's Not Enough

Once you understand the problem, the fix seems obvious: use try/finally.

finally blocks always run, whether the code inside succeeded, raised an exception, or even hit a return statement.

file1 = open("input.txt", "r")
try:
    file2 = open("output.txt", "w")
    try:
        data = file1.read()
        file2.write(data.upper())
    finally:
        file2.close()
finally:
    file1.close()

This is correct but exhausting to write and read. There has to be a better way. Don't you think so? 🤔

There Is a Better Way

Python 2.5 introduced the with statement (via PEP 343) specifically to solve this problem. It packages the try/finally pattern into a clean, reusable interface that's impossible to forget.

The same two-file example from above becomes:

with open("input.txt", "r") as file1, open("output.txt", "w") as file2:
    data = file1.read()
    file2.write(data.upper())
# both files are closed here — automatically, always

No nesting, no finally. No way to forget to cleanup. The same guarantee, with none of the ceremony.

That's what context managers are, a Python-native way to say: "when this block exits, run this cleanup, no matter what."

The Mental Model to Take Away

Every resource your program borrows from the OS need to be returned:

Open a file, close it
Acquire a lock, release it
Open a connection, close it.

The problem isn't that developers don't know this. It's that code between acquiring and releasing can fail, and when it does, the cleanup gets skipped.

try/finally is the manual solution. Context manager is the automatic one.

In the next article, we'll look at exactly how the with statement works, go deep on open(), and start seeing how Python's most common operation, reading and writing files, becomes foolproof with context managers.

Acronyms Used in This Article

OS — Operating System. The software that manages hardware resources and provides services to programs. On most servers, this is Linux.
GC — Garbage Collector. The part of a language runtime responsible for automatically reclaiming memory that's no longer in use.
PEP — Python Enhancement Proposal. A design document used by the Python community to propose and discuss new language features. PEP 343 is the one that introduced the with statement.

Thank you for reading 🙂.

This is Part 1 of 5 in the Python Context Managers Series.

Next up: Part 2 - The with Statement and open() in Depth.

Class-Based Python Decorators: When Functions Aren't Enough

Moussa Kalam AMZAT — Sun, 22 Mar 2026 21:31:10 GMT

You've built decorators with functions. You've nested them two layers deep, three layers deep, stacked them on top of each other. And it all works.

But at some point, you'll write a decorator that needs to remember things between calls: a counter, a cache, a log of every invocation... And you'll find yourself reaching nonlocal, juggling closure variables, and wondering if there'a a cleaner way.

There is. It's a class.

A Quick Prerequisite: `call`

Before we build anything, you need to know one thing about Python classes: any object can behave like a function if its class defines a __call__ method.

class Greeter:
    def __call__(self, name):
        print(f"Hello, {name}!")

greet = Greeter()
greet("Moussa")  # Hello, Moussa!

greet is not a function, it's an instance of Greeter. But because Greeter has __call__, you can use parentheses on it as if it were a function. Python sees greet("Moussa") and internally calls greet.__call__("Moussa").

This is the entire foundation of class-based decorators. If an object is callable, it can replace a function. And if it can replace a function, it can be a wrapper.

Your First Class-Based Decorator

Let's start with something familiar, a decorator that logs every time a function is called:

Function-based version (what you already know):

def log_calls(func):
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

Class-based version:

class LogCalls:
    def __init__(self, func):
        self.func = func

    def __call__(self, *args, **kwargs):
        print(f"Calling {self.func.__name__}")
        return self.func(*args, **kwargs)

@LogCalls
def greet(name):
    return f"Hello, {name}"

print(greet("Moussa"))
# Calling greet
# Hello, Moussa

Let's trace through what Python does when it sees @LogCalls:

Python calls @LogsCall(greet): This triggers __init__, which stores the original function as self.func
greet is now replaced by the LogCalls instance
When you call greet("Moussa"), Python calls the instance, which triggers __call__
Inside __call__, we run our logic and call self.func("Moussa")

Same pattern as before: take a function in, return something callable that wraps. The difference is that the "something callable" is now an object instead of an inner function.

Why Bother? The State Problem

So far, the class version looks like more code for the same result. Fair enough 😀!
The real advantage shows up when your decorator needs to maintain state.

Let's build a decorator that counts how many times a function has been called.

Function-based version:

def count_calls(func):
    count = 0
    def wrapper(*args, **kwargs):
        nonlocal count
        count += 1
        print(f"{func.__name__} has been called {count} time(s)")
        return func(*args, **kwargs)
    return wrapper

It works, but there's a problem: count is trapped inside the closure. You can't access it from outside. You can't reset it. You can't inspect it. It's invisible.

Class-based version

class CountCalls:
    def __init__(self, func):
        self.func = func
        self.count = 0

    def __call__(self, *args, **kwargs):
        self.count += 1
        print(f"{self.func.__name__} has been called {self.count} time(s)")
        return self.func(*args, **kwargs)

@CountCalls
def greet(name):
    return f"Hello, {name}"

greet("Moussa")   # greet has been called 1 time(s)
greet("Fabien")   # greet has been called 2 time(s)

print(greet.count)  # 2 — accessible!
greet.count = 0     # reset it
greet("Moussa")     # greet has been called 1 time(s)

The state lives on self, not inside a closure. You can read it, reset it, and even add methods to interact with it. The decorator becomes a proper object, not a black box.

This is the key insight: function-based decorators use closure to remember state. Class-based decorators use self. Same concept, different container, but self is far more accessible.

Adding Methods to Your Decorators

Since the wrapper is now an object, you can give it useful methods:

class CountCalls:
    def __init__(self, func):
        self.func = func
        self.count = 0

    def __call__(self, *args, **kwargs):
        self.count += 1
        return self.func(*args, **kwargs)

    def reset(self):
        self.count = 0

    def report(self):
        print(f"{self.func.__name__} has been called {self.count} time(s)")

@CountCalls
def process_order(order_id):
    return f"Order {order_id} processed"

process_order(1)
process_order(2)
process_order(3)
process_order.report()  # process_order has been called 3 times
process_order.reset()
process_order.report()  # process_order has been called 0 times

Try doing that with a function-based decorator. You'd have to attach functions as attributes on the wrapper, awkward and messy. With a class, it's natural.

Class-Based Decorators with Arguments

Just like function-based decorators, you can make class-based decorators configurable. The pattern shifts slightly.

Without arguments, __init__ receives the arguments, and __call__ receives the function:

@MyDecorator(arg)   # Python calls MyDecorator(arg), then the result(func)
def my_function():
    pass

Here's a practical example: a decorator that slows down a function by a configurable number of seconds:

import time

class SlowDown:
    def __init__(self, seconds):
        self.seconds = seconds

    def __call__(self, func):
        def wrapper(*args, **kwargs):
            print(f"Waiting {self.seconds}s before calling {func.__name__}...")
            time.sleep(self.seconds)
            return func(*args, **kwargs)
        return wrapper

@SlowDown(2)
def send_email(to):
    print(f"Email sent to {to}")

send_email("moussa@example.com")
# Waiting 2s before calling send_email...
# Email sent to moussa@example.com

Let's trace through it:

Python evaluates SlowDown(2): This creates an instance with self.seconds = 2
Python calls that instance with the function: instance(send_email), which triggers __call__
__call__ returns the wrapper function
send_email is now replaced by wrapper

Notice the difference: when there are no arguments, __call__ is the wrapper itself (it gets called every time the decorated function is called). When there are arguments, __call__ is the decorator (it gets called once, receiving the function, and returns a wrapper).

This is the trickiest part of class-based decorators. Read that paragraph again if you need to.

Practical Example: A Rate Limiter

Here's a class-based decorator that limits how often a function can be called:

import time

class RateLimit:
    def __init__(self, min_interval):
        self.min_interval = min_interval

    def __call__(self, func):
        last_called = [0]  # using list to allow mutation in closure

        def wrapper(*args, **kwargs):
            elapsed = time.time() - last_called[0]
            if elapsed < self.min_interval:
                wait = self.min_interval - elapsed
                print(f"Rate limited. Wait {wait:.1f}s")
                return None
            last_called[0] = time.time()
            return func(*args, **kwargs)
        return wrapper

@RateLimit(min_interval=2)
def call_api(endpoint):
    print(f"Calling {endpoint}")
    return {"status": "ok"}

call_api("/users")      # Calling /users
call_api("/users")      # Rate limited. Wait 1.8s
time.sleep(2)
call_api("/users")      # Calling /users

The min_interval configuration lives on the instance. The call timing state lives in the closure. This hybrid approach: class for configuration, closure for per-call state, is a common and effective pattern.

Practice Example: A Retry with Exponential Backoff

import time

class Retry:
    def __init__(self, max_attempts=3, backoff_factor=2):
        self.max_attempts = max_attempts
        self.backoff_factor = backoff_factor

    def __call__(self, func):
        def wrapper(*args, **kwargs):
            for attempt in range(1, self.max_attempts + 1):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    if attempt == self.max_attempts:
                        print(f"All {self.max_attempts} attempts failed.")
                        raise
                    wait = self.backoff_factor ** attempt
                    print(f"Attempt {attempt} failed: {e}. Retrying in {wait}s...")
                    time.sleep(wait)
        return wrapper

@Retry(max_attempts=3, backoff_factor=2)
def fetch_data(url):
    raise ConnectionError("Server unreachable")

# fetch_data("https://api.example.com")
# Attempt 1 failed: Server unreachable. Retrying in 2s...
# Attempt 2 failed: Server unreachable. Retrying in 4s...
# All 3 attempts failed.

The class makes the configuration readable: max_attempts=3, backoff_factor=2 reads like a sentence. Compare this to the function-based version where these would be arguments to a factory function. Same result, but the class version communicates intent more clearly when the configuration is complex.

When to Use Function-Based vs Class-Based

This isn't a "one is better" situation. They're tools for different contexts:

Use function-based decorators when:

Your decorator is simple: log, time, validate, then call the function
You don't need to maintain state between calls
You don't need to expose any interface to the caller
You want less boilerplate for a quick wrapper

Use class-based decorators when:

You need to maintain state across calls (counters, caches, history)
You want to expose methods or properties on the decorated function (.reset(), .count, .report())
Your decorator has complex configuration with multiple parameters
You want to use inheritance to create decorator families
Readability matters more than brevity, classes make the structure explicit

Most decorators you'll write and encounter are function-based. But when the logic gets complex or stateful, classes keep things organized where closures start to get tangled.

A Note on `functools.wraps`

One thing we haven't addressed: when you decorate a function with a class, the function's __name__ and __doc__ get replaced by the class's.

@CountCalls
def greet(name):
    """Greet someone by name."""
    return f"Hello, {name}"

print(greet.__name__)  # 'CountCalls' — not 'greet'!
print(greet.__doc__)   # None — the docstring is gone!

For function-based decorators, you'd use @functools.wraps(func) on the wrapper.
For class-based decorators, you can apply it in __init__:

import functools

class CountCalls:
    def __init__(self, func):
        functools.update_wrapper(self, func)
        self.func = func
        self.count = 0

    def __call__(self, *args, **kwargs):
        self.count += 1
        return self.func(*args, **kwargs)

@CountCalls
def greet(name):
    """Greet someone by name."""
    return f"Hello, {name}"

print(greet.__name__)  # 'greet' — preserved!
print(greet.__doc__)   # 'Greet someone by name.' — preserved!

functools.update_wrapper copies the original function's metadata on to the instance. Always do this as it keeps debugging, documentation, and introspection tools working correctly.

The Mental Model

Here's how function-based and class-based decorators map to each other:

Function-based:

Outer function receives the function (or arguments)
Inner function (wrapper) replaces the function
Closure variables are the state

Class-based

__init__ receives the function (or arguments)
__call__ replaces the function (or returns the wrapper)
self represents the state.

Same architecture, different syntax. If you understand one, you understand both. The only question is which one keeps your code for the specific problem you're solving.

What's Next?

This article extends the Python Decorators series with a pattern you'll encounter in more advanced codebases, especially in frameworks, ORMs, and testing libraries. If you haven't read the earlier parts, here's the full series:

Part 1: Understanding Python Decorators From Scratch: The foundations
Part 2: The Print vs Return Trap: The most common silent bug
Part 3: Advanced Patterns — Arguments and Stacking: The real-world patterns
Part 4: 10 Exercises to Master Decorators: Hands-on practice

Thank you for reading 🙂.

This is a bonus article in the Python Decorators series on Build, Break, Learn.
Written by a developer who learned the hard way so you don't have to.

10 Exercises to Master Python Decorators (With Solutions)

Moussa Kalam AMZAT — Tue, 17 Mar 2026 08:35:25 GMT

You've read the theory. You understood how decorators work. Now it's time to prove to yourself.

These exercises are ordered deliberately. The first few build the foundation skills, and each one adds a layer until you're writing production-style decorators by the end. Try each exercise before looking at the solution. Struggling is where the learning happens.

Let's go.

Exercise 1: Functions as Objects

Task: Write a function called apply that takes a function and a value, and returns the result of calling that function with that value.

def square(x):
    return x * x

def double(x):
    return x * 2

# Your code should make this work:
print(apply(square, 5))   # 25
print(apply(double, 5))   # 10

💡

What this tests: Can you pass a function as an argument and call it?

Click to reveal solution

Advanced Python Decorators Patterns: Arguments and Stacking

Moussa Kalam AMZAT — Wed, 11 Mar 2026 21:17:53 GMT

You've learned how decorators work. You've survived the print vs return trap. Now it's time for the patterns you'll actually encounter in the wild: decorators that take arguments and decorators that stacked on top of each other.

If you've ever wondered how FastAPI's @app.get("/shipments") work under the hood, this is the article for you.

The Problem with Simple Decorators

Our decorators so far have all looked like this:

@my_decorator
def some_function():
    pass

The decorator receives the function, wraps it, and returns the wrapper. Clean and simple.

But what if you want a decorator that repeats a function a configurable number of times? You want to use it like this:

@repeat(3)
def say_hello():
    print("Hello!")

say_hello()
# Hello!
# Hello!
# Hello!

And on another function:

@repeat(5)
def say_goodbye():
    print("Goodbye!")

Same decorator, different configuration. How do we build this?

Your First Instinct Is Wrong (And That's OK)

Your first thought might be: "Just add the number as another parameter."

def repeat(func, n):  # <-- this won't work with @
    def wrapper(*args, **kwargs):
        for _ in range(n):
            result = func(*args, **kwargs)
        return result
    return wrapper

But this breaks with the @ syntax. When Python sees @repeat(3), it calls @repeat(3) before it knows about the function. So repeat receives 3, not a function. There's no way to pass both the number and the function at the same time.

@repeat and @repeat(3) are not the same pattern. The first expect repeat itself to be a decorator. The second expect repeat(3) to return a decorator.

Understanding What `@repeat(3)` Actually Does

Let's slow down and think about what Python does when it sees:

@repeat(3)
def say_hello():
    print("Hello!")

It evaluates this in two steps:

First, it calls repeat(3). This must return a decorator.
Then, it applies that decorator to say_hello.

Written out explicitly:

# Step 1: repeat(3) returns a decorator
decorator = repeat(3)

# Step 2: that decorator wraps say_hello
say_hello = decorator(say_hello)

Or in one line: say_hello = repeat(3)(say_hello).

This means repeat is not the decorator itself anymore. It's a function that builds and returns a decorator. One extra layer.

This wrapping happens once, when Python executes the def statement. After that, the name say_hello no longer refers to the original function. It refers to the wrapper returned by the decorator.

Building It Step by Step

Let's start with something we already know, a decorator with the number hardcoded:

from functools import wraps

def repeat_three(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        result = None
        for _ in range(3):
            result = func(*args, **kwargs)
        return result
    return wrapper


@repeat_three
def say_hello():
    print("Hello!")

💡

Remember from the first article in this series: You will usually use functools.wraps(func) on the wrapper so the decorated function keeps metadata like its original name and docstring.

This works, but 3 is baked in. To make it configurable, wrap the whole thing in a function that takes n:

from functools import wraps

def repeat(n):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            result = None
            for _ in range(n):
                result = func(*args, **kwargs)
            return result
        return wrapper
    return decorator

Three layers. Read them from the outside in:

repeat(n) takes your configuration argument
decorator(func) takes the function being decorated (this is the actual decorator)
wrapper(*args, **kwargs) replaces the original function

That's it. Now it works with any number:

@repeat(3)
def say_hello():
    print("Hello!")

@repeat(5)
def say_goodbye():
    print("Goodbye!")

say_hello()
# Hello!
# Hello!
# Hello!

say_goodbye()
# Goodbye!  (x5)

Notice that repeat returns the result from the final execution of the function. If the function returns different values on each call, only the last one is preserved.

💡

If n were 0, this implementation would return None, so in real code you may want to validate that n >= 1.

Let's Trace Through the Execution

When Python sees @repeat(3) above say_hello, here's exactly what happens:

Python calls repeat(3)
repeat(3) returns the decorator function, with n=3 remembered (closure)
Python applies that decorator to say_hello: decorator(say_hello)
decorator(say_hello) returns the wrapper function, with func=say_hello remembered
say_hello is now replaced by wrapper
When you call say_hello(), you're calling wrapper()
wrapper runs the original say_hello 3 times (because n=3 is remembered)

Closures are doing all the heavy lifting here. Each layer remembers the values from the layer above it.

A closure is a function that remembers variables from the scope where it was created, even after that outer function has finished running.

Practical Example: A Retry Decorator

Here's a decorator that retries a function if it throws an exception:

from functools import wraps
import time

def retry(max_attempts):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(1, max_attempts + 1):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    print(f"Attempt {attempt} failed: {e}")
                    if attempt < max_attempts:
                        print("Retrying...")
                        time.sleep(1)
                    else:
                        print("All attempts failed!")
                        raise # Re-raise the exception if all attempts exhausted
        return wrapper
    return decorator

@retry(3)
def connect_to_server():
    print("Trying to connect...")
    raise ConnectionError("Server is down")

connect_to_server()
# Trying to connect...
# Attempt 1 failed: Server is down
# Retrying...
# Trying to connect...
# Attempt 2 failed: Server is down
# Retrying...
# Trying to connect...
# Attempt 3 failed: Server is down
# All attempts failed!

Notice how the return inside the try block exits the wrapper immediately on success. The loop only continues if an exception is caught.

This is a simplified example for learning. Real retry logic usually catches specific exceptions, may use exponential backoff, and often avoids retrying on every kind of failure.

Practical Example: Role-Based Access Control

from functools import wraps
 
def require_role(role):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            current_user_role = "editor"  # imagine this from a database
            if current_user_role != role:
                print(f"Access denied! You need '{role}' role.")
                return None
            return func(*args, **kwargs)
        return wrapper
    return decorator

@require_role("admin")
def delete_user(user_id):
    print(f"User {user_id} deleted!")

@require_role("editor")
def edit_post(post_id):
    print(f"Post {post_id} edited!")

delete_user(42)   # Access denied! You need 'admin' role.
edit_post(7)      # Post 7 edited!

⚠

In real code, current_user_role would be injected (e.g, from a request context or a passed argument), not hardcoded. The hardcoded "editor" is just a placeholder to make the demo runnable.

Same decorator, different configuration. That's the power of decorator arguments.

The Pattern to Remember

Without arguments - Two layers:

from functools import wraps

def decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

With arguments - Three layers:

from functools import wraps

def decorator_factory(arguments):    # takes your settings
    def decorator(func):              # takes the function
        @wraps(func)
        def wrapper(*args, **kwargs):  # replaces the function
            return func(*args, **kwargs)
        return wrapper
    return decorator

The only difference is one extra outer function that holds your configuration. That's all there is to it.

Stacking Decorators

You can apply multiple decorators to a single function. They apply bottom-up: the bottom decorator wraps the function first, and the top decorator wraps the result.

@timer
@repeat(3)
def greet():
    print("Hi!")

# Equivalent to:
decorated = repeat(3)(greet)
greet = timer(decorated)

Here, repeat(3) wraps greet first, then timer wraps the result. When you call greet(), timer's wrapper runs first, which calls repeat's wrapper, which calls the original greet three times.

The bottom decorator wraps first, but the top decorator's wrapper runs first when the function is called.

When Stacking Works Well

Decorators that transform return values compose beautifully together, because each decorator receives the output of the one below it and can modify it before passing it up:

from functools import wraps

def add_exclamation(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return result + "!"
    return wrapper

def make_uppercase(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return result.upper()
    return wrapper

@add_exclamation
@make_uppercase
def greet(name):
    return f"hello, {name}"

print(greet("Moussa"))  # HELLO, MOUSSA!

make_uppercase wraps first, turning the return value to "HELLO, MOUSSA".

Then add_exclamation wraps that, adding "!" to make "HELLO MOUSSA!".

Clean, predictable, composable.

💡

Because each wrapper receives a value and returns a new value, the decorators form a chain where each layer can still influence the final result.

When Stacking Gets Tricky

Decorators that use side effects (like print()) don't compose as cleanly. If one decorator prints something and another transforms return values, the printed output can't be intercepted or reordered by the other decorator. The side effects have already escaped the chain.

The general principle: When you're designing decorators that might be stacked, prefer working with return values over side effects. This gives other decorators in the chain a chance to interact with your output.

print() sends text directly to standard output and returns None, so another decorator cannot "catch" that printed text the way it can catch and modify a normal return value.

Common Decorator Patterns in the Wild

Now that you understand the mechanics, you'll start recognizing these patterns everywhere:

FastAPI routes

@app.get("/")
def root():
    return {"message": "Welcome to my API"}

Django authentication

@login_required             # simple decorator
def dashboard(request):
    return render(request, "dashboard.html")

Python builtins

class MyClass:
    @staticmethod           # simple decorator
    def utility():
        pass

    @property               # simple decorator
    def name(self):
        return self._name

Functools caching

from functools import lru_cache

@lru_cache(maxsize=128)    # decorator with arguments
def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

They all follow the same principles we've learned. Some take arguments (three layers), some don't (two layers). But the core pattern is always the same: take a function in, return a wrapped version out.

What's Next?

You now have the complete picture of Python decorators, from the foundations through the common pitfalls to advanced patterns. In the final part of this series, I've put together 10 hands-on exercises that will test and solidify everything you've learned.

Subscribe to my newsletter if you don't want to miss any updates.
Thank you for reading 🙂.

This is Part 3 of my Python Decorator series. Check out Part 1: Understanding Decorators From Scratch for foundations and Part 2: The Print vs Return Trap for the most common pitfall.

The Print vs Return Trap That Silently Breaks Your Python Decorators

Moussa Kalam AMZAT — Sun, 08 Mar 2026 21:05:00 GMT

When I was learning about decorators, I kept running into the same frustrating problem: my decorated function kept returning None. The decorator looked right. The function looked right. But the values just... vanished.

It took me an embarrassingly long time to realized I was confusing print with return. And I don't think I'm alone as this is the single most common bug when learning decorators, especially you're coming from JavaScript where console.log is your best friend.

Let me save you the headache.

The Difference That Changes Everything

Let's get this absolutely clear before we touch decorators.

print() sends text to the screen. That's it. It's a one-way trip. The value goes to the terminal and vanishes from the program's perspective. You can't catch it, store it, or pass it along.

return silently passes a value back to the caller. Nothing appears on the screen. The value stays inside the program where it can be stored, transformed, or used however the caller wants.

def version_a():
    print("hello")     # shows on screen, returns None

def version_b():
    return "hello"     # shows nothing, gives value to caller

These two functions look almost identical, but they behave completely differently:

# Using version_a:
x = version_a()         # "hello" appears on screen
print(x)                # None  <-- the value is GONE
print(type(x))          # 

# Using version_b:
y = version_b()         # nothing appears on screen
print(y)                # hello  <-- the value is HERE
print(y.upper())        # HELLO  <-- we can transform it
print(len(y))           # 5     <-- we can use it

Think of it this way: print() is like shouting something in a room. Everyone hears it, but you can't unsay it or hand it to someone specific. return is like writing something on a note and handing it to the person who asked. They can read it, pass it on, or put it in their pocket for later.

Why This Breaks Decorators

A decorator's wrapper function is a middleman. It sits between the caller and the original function. Whatever the original function returns, the wrapper has to catch and pass along. If it doesn't, the value disappears.

Here is the most common mistake:

Mistake 1: Forgetting to Return

from functools import wraps

def log_calls(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__}")
        func(*args, **kwargs)   # called, but result THROWN AWAY
        print("Done")
    return wrapper


@log_calls
def add(a, b):
    return a + b

result = add(2, 3)
print(result)
# Calling add
# Done
# None    <--- WHERE IS THE 5?!

The function add(2, 3) computed 5 and returned it to the wrapper. But the wrapper caught it in mid-air and dropped it. The wrapper itself has no return statement so it returns None. The 5 simply ceased to exist.

The fix is two lines:

from functools import wraps

def log_calls(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__}")
        result = func(*args, **kwargs)  # CATCH the value
        print("Done")
        return result                    # PASS IT ALONG
    return wrapper

Mistake 2: Printing Instead of Returning

This one is sneakier because if feels like it's working:

from functools import wraps

def cache(func):
    @wraps(func)
    def wrapper(*args):
        if args in wrapper.memory:
            print(f"Cached: {wrapper.memory[args]}")    # prints to screen!
        else:
            result = func(*args)
            wrapper.memory[args] = result
            print(f"Computed: {result}")    # prints to screen!

    wrapper.memory = {} # Functions are objects 😉
    return wrapper


@cache
def square(n):
    return n * n

answer = square(5)
print(answer)
# Computed: 25
# None          <--- the answer never arrived!

# Even worse:
total = square(5) + square(3)
# TypeError: unsupported operand type(s) for +: 'NoneType' and 'NoneType'

You see 25 on the screen, so it looks like it's working. But the value went to the terminal, not to the caller. The variable answer holds None, not 25. The wrapper printed the result instead of returning it. It shouted the answer across the room instead of handing it over.

Mistake 3: Returning Formatted Strings Instead of Raw Values

Another trap I fell into was returning descriptive strings from the wrapper:

from functools import wraps

def cache(func):
    @wraps(func)
    def wrapper(*args):
        if args in wrapper.memory:
            return f"(instant!) -> {wrapper.memory[args]}"
        result = func(*args)
        wrapper.memory[args] = result
        return f"(computed) -> {result}"
    wrapper.memory = {} # A function is an object
    return wrapper

@cache
def add(a, b):
    return a + b

result = add(2, 3)
print(result)          # (computed) -> 5
print(result + 10)     # TypeError! Can't add string + int

The decorator changed the function's return type from a number to a string. Any code expecting a number back from add will break. A decorator should be invisible, the caller shouldn't be able to tell the function is decorated.

The Correct Pattern

Always capture the return value and always return it:

def my_decorator(func):
    def wrapper(*args, **kwargs):
        # do whatever you want before
        result = func(*args, **kwargs)    # CATCH the value
        # do whatever you want after
        return result                      # PASS IT ALONG
    return wrapper

Two lines. That's the difference between a decorator that works and one that silently eats your data.

"But What If My Function Doesn't Return Anything?"

Great question! Some functions just do things without returning a value:

def say_hello():
    print("Hello!")    # prints, returns None implicitly

If you wrap this function, result will be None. And returning None is perfectly harmless:

@log_calls
def say_hello():
    print("Hello!")    # no return statement

say_hello()
# Calling say_hello
# Hello!
# Done

# result is None, but nobody cares — it works perfectly

This is exactly why you should always return the result, even if you think the function won't return anything:

If the function returns something, you've preserved it. ✅
If the function returns nothing, you return None, which is harmless. ✅

You're safer either way.

💡

Making return result your reflex in every wrapper means you never have to think about it.

The Delivery Person Analogy

I find this mental model helpful:

Your wrapper function is a delivery person standing at a door. They knock (call the original function), and the person inside either hands them a package (return value) or just waves hello (no return value).

If the delivery person always takes whatever is offered and passes it along, the package arrives safely, and the wave is harmless. Everything works.
If the delivery person shouts out the package contents (print), the neighborhood hears it, but the actual recipient gets nothing. The package is "delivered" to the air.
If the delivery person ignores what's handed to them (no return), the package sits on the doorstep and rots. The recipient never knows it existed.

Always take the package. Always deliver it.

How This Affects Stacking Decorators

The print vs return distinction also explains a confusing behavior when you stack multiple decorators. Consider these two:

from functools import wraps

def shout(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return result.upper()          # transforms the RETURN VALUE
    return wrapper

def surround(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        print("-" * 20)                # SIDE EFFECT - escapes immediately
        result = func(*args, **kwargs)
        print("-" * 20)                # SIDE EFFECT - escapes immediately
        return result

shout works with the return values. surround works with side effect (print). Watch what happens when you stack them:

@shout
@surround
def greet(name):
    return f"Hello, {name}!"

print(greet("Moussa"))

You might expect:

--------------------
HELLO, MOUSSA!
--------------------

But what you actually get is:

--------------------
--------------------
HELLO, MOUSSA!

The dashes aren't surrounding anything. They appear back-to-back at the top, and the uppercase greeting appears separately at the bottom.

Here's why. When greet("Moussa") is called, shout's wrapper runs first (outer decorator runs first). It calls surround's wrapper, which prints the first line of dashes (side effect - immediately on screen), calls the original greet which returns "Hello, Moussa!" silently, prints the second line of dashes (another side effect - immediately on screen), and returns the string. Back in shout's wrapper, it receives the string and uppercases it to HELLO, MOUSSA!, then returns it. Finally your print() call in the main code displays it.

The key: between the two lines of dashes, the string was being passed around silently as a return value. No print() call happened for it between the dashes. The only things that printed between "calling surround's wrapper" and "surround's wrapper returning) were the two lines of dashes, back to back.

💡

The lesson: Decorators that transform values compose beautifully together. Decorators that use side effects like print() don't, because side effects escape the decorator chain immediately and can't be controlled by other decorators.

The fix is to make surround use return values instead:

def surround(func):
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return f"{'—' * 20}\n{result}\n{'—' * 20}"
    return wrapper

Now both decorators work with return values, and stacking produces the expected result regardless of order.

The Rules to Live By

print() sends a value to the screen. It's a one-way trip. The value is gone from the program.
return sends a value back to the caller. It stays in the program and can be used further.
In a decorator wrapper, always use result = func(*args, **kwargs) followed by return result. This is the universal safe pattern.
A decorator should be invisible. The caller shouldn't be able to tell the function is decorated. Don't change return types. Don't print inside the wrapper when you should be returning.
Decorators that work with return values stack well. Decorators that use side effects don't. Prefer return values when designing decorators meant for composition.
When in doubt, return. It's always safe.

What's Next?

In the next article, we'll tackle decorators that accept their own arguments, patterns like @repeat(3) and @retry(5). We'll also learn how to stack decorators effectively.

This is Part 2 of my Python Decorators series. Check out Part 1: Understanding Decorators From Scratch for the foundations, and stay tuned for Part 3 on advanced patterns.

How Python Handles Unknown Arguments: A Deep Dive into *args and **kwargs

Moussa Kalam AMZAT — Fri, 06 Mar 2026 13:14:08 GMT

If you've spent any time reading Python code, you've probably come across function signatures that look like this:

def some_function(*args, **kwargs):
    pass

And wondered, what are those asterisks doing there? What are *args and **kwargs? Why does every Python codebase seem to have them?

By the end of the article, you'll have a complete understanding of what they are, how they work, and more importantly why they exist. We'll build up from the problem they solve, through the mechanics, all the way to a real-world decorator you can use in your own projects.

Before We Begin: Two Types of Arguments

Python functions accepts two distinct types of arguments. Understanding the difference is essential before diving into *args and **kwargs.

Positional Arguments

A positional argument is passed by position. In other words, its meaning is determined by where it appears in the function call:

def create_user(name, age, city):
    print(f"{name}, {age}, {city}")

create_user("Moussa", 27, "Porto-Novo")
# Moussa, 27, Porto-Novo

Here, "Moussa" maps to name, 27 maps to age, and Porto-Novo maps to city, purely based on their order,

Swap them and the meaning changes entirely:

create_user("Porto-Novo", 27, "Moussa")
# Porto-Novo, 27, Moussa (WRONG)

Keyword Arguments

A keyword argument is a passed by name. You explicitly state which parameter receives which value, so order no longer matters:

create_user(city="Porto-Novo", name="Moussa", age=27)
# Moussa, 27, Porto-Novo (correct, despite different order)

The same function accepts both styles. Python handles they differently under the hook, and that distinction is exactly what *args and **kwargs are built on.

💡

Parameter is the variable name defined in the function signature. Argument is the actual value passed when calling the function.

def greet(name):   # 'name' is a PARAMETER
    print(name)

greet("Moussa")    # "Moussa" is an ARGUMENT

The Problem: Functions With Fixed Arguments

Let's start with something familiar. Here's a basic Python function:

def add(a, b):
    return a + b

print(add(1, 2))  # 3

This works perfectly, as long as you always have exactly two numbers to add. But what if you want to add three? Or five? Or you don't know in advance how many you'll have?

print(add(1, 2, 3))
# TypeError: add() takes 2 positional arguments but 3 were given

Python refuses. The function signature is a "contract": exactly two arguments. No more, no less.

You could try to work around it by writing separate functions:

def add_two(a, b):
    return a + b

def add_three(a, b, c):
    return a + b + c

But this obviously doesn't scale. You'd need a new function for every possible number of arguments. There has to be a better way. Don't you think so 😀? That's exactly what *args was designed to solve.

Part 1: `*args` - Collecting Unlimited Positional Arguments

Here's the solution:

def add(*args):
    return sum(args)

print(add(1, 2))           # 3
print(add(1, 2, 3))        # 6
print(add(1, 2, 3, 4, 5))  # 15

The * in the function signature tells Python: collect all positional arguments into a single tuple. Inside the function, args is just a regular tuple. You can iterate it, index it, pass it to sum(), or anything else you'd do with a normal tuple.

The `*` Is the Mechanism, Not the Name

This is important: the * is what does the work, not the word args. You can call it anything:

def add(*numbers):
    return sum(numbers)

def add(*values):
    return sum(values)

Both work identically. The name args is a widely adopted convention. You'll see it in almost every Python codebase, but it's just a name.

Mixing Fixed Arguments With `*args`

You can combine fixed arguments with args. The fixed ones must come first:

def greet(greeting, *names):
    for name in names:
        print(f"{greeting}, {name}!")

greet("Hello", "Fabien", "Yves", "John")
# Hello, Fabien!
# Hello, Yves!
# Hello, John!

greeting captures the first argument, and *names collects everything else into a tuple.

Common Mistake: Putting `*args` Before Fixed Arguments

def greet(*names, greeting):
    pass

greet("Alice", "Bob", "Hello")
# TypeError: greet() missing 1 required keyword-only argument: 'greeting'

When *args appears before a named parameter, that named parameter becomes keyword-only. As a result, it must be passed by name, not position. This is a common source of confusion. Keep fixed positional arguments before *args and you'll avoid it.

Mental Model

*args = "Pack all positional arguments into a tuple called args".

Part 2: `**kwargs` - Collecting Unlimited Keyword Arguments

Python functions also accept keyword arguments, arguments passed by name:

def create_user(name, age, city):
    print(f"{name}, {age}, {city}")

create_user(name="Moussa", age=27, city="Porto-Novo")

What if you don't know which keyword argument will be passed in advance? That's where **kwargs comes in:

def create_user(**kwargs):
    print(kwargs)

create_user(name="Moussa", age=27, city="Porto-Novo")
# {'name': 'Moussa', 'age': 27, 'city': 'Porto-Novo'}

The ** tells Python: collect all keyword arguments into a dictionary. The argument names become keys, and the values you pass become the dictionary values.

Inside the function, kwargs is just a regular dictionary:

def create_user(**kwargs):
    for key, value in kwargs.items():
        print(f"{key}: {value}")

create_user(name="Moussa", age=27, city="Porto-Novo")
# name: Moussa
# age: 27
# city: Porto-Novo

Accessing Specific Keys Safely

When you know which keys you're looking for, use .get() with a default value:

def create_server(**kwargs):
    host = kwargs.get("host", "localhost")
    port = kwargs.get("port", 8000)
    debug = kwargs.get("debug", False)
    print(f"Starting {host}:{port} | debug={debug}")

create_server(port=3000)
# Starting localhost:3000 | debug=False

💡

.get() safely returns the default value if a key is missing, rather than throwing a KeyError. Note that the default value is the second argument you pass to .get()

Mental Model

**kwargs = "Pack all keyword arguments into a dictionary called kwargs

Same pattern as *args, but with a different container:

*args: Positional arguments (tuple)
**kwargs: Keyword arguments (dict)

Part 3: The `*` Unpack Direction - and `**` at the Call Site

Here's the part that trips most people up: the * and ** operators work in both directions.

In a function definition, they pack arguments in
In a function call, they unpack a collection out

 def add(a, b, c):
    return a + b + c

numbers = [1, 2, 3]
print(add(*numbers))  # ✅ Unpacks the list into positional arguments → 6

details = {"a": 1, "b": 2, "c": 3}
print(add(**details))  # ✅ Unpacks the dict into keyword arguments → 6

The * doesn't care whether you give it a list or a tuple. It works on any iterable:

my_tuple = (1, 2, 3)
my_list = [1, 2, 3]

print(add(*my_tuple))  # ✅ 6
print(add(*my_list))   # ✅ 6

💡

An iterable is any object Python can loop over. Under the hook, it is simply an object that implements the __iter__(). method, which returns an iterator that yields values one at a time.

The ** operator only works on mappings (objects with key-value pairs). For example, a set has no keys, so Python has no idea which value maps to which argument:

my_set = {"Moussa", "Porto-Novo"}
some_function(**my_set)  # ❌ TypeError — sets have no keys

The Mental Model

Syntax	Where	What it does	Result
`*args`	Definition	Packs positional args	Tuple
`**kwargs`	Definition	Packs keyword args	Dict
`*iterable`	Call	Unpacks into positional args	Spread
`**dict`	Call	Unpacks into keyword args	Spread

Same symbol, opposite direction. Once you internalize the table above, the behavior becomes predictable everywhere you encounter it.

Part 4: Combining `*args` and `**kwargs`

You can use both in the same function. Python automatically routes each argument to the right place. No name (position) argument attached goes to args, name argument attached goes to kwargs:

def describe(*args, **kwargs):
    print("Positional:", args)
    print("Keyword:", kwargs)

describe(1, 2, 3, name="Moussa", city="Porto-Novo")
# Positional: (1, 2, 3)
# Keyword: {'name': 'Moussa', 'city': 'Porto-Novo'}

The Order Rule

When combining everything, Python enforces a strict order:

def func(fixed, *args, **kwargs):
    pass

Fixed positional arguments first
*args second
**kwargs last

Breaking this order produces an immediate SyntaxError and Python won't even run the file.

Empty Defaults

When no arguments are passed, *args and **kwargs don't become None. They become their empty defaults:

def safe_summary(*args, **kwargs):
    print(args)   # ()  ← empty tuple
    print(kwargs) # {}  ← empty dict

safe_summary()

This matters because code like for item in args still works safely with no arguments. None would crash it.

Part 5: The Wrapper Pattern - Where This Gets Powerful

The most important real-world use of *args and **kwargs I know is the wrapper pattern: forwarding arguments through a function without caring what they are.

Here is the code idea:

def log_call(func, *args, **kwargs):
    print(f"Calling {func.__name__}")
    result = func(*args, **kwargs)
    print(f"Done")
    return result

def add(a, b):
    return a + b

def greet(name, greeting="Hello"):
    return f"{greeting}, {name}!"

log_call(add, 1, 2)
log_call(greet, "Moussa", greeting="Hey")

log_call doesn't know or care what add or greet need. It collects everything with *args, **kwargs and passed it straight through. The structure is always the same:
Collect --> Do something --> Forward

Part 6: Building a Real Decorator

The wrapper pattern is the foundation of Python decorators. A decorator is a function that takes a function, wraps it with extra behavior, and returns the wrapped version.

💡

You can learn more about the concept of decorators in Python on my blog. I have a comprehensive series that teaches you everything from the ground up.

Here's a @timed decorator that measures how long any function takes to run:

import time

def timed(func):
    def wrapper(*args, **kwargs):
        start_time = time.time()
        result = func(*args, **kwargs)
        elapsed_time = (time.time() - start_tim) * 1000
        print(f"Ran {func.__name__} in ~{elapsed_time:.0f}ms")
        return result
    return wrapper

@timed
def slow_add(a, b):
    time.sleep(0.1)
    return a + b

@timed
def greet(name, greeting="Hello"):
    time.sleep(0.05)
    return f"{greeting}, {name}!"

result = slow_add(1, 2)
print(result)
# Ran slow_add in ~100ms
# 3

result = greet("Moussa", greeting="Hey")
print(result)
# Ran greet in ~50ms
# Hey, Moussa!

Notice that wrapper uses *args, and **kwargs to collect and forward arguments, making @timed reusable across any function regardless of its signature. This is exactly how decorators work in Flask and FastAPI.

Key Takeaways

*args collects unlimited positional arguments into a tuple
**kwargs collects unlimited keyword arguments into a dict
Inside the function, both are just normal Python data structures
The correct order is always: fixed -> *args -> **kwargs
Empty *args is () and empty **kwargs is {}, never None
* and ** work in both directions: packing in definitions, unpacking at call sites
The wrapper pattern: collect, act, forward is the foundation of decorators.

Once these rules are internalized, you'll recognize the pattern everywhere: in the standard library, in popular frameworks, and in well-written Python code across the ecosystem.

Thank you for reading 📖🙂.

Understanding Python Decorators From Scratch

Moussa Kalam AMZAT — Thu, 05 Mar 2026 09:30:52 GMT

If you've ever seen the @ symbol sitting on top of a Python function and wondered what sorcery that is, this article is for you.

Decorators are one of those Python concepts that look intimidating but are built on ideas you already know. The problem is that most tutorials jump straight to the syntax without building the mental model first. So you end up memorizing the pattern without truly understanding why it works.

Let's fix that. We're going to build up to decorators one concept at a time, and by the end, you'll be writing your own with confidence

Functions Are Objects: That Changes Everything

Here is the thing you need to internalize: in Python, a function is just an object. Like a string, like a number, like a list, you can store it in a variable, pass it around, and do whatever you want with it.

def say_hello():
    print("Hello!")

# Store the function in another variable (no parentheses!)
my_function = say_hello

# Both names point to the same function
say_hello() # Hello!
my_function() # Hello!

Notice something critical here: say_hello without parentheses is the function itself, the object. say_hello() with parentheses calls the function and gives you the result. This distinction matters for everything that follows.

Think of a recipe card. say_hello is the card itself. You can hand it to someone, photocopy it, pin it on a wall. say_hello() is you actually cooking the recipe.

You Can Pass a Function to Another Function

Since functions are objects, you can hand one to another function as an argument, just like you'd pass a string or a number.

def say_hello():
    print("Hello!")

def say_goodbye():
    print("Goodbye!")

def call_twice(func):
    func()
    func()

call_twice(say_hello)
# Hello!
# Hello!

call_twice(say_goodbye)
# Goodbye!
# Goodbye!

call_twice doesn't know or care about which function you give it. It just calls whatever arrives, twice. We're passing say_hello (the object), not say_hello() (the result).

This might feel strange if you're coming from another language, but it's one of Python's superpowers. Functions are first-class citizens. They can go anywhere any other value can go.

A Function Can Create and Return Another Function

This where things get interesting. A function can build a new function inside itself and give it back to you:

def make_greeter(name):
    def greeter():
        print(f"Hello, {name}!")
    return greeter

greet_moussa = make_greeter("Moussa")
greet_kalam = make_greeter("Kalam")

greet_moussa()  # Hello, Moussa!
greet_kalam()   # Hello, Kalam!

Each call to make_greeter creates a brand-new function that remembers the name it was created with. The inner function greeter holds onto the name variable even after make_greeter has finished executing.

This pattern is called closure, a function that remembers values from the scope where it was created. Closures are the engine that powers decorators, so make sure this concept clicks before moving on.

Combining the Pieces: Take a Function, Return a New One

Now let's combine everything. What if we write a function that takes a function as input and returns a new function as output?

def make_louder(func):
    def new_function():
        print("I'M ABOUT TO DO SOMETHING!")
        func()
        print("I'M DONE!")
    return new_function

def say_hello():
    print("Hello!")

louder_hello = make_louder(say_hello)

# The original still works normally
say_hello()
# Hello!

# The new version adds extra behavior
louder_hello()
# I'M ABOUT TO DO SOMETHING!
# Hello!
# I'M DONE!

Please read that carefully! make_louder received say_hello, wrapped it in extra behavior (printing before and after), and returned a brand new function. The original say_hello is untouched.

This is the entire idea behind decorators. Everything else is just syntax and polish.

Replacing the Original

Instead of keeping both the old and new versions, what if we replace say_hello with the wrapped version?

say_hello = make_louder(say_hello)

say_hello()
# I'M ABOUT TO DO SOMETHING!
# Hello!
# I'M DONE!

Look at this line: say_hello = make_louder(say_hello). We're saying: "take the old say_hello, wrap it and store the result back as say_hello."

Now whenever anyone calls say_hello(), they get the enhanced the version. And that one line is so common in Python that the language gives us a shortcut for it.

The `@` Symbol Is Just a Shortcut

def make_louder(func):
    def new_function():
        print("I'M ABOUT TO DO SOMETHING!")
        func()
        print("I'M DONE!")
    return new_function

@make_louder
def say_hello():
    print("Hello!")

say_hello()
# I'M ABOUT TO DO SOMETHING!
# Hello!
# I'M DONE!

@make_louder on top of say_hello is exactly identical to writing say_hello = make_louder(say_hello) after the function definition. It's just cleaner syntax, what Python calls "syntactic sugar".

That's literally all the @ symbol does. No magic. No special mechanism. Just a shortcut for a pattern we already understand.

make_louder is a decorator.

The Arguments Problem

There's a catch with our current approach. What if the decorated function takes arguments?

def log_calls(func):
    def wrapper():          # takes NO arguments!
        print(f"Calling {func.__name__}")
        func()              # passes NO arguments!
    return wrapper

@log_calls
def add(a, b):
    return a + b

add(2, 3)  # TypeError: wrapper() takes 0 arguments but 2 were given

It breaks because add(2, 3) now actually calls wrapper(2, 3), but wrapper doesn't accept any arguments.

The fix is *args and **kwargs.
You've probably seen these before, but here's what they actually do:

*args lets a function accept any number of positional arguments. It packs them into a tuple.
**kwargs does the same for keyword arguments. It packs them into a dictionary.

You can read more *args and **kwargs in this article I wrote.

Put them together in the wrapper, and it can accept literally any combination of arguments and pass them straight through to the original function. It doesn't need to know what the function expects. It just forwards everything.

def log_calls(func):
    def wrapper(*args, **kwargs):         # accept anything
        print(f"Calling {func.__name__}")
        result = func(*args, **kwargs)    # forward everything
        return result                     # return the result
    return wrapper

@log_calls
def add(a, b):
    return a + b

@log_calls
def greet(name, greeting="Hello"):
    return f"{greeting}, {name}!"

print(add(2, 3))                          # Calling add → 5
print(greet("Moussa", greeting="Hey"))    # Calling greet → Hey, Moussa!

By using *args and **kwargs, the wrapper doesn't need to know anything about the original function's signature. It catches everything and forwards it blindly. This is what makes the decorator generic, working with any function.

A Practical Example: Logging

Let's see why this pattern is actually useful. Imagine you want to log every time certain functions are called:

def log_calls(func):
    def wrapper(*args, **kwargs):
        print(f">>> Calling {func.__name__}()")
        result = func(*args, **kwargs)
        print(f">>> {func.__name__}() finished")
        return result
    return wrapper

@log_calls
def process_payment():
    print("Payment processed!")

@log_calls
def send_email():
    print("Email sent!")

@log_calls
def update_database():
    print("Database updated!")

💡

Call each of the decorated functions, and analyze the results.

You wrote the logging logic once and applied it to three functions. Without decorators, you'd have to copy and paste those print statement into every single function. And when you want to change the log format, you change it in one place instead of hunting through your entire codebase.

The Universal Template

Every decorator follows the same recipe:

def my_decorator(func):            # 1. Take a function in
    def wrapper(*args, **kwargs):   # 2. Create a new function
        # do something before
        result = func(*args, **kwargs)  # 3. Call the original
        # do something after
        return result               # 4. Return the result
    return wrapper                  # 5. Return the wrapper

@my_decorator                      # 6. Replace the original
def my_function():
    pass

💡

That's the pattern. Memorize it now that you understand the idea behind it. Once this clicks, you can write any decorator by just filling in the before and after parts.

One Last Best Practice: `functools.wraps`

When you wrap a function, the wrapper replaces the original's metadata: its name, docstring, and other attributes. This can cause confusion during debugging.

@log_calls
def add(a, b):
    """Add two numbers.""" # Here is the docstring
    return a + b

print(add.__name__)  # "wrapper" — not "add"!
print(add.__doc__)  # None — the docstring is gone!

Fix this with functools.wraps

from functools import wraps


def log_calls(func):
    @wraps(func)  # preserves func's name, docstring, etc.
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__}")
        result = func(*args, **kwargs)
        return result
    return wrapper


@log_calls
def add(a, b):
    """Add two numbers.""" # Here is the docstring
    return a + b

print(add.__name__)  # add
print(add.__doc__)  # Add two numbers.

💡

I'd advise you always use @wraps. It's a one-line addition that prevents real headaches down the road.

What's Next?

You now understand the complete foundation of Python decorators. In the next article, we'll tackle a subtle but critical trap that catches almost every developer learning decorators: the difference between print and return inside wrappers, and why confusing them makes your values silently disappear.

This is Part 1 of my Python Decorators series. Follow along for the next parts where we cover the print vs return trap, decorators with arguments, stacking, and practice exercises.

Welcome to Build, Break, Learn

Moussa Kalam AMZAT — Tue, 03 Mar 2026 22:19:04 GMT

If you're reading this, you're probably a developer, or becoming one.
Either way, welcome. I'm glad you're here 🙂.

I'm Moussa Kalam AMZAT, a proud citizen of the Benin Republic 🇧🇯.
I'm a Software Engineer with 2+ years of work experience based in Kigali, Rwanda, and this blog is something I should have started a long time ago.
Let me tell you why.

The long road here

My journey into tech didn't start with a computer science degree. It started with Diplomacy and International Relations. That's what I studied. That's the career I was building. And for a while, that was the plan.

But somewhere along the way, I feel in love with learning autonomously and building things. Not policy frameworks, actual systems that solve real problems. So I made a decision that scared me: I broke away from everything I knew and started over in tech. From ZERO.

So I went all in. I enrolled in a BSc. (Honors) in Software Engineering, graduated in June 2025, and taught myself everything I could alongside it: YouTube tutorials, documentation, online courses, bootcamps, and a stubborn refusal to give up.

That journey, building something, breaking away from it and learning through the process, is exactly why this blog is called Build, Break, Learn. It's not just catchy name. It's the cycle that defines how I got here, and it's how I approach every new thing I learn as a developer: I build it, I break it, I figure out why, and I come out the other side understanding it at a level I couldn't have reached by just reading about it.

Why this blog exists

For years, every time I learned something new, I documented it. Detailed notes, step-by-step breakdowns, real examples, the works. But I never shared any of it. I figured everything was already on the internet. Someone smarter had already explained it better. Why bother?

Then a colleague of mine, Fabien Ishimwe, asked me a question I couldn't answer: "You document everything you learned. You are great at explaining what you know. Why are you keeping all that to yourself?"

He was right. So here I am.

Who is this blog for

I write for developers who want to actually understand what they're using, not just copy-paste code and hope it works.

If you've ever stared at a tutorial and thought "Okay, but why does this work?", this blog is for you.

If you're starting out and most resources feel like they're written for people who already know the thing they're trying to learn, this blog is for you.

I especially write with aspiring developers and students in mind, because I believe we deserve technical content that is practical, clear, and doesn't assume we all had the same starting point.

How I write

I have a few principles that shape every article on this blog:

I put myself in your shoes: I mainly write about things that took me time to understand. If something confused me, I assume it'll confuse someone else too. So I take the time to break it down the way I wish someone had broken it down for me.
I explain the why, not just the how: I'm not interested in showing you how to use something without helping you understand why it works. I want you to see what's happening underneath, how the pieces connect, and what's actually going on when you run that code.
I keep it digestible: No 45-min reads. I organize topics into short series so you can learn at your own pace without feeling overwhelmed. Each article is a small, focused step forward.
I write like we're talking: No academic tone. No unnecessary jargon. Just a clear, honest conversation between two people who care about getting better at this craft.

What I'll be covering

This blog will span everything I'm learning and building as a developer:

Full-stack web development: TypeScript, React, Next.js, and the frameworks and tools I use every day.
Python: From the fundamentals to more advanced patterns.
AI and Data: I'm investing deeply into this space and I'll be documenting as I go.
Authentication and databases: Real-world patterns using the best and recommended tools out there.
Developer Life: Career switches, learning strategies, and the things nobody tells you when you're starting out.

💡

New articles will be dropping 1 - 2 times a week, organized into series so you can follow along at your own pace.

A personal note

If you're someone who's just getting started in tech, or if you've ever felt like you don't have the "right" background to be a developer, I want you to know that I get it. I've been there. I studied diplomacy and international relations. I learned English on my own through the internet and English communities in Benin, a country that primarily speaks French, and then switched careers in a way that baffled many people I knew.

And here I am, writing to you as a Software Engineer.

The path doesn't have to be straight. It just has to keep moving. Some moves are so decisive that they don't need constant motion to matter. Build, break, learn and repeat.

I'm glad you're here. Let's learn together

-- Moussa Kalam AMZAT

Add value and get rewarded ❤️

Build, Break, Learn

Generator Functions in Python: How to Pause a Function Mid-Execution

The Problem Generators Solve

What yield Actually Does

StopIteration - How Generators Signal "Done"

Generators Are Lazy

Generators Remember Their State

Generator Expressions

When to Use Each

Real-World Usage 1: Reading Large Files

Real-World Usage 2: Infinite Sequences

The JavaScript Parallel

What You Can't Do with a Generator

The Bridge to Context Managers

The Mental Model to Take Away

Acronyms Used in This Article

The with Statement and open() in Depth

The with Statement: Clean Resource Management

Anatomy of the with Statement

Proving the Guarantee Holds on Error

The JavaScript Parallel

Deep Dive: open()

What open() Actually Does

The Full Signature

Parameter 1: file - What to Open

Parameter 2: mode - What You Intend to Do

The Mode That Silently Destroys Your Data

Parameter 3: encoding - Always Specify It

Reading and Writing: The Core Methods

Reading

Writing

The File Cursor

Why open() Is a Context Manager

Quick Reference

The Mental Model to Take Away

Why Python Makes you "Close" Things (And What Happens When You Don't)

Your Program Borrows Things from the OS

The Leak You Don't See Coming

It's Not Just Files

The Data Corruption You Don't Expect

Won't the Garbage Collector Handle It?

The Manual Fix, And Why It's Not Enough

There Is a Better Way

The Mental Model to Take Away

Acronyms Used in This Article

Class-Based Python Decorators: When Functions Aren't Enough

A Quick Prerequisite: __call__

Your First Class-Based Decorator

Why Bother? The State Problem

Adding Methods to Your Decorators

Class-Based Decorators with Arguments

Practical Example: A Rate Limiter

Practice Example: A Retry with Exponential Backoff

When to Use Function-Based vs Class-Based

A Note on functools.wraps

The Mental Model

What's Next?

10 Exercises to Master Python Decorators (With Solutions)

Exercise 1: Functions as Objects

Advanced Python Decorators Patterns: Arguments and Stacking

The Problem with Simple Decorators

Your First Instinct Is Wrong (And That's OK)

Understanding What @repeat(3) Actually Does

Building It Step by Step

Let's Trace Through the Execution

Practical Example: A Retry Decorator

Practical Example: Role-Based Access Control

The Pattern to Remember

Stacking Decorators

When Stacking Works Well

When Stacking Gets Tricky

Common Decorator Patterns in the Wild

What's Next?

The Print vs Return Trap That Silently Breaks Your Python Decorators

The Difference That Changes Everything

Why This Breaks Decorators

Mistake 1: Forgetting to Return

Mistake 2: Printing Instead of Returning

Mistake 3: Returning Formatted Strings Instead of Raw Values

The Correct Pattern

What `yield` Actually Does

`StopIteration` - How Generators Signal "Done"

The `with` Statement: Clean Resource Management

Anatomy of the `with` Statement

Deep Dive: `open()`

What `open()` Actually Does

Parameter 1: `file` - What to Open

Parameter 2: `mode` - What You Intend to Do

Parameter 3: `encoding` - Always Specify It

Why `open()` Is a Context Manager

A Quick Prerequisite: `call`

A Note on `functools.wraps`

Understanding What `@repeat(3)` Actually Does

Part 1: `*args` - Collecting Unlimited Positional Arguments

The `*` Is the Mechanism, Not the Name

Mixing Fixed Arguments With `*args`

Common Mistake: Putting `*args` Before Fixed Arguments

Part 2: `**kwargs` - Collecting Unlimited Keyword Arguments

Part 3: The `*` Unpack Direction - and `**` at the Call Site

Part 4: Combining `*args` and `**kwargs`

The `@` Symbol Is Just a Shortcut

One Last Best Practice: `functools.wraps`