summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Doc/tutorial/controlflow.rst41
1 files changed, 23 insertions, 18 deletions
diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
index cb9597f..5ed5aea 100644
--- a/Doc/tutorial/controlflow.rst
+++ b/Doc/tutorial/controlflow.rst
@@ -412,8 +412,8 @@ write the function like this instead::
Keyword Arguments
-----------------
-Functions can also be called using keyword arguments of the form ``keyword =
-value``. For instance, the following function::
+Functions can also be called using :term:`keyword arguments <keyword argument>`
+of the form ``kwarg=value``. For instance, the following function::
def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
print("-- This parrot wouldn't", action, end=' ')
@@ -421,26 +421,31 @@ value``. For instance, the following function::
print("-- Lovely plumage, the", type)
print("-- It's", state, "!")
-could be called in any of the following ways::
+accepts one required argument (``voltage``) and three optional arguments
+(``state``, ``action``, and ``type``). This function can be called in any
+of the following ways::
- parrot(1000)
- parrot(action = 'VOOOOOM', voltage = 1000000)
- parrot('a thousand', state = 'pushing up the daisies')
- parrot('a million', 'bereft of life', 'jump')
+ parrot(1000) # 1 positional argument
+ parrot(voltage=1000) # 1 keyword argument
+ parrot(voltage=1000000, action='VOOOOOM') # 2 keyword arguments
+ parrot(action='VOOOOOM', voltage=1000000) # 2 keyword arguments
+ parrot('a million', 'bereft of life', 'jump') # 3 positional arguments
+ parrot('a thousand', state='pushing up the daisies') # 1 positional, 1 keyword
-but the following calls would all be invalid::
+but all the following calls would be invalid::
parrot() # required argument missing
- parrot(voltage=5.0, 'dead') # non-keyword argument following keyword
- parrot(110, voltage=220) # duplicate value for argument
- parrot(actor='John Cleese') # unknown keyword
-
-In general, an argument list must have any positional arguments followed by any
-keyword arguments, where the keywords must be chosen from the formal parameter
-names. It's not important whether a formal parameter has a default value or
-not. No argument may receive a value more than once --- formal parameter names
-corresponding to positional arguments cannot be used as keywords in the same
-calls. Here's an example that fails due to this restriction::
+ parrot(voltage=5.0, 'dead') # non-keyword argument after a keyword argument
+ parrot(110, voltage=220) # duplicate value for the same argument
+ parrot(actor='John Cleese') # unknown keyword argument
+
+In a function call, keyword arguments must follow positional arguments.
+All the keyword arguments passed must match one of the arguments
+accepted by the function (e.g. ``actor`` is not a valid argument for the
+``parrot`` function), and their order is not important. This also includes
+non-optional arguments (e.g. ``parrot(voltage=1000)`` is valid too).
+No argument may receive a value more than once.
+Here's an example that fails due to this restriction::
>>> def function(a):
... pass