Functions & Arguments

Almost every useful Python program is built from functions: small, named pieces of work that take some input, do one job and hand back a result. A function lets you write an idea once and use it everywhere, give it a name that explains itself, and test it on its own. Most bugs that beginners meet, such as a function that returns None when a value was expected, a list that mysteriously keeps growing between calls, or a variable that changes in the wrong place, come from a handful of details about how functions really behave.

This chapter walks through those details in order. You start with def and return, then see how arguments reach a function by position, by keyword, by default value and through *args and **kwargs. After that you look at where names live, using the LEGB rule for scope, and at how a function can remember its surroundings through a closure. The later parts treat functions as ordinary objects that you can pass around, wrap in a lambda, describe with type hints and document with docstrings.

By the end you will be able to design a function signature on purpose instead of by trial and error, predict what a call will do before you run it, and spot the mutable-default trap and other common mistakes in code review. You will also be able to read other people's function-heavy code, such as decorators, callbacks and key functions, without guessing.

A function is a named block of code you can run whenever you want. You write it with a def statement: the keyword, a name, a list of parameters in parentheses, a colon, and an indented body. The key idea is that def is not a declaration. It is an ordinary statement that runs when Python reaches it, builds a function object from the body, and binds that object to the name.

def greet(name):
    return 'Hi ' + name

print(greet('Sam'))

def creates greet; the call greet('Sam') runs the body

Creating the function and running it are two separate events. When def executes, the body is only compiled and stored. Nothing inside it runs until somebody calls the function with parentheses.

The next example makes the gap visible. The body contains a print, but it stays silent until the call, so the line printed after the def comes first.

def shout(text):
    print('running body')
    return text.upper()

print('after def')
print(shout('hey'))

Defining prints nothing; calling runs the body

Two words that are often mixed up have precise meanings. Parameters are the names listed in the def line. Arguments are the actual values you pass at the call site. Inside the body, each parameter becomes a local name bound to the matching argument.

def add_tax(price, rate):
    total = price * (1 + rate)
    return total

print(add_tax(100, 0.5))
print(add_tax(40, 0.25))

price and rate are parameters; 100 and 0.5 are arguments

Every call gets its own fresh local namespace and a new stack frame. Local names such as total are created when the call starts and thrown away when it ends, so one call can never see another call's locals. The counter below shows it: if locals survived between calls, the second result would be 2.

def counter():
    count = 0
    count += 1
    return count

print(counter())
print(counter())

Each call starts with a brand-new count

A function's name is just a variable holding the function object. Writing greet evaluates to that object. Only greet() with parentheses performs the call and evaluates to the returned value.

f = greet
print(type(f).__name__)
print(type(greet('Ana')).__name__)

greet is a function; greet('Ana') is a str

Because def is a statement that runs, the name does not exist until Python has executed it. Calling a function on a line above its def raises a NameError. Once the def has run, the call works normally.

try:
    hello()
except NameError as err:
    print('NameError:', err)

def hello():
    return 'hello'

print(hello())

The first call happens before def has executed

The rule applies to when the call happens, not to where the text sits in the file. A function body may mention names that are defined later. Those names are only looked up when the body runs, so they just have to exist by call time.

def report():
    return helper() + '!'

def helper():
    return 'done'

print(report())

helper is defined after report, but before report is called

A body needs at least one statement. When you want to sketch a function and fill it in later, use pass, a statement that does nothing.

def todo():
    pass

print(todo())

A valid placeholder; calling it returns None

A function hands a result back to whoever called it with the return statement. The moment Python reaches return, the function stops right there. Any lines below it in that call never run, and the value after the word return becomes the value of the call expression.

The loop below shows the early exit. It checks numbers one at a time and returns the first negative one it meets, so the later numbers are never examined.

def first_negative(xs):
    for x in xs:
        print("checking", x)
        if x < 0:
            return x
    return None

print(first_negative([3, 5, -2, 8, -9]))

return leaves the loop and the function at once

Notice that 8 and -9 were never checked. Every function call produces a value, even when you did not ask for one. If the body ends without a return, or uses a bare return with nothing after it, Python hands back None, the built-in value that means "nothing here".

The last row deserves a closer look. Python has no special mechanism for sending back several values. return a, b builds a tuple (the comma makes it, not the parentheses), and the caller can unpack that tuple into separate names.

def greet(name):
    print("Hello,", name)

