Understanding Keyword-Only Function Arguments in Python

Zettel#116

zettelkasten
Published

2023-09-13

A lone * forces the rest of the arguments to be keyword-only arguments, meaning they must be specified as a keyword arguments.

def multiply(*, x, y):
        return x * y

The lone * before x and y means that they must be specified as keyword arguments.

So, if we were to try to call multiply with two positional arguments, we’ll get an error:

>>> multiply(1, 2)
Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
TypeError: multiply() takes 0 positional arguments but 2 were given

To call this function, we have to explicitly specify x and y as keyword arguments:

>>> multiply(x=1, y=2)
2

If we call this function with nothing you’ll see an error message similar to what we saw before about required keyword-only arguments:

>>> multiply()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: multiply() missing 2 required keyword-only arguments: 'x' and 'y'

So, whenever you see a function that uses * to capture any number of positional arguments (e.g. *args in the function definition), note that any arguments defined after that * capturing can only be specified as a keyword argument (they’re keyword-only arguments).

Additionally, if you come across a function with a lone * followed by a comma, that means that every argument after that point is a keyword-only argument (it must be specified by its name when that function is called).

References