Python Default Argument Binding: The Principle of Least Astonishment and Mutable Object Pitfalls

Problem Phenomenon and Background

Many Python developers encounter a puzzling issue when working with mutable objects as default arguments: multiple calls produce unexpected cumulative effects. Consider this classic example:

def foo(a=[]):
    a.append(5)
    return a

Novices might expect each parameterless call to foo() to return [5], but the actual behavior differs significantly:

>>> foo()
[5]
>>> foo()
[5, 5]
>>> foo()
[5, 5, 5]

This behavior is often mistaken for a language design flaw, but it actually stems from the fundamental nature of Python function objects.

Functions as First-Class Objects

The key to understanding this phenomenon lies in recognizing that functions in Python are first-class objects. The def statement creates a function object when executed by the interpreter, containing the code body, parameter information, and default argument values among other metadata.

Default arguments are evaluated and bound at function definition time, not re-evaluated on each call. For mutable objects like lists and dictionaries, this means all function calls share the same default argument instance.

Design Rationale Analysis

This design choice maintains internal consistency: all elements of the function definition line are evaluated at definition time. If default arguments were bound at call time, it would split the semantics of the def statement—part handled at definition, part at invocation—introducing greater complexity and potential issues.

From an implementation perspective, function objects store default arguments in the __defaults__ attribute, a tuple that remains constant throughout the function's lifetime. Modifying mutable elements in this tuple naturally affects all subsequent calls.

In-Depth Example Analysis

Consider a more complex example demonstrating default argument evaluation timing:

def a():
    print("a executed")
    return []

def b(x=a()):
    x.append(5)
    print(x)

When this code is executed, a executed is printed immediately, proving that the default argument expression is evaluated at function definition. Subsequent calls behave consistently with the previous example.

Solutions and Best Practices

To avoid issues with mutable default arguments, it's recommended to use None as the default value and initialize within the function:

def foo(a=None):
    if a is None:
        a = []
    a.append(5)
    return a

This approach ensures each call receives a new list instance, aligning with expectations in most use cases.

Language Design Philosophy

This Python feature is not a design flaw but a reflection of language consistency. Treating functions as complete objects with all attributes (including default arguments) determined at creation simplifies language implementation and provides a clear semantic model.

Understanding this mechanism helps developers write more robust code and accurately diagnose similar issues. As Fredrik Lundh noted in related discussions, this design stems from a deep understanding of function object nature.