Positional, keyword, and default arguments are the three ways that a value reaches a function, and Python binds them in a strict and documented order. Once you know that order, the confusing TypeError messages become completely predictable. This lesson walks through the binding rules, explains why a mutable default argument is a well known trap, and shows you how positional-only and keyword-only parameters give you more control.
The previous lesson in this module covered "Defining and Calling Functions", and the next lesson in this module is about "*args, **kwargs and Unpacking Arguments".
How does Python bind arguments to parameters?
When you call a function, Python matches the values that you supplied to the parameters that you declared, and it does this in a fixed order of operations. Positional values are consumed first, and they fill the parameters from left to right. Keyword values are matched by name, in whatever order you wrote them. Any parameter that is still unfilled afterwards falls back to its default value. If a parameter has no default and is still unfilled, the call fails immediately with TypeError: missing 1 required positional argument.
def make_label(prefix, item, quantity=1):
return prefix + item + ' x' + str(quantity)
print(make_label('Box ', 'tea'))
print(make_label('Box ', 'tea', 3))
print(make_label(item='tea', prefix='Box '))
print(make_label('Box ', item='tea', quantity=2))
Notice the fourth call. The positional value fills prefix, the keyword value fills item, and the default fills quantity. Mixing the two styles is completely legal as long as every positional value comes before every keyword value in the call.
The parameters in a definition are not all alike. Python recognises five kinds, and knowing which kind you are looking at tells you exactly how a caller may pass it.
| Parameter kind | Written as | How callers may pass it |
|---|---|---|
| Positional-only | def f(a, /) | By position only, and the name is invisible to callers |
| Positional-or-keyword | def f(a) | By position or by name |
| Keyword-only | def f(*, a) | By name only |
| Var-positional | def f(*args) | Any number of extra positional values |
| Var-keyword | def f(**kwargs) | Any number of extra keyword values |
What is the difference between positional and keyword arguments?
Positional arguments rely on order. Swap two of them and the function still runs, but it now means something different, and that is why a positional call becomes fragile the moment a signature has more than two parameters. Keyword arguments rely on names, so the order stops mattering and the call site documents itself.
def connect(host, port, timeout, retries):
return host + ':' + str(port) + ' timeout=' + str(timeout) + ' retries=' + str(retries)
print(connect('db.internal', 5432, 30, 3))
print(connect(host='db.internal', port=5432, timeout=30, retries=3))
print(connect('db.internal', port=5432, timeout=30, retries=3))
The third line is the one worth remembering. Positional values must come first and keyword values after. Writing connect(port=5432, 'db.internal') is a SyntaxError, because Python cannot tell which parameter the second positional value was meant for once you started naming things explicitly.
There is a real cost to keyword arguments as well, and it shows up in a busy loop. Building a keyword call means that Python assembles a dictionary for the call, while a plain positional call skips that work. For a function that is called millions of times, positional arguments are measurably cheaper. For a function that is called a handful of times, the clarity of connect(host=..., port=...) is worth much more. Decide per call site instead of by dogma.
Supplying the same parameter twice is also an error, and the message names the culprit. Note that the two failure modes are different. The compiler rejects a repeated keyword, while the interpreter rejects a parameter that received both a positional value and a keyword value.
def connect(host, port):
return host + ':' + str(port)
try:
connect('db.internal', 5432, port=3306)
except TypeError as error:
print('TypeError:', error)
When should you use default arguments?
A default says "this parameter is optional, and here is what it means when the caller says nothing". That is exactly the right tool for configuration knobs such as a timeout, a page size, or a separator. It is the wrong tool for data that the function genuinely cannot work without, because a default silently invents a value that may make no sense for the caller's data.
Python enforces one ordering rule in a definition. A parameter without a default cannot follow one that has a default, and the compiler rejects it at parse time, long before your program runs.
# A parameter without a default cannot follow one with a default.
source = 'def broken(a=1, b): pass'
try:
compile(source, '', 'exec')
except SyntaxError as error:
print('SyntaxError:', error.msg)
When a signature mixes required and optional parameters, keep the required ones first. If that feels awkward, make the optional ones keyword-only, and the ordering problem disappears completely.
Defaults also change what a function's signature promises to a type checker. With def scale(value, factor=2), a checker knows that scale(x) returns the same type as scale(x, 2) does. With def scale(value, factor=None), the checker has no idea what None turns into, so you are forced to handle that case yourself. Defaults are part of the interface, and the interface should tell the truth about what the function does with the value it was given.
Why are mutable default arguments a trap?
Default values are worked out once, when the def statement runs, and not on every call. A default of [] therefore creates one list that every call to the function shares. Append to that list and the next caller inherits your leftovers.
def collect(item, bucket=[]):
bucket.append(item)
return bucket
print(collect('apple'))
print(collect('pear'))
That is the classic symptom of a shared default. The second call shows a list that holds both items, even though the caller only ever passed a pear. The fix is to use None as a sentinel and to build the real default inside the body of the function.
def collect(item, bucket=None):
if bucket is None:
bucket = []
bucket.append(item)
return bucket
print(collect('apple'))
print(collect('pear'))
Immutable defaults such as 0, '', or None are safe, because the caller cannot change them in place. The trap only bites when the default is a list, a dictionary, or a set.
How do positional-only and keyword-only parameters work?
A forward slash in the parameter list marks every parameter to its left as positional-only. A lone asterisk marks every parameter to its right as keyword-only. Both have been available since Python 3.8, and both exist to protect you from yourself.
def send(sender, recipient, /, *, subject, body='', urgent=False):
tag = 'URGENT ' if urgent else ''
return (tag + 'from ' + sender + ' to ' + recipient + ': '
+ subject + ' ' + body).strip()
print(send('[email protected]', '[email protected]', subject='Welcome'))
print(send('[email protected]', '[email protected]',
subject='Deadline', body='Submit by Friday', urgent=True))
Marking sender and recipient as positional-only stops a caller from writing sender='x', recipient='y', which sounds friendlier but breaks the moment you rename a parameter. Marking the rest as keyword-only means that the order of subject, body, and urgent can never be misremembered, and it lets you add a new keyword-only parameter later without breaking any existing call.
Positional-only parameters are also the right choice when a parameter name is a poor description. If your function has two parameters called mode, the name alone cannot tell the calls apart, so you make them positional-only and let the position carry the meaning. The standard library does this constantly. str.replace(old, new, count) would be confusing if you were allowed to write replace(new='x').
What to remember
The error messages are precise if you read them properly, so keep this table next to you while you are debugging.
| Error message | What you did | Fix |
|---|---|---|
missing 1 required positional argument | Forgot a parameter that has no default | Pass it, or give it a default |
got multiple values for argument 'x' | Supplied the same parameter twice | Remove the duplicate |
takes from 1 to 2 positional arguments but 3 were given | Passed too many positional values | Drop the extra, or accept it with *args |
parameter without a default follows parameter with a default | Wrote the signature in the wrong order | Reorder it, or make the later ones keyword-only |
got an unexpected keyword argument 'x' | A typo, or the parameter is positional-only | Check the spelling and the parameter kind |
Now try it yourself. Build a schedule_job function with name and hour as required positional parameters, minute=0 and recurring=False as keyword-only parameters with defaults, and a signature that still forces minute and recurring to be named. Call it five ways, including one call that raises a TypeError, and paste the error text into a comment. Then write a second version with a mutable default, call it twice, and explain in a comment why the second result is different from the first.