Default vs Keyword Arguments & The Mutable Default Trap0%

Default vs Keyword Arguments & The Mutable Default Trap

Intermediate14 min read•Updated: 2026-10-01

Default vs Keyword Arguments & The Mutable Default Trap

In Python, function parameters can be supplied with default values to make arguments optional. While intuitive at first glance, parameter evaluation in Python operates under a crucial architectural mechanism that catches even experienced engineers off-guard: Default arguments are evaluated exactly once at definition time (when the function is first loaded into memory), NOT every time the function is called.

This mechanism leads to one of Python's most notorious bugs: the Mutable Default Argument Trap. In this lesson, you will master function parameter mechanics, inspect __defaults__ in memory, implement the None sentinel pattern, and utilize positional-only (/) and keyword-only (*) markers.

Real-World Analogy: The Shared Office Chai Thermos

Imagine a shared community chai thermos in a busy Indian office pantry:

Visual Architecture Blueprint

+-------------------------------------------------------------------------+
|                  THE SHARED OFFICE CHAI THERMOS ANALOGY                 |
+-------------------------------------------------------------------------+
|                                                                         |
|  The Mutable Trap: def pour_chai(cup, tray=[]):                         |
|  ──> Python creates ONE single physical tray in RAM at compile time!    |
|                                                                         |
|  Employee 1 (Aman): Calls pour_chai("Masala Chai")                      |
|  ──> Puts cup on the shared tray: ['Masala Chai']                       |
|                                                                         |
|  Employee 2 (Priya): Calls pour_chai("Ginger Tea")                      |
|  ──> Expects a fresh tray, but receives Aman's leftover tray!           |
|  ──> Tray now holds: ['Masala Chai', 'Ginger Tea'] (Data Leakage!)      |
|                                                                         |
|  The Sentinel Fix: def pour_chai(cup, tray=None):                       |
|  ──> if tray is None: tray = []                                         |
|  ──> Every employee gets their own fresh, private, clean tray!          |
|                                                                         |
+-------------------------------------------------------------------------+

When you write tray=[] in the def header, Python binds a single list in heap memory when the file is imported. Every call that omits the parameter mutates that exact same list object.

Under the Hood: The `defaults` Tuple

To understand why this occurs, inspect the function object's internal attribute __defaults__:

1def add_item(item, basket=[]):
2    basket.append(item)
3    return basket
4 
5# Python stores the default value in the function object itself!
6print(add_item.__defaults__)  # ([],)
7 
8add_item("Apple")
9print(add_item.__defaults__)  # (['Apple'],) <-- Mutated in-place!
10 
11add_item("Banana")
12print(add_item.__defaults__)  # (['Apple', 'Banana'],) <-- Persists!

Because Python functions are first-class objects created when the def statement executes, the default value expression is evaluated once and attached to func.__defaults__.

The Gold-Standard Sentinel Pattern

To safely supply a fresh mutable container (list, dictionary, set) on every call, use None as the default argument:

Visual Architecture Blueprint

+------------------------------------+------------------------------------+
|  Anti-Pattern (Dangerous Mutation) |  Gold-Standard (Sentinel Pattern)  |
+------------------------------------+------------------------------------+
|  def log_event(msg, events=[]):    |  def log_event(msg, events=None):  |
|      events.append(msg)            |      if events is None:            |
|      return events                 |          events = []  # Fresh!     |
|                                    |      events.append(msg)            |
|                                    |      return events                 |
+------------------------------------+------------------------------------+

Comprehensive Code Examples

1. The Mutable Default Trap Demonstrated and Fixed

