Introduction

One of the most frequently encountered “gotchas” in Python arises from the way the language handles default argument values in function definitions—particularly when those defaults are mutable (e.g., lists or dictionaries). This phenomenon is often cited in discussions of Python’s behavior compared to the so-called “Principle of Least Astonishment,” which suggests that language features should behave in a way that least surprises or astonishes the users.

In this article, we’ll explore:

• What the Principle of Least Astonishment means and how it relates to Python.
• How Python’s default argument mechanism works under the hood.
• The pitfalls of using mutable default arguments.
• Best practices to avoid these pitfalls.

The Principle of Least Astonishment

What is the Principle of Least Astonishment?

The Principle of Least Astonishment (PoLA) states that software (and interfaces in general) should behave in such a way that “surprises” or “astonishments” for users are minimized. In simpler terms, it encourages designing features and APIs so that they act in the most intuitive way possible.

PoLA in the Python World

Python emphasizes readability and clarity. Its motto often points to explicitness being preferable to implicitness. However, some aspects of Python’s design can still catch users off guard—especially newcomers. One of these aspects is how Python treats mutable objects as default function arguments.

Understanding Python’s Default Argument Mechanism

Function Definition vs. Function Call

In many programming languages, you might assume that default parameters are re-created every time a function is called. However, in Python, default parameter values are evaluated only once at function definition time. This subtlety means:

1. If the default parameter is an immutable object (like an integer or a string), the object’s state can’t change between calls, so you rarely notice any “surprising” behavior.
2. If the default parameter is a mutable object (like a list, dictionary, or custom class instance), then any modifications to that object persist across function calls. This is where things become unintuitive.

The Gotcha: Mutable Default Argument

Consider the following Python function:

pythonCopyEditdef append_to_list(value, my_list=[]):
    my_list.append(value)
    return my_list

At first glance, many would expect that each call to append_to_list starts with a fresh, empty list if my_list is not provided. In reality:

pythonCopyEdit>>> append_to_list(1)
[1]
>>> append_to_list(2)
[1, 2]
>>> append_to_list(3)
[1, 2, 3]

We see that the list keeps growing across calls. Why does this happen? Because my_list is created once when the function is defined, not each time it’s called. Each subsequent function call reuses the same list reference.

Why Might This Be Surprising?

From a user standpoint, you might think “Every call to the function should get a new list unless I specify otherwise!” Yet Python’s behavior is more about efficiency: evaluating default parameters once can speed up the program, but it can lead to unintuitive side effects if the default is mutable.

How to Avoid the Pitfall

Use None as a Sentinel

The most common and Pythonic workaround is to set the default argument to None (an immutable object) and then create a new mutable object within the function body:

pythonCopyEditdef append_to_list(value, my_list=None):
    if my_list is None:
        my_list = []
    my_list.append(value)
    return my_list

Now, every time you call append_to_list without providing my_list, a new list will be created inside the function.

Example:

pythonCopyEdit>>> append_to_list(1)
[1]
>>> append_to_list(2)
[2]
>>> append_to_list(3)
[3]

As expected, each call now returns a different list.

Watch Out for Other Mutable Types

The same principle applies to other mutable types:

• Dictionaries: Use my_dict=None and then my_dict = {} if needed.
• Sets: Use my_set=None and then my_set = set() if needed.
• Custom Classes: If your default argument is an instance of a class that can be modified internally, you likely need the same pattern.

Avoid Using Global or Shared Structures

If your code must rely on global or shared structures, try to do so explicitly, rather than relying on a function’s default parameter to carry state. This will make the code’s intent clearer and reduce the chance of unintentional side effects.

Why Doesn’t Python Change This Behavior?

For better or worse, Python’s approach to function defaults is ingrained in the language design. It provides efficiency benefits and is also conceptually simpler once you understand that function definitions are executable statements (i.e., the code runs at definition time). Though it can be surprising initially, it fits logically with Python’s internal model.

In practice, most of the time you learn this once, adopt the “use None as a default” pattern, and then rarely run into the issue again.

Conclusion

The mutable default argument issue in Python is a classic demonstration of how a feature can violate (or at least seem to violate) the Principle of Least Astonishment. Despite its initial surprises, it follows naturally from Python’s design philosophy where default arguments are evaluated at definition time.

To avoid confusion and potential bugs:

• Never use mutable objects as default arguments unless you specifically want the shared state.
• Use None (or another sentinel) and initialize a new object within the function body as needed.

By following these guidelines, you’ll keep your code intuitive, readable, and consistent with Python’s best practices, thus upholding the spirit of the Principle of Least Astonishment.

Further Reading

• Python Official Documentation – More on Defining Functions
• PEP 20 – The Zen of Python
• Python FAQ – Why are default values shared between objects?