Reference · module 10
Functions, further
Everything this module explains, on one page.
Default arguments
Make an argument optional.
- def greet(name, greeting="Hi") gives greeting a default, so callers may leave it out.
- Arguments with defaults must come after those without. Python refuses the other order outright.
- Never default to a list. The default is created once, so it is shared by every call — use None and build it inside.
The mistake you are about to make
def add(x, xs=[]):
def add(x, xs=None):
An empty list default reads as "empty every time". It is created once, when the function is defined, and shared: the second call inherits what the first left in it.
Naming the arguments
Pass arguments by name.
- Arguments normally match by position: the first value goes to the first parameter.
- You can name them instead: send(message="hi", urgent=True). Named ones may be given in any order.
- Naming pays off at the call: resize(img, True, False) says nothing, while resize(img, crop=True) does.
The mistake you are about to make
resize(img, True, False)
resize(img, crop=True, keep_ratio=False)
At the call site positional arguments say nothing: True and False tell the reader nothing at all. Names start paying for themselves by the third one.
Where a name lives
Know what a function can see.
- A name created inside a function exists only while that call runs. Afterwards it is gone.
- A function can READ a name from outside it. That is how it uses constants defined at the top of a file.
- But assigning to a name anywhere in the function makes it local for the whole function, which surprises people.
The mistake you are about to make
total += 1 inside a function, with total outside
take it as an argument and return the result
Reading an outer name works, so changing one looks like it should. Any assignment makes the name local for the whole function, and the read before it raises.
Returning more than one thing
Hand back several values.
- return a, b hands back both. Python wraps them in a tuple, so it is still one object.
- The caller can unpack it in one line: low, high = limits(). The counts on each side must match.
- return also ends the function immediately. Anything written after it on that path never runs.
The mistake you are about to make
low, high, mid = limits() where it returns a, b
low, high = limits()
Unpacking needs the counts on both sides to match. More names than values, or fewer, gives a ValueError that names both numbers.
Docstrings
Say what a function is for.
- A string on the first line of a function is its docstring. It is not a comment: Python keeps it.
- help(f) prints it, and editors show it when you hover a call. That is the payoff over a comment.
- Describe what it does and what it gives back. The how is in the body, right below.
The mistake you are about to make
a comment above the def
a docstring as the first line inside it
A comment above the function is only seen by someone reading the file. Python keeps a docstring: help() prints it and editors show it at the call.