1# ANTI-PATTERN: Shared mutable list
2def append_student_bad(name, roster=[]):
3    roster.append(name)
4    return roster
5 
6print("--- Bad Pattern (Shared Mutation) ---")
7batch1 = append_student_bad("Aarav")
8print("Batch 1:", batch1)
9 
10batch2 = append_student_bad("Sneha")  # Expected only ['Sneha']!
11print("Batch 2:", batch2)  # Sneha received Aarav's data!
12 
13# GOLD STANDARD: Sentinel Pattern
14def append_student_good(name, roster=None):
15    if roster is None:
16        roster = []  # Fresh list allocated in RAM per invocation
17    roster.append(name)
18    return roster
19 
20print("\n--- Gold Standard (Isolated Invocations) ---")
21fresh_batch1 = append_student_good("Aarav")
22print("Fresh Batch 1:", fresh_batch1)
23 
24fresh_batch2 = append_student_good("Sneha")
25print("Fresh Batch 2:", fresh_batch2)  # Clean and isolated!

Expected Output:

1--- Bad Pattern (Shared Mutation) ---
2Batch 1: ['Aarav']
3Batch 2: ['Aarav', 'Sneha']
4 
5--- Gold Standard (Isolated Invocations) ---
6Fresh Batch 1: ['Aarav']
7Fresh Batch 2: ['Sneha']

2. Positional-Only (`/`) vs Keyword-Only (`*`) Parameters

Introduced in Python 3.8 (PEP 570), the forward slash / indicates that parameters before it are positional-only, while the asterisk * indicates that parameters after it are keyword-only:

Visual Architecture & Process Flow

How data and code flow step-by-step

Flowchart

Step 1

Step 2

TypeError: configure_server() got some positional-only arguments passed as keyword arguments: 'ip_address, port'

Expected Output:

1Configured Server: {'address': 'http://192.168.1.1:8080', 'timeout': 60, 'debug': True}

3. Dynamic Default Evaluation (The Datetime Trap)

Another classic pitfall is calling a function like datetime.now() in the parameter definition:

1from datetime import datetime
2import time
3 
4# ANTI-PATTERN: Evaluates datetime.now() once when the module imports!
5def log_transaction_bad(txn_id, created_at=datetime.now()):
6    return f"TXN {txn_id} stamped at {created_at.strftime('%H:%M:%S')}"
7 
8# GOLD STANDARD: Evaluates datetime.now() inside the function at call time!
9def log_transaction_good(txn_id, created_at=None):
10    if created_at is None:
11        created_at = datetime.now()
12    return f"TXN {txn_id} stamped at {created_at.strftime('%H:%M:%S')}"
13 
14t1 = log_transaction_good("101")
15print(t1)
16 
17time.sleep(1)  # Wait 1 second
18 
19t2 = log_transaction_good("102")
20print(t2)  # Notice the timestamp updates accurately!

Expected Output:

1TXN 101 stamped at 15:04:47
2TXN 102 stamped at 15:04:48

Best Practices & Comparison: Do's and Don'ts

Practice	Dangerous Anti-Pattern	Recommended Gold Standard
Mutable Defaults	`def fn(data=[]):`	`def fn(data=None): if data is None: data = []`
Dict Defaults	`def config(options={}):`	`def config(options=None): if options is None: options = {}`
Timestamps	`def stamp(time=datetime.now()):`	`def stamp(time=None): if time is None: time = datetime.now()`
API Parameter Locks	Exposing internal variable names blindly	Use `/` for positional-only to safely rename parameters later
Flags & Booleans	`def process(x, False, True):` (Cryptic!)	`def process(x, *, dry_run=False, verbose=True):` (Clear!)

Quick Revision Summary Cheat Sheet

