Functions in Python: Parameters, Return Values, and Scope

Scenario context

Python functions are first-class objects, not just reusable blocks. They support keyword arguments, safe defaults with None, variadic *args/**kwargs, closures, and LEGB scope resolution. These five ideas are not advanced features — they are the foundation of everything from decorators to FastAPI route definitions.

Carlos has three years of Java experience. He is comfortable. On day one with Python he wri…

This walkthrough focuses on The Argument Error That Broke Carlos's First Python Production Deploy.

Before making a design choice, clarify:

• Carlos has three years of Java experience.
• On day one with Python he writes a pipeline utility with six parameters and calls it like this: Three weeks later a teammate mistakenly passes the currency symbol as the third argument instead of the fifth.
• The column totals look reasonable.

Concepts in play: python-concurrency-nogil, jvm-internals-and-garbage-collection, api-security-oauth2, low-level-design-systems

Stage 1 — Defining Your First Python Function: Syntax, Return Values, and Calling Conventions

• A Python function is defined with the def keyword, a name, parameters in parentheses, a colon, and an indented body: That is the entire syntax.
• No access modifier, no return-type annotation (optional but not required), no semicolons.
• The return statement hands a value back to the caller.
• What happens when there is no return ?

def add(a, b):
    return a + b

result = add(3, 5)
print(result)  # 8

def greet(name):
    print(f"Hello, {name}!")
    # No return statement — implicitly returns None

value = greet("Alice")  # Prints: Hello, Alice!
print(value)            # None

Observable outcome: What happens when there is no return ?

Stage 2 — Default Arguments, the Mutable Default Trap, and Variadic args / *kwargs

• Giving Parameters Default Values Parameters can have default values, making them optional at the call site: Defaults are ideal for configuration options that rarely change.
• They reduce boilerplate at call sites while still exposing every knob to callers who need it.
• The Mutable Default Argument Bug — and the Exact Reason It Happens This is the single most common Python trap for developers coming from other languages.
• Read this function carefully: The second call should return ['beta'] .

def connect(host, port=5432, ssl=True):
    print(f"Connecting to {host}:{port}, SSL={ssl}")

connect("db.example.com")               # port=5432, ssl=True (defaults)
connect("db.example.com", port=3306)    # override port only
connect("db.example.com", 3306, False)  # override both positionally

def add_item(item, collection=[]):
    collection.append(item)
    return collection

print(add_item("alpha"))   # ['alpha']
print(add_item("beta"))    # ['alpha', 'beta']  ← expected ['beta']
print(add_item("gamma"))   # ['alpha', 'beta', 'gamma']  ← still wrong

Observable outcome: Read this function carefully: The second call should return ['beta'] .

Stage 3 — How Python Actually Treats Functions Under the Hood

• The Internals of Python Functions as First-Class Objects In Python, a function is a first-class object .
• That sentence means exactly what it says: a function is a value of the same kind as an integer, a string, or a list.
• You can assign it to a variable, pass it as an argument to another function, return it from a function, and store it in a data structure.
• When Python executes a def statement, it allocates a function object in memory.

def square(n):
    return n ** 2

# Assign to a variable
operation = square
print(operation(5))  # 25

# Store in a list alongside other callables
ops = [square, abs, lambda x: x + 1]
print([f(4) for f in ops])  # [16, 4, 5]

def make_multiplier(factor):
    def multiply(value):
        return value * factor   # 'factor' is captured from make_multiplier's scope
    return multiply

double = make_multiplier(2)
triple = make_multiplier(3)

print(double(10))  # 20
print(triple(10))  # 30

# The captured variable lives inside __closure__
print(double.__closure__[0].cell_contents)  # 2

Observable outcome: When Python executes a def statement, it allocates a function object in memory.

Stage 4 — How Python Resolves a Name: The LEGB Scope Lookup

• When Python encounters a variable name in your code — reading a value, not assigning one — it does not search every namespace in the program.
• It follows a fixed four-step order known as LEGB : - L — Local : Variables assigned inside the currently executing function.
• • E — Enclosing : Variables in any enclosing function scopes (the make multiplier scope when you are inside multiply , for example).
• • G — Global : Names defined at the top level of the current module.

graph TD
    A[Name referenced in code] --> B{In Local scope?}
    B -->|Yes| C[Use local variable]
    B -->|No| D{In Enclosing scope?}
    D -->|Yes| E[Use enclosing variable]
    D -->|No| F{In Global scope?}
    F -->|Yes| G[Use global variable]
    F -->|No| H{In Built-in scope?}
    H -->|Yes| I[Use built-in name]
    H -->|No| J[NameError raised]

# Built-in scope: len lives here
SIZE = 10  # Global scope

def outer():
    multiplier = 3  # Enclosing scope for inner()

    def inner():
        count = 5       # Local scope
        print(count)        # L: found in local
        print(multiplier)   # E: found in enclosing outer()
        print(SIZE)         # G: found in global module scope
        print(len([]))      # B: found in built-in scope

    inner()

outer()
# Output:
# 5
# 3
# 10
# 0

Observable outcome: - G — Global : Names defined at the top level of the current module.

Stage 5 — Real-World Patterns That Rely on Python's Function Flexibility

• Factory Functions: Configurable Validators and Converters A factory function returns a newly configured function as its output.
• This is a clean alternative to class-based configuration when the configuration state is small and the resulting callable is what you care about: Each call to make validator produces a fresh closure.
• username validator captures min len=3, max len=20 ; password validator captures min len=8, max len=64 .
• They are independent objects that share no state.

def make_validator(min_len, max_len):
    """Return a validator that checks string length against [min_len, max_len]."""
    def validate(value):
        if len(value) < min_len:
            return False, f"Too short (minimum {min_len} characters)"
        if len(value) > max_len:
            return False, f"Too long (maximum {max_len} characters)"
        return True, "OK"
    return validate

username_validator = make_validator(3, 20)
password_validator = make_validator(8, 64)

print(username_validator("ab"))          # (False, 'Too short (minimum 3 characters)')
print(password_validator("s3cr3t!23"))   # (True, 'OK')

numbers = [4, 1, 9, 2, 7]

# map: apply a function to every element, return an iterator
squared = list(map(lambda x: x ** 2, numbers))
print(squared)  # [16, 1, 81, 4, 49]

# filter: keep elements where the function returns True
evens = list(filter(lambda x: x % 2 == 0, numbers))
print(evens)  # [4, 2]

# sorted with a key function: sort by a derived property
words = ["banana", "fig", "apple", "kiwi"]
print(sorted(words, key=len))   # ['fig', 'kiwi', 'apple', 'banana']
print(sorted(words, key=str.upper))  # alphabetical, case-insensitive

Observable outcome: They are independent objects that share no state.

Stage 6 — Choosing Between *args, Explicit Parameters, and Dataclasses

• No parameter style is universally correct.
• The trade-offs depend on the number of parameters, the likelihood the signature will change, and how clearly callers need to understand each argument's meaning.
• Python 3.8 introduced two special parameter separators that give you fine-grained control over calling conventions: Positional-only ( / ) is useful in library APIs where the parameter name is an implementation detail th…
• Renaming source to path later would break callers who used source=...

# Parameters before / are positional-only — callers cannot use the keyword syntax
# Parameters after * are keyword-only — callers must use the keyword syntax
def process(source, /, *, output="stdout", verbose=False):
    print(source, output, verbose)

process("data.csv")                      # OK
process("data.csv", output="file")       # OK — keyword-only, fine
process(source="data.csv")              # TypeError — source is positional-only
process("data.csv", "file")             # TypeError — output is keyword-only

Observable outcome: Renaming source to path later would break callers who used source=...

End-to-end outcome

After working through the stages, you should be able to explain:

• Always use None for mutable defaults.
• The pattern def f(items=[]) is syntactically valid, technically works on the first call, and will silently corrupt subsequent calls.
• TLDR: Python functions are first-class objects that support keyword arguments, safe None defaults, variadic args / kwargs , closures, and LEGB scope resolution.
• These are the core mechanics behind decorators, factory functions, and the way FastAPI and Click read your function signature to build complete APIs.

Alternatives considered

Which Parameter Style Should You Use? A Decision Guide

Use the table below when you are designing a new function signature.

Failure and degraded modes

The source does not isolate a separate failure mode. Limits that matter for the scenario are called out in the stage decisions above.