Functions, Args & Scope

Functions bundle reusable logic with flexible parameter binding. Python's LEGB scope rules, variadic *args/**kwargs, and keyword-only parameters let you design APIs that are both expressive and safe.

Recipe

def greet(name: str, *, excited: bool = False) -> str:
    msg = f"Hello, {name}"
    return msg + "!" if excited else msg
 
def connect(host: str, port: int = 443, **options: object) -> dict:
    return {"host": host, "port": port, **options}
 
def total(*amounts: float, tax: float = 0.0) -> float:
    return sum(amounts) * (1 + tax)

When to reach for this:

• Designing library APIs with optional configuration
• Wrapping callables with decorators (see iterators section)
• Implementing closures that remember state
• Avoiding global mutable state in modules

Working Example

from collections.abc import Callable
 
def make_multiplier(factor: int) -> Callable[[int], int]:
    def multiply(value: int) -> int:
        return value * factor
    return multiply
 
def append_item(item: object, bucket: list | None = None) -> list:
    if bucket is None:
        bucket = []
    bucket.append(item)
    return bucket
 
def call_with_retry(fn: Callable[[], object], retries: int = 3) -> object:
    last_error: Exception | None = None
    for attempt in range(retries):
        try:
            return fn()
        except Exception as exc:
            last_error = exc
    raise RuntimeError("failed") from last_error
 
counter = 0
 
def increment_global() -> int:
    global counter
    counter += 1
    return counter
 
def make_counter() -> Callable[[], int]:
    count = 0
    def inc() -> int:
        nonlocal count
        count += 1
        return count
    return inc
 
if __name__ == "__main__":
    double = make_multiplier(2)
    print(double(21))
    print(append_item("a"))
    print(append_item("b"))  # fresh list - no shared default
    inc = make_counter()
    print(inc(), inc())

What this demonstrates:

• Closure captures factor from enclosing scope
• None sentinel avoids mutable default list bug
• nonlocal updates count inside nested function
• global modifies module-level counter explicitly

Deep Dive

How It Works

• LEGB - Local (function), Enclosing (nested), Global (module), Built-in (len, print).
• Parameter kinds - Positional, keyword, positional-only (/), keyword-only (*).
• *args - Tuple of extra positional arguments.
• **kwargs - Dict of extra keyword arguments.
• Annotations - Stored in __annotations__; evaluated at function definition time.

Parameter Ordering

def f(pos_only, /, standard, *, kw_only, **kwargs): ...

Python Notes

# Unpacking at call site
args = (1, 2)
kwargs = {"excited": True}
greet("Ada", **kwargs)
 
# functools.partial defers arg binding
from functools import partial
double = partial(make_multiplier, 2)

Gotchas

• Mutable defaults - def f(x=[]) shares one list across calls. Fix: None default and assign inside.
• Late-binding closures - funcs = [lambda: i for i in range(3)] captures variable, not value. Fix: Default arg lambda i=i: i.
• Shadowing builtins - def len(x): breaks len(). Fix: Rename parameters.
• global for module state - Makes testing harder. Fix: Prefer classes or explicit config objects.
• **Too many *args/kwargs - Hides API surface. Fix: Name important parameters explicitly.

Alternatives

FAQs

Related

• Closures & Scope Capture - free variables and factories
• Writing Decorators - wrapping functions
• functools - partial and wraps
• Type Hints Basics - annotating signatures

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.