Definition-Time Evaluation: Default argument expressions execute once when the function is defined, not per call.
The Mutable Trap: Using [], {}, or set() as defaults leads to state sharing across independent invocations.
The Sentinel Idiom: Set parameter to None, then instantiate val = [] or val = {} inside the function body.
Positional-Only (/): Parameters to the left of / cannot be called via name=val.
*Keyword-Only (`):** Parameters to the right of * must be specified explicitly via name=val`.

Practice Challenge

Scenario: Safe Multi-Tenant Banking Transaction Logger

A banking system in Mumbai records customer transactions. A junior developer wrote the following flawed function:

1def record_transaction(account_id, amount, txn_type="Credit", audit_log=[]):
2    audit_log.append(f"{txn_type} ₹{amount} for {account_id}")
3    return audit_log

Because of the mutable default argument trap, transactions from different bank customers are leaking into each other's audit logs!

Your task:

1
Refactor record_transaction using the Sentinel Pattern (audit_log=None).
2
Add positional-only constraints so that account_id and amount must be passed positionally.
3
Add a keyword-only constraint so that txn_type must be passed as a keyword argument (*, txn_type="Credit").
4
Demonstrate that two independent transactions for different customers maintain completely separate, isolated audit logs.

Starter Code

1# Refactor this flawed implementation
2def record_transaction(account_id, amount, txn_type="Credit", audit_log=[]):
3    audit_log.append(f"{txn_type} ₹{amount} for {account_id}")
4    return audit_log

Complete Solution

1# Refactored Gold-Standard Implementation
2def record_transaction(account_id, amount, /, *, txn_type="Credit", audit_log=None):
3    # Sentinel pattern: guarantee fresh list per call
4    if audit_log is None:
5        audit_log = []
6    
7    entry = f"{txn_type.upper()} of ₹{amount:,.2f} on Account [{account_id}]"
8    audit_log.append(entry)
9    return audit_log
10 
11# Test customer 1: Aarav
12aarav_log = record_transaction("SBIN-101", 5000.0, txn_type="Credit")
13print("Aarav's Initial Log:", aarav_log)
14 
15# Test customer 2: Priya (Must NOT contain Aarav's transaction!)
16priya_log = record_transaction("HDFC-999", 12500.0, txn_type="Debit")
17print("Priya's Private Log:", priya_log)
18 
19# Append subsequent transaction to Aarav's existing log explicitly
20record_transaction("SBIN-101", 1200.0, txn_type="Debit", audit_log=aarav_log)
21print("Aarav's Updated Log:", aarav_log)

Expected Output

1Aarav's Initial Log: ['CREDIT of ₹5,000.00 on Account [SBIN-101]']
2Priya's Private Log: ['DEBIT of ₹12,500.00 on Account [HDFC-999]']
3Aarav's Updated Log: ['CREDIT of ₹5,000.00 on Account [SBIN-101]', 'DEBIT of ₹1,200.00 on Account [SBIN-101]']

Interactive Quiz• Knowledge Check

Practice Quiz

Question 1

When is a default argument expression like def func(x=[]): evaluated in Python?

Question 2

What is the output of the following code snippet?

PythonCode Snippet

def add(item, box=[]):

box.append(item)

return len(box)

print(add(1), add(2), add(3))

Question 3

What is the recommended idiom to avoid the mutable default argument trap?

Question 4

Given def calculate(a, b, /, c, *, d):, how can argument 'a' be passed?

Question 5

Why should datetime.now() NOT be written directly as a default argument: def create_record(timestamp=datetime.now())?

🚀 What's Next?

In the next lesson, we will continue your intermediate Python journey with Closures (2: Functions Deep Dive).

👉 Continue to Next Lesson: Closures →

Next Lesson

Closures

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous Lesson	Next Lesson
Arguments Recap (args, *kwargs)	Closures

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

Previous Next

PreviousPrevNext

MSK Institute • Shikohabad

Loading Page Content...

Preparing courses, live labs, and learning resources.सामग्री लोड हो रही है, कृपया प्रतीक्षा करें...

Connecting serverPlease wait...

💻 Practical Labs🚀 Free Demo📜 Verified Certificates

Closures

Default vs Keyword Arguments & The Mutable Default Trap

Intermediate14 min read•Updated: 2026-10-01

Study Materials Cheatsheet

Default vs Keyword Arguments & The Mutable Default Trap

Real-World Analogy: The Shared Office Chai Thermos

Imagine a shared community chai thermos in a busy Indian office pantry:

Visual Architecture Blueprint

+-------------------------------------------------------------------------+
|                  THE SHARED OFFICE CHAI THERMOS ANALOGY                 |
+-------------------------------------------------------------------------+
|                                                                         |
|  The Mutable Trap: def pour_chai(cup, tray=[]):                         |
|  ──> Python creates ONE single physical tray in RAM at compile time!    |
|                                                                         |
|  Employee 1 (Aman): Calls pour_chai("Masala Chai")                      |
|  ──> Puts cup on the shared tray: ['Masala Chai']                       |
|                                                                         |
|  Employee 2 (Priya): Calls pour_chai("Ginger Tea")                      |
|  ──> Expects a fresh tray, but receives Aman's leftover tray!           |
|  ──> Tray now holds: ['Masala Chai', 'Ginger Tea'] (Data Leakage!)      |
|                                                                         |
|  The Sentinel Fix: def pour_chai(cup, tray=None):                       |
|  ──> if tray is None: tray = []                                         |
|  ──> Every employee gets their own fresh, private, clean tray!          |
|                                                                         |
+-------------------------------------------------------------------------+

When you write tray=[] in the def header, Python binds a single list in heap memory when the file is imported. Every call that omits the parameter mutates that exact same list object.

Under the Hood: The `defaults` Tuple

To understand why this occurs, inspect the function object's internal attribute __defaults__:

1def add_item(item, basket=[]):
2    basket.append(item)
3    return basket
4 
5# Python stores the default value in the function object itself!
6print(add_item.__defaults__)  # ([],)
7 
8add_item("Apple")
9print(add_item.__defaults__)  # (['Apple'],) <-- Mutated in-place!
10 
11add_item("Banana")
12print(add_item.__defaults__)  # (['Apple', 'Banana'],) <-- Persists!

Because Python functions are first-class objects created when the def statement executes, the default value expression is evaluated once and attached to func.__defaults__.

The Gold-Standard Sentinel Pattern

To safely supply a fresh mutable container (list, dictionary, set) on every call, use None as the default argument:

Visual Architecture Blueprint

+------------------------------------+------------------------------------+
|  Anti-Pattern (Dangerous Mutation) |  Gold-Standard (Sentinel Pattern)  |
+------------------------------------+------------------------------------+
|  def log_event(msg, events=[]):    |  def log_event(msg, events=None):  |
|      events.append(msg)            |      if events is None:            |
|      return events                 |          events = []  # Fresh!     |
|                                    |      events.append(msg)            |
|                                    |      return events                 |
+------------------------------------+------------------------------------+

Comprehensive Code Examples

1. The Mutable Default Trap Demonstrated and Fixed

1# ANTI-PATTERN: Shared mutable list
2def append_student_bad(name, roster=[]):
3    roster.append(name)
4    return roster
5 
6print("--- Bad Pattern (Shared Mutation) ---")
7batch1 = append_student_bad("Aarav")
8print("Batch 1:", batch1)
9 
10batch2 = append_student_bad("Sneha")  # Expected only ['Sneha']!
11print("Batch 2:", batch2)  # Sneha received Aarav's data!
12 
13# GOLD STANDARD: Sentinel Pattern
14def append_student_good(name, roster=None):
15    if roster is None:
16        roster = []  # Fresh list allocated in RAM per invocation
17    roster.append(name)
18    return roster
19 
20print("\n--- Gold Standard (Isolated Invocations) ---")
21fresh_batch1 = append_student_good("Aarav")
22print("Fresh Batch 1:", fresh_batch1)
23 
24fresh_batch2 = append_student_good("Sneha")
25print("Fresh Batch 2:", fresh_batch2)  # Clean and isolated!

Expected Output:

1--- Bad Pattern (Shared Mutation) ---
2Batch 1: ['Aarav']
3Batch 2: ['Aarav', 'Sneha']
4 
5--- Gold Standard (Isolated Invocations) ---
6Fresh Batch 1: ['Aarav']
7Fresh Batch 2: ['Sneha']

2. Positional-Only (`/`) vs Keyword-Only (`*`) Parameters

Introduced in Python 3.8 (PEP 570), the forward slash / indicates that parameters before it are positional-only, while the asterisk * indicates that parameters after it are keyword-only:

Visual Architecture & Process Flow

How data and code flow step-by-step

Flowchart

Step 1

Step 2

TypeError: configure_server() got some positional-only arguments passed as keyword arguments: 'ip_address, port'

Expected Output:

1Configured Server: {'address': 'http://192.168.1.1:8080', 'timeout': 60, 'debug': True}

3. Dynamic Default Evaluation (The Datetime Trap)

Another classic pitfall is calling a function like datetime.now() in the parameter definition:

1from datetime import datetime
2import time
3 
4# ANTI-PATTERN: Evaluates datetime.now() once when the module imports!
5def log_transaction_bad(txn_id, created_at=datetime.now()):
6    return f"TXN {txn_id} stamped at {created_at.strftime('%H:%M:%S')}"
7 
8# GOLD STANDARD: Evaluates datetime.now() inside the function at call time!
9def log_transaction_good(txn_id, created_at=None):
10    if created_at is None:
11        created_at = datetime.now()
12    return f"TXN {txn_id} stamped at {created_at.strftime('%H:%M:%S')}"
13 
14t1 = log_transaction_good("101")
15print(t1)
16 
17time.sleep(1)  # Wait 1 second
18 
19t2 = log_transaction_good("102")
20print(t2)  # Notice the timestamp updates accurately!

Expected Output:

1TXN 101 stamped at 15:04:47
2TXN 102 stamped at 15:04:48

Best Practices & Comparison: Do's and Don'ts

Practice	Dangerous Anti-Pattern	Recommended Gold Standard
Mutable Defaults	`def fn(data=[]):`	`def fn(data=None): if data is None: data = []`
Dict Defaults	`def config(options={}):`	`def config(options=None): if options is None: options = {}`
Timestamps	`def stamp(time=datetime.now()):`	`def stamp(time=None): if time is None: time = datetime.now()`
API Parameter Locks	Exposing internal variable names blindly	Use `/` for positional-only to safely rename parameters later
Flags & Booleans	`def process(x, False, True):` (Cryptic!)	`def process(x, *, dry_run=False, verbose=True):` (Clear!)

Quick Revision Summary Cheat Sheet

Definition-Time Evaluation: Default argument expressions execute once when the function is defined, not per call.
The Mutable Trap: Using [], {}, or set() as defaults leads to state sharing across independent invocations.
The Sentinel Idiom: Set parameter to None, then instantiate val = [] or val = {} inside the function body.
Positional-Only (/): Parameters to the left of / cannot be called via name=val.
*Keyword-Only (`):** Parameters to the right of * must be specified explicitly via name=val`.

Practice Challenge

Scenario: Safe Multi-Tenant Banking Transaction Logger

A banking system in Mumbai records customer transactions. A junior developer wrote the following flawed function:

1def record_transaction(account_id, amount, txn_type="Credit", audit_log=[]):
2    audit_log.append(f"{txn_type} ₹{amount} for {account_id}")
3    return audit_log

Because of the mutable default argument trap, transactions from different bank customers are leaking into each other's audit logs!

Your task:

1
Refactor record_transaction using the Sentinel Pattern (audit_log=None).
2
Add positional-only constraints so that account_id and amount must be passed positionally.
3
Add a keyword-only constraint so that txn_type must be passed as a keyword argument (*, txn_type="Credit").
4
Demonstrate that two independent transactions for different customers maintain completely separate, isolated audit logs.

Starter Code

1# Refactor this flawed implementation
2def record_transaction(account_id, amount, txn_type="Credit", audit_log=[]):
3    audit_log.append(f"{txn_type} ₹{amount} for {account_id}")
4    return audit_log

Complete Solution

1# Refactored Gold-Standard Implementation
2def record_transaction(account_id, amount, /, *, txn_type="Credit", audit_log=None):
3    # Sentinel pattern: guarantee fresh list per call
4    if audit_log is None:
5        audit_log = []
6    
7    entry = f"{txn_type.upper()} of ₹{amount:,.2f} on Account [{account_id}]"
8    audit_log.append(entry)
9    return audit_log
10 
11# Test customer 1: Aarav
12aarav_log = record_transaction("SBIN-101", 5000.0, txn_type="Credit")
13print("Aarav's Initial Log:", aarav_log)
14 
15# Test customer 2: Priya (Must NOT contain Aarav's transaction!)
16priya_log = record_transaction("HDFC-999", 12500.0, txn_type="Debit")
17print("Priya's Private Log:", priya_log)
18 
19# Append subsequent transaction to Aarav's existing log explicitly
20record_transaction("SBIN-101", 1200.0, txn_type="Debit", audit_log=aarav_log)
21print("Aarav's Updated Log:", aarav_log)

Expected Output

1Aarav's Initial Log: ['CREDIT of ₹5,000.00 on Account [SBIN-101]']
2Priya's Private Log: ['DEBIT of ₹12,500.00 on Account [HDFC-999]']
3Aarav's Updated Log: ['CREDIT of ₹5,000.00 on Account [SBIN-101]', 'DEBIT of ₹1,200.00 on Account [SBIN-101]']

Interactive Quiz• Knowledge Check

Practice Quiz

Question 1

When is a default argument expression like def func(x=[]): evaluated in Python?

Question 2

What is the output of the following code snippet?

PythonCode Snippet

def add(item, box=[]):

box.append(item)

return len(box)

print(add(1), add(2), add(3))

Question 3

What is the recommended idiom to avoid the mutable default argument trap?

Question 4

Given def calculate(a, b, /, c, *, d):, how can argument 'a' be passed?

Question 5

Why should datetime.now() NOT be written directly as a default argument: def create_record(timestamp=datetime.now())?

🚀 What's Next?

In the next lesson, we will continue your intermediate Python journey with Closures (2: Functions Deep Dive).

👉 Continue to Next Lesson: Closures →

Next Lesson

Closures

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous Lesson	Next Lesson
Arguments Recap (args, *kwargs)	Closures

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

Previous Next

Default vs Keyword Arguments & The Mutable Default Trap

Real-World Analogy: The Shared Office Chai Thermos

Under the Hood: The __defaults__ Tuple

The Gold-Standard Sentinel Pattern

Comprehensive Code Examples

1. The Mutable Default Trap Demonstrated and Fixed

2. Positional-Only (/) vs Keyword-Only (*) Parameters

Visual Architecture & Process Flow

3. Dynamic Default Evaluation (The Datetime Trap)

Best Practices & Comparison: Do's and Don'ts

Quick Revision Summary Cheat Sheet

Practice Challenge

Scenario: Safe Multi-Tenant Banking Transaction Logger

Starter Code

Complete Solution

Expected Output

Practice Quiz

🚀 What's Next?

Closures

Related Lessons

Practice Quiz

Loading Page Content...

Default vs Keyword Arguments & The Mutable Default Trap

Real-World Analogy: The Shared Office Chai Thermos

Under the Hood: The __defaults__ Tuple

The Gold-Standard Sentinel Pattern

Comprehensive Code Examples

1. The Mutable Default Trap Demonstrated and Fixed

2. Positional-Only (/) vs Keyword-Only (*) Parameters

Visual Architecture & Process Flow

3. Dynamic Default Evaluation (The Datetime Trap)

Best Practices & Comparison: Do's and Don'ts

Quick Revision Summary Cheat Sheet

Practice Challenge

Scenario: Safe Multi-Tenant Banking Transaction Logger

Starter Code

Complete Solution

Expected Output

Practice Quiz

🚀 What's Next?

Closures

Related Lessons

Practice Quiz

Under the Hood: The `defaults` Tuple

2. Positional-Only (`/`) vs Keyword-Only (`*`) Parameters

Under the Hood: The `defaults` Tuple

2. Positional-Only (`/`) vs Keyword-Only (`*`) Parameters