Keyword argument demystify

There’s a lot of baffling among Python programmers on what exactly “keyword arguments” are. Let’s go through some of them.

If you somehow are writing for a Python 3 only codebase, I highly recommend making all your keyword arguments keyword only, especially keyword arguments that represent “options”.

There are many problems with this sentence. The first is that this is mixing up “arguments” (i.e. things at the call site) and “parameters” (i.e. things you declare when defining a function). So:

def foo(a, b):  # <- a and b are "parameters" or "formal arguments"
    pass

foo(1, 2)  # <- 1 and 2 are arguments to foo, that match a and b

This confusion is common among programmers. I also use the word “argument” when I mean “parameter”, because normally in conversation we can tell the difference in context. Even the documentation in the Python standard library uses these as synonyms.

The code above is the basic case with positional arguments. But we were talking about keyword arguments so let’s talk about those too:

def bar(a,    # <- this parameter is a normal python parameter
        b=1,  # <- this is a parameter with a default value
        *,    # <- all parameters after this are keyword only
        c=2,  # <- keyword only argument with default value
        d):   # <- keyword only argument without default value
    pass

So far so good. Now, let’s think about the statement we started with:

I highly recommend making all your keyword arguments keyword only

That implies there are keyword arguments that are not keyword only arguments. That’s sort of correct, but also very wrong. Let’s have some examples of usages of bar :

bar(1)         # one positional argument
bar(1, 2)      # two positional arguments
bar(a=1)       # one keyword argument
bar(a=1, b=2)  # two keyword arguments
bar(1, d=2)    # one positional and one keyword argument

The trick here is to realize that a “keyword argument” is a concept of the call site, not the declaration. But a “keyword only argument” is a concept of the declaration, not the call site. Super confusing!

There are also parameters that are positional only. The function sum in the standard library is like this: according to the documentation it looks like this:sum(iterable[, start]) But there’s a catch!

>>> sum(iterable=[1, 2])
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: sum() takes no keyword arguments

And the start parameter can’t be used as a keyword argument either, even though it’s optional! Recap

(I’m using “argument” here even though “parameter” or “formal argument” would be more correct, but the Python standard library uses these all as synonyms so I will too, so my wording matches the documentation.)

Python functions can have :

Arguments that can be used both as positional and keyword arguments (this is the most common case)
Arguments that can be used both as positional and keyword arguments with default values (or just “arguments with default values”)
Positional only arguments (like the first argument tosum, this is uncommon and can only be achieved by functions implemented in C)
Positional only arguments with default values (like above, only for C)
Optional positional only arguments (2nd argument to sum, like above, only for C)
Keyword only arguments
Keyword only arguments with default values
Arbitrary positional arguments ( *args )
Arbitrary keyword arguments ( **kwargs )

When calling Python functions you can have:

Positional arguments
Keyword arguments

It’s very simple at the call site, but a lot more complex at the function definition, and how call site arguments are mapped to the declaration is quite complex.

Summary

Python appears simple because most of these rules and distinctions are so well thought out that many programmers can go years in a professional career and believe defaults arguments and keyword arguments are the same, and never get bitten by this incorrect belief.

Summary#

Summary