#6570: clarify tutorial section about keyword arguments.

This commit is contained in:
Ezio Melotti 2011-12-13 15:49:22 +02:00
parent 4a72d1a661
commit 05a7f0dcac
1 changed files with 22 additions and 17 deletions

View File

@ -383,8 +383,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,
@ -392,26 +392,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
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 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::
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