5.14. Defining functions

A function packages a block of code under a name so it can be called from many places. Anywhere a calculation, action, or shaped piece of work shows up more than once, a function turns it into a single named thing.

The keyword is def:

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

greet("Alice")
greet("Bob")

Output:

hello, Alice
hello, Bob

The line starting with def is the definition – it creates the function but does not run the body. Calling greet("Alice") is what runs the indented block.

5.14.1. Parameters and arguments

The names in the parentheses on the def line are parameters – placeholders for values the caller will supply. The actual values passed in are arguments. A function can take zero or more parameters:

def square(x):
    return x * x

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

def is_even(n):
    return n % 2 == 0

A call with the wrong number of arguments raises TypeError right away.

5.14.2. return

A return statement ends the function immediately and hands a value back to the caller:

def absolute(x):
    if x < 0:
        return -x
    return x

A function that never reaches a return (or has a bare return with no value) returns None:

>>> def shout(text):
...     print(text.upper())
...
>>> result = shout("hi")
HI
>>> print(result)
None

A function can have several return statements; the first one reached wins, and the rest of the body is skipped.

5.14.2.1. Returning multiple values

Python returns one object per call, but that object can be a tuple – and the caller can unpack it on the spot:

def minmax(values):
    return (min(values), max(values))

lo, hi = minmax([3, 1, 4, 1, 5, 9])

The parentheses around the return value are optional; return a, b and return (a, b) are the same.

5.14.3. Docstrings

A string literal placed as the first statement of a function body is a docstring. It is stored on the function object and is what help() displays:

def scale(value, factor):
    """Multiply ``value`` by ``factor`` and return the result."""
    return value * factor

The IDE shows docstrings in tooltips when the cursor hovers over the function name, so even a one-line summary pays for itself. Triple-quoted strings allow the docstring to span multiple lines when more detail is useful.

5.14.4. Naming conventions

Function names use snake_case – lowercase words separated by underscores. The name should describe what the function does:

  • Good: read_temperature, parse_header, is_valid.

  • Avoid: do_stuff, handle1, temp_func.

A leading underscore (_helper) marks a function as internal to its module. The convention is widely respected but not enforced by Python.