def stop_early(n):
    if n < 0:
        return
    print("not negative")

def bounds(xs):
    return min(xs), max(xs)

print(greet("Asha"))
print(stop_early(-1))
pair = bounds([4, 9, 1, 7])
print(pair, type(pair).__name__)
lo, hi = pair
print(lo, hi)

no return, bare return, and a tuple return

Both greet and stop_early give back None, so printing their calls shows None. In practice you usually write lo, hi = bounds(xs) in one step, and the tuple is unpacked straight into two names.

Beginners often treat print and return as the same thing, because both make a number appear while you are testing in a console. They are very different. print only writes text to the screen and the function's result is still None. return gives the caller a real value it can store, compare or calculate with.

def add_print(a, b):
    print(a + b)

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

x = add_print(2, 3)
y = add_return(2, 3)
print(x, y)
print(y * 10)

only the returned value can be reused

The first 5 comes from the print inside add_print. After that, x holds None, while y holds 5 and works in further arithmetic. The table sums up the difference.

Because return ends the function, it is also a handy way to deal with special cases first. A guard clause is an early return placed at the top that handles the odd situation (an empty list, a missing value) and leaves the rest of the body for the normal case. This avoids stacking if/else blocks deeper and deeper.

def shipping(order):
    if not order["items"]:
        return 0
    if order["total"] >= 50:
        return 0
    return 5

print(shipping({"items": [], "total": 0}))
print(shipping({"items": ["pen"], "total": 80}))
print(shipping({"items": ["pen"], "total": 20}))

each guard returns early, so the main case stays flat

The final return 5 sits at the normal indentation level with no else wrapped around it. A reader can see the special cases first and the ordinary result last.

Methods that change an object in place, such as list.sort(), list.append(), list.extend(), list.reverse() and dict.update(), deliberately return None. This tells you the object itself was modified and there is no new object to hand back. The result is a classic bug: xs = xs.sort() sorts the list and then overwrites the name xs with None, so your data is gone.

xs = [3, 1, 2]
xs = xs.sort()
print(xs)

nums = [3, 1, 2]
nums.sort()
print(nums)
print(sorted(nums, reverse=True))

words = ["b", "a"]
print(words.append("c"))
print(words)

sort() and append() change the list and return None

Two more traps involve how a function ends. First, unreachable code: any statement placed after return in the same block can never run. If you write return total and then print("done") on the next line, the print is dead code, and Python will not warn you. Put logging or cleanup before the return, not after it. Second, mixed return types. If a function returns an int on some paths and falls off the end (None) on others, every caller must remember to check for None, and the ones who forget crash far from the real cause.

ages = {"Asha": 31, "Ravi": 27}

def find_age(name):
    if name in ages:
        return ages[name]

print(find_age("Asha"))
print(find_age("Zed"))
try:
    print(find_age("Zed") + 1)
except TypeError as e:
    print("Error:", e)

the missing branch silently returns None

When you call a function, Python has to decide which value goes into which parameter. You can steer that decision in two ways. A positional argument is matched by where it sits in the call: the first value goes to the first parameter, the second to the second, and so on. A keyword argument is matched by name, written as name=value, so its place in the call no longer matters.

The next example defines two functions. area is symmetric, so you cannot see the difference, but divide is not: swapping the positional values changes the answer, while swapping keyword arguments does not.

You can mix the two styles in a single call, with one rule: every positional argument must come before the first keyword argument. Python fills the leading parameters by position and then looks up the rest by name. Putting a positional value after a keyword one is not a runtime error but a SyntaxError, caught before the call is ever tried. The snippet below asks Python to compile the bad call so we can read its message safely.

try:
    compile("area(width=3, 5)", "<call>", "eval")
except SyntaxError as error:
    print(error.msg)

print(area(3, height=5))

Positional first, then keywords: fine. The reverse never runs.

After the binding step, Python checks that every parameter received exactly one value and that every name you used actually exists. Any mismatch raises a TypeError before the function body starts. The messages are specific, so they are worth reading carefully rather than guessing. The most surprising case is giving the same parameter two values: area(3, width=4) fills width by position with 3 and then again by name with 4.

try:
    area(3, width=4)
except TypeError as error:
    print(error)

try:
    area(3)
except TypeError as error:
    print(error)

try:
    area(3, 5, depth=2)
except TypeError as error:
    print(error)

try:
    area(3, 5, 7)
