Historical Context & Motivation
When programmers write functions, they often want some parameters to have a "standard" value that kicks in when the caller doesn't supply one. Before languages supported default arguments, developers had to write repetitive code that checked whether each value was provided and then manually assigned fallbacks. This was tedious, error-prone, and cluttered the logic of the function itself.
The idea of letting the function signature declare a fallback value dates back to early programming languages, but Python's approach—introduced right from version 1.0 in 1994—brought both elegance and a famous trap. Because Python evaluates default values only once, at the moment the function is defined rather than each time it is called, mutable defaults like lists and dictionaries can behave in surprising ways. Understanding this quirk is a rite of passage for every Python programmer.
So the central question this lesson addresses is: How do default arguments work under the hood, and what happens when the default value is something that can change—like a list?
Core Principles & Definitions
Before diving into code, you need to grasp a handful of foundational ideas. A default argument is a value you assign to a parameter in the function definition itself, using an equals sign. When the caller omits that argument, the default kicks in automatically. Meanwhile, an immutable object is something that cannot be changed after creation (like a number, string, or tuple), whereas a mutable object can be modified in place (like a list, dictionary, or set).
Default Argument
def greet(name="World"). If no name is passed, the function uses "World".Definition-Time Evaluation
def statement runs, not each time the function is called.Mutable vs. Immutable
The None Sentinel Pattern
None, then create a fresh mutable object inside the function body if the argument is None.None as the sticky note and hand out a new notebook inside the function.Visual Explanation — How Defaults Are Stored
The diagram below illustrates what happens in memory when Python processes a def statement with a mutable default. Notice that the default list object is created once and stored inside the function object. Every subsequent call that relies on the default points to the exact same list.
__defaults__ tuple holds a single list object. Call 1 appends 'a' to it; Call 2 finds ['a'] already there and appends 'b'. The result is ['a', 'b']—not ['b'] as you might expect.This is the crux of the mutable default pitfall. The diagram makes it clear that the list is not recreated on each call—it's a single object that persists for the lifetime of the function. If the default were an immutable value like 0 or "hello", this wouldn't matter because you can't modify those objects in place.
How Python Handles Defaults Under the Hood
The def Statement Is Executable
In Python, def is not just a declaration—it's an executable statement. When the interpreter reaches a def line, it creates a new function object and evaluates all default-value expressions immediately. The resulting objects are stored in a tuple attached to the function as the attribute __defaults__. This happens exactly once, no matter how many times the function is later called.
Step-by-Step Evaluation Flow
- Step 1 — Encounter
def: Python reads the function header and evaluates each default expression left-to-right. - Step 2 — Store defaults: The evaluated objects are packed into
func.__defaults__. - Step 3 — Call without argument: Python looks up the corresponding default from
__defaults__and binds it to the parameter name. - Step 4 — Mutate?: If the function modifies the default object in place (e.g.,
lst.append(x)), the change persists across future calls.
Inspecting Defaults in the REPL
You can actually see the stored defaults at any time. After defining a function like def f(x, items=[]): and calling f.__defaults__ you'll get ([],) the first time, and if you call f(5) a few times while the function appends to items, you'll see the list growing inside __defaults__. This makes the behavior concrete and observable.
None as a sentinel when you want a fresh mutable object each time.Safe vs. Unsafe Default Types
Not every default is dangerous. The key question is whether the default object can be modified in place. The following diagram groups Python's common types into safe (immutable) and unsafe (mutable) categories, along with the recommended fix for each unsafe type.
| Type | Mutable? | Safe as Default? | Recommended Default |
|---|---|---|---|
int, float, bool | No | ✓ Yes | Use directly, e.g. 0, 1.0 |
str | No | ✓ Yes | Use directly, e.g. "hello" |
tuple, frozenset | No | ✓ Yes | Use directly |
list | Yes | ✗ No | Use None, create inside |
dict | Yes | ✗ No | Use None, create inside |
set | Yes | ✗ No | Use None, create inside |
Worked Example — The Bug and The Fix
Let's walk through a realistic example. Imagine you're building a simple logging system where a function collects messages into a list.
def log(msg, messages=[]): followed by messages.append(msg) and return messages. The empty list [] is evaluated once when Python processes the def statement.log("Error A"). Since we didn't pass messages, Python binds it to the default list. The function appends "Error A" and returns the list.["Error A"] ← looks correct!log("Error B"). Again, messages binds to the same default list—which already contains "Error A" from the previous call. After appending, the list now has both items.["Error A", "Error B"] ← BUG! We expected ["Error B"]def log(msg, messages=None): then inside the body: if messages is None: messages = []. Now each call that doesn't pass messages gets a brand-new empty list.log("Error A") returns ["Error A"]. Calling log("Error B") now returns ["Error B"]. Each call starts fresh, and callers who pass their own list still get the expected behavior.Strengths, Pitfalls, and Trade-offs
Default arguments are one of Python's most convenient features, but they come with trade-offs. The table below lays out the advantages alongside the common pitfalls so you can use defaults confidently.
| Strengths | Pitfalls |
|---|---|
| Simplify function calls — callers can skip arguments that usually stay the same. | Mutable defaults (list, dict, set) are shared across calls, leading to unexpected data leakage. |
| Make APIs self-documenting — the signature shows what the "normal" values are. | Definition-time evaluation can surprise beginners who expect call-time evaluation. |
| Allow one function to serve many use cases without overloading. | Overusing defaults can make function signatures hard to read if there are many parameters. |
| The None sentinel pattern is easy to learn and universally understood. | Forgetting the is None check leads to subtle bugs that may only appear after many calls. |
None to give each caller their own brand-new charger. In practice, this means any time your default is [], {}, or set(), replace it with None and initialize inside the function.Connection to Advanced Concepts
The mutable default pattern is your first encounter with a broader theme in Python: objects vs. names. In Python, variables are labels that point to objects, not boxes that contain values. Understanding this distinction prepares you for more advanced topics like closures, decorators, and class-level attributes.
| This Lesson | Advanced Concept |
|---|---|
| Default arguments evaluated at definition time | Closures — inner functions capture variables from their enclosing scope at definition time, a similar "snapshot" idea. |
| Using None as a sentinel | Sentinel objects — libraries sometimes create custom sentinel objects (e.g., _MISSING = object()) for more nuanced defaults. |
| Shared mutable state across calls | Class attributes vs. instance attributes — a class-level list is shared by all instances, the same pattern as a mutable default. |
| Immutable defaults are safe | Functional programming — favoring immutable data eliminates a whole class of bugs, a principle you'll see in languages like Haskell and Rust. |
As you progress, you'll also encounter type hints (e.g., def f(items: list[int] | None = None) -> list[int]:) that make the None-sentinel pattern even clearer to readers and to static analysis tools like mypy. For now, the core skill is recognizing when a default is mutable and applying the fix.
Practice Problems
def add_score(score, scores=[]):
scores.append(score)
return scores
What does add_score(10) return the first time? What does add_score(20) return the second time? Explain why.def register_student(name, roster=[]):
roster.append(name)
return roster
Your fixed version should return a list containing only the current call's student when no roster is provided, yet still accept an existing roster if one is passed.def create_profile(username, settings={}):
settings['theme'] = settings.get('theme', 'light')
return {'user': username, 'settings': settings}
A tester calls create_profile('Alice') and then create_profile('Bob'). Describe the bug that occurs and write a corrected version.def fibonacci(n, cache={}):
if n in cache:
return cache[n]
if n <= 1:
return n
result = fibonacci(n-1, cache) + fibonacci(n-2, cache)
cache[n] = result
return result
Explain how this function uses the mutable default intentionally and why it makes the function faster. When would this approach be appropriate, and when should you avoid it?Lesson Summary
Default arguments let you assign fallback values to function parameters so that callers can omit arguments that usually stay the same. Python evaluates these defaults once at definition time and stores them in the function's __defaults__ attribute. When the default is an immutable type (int, str, tuple, None, bool), this is perfectly safe. When the default is a mutable type (list, dict, set), all calls that rely on the default share the same object, leading to the infamous mutable default pitfall.
The standard fix is the None sentinel pattern: set the default to None and create a fresh mutable object inside the function body with if param is None: param = []. This ensures each call gets its own independent object. As you advance, you'll see this pattern echoed in closures, class attributes, and type hints—making it one of the most important Python fundamentals to master early.