Function Design Concepts

In the previous section, we built our first functions. Now, we will look at how functions actually behave in your computer’s memory. This section covers critical design concepts that may save you hours of debugging when building more complex spatial data pipelines.

1. Scope and Namespaces¶

A common point of confusion for new programmers is understanding how variable names inside functions relate to those defined elsewhere in their notebooks.

Think of your main Python script as a giant “White Room.” When you define a function, you are building a smaller, soundproof room inside it.

Local Variables Stay Local¶

When you create a variable inside a function, it is a local variable. It only exists within that specific function’s room. Once the function finishes running, the room is demolished, and the variable disappears.

Output:

NameError: name 'area' is not defined

This is actually a brilliant feature! It means you can use simple variable names like area, distance, or x inside your functions without worrying about accidentally overwriting variables with the same names in your main script.

The Danger of Global Variables¶

Python searches for variables from the inside out. If it cannot find a variable inside the function (local scope), it will peek outside into the main script (global scope) to see if it exists there.

This can lead to dangerous bugs. Look at this example:

This code works, but it is poor software design. The function calculate_relative_elevation is no longer a standalone tool. It secretly relies on base_elevation existing elsewhere in the notebook. If you copy this function into a new script, or if you accidentally change base_elevation in a different cell, your pipeline will break, and it might be hard to figure out why.

2. Required vs. Optional Parameters¶

Up to this point, every parameter we have created has been a required parameter. If the user forgets to provide an argument, the program crashes.

However, we can design our tools to be much more flexible by providing optional parameters with default values.

Setting Default Values¶

Imagine a function that checks if a GPS point is within a certain accuracy threshold. Most of the time, our acceptable threshold is 5 meters. We can set that as the default!

Now, the user has a choice:

The Ordering Rule¶

There is a strict grammatical rule in Python regarding defaults: Required parameters must always come before optional parameters in the function definition.

3. The Mutable Default Trap¶

This is a high-value moment. Understanding this concept separates beginners from professional data scientists.

We just learned that we can set default values (like threshold=5). But what happens if we set a default value to a mutable object, like an empty list ([])?

Let’s write a function that takes a new GPS waypoint and adds it to a route list. If no route list is provided, it should default to an empty list.

Watch what happens when we use it to track two different animals:

Output:

Bear Track: ['Point A']
Wolf Track: ['Point A', 'Point X']

What happened?! The wolf is somehow inheriting the bear’s GPS points!

When you define a function, Python evaluates the default arguments only once. It creates that single empty list [] and stores it in memory. Every time you call the function without providing a route, it grabs that exact same list. The state carries over (a “side effect”), destroying the reproducibility of your data.

The Fix: Use None¶

To fix this, we must use None as our default value, and create the fresh list inside the function block.

Click here for a more detailed breakdown of the Mutable Default Trap

1. The Core Problem: Definition vs. Execution¶

In Python, a function’s default arguments are evaluated only once, at the exact moment the def statement is read by the computer (the “definition phase”). They are not evaluated every time you call the function (the “execution phase”).

When Python reads this line of code:

def add_waypoint(waypoint, route=[]):

It says: “Okay, I’m creating a new function. The default value for route is an empty list. I will create a single, empty list in my memory right now, and attach it to this function permanently.”

Let’s use a “Shared Backpack” analogy:

1. When the function is defined, Python creates a single backpack (the default list []) and leaves it at the door of the function.

2. The Bear’s turn: You call add_waypoint("Bear Point") without providing a list. Python says, “Use the default backpack!” The function puts the bear’s GPS point inside the backpack. The backpack now contains ["Bear Point"].

3. The Wolf’s turn: You call add_waypoint("Wolf Point") without providing a list. Python says, “Use the default backpack!” It hands the wolf the exact same backpack from step 1. But wait—the bear’s GPS point is still inside it! The function adds the wolf’s point, and the backpack now contains ["Bear Point", "Wolf Point"].

Because lists are mutable (they can be changed in place), any changes made to the default list are permanent. Every subsequent call to the function uses that exact same, increasingly contaminated list.

2. Why doesn’t this happen with numbers or strings?¶

You might wonder why we don’t have this problem when we set defaults to numbers, like buffer=5.

Numbers, strings, and booleans (True/False) are immutable in Python. You cannot alter them in place. If you change a number, Python actually throws the old number away and creates a brand-new number in memory. Therefore, they cannot accumulate “state” or carry over contamination from previous function calls.

Because lists ([]) and dictionaries ({}) are mutable, they can be modified without losing their original identity in memory.