except TypeError as error:
    print(error)

Uses the area function defined on the previous example.

By default a parameter accepts either style. A function author can narrow that with two markers in the signature. A bare * means that everything after it is keyword-only: callers must write the name. A / means that everything before it is positional-only: callers must not write the name. Here is the keyword-only side first.

The third call fails because sep sits after the *, so a third positional value has nowhere to go. Now the positional-only side: the / in double(x, /) locks x to its position.

Both markers can appear in one signature, and the parameters between them accept either style. Read a signature left to right and it splits into three zones.

The built-ins show both styles. len(x) takes its one value positionally only, while the sep option of print can only be given by name, which is why a stray third string is printed as text rather than used as a separator.

A default value makes a parameter optional. Write name=value in the def line, and callers may leave that argument out. When they do, Python fills in the default for them.

def power(x, n=2):
    return x ** n

print(power(5))
print(power(5, 3))
print(power.__defaults__)

n is optional; x is required

The last line shows where the default lives. Python stores all defaults in a tuple on the function object itself, called __defaults__. Keep that in mind, because it explains the trap later in this section.

Parameters without a default must come first, and parameters with a default come after them. Python rejects the reverse order when it reads the def, before any call happens. It would otherwise have no way to know which argument a positional value was meant for.

This is the key idea of the section. The default expression is evaluated once, at the moment the def statement runs. It is not re-evaluated on each call. Python keeps the resulting object in f.__defaults__ and hands you that same object every time you skip the argument.

You can prove it by making the default expression announce itself. The message appears once, before any call, and never again.

With an integer this is harmless, because a number can never change. The danger begins when the stored default is an object that can be modified.

Suppose a function collects items into a list, and you give the list parameter an empty list as its default. It looks natural, and it is one of the best-known bugs in Python.

def add(item, bucket=[]):
    bucket.append(item)
    return bucket

print(add(1))
print(add(2))
print(add(3))
print(add.__defaults__)

every call without bucket shares one list

The empty list was created once, when def ran. Each call that omits bucket receives that same list, appends to it, and returns it. The list grows across calls, so add(2) returns [1, 2] rather than [2]. The last line shows the damage: the stored default itself has changed.

Lists are not special here. Any mutable object used as a default behaves the same way, including {}, set(), and a dict default of any contents.

def tally(word, counts={}):
    counts[word] = counts.get(word, 0) + 1
    return counts

print(tally("a"))
print(tally("b"))
print(tally("a"))

a dict default is shared too

Unrelated callers end up sharing counts, and the bug is hard to spot because the first call always looks correct.

The fix is to make the default something immutable, almost always None, and create the real container inside the function body. The body runs on every call, so each call gets its own fresh object. In this role None is called a sentinel: a marker meaning "the caller gave me nothing."

def add(item, bucket=None):
    if bucket is None:
        bucket = []
    bucket.append(item)
    return bucket

print(add(1))
print(add(2))
mine = []
add(7, mine)
print(mine)
print(add.__defaults__)

each call without bucket builds its own list

Now add(2) returns [2], because the list was created during that call. A caller who passes their own list still gets it back with the item appended. The stored default stays None and can never accumulate state.

It is tempting to write if not bucket: because it reads shorter. But an empty list is falsy, so that test also fires when the caller deliberately passed an empty list of their own. Your function then quietly swaps in a different list, and the caller's list never receives the item.

def add_bad(item, bucket=None):
    if not bucket:
        bucket = []
    bucket.append(item)
    return bucket

a, b = [], []
add_bad("x", a)
add("x", b)
print(a)
print(b)

a is ignored, b is honored

The is None check asks one precise question: did the caller omit the argument? An empty list, 0 or an empty string passed on purpose all count as real values and are respected.

Sometimes a function cannot know in advance how many arguments it will receive. A logger might get a message plus any number of values, and a wrapper must accept whatever the function it wraps accepts. Python handles this with two special parameters. A parameter written with one star, *args, collects every extra positional argument into a tuple. A parameter written with two stars, **kwargs, collects every extra keyword argument into a dict.

The names args and kwargs are only convention, and you could call them *values and **options. The stars are what matter. Everything else in the signature is matched first, and the leftovers land in these two containers.

def log(msg, *args, **kwargs):
    print(msg)
    print(args)
    print(kwargs)

log("start", 1, 2, level="info", tag="x")

