- Item 30: Know That Function Arguments Can Be Mutated
- Item 31: Return Dedicated Result Objects Instead of Requiring Function Callers to Unpack More Than Three Variables
- Item 32: Prefer Raising Exceptions to Returning None
- Item 33: Know How Closures Interact with Variable Scope and nonlocal
- Item 34: Reduce Visual Noise with Variable Positional Arguments
- Item 35: Provide Optional Behavior with Keyword Arguments
- Item 36: Use None and Docstrings to Specify Dynamic Default Arguments
- Item 37: Enforce Clarity with Keyword-Only and Positional-Only Arguments
- Item 38: Define Function Decorators with functools.wraps
- Item 39: Prefer functools.partial over lambda Expressions for Glue Functions
This chapter is from the book
This chapter is from the book
This chapter is from the book
Item 37: Enforce Clarity with Keyword-Only and Positional-Only Arguments
Passing arguments by keyword is a powerful feature of Python functions (see Item 35: “Provide Optional Behavior with Keyword Arguments”). Keyword arguments enable you to write flexible functions that will be clear to new readers of your code for many use cases.
For example, say that I want to divide one number by another while being very careful about special cases. Sometimes, I want to ignore ZeroDivisionError exceptions and return infinity instead. Other times, I want to ignore OverflowError exceptions and return zero instead. Here, I define a function with these options:
def safe_division(
number,
divisor,
ignore_overflow,
ignore_zero_division,
):
try:
return number / divisor
except OverflowError:
if ignore_overflow:
return 0
else:
raise
except ZeroDivisionError:
if ignore_zero_division:
return float("inf")
else:
raise
Using this function is straightforward. This call ignores the float overflow from division and returns zero:
result = safe_division(1.0, 10**500, True, False) print(result) >>> 0
This call ignores the error from dividing by zero and returns infinity:
result = safe_division(1.0, 0, False, True) print(result) >>> inf
The problem is that it’s easy to confuse the position of the two Boolean arguments that control the exception handling behavior. This can easily cause bugs that are hard to track down. One way to improve the readability of this code is to use keyword arguments. Using default keyword arguments (see Item 36: “Use None and Docstrings to Specify Dynamic Default Arguments”), the function can be overly cautious and can always re-raise exceptions:
def safe_division_b(
number,
divisor,
ignore_overflow=False, # Changed
ignore_zero_division=False, # Changed
):
...
Then, callers can use keyword arguments to specify which of the ignore flags they want to set for specific operations, overriding the default behavior:
result = safe_division_b(1.0, 10**500, ignore_overflow=True) print(result) result = safe_division_b(1.0, 0, ignore_zero_division=True) print(result) >>> 0 inf
The problem is, because these keyword arguments are optional behavior, there’s nothing forcing callers of your functions to use keyword arguments for clarity. Even with the new definition of safe_division_b, I can still call it the old way with positional arguments:
assert safe_division_b(1.0, 10**500, True, False) == 0
With complex functions like this, it’s better to require that callers are clear about their intentions by defining your functions with keyword-only arguments. These arguments can only be supplied by keyword, never by position.
Here, I redefine the safe_division function to accept keyword-only arguments. The * symbol in the argument list indicates the end of positional arguments and the beginning of keyword-only arguments (*args has the same effect; see Item 34: “Reduce Visual Noise with Variable Positional Arguments”):
def safe_division_c(
number,
divisor,
*, # Added
ignore_overflow=False,
ignore_zero_division=False,
):
...
Now, calling the function with positional arguments that correspond to the keyword arguments won’t work:
safe_division_c(1.0, 10**500, True, False) >>> Traceback ... TypeError: safe_division_c() takes 2 positional arguments but 4 ➥were given
But keyword arguments and their default values will work as expected (ignoring an exception in one case and raising it in another):
result = safe_division_c(1.0, 0, ignore_zero_division=True)
assert result == float("inf")
try:
result = safe_division_c(1.0, 0)
except ZeroDivisionError:
pass # Expected
However, a problem still remains with the safe_division_c version of this function: Callers may specify the first two required arguments (number and divisor) with a mix of positions and keywords:
assert safe_division_c(number=2, divisor=5) == 0.4 assert safe_division_c(divisor=5, number=2) == 0.4 assert safe_division_c(2, divisor=5) == 0.4
Later, I may decide to change the names of these first two arguments because of expanding needs or even just because my style preferences change:
def safe_division_d(
numerator, # Changed
denominator, # Changed
*,
ignore_overflow=False,
ignore_zero_division=False
):
...
Unfortunately, this seemingly superficial change breaks all of the existing callers that specified the number or divisor arguments using keywords:
safe_division_d(number=2, divisor=5) >>> Traceback ... TypeError: safe_division_d() got an unexpected keyword argument ➥'number'
This is especially problematic because I never intended for the keywords number and divisor to be part of an explicit interface for this function. These were just convenient parameter names that I chose for the implementation, and I didn’t expect anyone to rely on them explicitly.
Python 3.8 introduces a solution to this problem, called positional-only arguments. These arguments can be supplied only by position and never by keyword (the opposite of the keyword-only arguments demonstrated above).
Here, I redefine the safe_division function to use positional-only arguments for the first two required parameters. The / symbol in the argument list indicates where positional-only arguments end:
def safe_division_e(
numerator,
denominator,
/, # Added
*,
ignore_overflow=False,
ignore_zero_division=False,
):
...
I can verify that this function works when the required arguments are provided positionally:
assert safe_division_e(2, 5) == 0.4
But an exception is raised if keywords are used for the positional-only parameters:
safe_division_e(numerator=2, denominator=5) >>> Traceback ... TypeError: safe_division_e() got some positional-only arguments ➥passed as keyword arguments: 'numerator, denominator'
Now, I can be sure that the first two required positional arguments in the definition of the safe_division_e function are decoupled from callers. I won’t break anyone if I change the parameters’ names again.
One notable consequence of keyword- and positional-only arguments is that any parameter name between the / and * symbols in the argument list may be passed either by position or by keyword (which is the default for all function arguments in Python). Depending on your API’s style and needs, allowing both argument passing styles can increase readability and reduce noise. For example, here I’ve added another optional parameter to safe_division that allows callers to specify how many digits to use in rounding the result:
def safe_division_f(
numerator,
denominator,
/,
ndigits=10, # Changed
*,
ignore_overflow=False,
ignore_zero_division=False,
):
try:
fraction = numerator / denominator # Changed
return round(fraction, ndigits) # Changed
except OverflowError:
if ignore_overflow:
return 0
else:
raise
except ZeroDivisionError:
if ignore_zero_division:
return float("inf")
else:
raise
Now, I can call this new version of the function in all of these different ways, since ndigits is an optional parameter that may be passed either by position or by keyword:
result = safe_division_f(22, 7) print(result) result = safe_division_f(22, 7, 5) print(result) result = safe_division_f(22, 7, ndigits=2) print(result) >>> 3.1428571429 3.14286 3.14
Things to Remember
Keyword-only arguments force callers to supply certain arguments by keyword (instead of by position), which makes the intention of a function call clearer. Keyword-only arguments are defined after a * in the argument list (whether on its own or as part of variable arguments like *args).
Positional-only arguments ensure that callers can’t supply certain parameters using keywords, which helps reduce coupling. Positional-only arguments are defined before a single / in the argument list.
Parameters between the / and * characters in the argument list may be supplied by position or keyword, which is the default for Python parameters.