Learning Python - Mark Lutz [248]
func(**dict)
Caller
Pass all key/value pairs in dict as individual keyword arguments
def func(name)
Function
Normal argument: matches any passed value by position or name
def func(name=value)
Function
Default argument value, if not passed in the call
def func(*name)
Function
Matches and collects remaining positional arguments in a tuple
def func(**name)
Function
Matches and collects remaining keyword arguments in a dictionary
def func(*args, name)
def func(*, name=value)
Function
Arguments that must be passed by keyword only in calls (3.0)
These special matching modes break down into function calls and definitions as follows:
In a function call (the first four rows of the table), simple values are matched by position, but using the name=value form tells Python to match by name to arguments instead; these are called keyword arguments. Using a *sequence or **dict in a call allows us to package up arbitrarily many positional or keyword objects in sequences and dictionaries, respectively, and unpack them as separate, individual arguments when they are passed to the function.
In a function header (the rest of the table), a simple name is matched by position or name depending on how the caller passes it, but the name=value form specifies a default value. The *name form collects any extra unmatched positional arguments in a tuple, and the **name form collects extra keyword arguments in a dictionary. In Python 3.0 and later, any normal or defaulted argument names following a *name or a bare * are keyword-only arguments and must be passed by keyword in calls.
Of these, keyword arguments and defaults are probably the most commonly used in Python code. We’ve informally used both of these earlier in this book:
We’ve already used keywords to specify options to the 3.0 print function, but they are more general—keywords allow us to label any argument with its name, to make calls more informational.
We met defaults earlier, too, as a way to pass in values from the enclosing function’s scope, but they are also more general—they allow us to make any argument optional, providing its default value in a function definition.
As we’ll see, the combination of defaults in a function header and keywords in a call further allows us to pick and choose which defaults to override.
In short, special argument-matching modes let you be fairly liberal about how many arguments must be passed to a function. If a function specifies defaults, they are used if you pass too few arguments. If a function uses the * variable argument list forms, you can pass too many arguments; the * names collect the extra arguments in data structures for processing in the function.
The Gritty Details
If you choose to use and combine the special argument-matching modes, Python will ask you to follow these ordering rules:
In a function call, arguments must appear in this order: any positional arguments (value), followed by a combination of any keyword arguments (name=value) and the *sequence form, followed by the **dict form.
In a function header, arguments must appear in this order: any normal arguments (name), followed by any default arguments (name=value), followed by the *name (or * in 3.0) form if present, followed by any name or name=value keyword-only arguments (in 3.0), followed by the **name form.
In both the call and header, the **arg form must appear last if present. If you mix arguments in any other order, you will get a syntax error because the combinations can be ambiguous. The steps that Python internally carries out to match arguments before assignment can roughly be described as follows:
Assign nonkeyword arguments by position.
Assign keyword arguments by matching names.
Assign extra nonkeyword arguments to *name tuple.
Assign extra keyword arguments to **name dictionary.
Assign default values to unassigned arguments in header.
After this, Python checks to make sure each argument is passed just one value; if not, an