msg takes the first value; 1 and 2 are extra positionals; level and tag are extra keywords

If the caller passes nothing extra, the containers are not missing. They are simply empty, so your code never has to check for None.

When a signature mixes several kinds of parameters, Python insists on a fixed order. Ordinary positional parameters come first, then *args, then keyword-only parameters, and **kwargs comes last. Any parameter placed after *args can only be given by name, which is why it is called keyword-only.

def report(title, *items, sep=", ", **extra):
    print(title + ": " + sep.join(items), extra)

report("Fruit", "apple", "pear", sep=" | ", color="red")
report("Fruit", "apple", "pear")

sep sits after *items, so it can only be passed as sep=...

The stars also work in the opposite direction. In a call, * unpacks an iterable into separate positional arguments, and ** unpacks a dict into keyword arguments. So f(*[1, 2], **{'sep': '-'}) means exactly f(1, 2, sep='-').

You can unpack more than one dict in a single call, as in f(**a, **b). If both dicts contain the same key, Python cannot decide which value wins, so it refuses and raises a TypeError. To merge deliberately, build one dict first and unpack that. In {**a, **b} the later dict wins.

a = {"sep": "-"}
b = {"sep": "+"}

try:
    show(1, 2, **a, **b)
except TypeError as e:
    print(type(e).__name__)

show(1, 2, **{**a, **b})

the same key arrives twice in the first call; the merged dict has one value

The most common use is a forwarding wrapper. A decorator does not know what the wrapped function takes, so it accepts everything and passes everything along with return fn(*args, **kwargs). Because the wrapper simply repeats whatever arrived, it works for any signature.

The second use is a variadic helper, a function whose natural input is a list of values of any length. sum_all(*nums) lets callers write sum_all(1, 2, 3) instead of building a list first. The third use is optional configuration, where a function accepts a bag of named settings and reads the ones it understands.

Flexibility has a price. An explicit signature documents itself, and Python checks every call against it. With **kwargs, any keyword is accepted, including one you misspelled. The function then quietly falls back to its default.

def connect(host, **options):
    timeout = options.get("timeout", 30)
    return host, timeout

def connect_strict(host, *, timeout=30):
    return host, timeout

print(connect("db", timout=5))
try:
    connect_strict("db", timout=5)
except TypeError as e:
    print(e)

timout is a typo in both calls

Every time your code uses a name, Python has to decide which variable that name refers to. It does this by searching a fixed series of places, called scopes, in a fixed order. The first place that holds the name wins, and the search stops there. The order is remembered as LEGB.

The example below defines the same name x in three places. Each print finds the nearest one. The call to len is not defined anywhere in the file, so the search runs all the way to the built-in scope.

Reading a name from an outer scope works without any special syntax. A function that only reads limit finds it in the global scope because the local scope does not have it.

There is one rule that surprises almost everyone. Python decides whether a name is local by looking at the whole function body before running it. If the name is assigned anywhere in that function, including with +=, for, import or def, it is local for the entire function, even on the lines above the assignment.

That is why the classic counter fails. The statement count += 1 means count = count + 1, which assigns to count. So count is local, and the right-hand side tries to read a local that has no value yet.

The same thing happens when the assignment comes later than the read. Here the first line of show looks like it should print the global total, but the assignment on the next line has already made total local.

The usual fix is to stop depending on an outer variable. Pass the value in as a parameter and return the new value. Python also has the keywords global and nonlocal for changing outer names, which the section on closures covers.

Because the built-in scope is searched last, any name you create in an earlier scope shadows the built-in of the same name. Writing list = [1, 2] or sum = 0 hides the real list or sum for the rest of that scope. The next call to list('abc') then tries to call your list instead. Deleting your name makes the built-in visible again.

Loop variables behave differently depending on the kind of loop. A comprehension runs in its own scope, so its variable disappears when it finishes. A regular for loop has no scope of its own, so its variable stays behind in the enclosing scope with the last value it was given.

Inside a function, assigning to a name normally creates a local variable. That is usually what you want, but sometimes a function needs to change a name that lives outside it. Python gives you two keywords for this. global x makes the function rebind a module-level name. nonlocal x makes it rebind a name in the nearest enclosing function, never the module.

There is one rule that removes most confusion: only rebinding needs a keyword. Rebinding means =, += or any other assignment that points the name at a new object. Calling a method that changes an object in place, such as xs.append(...), does not rebind anything, so it needs neither keyword.

