Explain Keyword-Only Arguments (VarArgs) in Python [duplicate]
What part of docs.python.org/reference/expressions.html#calls confused you? Can you be more specific about which paragraph was not complete enough?
2 Answers 2
In your code numbers is assigned the (1,2,3) tuple. keywords is assigned a dictionary, containing vegetables and fruits .
One star ( * ) defines positional arguments. This means that you can receive any number of arguments. You can treat the passed arguments as a tuple.
Two stars ( ** ) define keywords arguments.
The reference material is available here.
Examples
Python 2.x (before keyword-only arguments)
def foo(x, y, foo=None, *args): print [x, y, foo, args] foo(1, 2, 3, 4) --> [1, 2, 3, (4, )] # foo == 4 foo(1, 2, 3, 4, foo=True) --> TypeError Python 3.x (with keyword-only arguments)
def foo(x, y, *args, foo=None): print([x, y, foo, args]) foo(1, 2, 3, 4) --> [1, 2, None, (3, 4)] # foo is None foo(1, 2, 3, 4, foo=True) --> [1, 2, True, (3, 4)] def combo(x=None, *args, y=None): . # 2.x and 3.x styles in one function Although a seasoned programmer understands what happened in 2.x, it’s counter-intuitive (a positional argument gets bound to foo= regardless of keyword arguments as long as there are enough positional arguments)
Python 3.x introduces more intuitive keyword-only arguments with PEP-3102 (keyword arguments after varargs can only be bound by name)
Thanks — more on this — so does that mean first argument is always a list/tuple and the second as dictionary?
Hi S.Lott — i read kgiannakakis explaination and then read docs.python.org/py3k/tutorial/… — it cleared my doubt — Thanks for checking
Let’s breakdown the function first.
This total function takes three parameters.
- initial=5 =>this is a keyword argument.
- *numbers =>this is a also known as *args. You can pass any number of arguments as you want.
- **keywords =>this is a keyword argument like a dictionary, each key that is associated with a given value.
*we know that initial is a keyword argument that contains a value of 5. So the value of 5 is now assigned to a variable called count.
*the number is a placeholder variable for numbers.
*we know that numbers is an arbitrary parameter so it can take any number of arguments or values.
*so now the number is going to contain the arguments which is passed in the numbers parameter while executing the function.
*each time it loops through the numbers arguments and adds the count to the number and returns a count
*when count is 5, it loops through the argument and adds the first instance of the argument. This will be repeated until the loop gets exhausted.
*this is tricky because this time the parameter is dictionary type which contains keys and corresponding values to that keys.
I know this answer is too big but understanding the underlying concept of each function is a core strength of a well rounded programmer.
PEP 3102 – Keyword-Only Arguments
This PEP proposes a change to the way that function arguments are assigned to named parameter slots. In particular, it enables the declaration of “keyword-only” arguments: arguments that can only be supplied by keyword and which will never be automatically filled in by a positional argument.
Rationale
The current Python function-calling paradigm allows arguments to be specified either by position or by keyword. An argument can be filled in either explicitly by name, or implicitly by position.
There are often cases where it is desirable for a function to take a variable number of arguments. The Python language supports this using the ‘varargs’ syntax ( *name ), which specifies that any ‘left over’ arguments be passed into the varargs parameter as a tuple.
One limitation on this is that currently, all of the regular argument slots must be filled before the vararg slot can be.
This is not always desirable. One can easily envision a function which takes a variable number of arguments, but also takes one or more ‘options’ in the form of keyword arguments. Currently, the only way to do this is to define both a varargs argument, and a ‘keywords’ argument ( **kwargs ), and then manually extract the desired keywords from the dictionary.
Specification
Syntactically, the proposed changes are fairly simple. The first change is to allow regular arguments to appear after a varargs argument:
def sortwords(*wordlist, case_sensitive=False): .
This function accepts any number of positional arguments, and it also accepts a keyword option called ‘case_sensitive’. This option will never be filled in by a positional argument, but must be explicitly specified by name.
Keyword-only arguments are not required to have a default value. Since Python requires that all arguments be bound to a value, and since the only way to bind a value to a keyword-only argument is via keyword, such arguments are therefore ‘required keyword’ arguments. Such arguments must be supplied by the caller, and they must be supplied via keyword.
The second syntactical change is to allow the argument name to be omitted for a varargs argument. The meaning of this is to allow for keyword-only arguments for functions that would not otherwise take a varargs argument:
The reasoning behind this change is as follows. Imagine for a moment a function which takes several positional arguments, as well as a keyword argument:
Now, suppose you wanted to have ‘key’ be a keyword-only argument. Under the above syntax, you could accomplish this by adding a varargs argument immediately before the keyword argument:
def compare(a, b, *ignore, key=None): .
Unfortunately, the ‘ignore’ argument will also suck up any erroneous positional arguments that may have been supplied by the caller. Given that we’d prefer any unwanted arguments to raise an error, we could do this:
def compare(a, b, *ignore, key=None): if ignore: # If ignore is not empty raise TypeError
As a convenient shortcut, we can simply omit the ‘ignore’ name, meaning ‘don’t allow any positional arguments beyond this point’.
(Note: After much discussion of alternative syntax proposals, the BDFL has pronounced in favor of this ‘single star’ syntax for indicating the end of positional parameters.)
Function Calling Behavior
The previous section describes the difference between the old behavior and the new. However, it is also useful to have a description of the new behavior that stands by itself, without reference to the previous model. So this next section will attempt to provide such a description.
When a function is called, the input arguments are assigned to formal parameters as follows:
- For each formal parameter, there is a slot which will be used to contain the value of the argument assigned to that parameter.
- Slots which have had values assigned to them are marked as ‘filled’. Slots which have no value assigned to them yet are considered ‘empty’.
- Initially, all slots are marked as empty.
- Positional arguments are assigned first, followed by keyword arguments.
- For each positional argument:
- Attempt to bind the argument to the first unfilled parameter slot. If the slot is not a vararg slot, then mark the slot as ‘filled’.
- If the next unfilled slot is a vararg slot, and it does not have a name, then it is an error.
- Otherwise, if the next unfilled slot is a vararg slot then all remaining non-keyword arguments are placed into the vararg slot.
- If there is a parameter with the same name as the keyword, then the argument value is assigned to that parameter slot. However, if the parameter slot is already filled, then that is an error.
- Otherwise, if there is a ‘keyword dictionary’ argument, the argument is added to the dictionary using the keyword name as the dictionary key, unless there is already an entry with that key, in which case it is an error.
- Otherwise, if there is no keyword dictionary, and no matching named parameter, then it is an error.
- If the vararg slot is not yet filled, assign an empty tuple as its value.
- For each remaining empty slot: if there is a default value for that slot, then fill the slot with the default value. If there is no default value, then it is an error.
In accordance with the current Python implementation, any errors encountered will be signaled by raising TypeError . (If you want something different, that’s a subject for a different PEP.)
Backwards Compatibility
The function calling behavior specified in this PEP is a superset of the existing behavior — that is, it is expected that any existing programs will continue to work.
Copyright
This document has been placed in the public domain.
Keyword-only arguments in Python
“Keyword-only arguments” is a Python feature that was added in version 3.0. But I’ve seen and used it much less use than I could have. It is described in PEP 3102, which is pretty readable, but I think the feature could benefit from more exposure with examples and rationale.
To understand keyword-only arguments, we first have to clear up a common misunderstanding about Python positional and keyword arguments. Consider the following function:
def print_greeting(name, use_colors=False): # .
We often think of this as having one positional argument and one keyword argument, and expect that calling code will use it like this:
print_greeting("Mary") print_greeting("Mary", use_colors=True) print_greeting("Mary", use_colors=False) # redundant but explicit
In fact, you can also call this function like the following (although it usually surprises me if I see these forms):
print_greeting("Mary", True) print_greeting(name="Mary") print_greeting(use_colors=True, name="Mary")
In other words, both arguments can be passed positionally or by name. Technically you should think about positional or keyword arguments as being defined by the function call and not the function definition. (If you know your computer science terminology, the function definition defines parameters, while it is the function call that defines arguments, which has now confused me about whether the PEP should really have been titled “Keyword-only parameters”…)
The correct distinction between name and use_colors is that use_colors has a default argument value, while name does not.
Having got that cleared up, we can now separate in our minds two different concerns:
- When people call our function, should we encourage/expect/force them to use a keyword argument, or a positional one?
- Do we have a good default for each of the parameters?
With Python’s keyword-only arguments we can address these two independently.
To make it impossible to pass use_colors positionally, we can define it like this:
def print_greeting(name, *, use_colors=False): # .
This brings some advantages:
- It makes the calling code more explicit (but also more verbose). It will no longer be possible to see code like:
Once we have these keyword-only arguments, we can also ask “do we actually have good default values?” Let’s say we realise that the use of color codes is something that is very important and must be passed every time our print_greeting function is used – we don’t have a good default. We can write our function like this:
def print_greeting(name, *, use_colors): pass
print_greeting("Mary", use_colors=True)
If the caller fails to pass use_colors , they see this error message:
TypeError: print_greeting() missing 1 required keyword-only argument: 'use_colors'
I haven’t seen keyword-only arguments that much in the wild, which I think is a shame. But now that Python 2 is much less of a concern for me, I’m going to be making much more use of this feature.
For further reading – the twin of this is positional only parameters, a more recent feature that makes it impossible to pass an argument by name.
You may also like: §