Functions Basics (Parameters, Defaults, Return)

Function Signatures Are APIs

A good signature reduces incorrect calls and makes failures obvious.

Avoid Mutable Defaults

# Bad
def add_tag(tags=[]):
    tags.append("x")
    return tags

# Good
def add_tag(tags=None):
    if tags is None:
        tags = []
    tags.append("x")
    return tags

Keyword-only for Risky Params

def fetch(url: str, *, timeout_seconds: int = 10, retries: int = 2) -> str:
    return "ok"

Operational Checklist

• No mutable defaults ([], {}, set()).
• Timeouts/retries are keyword-only and have sensible defaults.
• Return values are explicit; avoid ambiguous None/empty results.

Failure Modes

• Shared state: mutable defaults leak data across calls.
• Ambiguous returns: None/"" hides errors and complicates callers.