count = 0
log = []

def bump():
    global count
    count += 1
    log.append(count)

bump()
bump()
print(count, log)

count is rebound, so it needs global. log is only mutated, so it does not.

If you delete the global count line, count += 1 makes count local for the whole function body. Python then finds a read of a local that has no value yet and raises UnboundLocalError. The log.append(count) line works either way, because it never assigns to log.

nonlocal follows the same idea, but it targets an enclosing function. In the next example the module also has an x, yet nonlocal x skips past it and binds to the x inside outer.

A closure is an inner function that keeps access to variables from its enclosing function, even after that outer function has returned. This is where nonlocal is most useful. The classic example is a counter. The outer function creates n, the inner function updates it, and returning the inner function hands the caller something that carries its own private state.

def make_counter():
    n = 0
    def step():
        nonlocal n
        n += 1
        return n
    return step

a = make_counter()
b = make_counter()
print(a(), a(), a())
print(b())
print(a.__code__.co_freevars)
print(a.__closure__[0].cell_contents)

a and b come from separate calls, so each has its own n.

Every call to make_counter() runs the function body again and creates a fresh n, so a and b never interfere. The last two lines answer where the remembered value lives. The inner function's code object lists n as a free variable in co_freevars. The value itself sits in a cell object, reachable through the function's __closure__ tuple. The cell stays alive for as long as the function that refers to it does.

Closures look up a variable when the inner function is called, not when it is defined. That causes a well-known surprise in loops. In the code below, three functions are defined in a for loop and stored in a list. All three refer to the same loop variable i. By the time you call them, the loop has finished and i is 2.

The fix is to capture the current value at definition time. A default argument is evaluated once, when def runs, so def show(i=i) stores each loop value in its own function.

The same trap appears with lambdas, which are small unnamed functions written as a single expression (a later section covers them properly). Here lambda: i behaves like def returning i, and the same default-argument fix applies.

The last question is where to keep state that changes between calls. A global variable works, but any function can change it at any time. A closure or an ordinary parameter makes the dependency visible.

In Python a function is a value, just like a number or a string. When you write def add(a, b), Python builds a function object and binds the name add to it. Because it is an ordinary object, you can give it a second name, put it in a list or dict, hand it to another function, or return it from one. This is what people mean by first-class functions.

The first example shows the three simplest moves. f = len copies a reference to the built-in function, without calling it. The dict stores two functions as values, and the last lines look one up by key and call it right away.

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

def sub(a, b):
    return a - b

f = len
print(f('hello'))

ops = {'add': add, 'sub': sub}
print(ops['add'](2, 3))
print(ops['sub'](2, 3))

No parentheses after len means the function itself, not a call

A function object also carries data about itself. __name__ holds the name it was defined with, __doc__ holds its docstring, and __defaults__ holds a tuple of its default argument values. A second name for the same function is not a copy, so is reports True.

Passing and returning functions works the same way. apply_twice below receives a function as an argument. make_adder builds a new function inside itself and returns it, so the caller gets a function back.

A higher-order function is one that takes a function as an argument, returns a function, or both. Python ships several. sorted takes a key function and calls it once per item to decide the order. map applies a function to every item. filter keeps the items for which a function returns a true value.

words = ['pear', 'fig', 'banana', 'kiwi']
print(sorted(words, key=len))
print(list(map(str.upper, words)))

items = ['12', 'ab', '7', 'x9']
print(list(filter(str.isdigit, items)))

len, str.upper and str.isdigit are passed as objects, never called

Here is what sorted(words, key=len) does under the hood. It receives the function object, calls it on each word to get a sort value, and then orders the words by those values.

The most common slip is writing key=len(words). Python evaluates arguments before the call, so len(words) runs immediately, finds that the list has 4 items, and passes the integer 4 as the key. sorted then tries to call that integer on each word and fails. The rule is to pass the function itself, with no parentheses.

try:
    sorted(words, key=len(words))
except TypeError as e:
    print(e)

Wrong on purpose: len(words) is already the int 4

Because functions can be dict values, a long if/elif chain that picks an action by name can become a lookup. This is called a dispatch dict. The key is the command, the value is the handler function, and .get() lets you handle an unknown command without a KeyError.

Adding a new command now means adding one dict entry instead of another elif branch.

