An Introduction to Python by Guido van Rossum and Fred L. Drake, Jr. Paperback (6"x9"), 124 pages ISBN 0954161769 RRP £12.95 ($19.95) Sales of this book support the Python Software Foundation! Get a printed copy>>>

An Introduction to Python Buy the book here! >>> support free software

4.7.2 Keyword Arguments

Functions can also be called using keyword arguments of the form ‘keyword = value’. For instance, the following function:

    def parrot(voltage, state='a stiff', action='voom',
               type='Norwegian Blue'):
        print "-- This parrot wouldn't", action,
        print "if you put", voltage, "volts through it."
        print "-- Lovely plumage, the", type
        print "-- It's", state, "!"

could 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')

but the following calls would all 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:

    >>> def function(a):
    ...     pass
    ... 
    >>> function(0, a=0)
    Traceback (most recent call last):
      File "<stdin>", line 1, in ?
    TypeError: function() got multiple values for
      keyword argument 'a'

When a final formal parameter of the form **name is present, it receives a dictionary containing all keyword arguments except for those corresponding to a formal parameter. This may be combined with a formal parameter of the form *name (described in the next subsection) which receives a tuple containing the positional arguments beyond the formal parameter list. (*name must occur before **name.) For example, if we define a function like this:

    def cheeseshop(kind, *arguments, **keywords):
        print "-- Do you have any", kind, '?'
        print "-- I'm sorry, we're all out of", kind
        for arg in arguments: print arg
        print '-'*40
        keys = keywords.keys()
        keys.sort()
        for kw in keys: print kw, ':', keywords[kw]

It could be called like this:

    cheeseshop('Limburger', "It's very runny, sir.",
               "It's really very, VERY runny, sir.",
               client='John Cleese',
               shopkeeper='Michael Palin',
               sketch='Cheese Shop Sketch')

and of course it would print:

    -- Do you have any Limburger ?
    -- I'm sorry, we're all out of Limburger
    It's very runny, sir.
    It's really very, VERY runny, sir.
    ----------------------------------------
    client : John Cleese
    shopkeeper : Michael Palin
    sketch : Cheese Shop Sketch

Note that the sort() method of the list of keyword argument names is called before printing the contents of the keywords dictionary; if this is not done, the order in which the arguments are printed is undefined.