3. How the None Fix Actually Works¶

To fix the shared backpack problem, we need to force Python to create a brand-new list every single time the function runs, rather than just once when the function is defined.

Here is the safe code again:

def add_waypoint(waypoint, route=None):
    if route is None:
        route = []  # Creates a brand new, empty list every time it runs!
        
    route.append(waypoint)
    return route

Let’s look at how memory handles this:

1. Definition phase: Python reads route=None. None is an immutable placeholder. It just means “nothing.” Python attaches None to the function permanently.

2. The Bear’s turn: You call add_waypoint("Bear Point"). The route is None. The if statement triggers: route = []. Because this line is inside the function body, it runs during the execution phase. Python creates a brand new list in memory, adds the bear’s point, and returns it. Once the function finishes, that specific [] creation step is over.

3. The Wolf’s turn: You call add_waypoint("Wolf Point"). The route defaults back to None. The if statement triggers again: route = []. Python creates a second, entirely separate new list in memory. It adds the wolf’s point and returns it.

Summary¶

By using None as the default argument, you are delaying the creation of the list. Instead of creating the list when the function is defined (which creates a single shared object), you create the list when the function is executed (which creates a fresh, independent object every time).

4. Exercises¶

Test your understanding of function design and scope!

Exercise 1: The Scope Bug (Core)¶

A junior analyst wrote the following code to convert a list of elevations from feet to meters. When they try to run print(converted), Python throws a NameError.

Your Task: Without running the code, explain why the error occurs, and fix the code so it properly prints the result.

def feet_to_meters(elevation_ft):
    converted = elevation_ft * 0.3048
    return converted

# Catch the returned data in a new variable in the main script!
final_elevation = feet_to_meters(5000)
print(final_elevation)

Exercise 2: The Bounding Box (Stretch)¶

In spatial analysis, a common operation is to draw a square “bounding box” around a coordinate.

Your Task: Write a function create_bbox(lat, lon, buffer) that calculates a simplified bounding box around the point coordinates.

1. Make lat and lon required parameters.

2. Make buffer an optional parameter with a default value of 0.5 degrees.

3. The function should return a dictionary containing min_lat, max_lat, min_lon, and max_lon. (Hint: min_lat is lat - buffer, max_lat is lat + buffer, etc.)

def create_bbox(lat, lon, buffer=0.5):
    # Calculate the boundaries
    min_lat = lat - buffer
    max_lat = lat + buffer
    min_lon = lon - buffer
    max_lon = lon + buffer
    
    # Return them all packaged neatly in a dictionary
    return {
        "min_lat": min_lat,
        "max_lat": max_lat,
        "min_lon": min_lon,
        "max_lon": max_lon
    }

# Test 1: Using the default buffer
small_box = create_bbox(34.0, -118.0)
print(f"Default box: {small_box}")

# Test 2: Overriding the default buffer
large_box = create_bbox(34.0, -118.0, buffer=5.0)
print(f"Large box: {large_box}")

Exercise 3: The Contaminated River (Challenge)¶

You are writing a code pipeline to track pollution sampling sites along different rivers. Look at the code below.

Your Tasks:

1. Run the code in your head. What will the output look like?

2. Why is this happening?

3. Rewrite the function using best practices so that the Isar and the Inn get their own independent lists of samples.

Isar: [7.2, 7.4, 6.8]
Inn: [7.2, 7.4, 6.8]

# Use None as the default!
def log_sample(ph_level, river_samples=None):
    # Initialize the empty list INSIDE the function
    if river_samples is None:
        river_samples = []
        
    river_samples.append(ph_level)
    return river_samples

isar_data = log_sample(7.2)
isar_data = log_sample(7.4, isar_data)

inn_data = log_sample(6.8)

print(f"Isar: {isar_data}")
print(f"Inn: {inn_data}")
# Now prints correctly: 
# Isar: [7.2, 7.4]
# Inn: [6.8]

5. Summary¶

In this section, we moved from writing functional code to writing safe code:

• Scope: Variables created inside a function are destroyed when the function finishes. Do not rely on global variables; always use parameters.

• Defaults: Optional parameters make your tools flexible, but they must always be listed after required parameters.

• The Mutable Trap: Never use [] or {} as default values. Use None, and create the object inside the function block to prevent state leakage and side effects.

What comes next?¶

You now know how to build perfectly constrained, safe tools. But Python functions have one more superpower. Next, we will learn how to use *args and **kwargs to handle an infinite, unpredictable amount of spatial data inputs!