Functions are not the only things you can call. A callable is any object that has a __call__ method, and the built-in callable(x) tells you whether x qualifies. A class can make its instances callable by defining __call__. The Counter below is an object that remembers state between calls.

Finally, a decorator is just a higher-order function that takes a function and returns a replacement. Writing hello = shout(hello) rebinds the name to a wrapper. The @shout line above a def is shorthand for exactly that rebinding.

A lambda is a small function written as a single expression, with no name of its own. The form is lambda parameters: expression. Whatever the expression evaluates to is returned automatically, so there is no return keyword. Because a lambda is an ordinary function object, you can call it, pass it to other functions, or store it in a list.

The parameter list works like a def parameter list: you can use several parameters, defaults and *args. The one thing you cannot add is an annotation, because the lambda syntax has no place for one. The example below calls each lambda right where it is defined, so none of them needs a name.

print((lambda x: x * x)(7))
print((lambda a, b=10: a + b)(5))
print((lambda *args: len(args))(1, 2, 3))

Three anonymous functions, each called immediately

The body must be exactly one expression. A statement such as return, if as a block, for, while, import, assert or an assignment with = is a syntax error inside a lambda. A conditional expression like a if cond else b is fine, because it is an expression.

The best use of a lambda is a tiny key function that you hand to sorted, min, max or list.sort. These functions call your key once per item and compare the results. The logic is so small, and used in only one place, that giving it a name would add noise.

rows = [{'name': 'Asha', 'age': 31}, {'name': 'Ben', 'age': 24}, {'name': 'Chen', 'age': 28}]
print([r['name'] for r in sorted(rows, key=lambda r: r['age'])])

pairs = [('a', 3), ('b', 9), ('c', 5)]
print(max(pairs, key=lambda p: p[1]))

Sort rows by age; pick the pair with the biggest second item

Both calls read naturally: "sort the rows by their age" and "take the maximum pair by its second element". The lambda sits exactly where the idea is used.

The trade-off against def is about naming and readability. A named function appears by name in tracebacks, can carry a docstring, can be tested on its own and has room for several lines. The lambda's name is always <lambda>, as the next example shows.

add_one = lambda x: x + 1

def add_two(x):
    return x + 2

print(add_one.__name__)
print(add_two.__name__)

What an error message or a log line would show

Binding a lambda to a name, as in f = lambda x: x + 1, throws away the one thing a lambda is good for, which is being anonymous and inline. You get a function that still says <lambda> in every traceback, with no docstring. PEP 8 therefore recommends a def statement whenever the function needs a name. The example above with add_one is exactly the pattern to avoid.

Lambdas are also often used with map and filter, but a comprehension says the same thing with less ceremony. It reads left to right as "double x for each x that is positive", and it needs no nested lambdas.

xs = [-2, 3, 0, 5]
print(list(map(lambda x: x * 2, filter(lambda x: x > 0, xs))))
print([x * 2 for x in xs if x > 0])

Same result, very different readability

Another case where a lambda is unnecessary is when you only want to fix some arguments of an existing function. functools.partial does this directly. partial(pow, 2) is a new callable that already has 2 as its first argument, so calling it with 5 computes pow(2, 5). You can also fix keyword arguments.

from functools import partial

two_to = partial(pow, 2)
print(two_to(5), two_to(10))

from_binary = partial(int, base=2)
print(from_binary('101'))

partial fixes arguments without writing a lambda

A type hint (also called an annotation) tells the reader, and any checking tool, what kind of value a parameter expects and what the function gives back. You write it with a colon after the parameter name and an arrow before the final colon of the def line. The hint documents your intent; it does not change how the function runs.

def area(w: float, h: float = 1.0) -> float:
    return w * h

print(area.__annotations__)

Hints are stored on the function object, not thrown away

Python simply records the hints in a dictionary called __annotations__. The key return holds the hint for the result. Nothing reads that dictionary while your program runs, so a wrong type is not caught by the interpreter.

To see that nothing is enforced, pass a string where a float is promised. Python happily multiplies it, because str * int is legal.

print(area("ab", 3))

The hint says float, but Python does not object

The mistake only shows up when a tool such as mypy analyses the file, or when your editor underlines the call. The table lists the hint forms you will meet most often.

from typing import Callable

def apply(fn: Callable[[int], str], n: int) -> str:
    return fn(n)

def first_or_none(nums: list[int]) -> int | None:
    return nums[0] if nums else None

