diff options
| -rw-r--r-- | Doc/tutorial/controlflow.rst | 41 |
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 |