print(apply(lambda n: "#" * n, 3))
print(first_or_none([7]))
print(first_or_none([]))

Callable, list[int] and int | None in real signatures

A docstring is a string literal placed as the very first statement in a function body. Python stores it in the function's __doc__ attribute, and the built-in help(f) prints it nicely formatted. Editors show the same text when you hover over a call, so it is the documentation people actually read.

Start with a one-line summary in the imperative mood, such as Return the area of a rectangle., then leave a blank line. After that, list the arguments, the return value and any exceptions the function can raise.

def area(w: float, h: float = 1.0) -> float:
    """Return the area of a rectangle.

    Args:
        w: Width in metres.
        h: Height in metres. Defaults to 1.0.

    Returns:
        The area in square metres.

    Raises:
        ValueError: If w or h is negative.
    """
    if w < 0 or h < 0:
        raise ValueError("sizes must be non-negative")
    return w * h

print(area.__doc__.splitlines()[0])
print(area(3, 2))

The first line of __doc__ is the summary

Three layouts for the Args, Returns and Raises sections are common. All of them work with documentation tools, so the real rule is to choose one and use it everywhere in the project.

Hints and docstrings do different jobs, so a well-written function usually has both. A hint answers what types go in and out. A docstring explains why the function exists and how to use it: units, side effects, edge cases and the errors it raises. Neither one replaces tests, because tests are the only thing that actually runs your code against real inputs.

There is one trap that hints make easy to write. Giving a hinted parameter a mutable default such as items: list[int] = [] looks tidy, but the list is created once and shared by every call. The fix is the same as before: default to None and build the list inside the function.

def add(item: int, items: list[int] = []) -> list[int]:
    items.append(item)
    return items

def add_safe(item: int, items: list[int] | None = None) -> list[int]:
    if items is None:
        items = []
    items.append(item)
    return items

print(add(1))
print(add(2))
print(add_safe(1))
print(add_safe(2))

The hint does not stop the shared default

Most function bugs are not exotic. They come from a handful of habits that look reasonable when you write them and only misbehave when the function runs a second time, or when someone uses its result. This page covers the four most common ones. Each runs without any error, which is what makes them hard to spot.

A default value is built once, when def executes, not each time the function is called. If that default is a list, dict or set, every call that relies on it shares the same object, and anything one call appends is still there for the next. The usual fix is to use None as the default and create the fresh list inside the body.

def add_tag_bad(tag, tags=[]):
    tags.append(tag)
    return tags

def add_tag(tag, tags=None):
    if tags is None:
        tags = []
    tags.append(tag)
    return tags

print(add_tag_bad('a'))
print(add_tag_bad('b'))
print(add_tag('a'))
print(add_tag('b'))

The first pair shares one list; the second pair gets a new list per call.

A function that reaches the end of its body without a return hands back None. That is easy to cause by computing a value and forgetting to send it out. A close cousin is printing instead of returning: the number shows up on screen, so it feels finished, but the caller receives None and cannot use the value in further work. Finally, writing get_total without parentheses does not call anything. It names the function object, so you end up storing or passing the function when you meant its result.

def total(prices):
    s = 0
    for p in prices:
        s += p

def show_total(prices):
    print(sum(prices))

def get_total(prices):
    return sum(prices)

print(total([2, 3]))
x = show_total([2, 3])
print(x)
ref = get_total
print(type(ref).__name__, type(get_total([2, 3])).__name__)

Four lines, four different outcomes.

The next group of bugs comes from misunderstanding what a function can change outside itself. There are two separate questions: which name a statement refers to, and whether the statement rebinds that name or mutates the object behind it.

Python decides whether a name is local by looking at the whole function body before running it. If the body assigns to a name anywhere, including with +=, that name is local for the entire function. Reading it before the assignment then fails, because the local variable has no value yet. The global of the same name is not consulted. If you really mean to change the global, declare it with global count, or better, pass the value in and return the new one.

Python passes object references, a model often called pass by assignment. Inside the call, the parameter is a new name bound to the very same object the caller holds. Calling a method like xs.append(2) changes that shared object, so the caller sees it. Writing xs = [] only points the local name at a new list, and the caller's variable is untouched.

count = 0

def bump():
    count += 1

try:
    bump()
except UnboundLocalError as e:
    print(type(e).__name__)

def mutate(xs):
    xs.append(2)

def rebind(xs):
    xs = []

a = [1]
mutate(a)
print(a)
rebind(a)
print(a)

mutate changes the caller's list; rebind does not.

Names like list, sum, id and input are ordinary names that Python happens to define for you. If you assign to one of them, or use it as a parameter name, your version hides the built-in in that scope. The failure then shows up later, far from the line that caused it, as a confusing error such as an integer that is suddenly not callable.

sum = 10

try:
    sum([1, 2])
except TypeError as e:
    print(type(e).__name__, e)

del sum
print(sum([1, 2]))

Deleting the shadowing name makes the built-in visible again.

A function created inside a loop looks up the loop variable when it is called, not when it is created. By then the loop has finished and the variable holds its last value. Every function therefore reports the same number. Binding the current value as a default argument, i=i, freezes it at creation time.

A function that accepts **options will happily take any keyword, including a misspelled one, and the misspelled option is silently ignored. A function with explicit parameters rejects the typo with a TypeError. Recent Python versions (3.13 and newer) even add a hint to that message, ending with "Did you mean 'timeout'?", while 3.11 and 3.12 print the same message without the hint. That hint only appears for explicit parameters; it never fires when the name lands in **kwargs. The example prints only the error type so its output is identical on every version.

def connect_loose(host, **options):
    return options.get('timeout', 30)

def connect_strict(host, timeout=30):
    return timeout

print(connect_loose('db', timout=5))

try:
    connect_strict('db', timout=5)
except TypeError as e:
    print(type(e).__name__)

The loose version quietly uses 30 instead of 5.

Some problems are about shape rather than syntax. A function with six or more parameters is hard to call correctly, and a body nested three or four levels deep is hard to read and test. Either one usually means the function does more than one job.

A function header packs a lot into one line. Python reads the parameters in a fixed order, and a docstring then the body follow. The example below uses every kind of parameter at once, so you can see what each one collects.

def f(a, b=1, *args, key=None, **kw) -> int:
    """Add a, b and any extras; report the rest."""
    print("args:", args, "key:", key, "kw:", kw)
    return a + b + sum(args)

print(f(1))
print(f(1, 2, 3, 4, key="x", unit="cm"))

The docstring comes first, then the body. The arrow only documents the return type.

What a function hands back depends on its return statement. If it never reaches one, the caller gets None. If it returns several values separated by commas, Python quietly packs them into a single tuple, which you can unpack on the other side.

Default values are evaluated once, when the def line runs, not on every call. A list or dict used as a default is therefore one shared object that every call mutates. The cure is a None sentinel: test for it inside the body and build a fresh container there.

There are four ways to pass arguments. f(1, 2) matches by position. f(b=2, a=1) matches by name, so order no longer matters. f(*seq, **mapping) unpacks a sequence into positionals and a dict into keywords at the call site. Two markers in the signature can restrict how callers pass things.

When Python meets a name inside a function, it searches four places in a fixed order and stops at the first match. This is the LEGB rule.

Reading an outer name needs nothing special. You need global or nonlocal only when you want to rebind the name, meaning point it at a new object. Mutating an object, such as appending to a list, never needs either keyword.

Functions are ordinary objects. You can pass one as an argument, store it in a list or dict, and return it from another function. Everything in this page follows from that single fact.

A dispatch dict looks the function up by name and calls it, so adding a case means adding one entry. The closure example at the end shows late binding: a closure captures the *variable*, not its value at that moment. Every lambda in late therefore sees the final i. Writing i=i as a default freezes the current value for each lambda.

Interviewers like short, sharp questions on functions. Each one below has a one-line answer you should be able to give, then write or fix in under a minute.

Work out each answer in your head first, then open the answer. These questions ask you to predict what runs and to find the bug, so tracing the code matters more than remembering the rules.

• A function with no return, or a bare return, gives back None; return a, b gives back one tuple.
• Defaults are evaluated once when def runs, so use a None sentinel and is None for lists and dicts.
• *args is a tuple and **kwargs is a dict; a bare * makes later parameters keyword-only and / makes earlier ones positional-only.
• Names resolve Local, Enclosing, Global, Built-in; assigning to a name anywhere in a function makes it local for the whole function.
• Use global or nonlocal only to rebind a name, never to mutate, and remember closures capture variables, not values.
• Functions are objects: pass key=len, not key=len(words), and keep lambda for short one-expression throwaways.
• Type hints are not enforced at run time, and a docstring lives in __doc__.