Python ** and * Parameters – What Do They Do?

argument-unpackingparameter-passingpythonsyntaxvariadic-functions

What do *args and **kwargs mean in these function definitions?

def foo(x, y, *args):
    pass

def bar(x, y, **kwargs):
    pass

_{See What do ** (double star/asterisk) and * (star/asterisk) mean in a function call? for the complementary question about arguments.}

Best Answer

The *args and **kwargs are common idioms to allow an arbitrary number of arguments to functions, as described in the section more on defining functions in the Python tutorial.

The *args will give you all positional arguments as a tuple:

def foo(*args):
    for a in args:
        print(a)        

foo(1)
# 1

foo(1, 2, 3)
# 1
# 2
# 3

The **kwargs will give you all keyword arguments as a dictionary:

def bar(**kwargs):
    for a in kwargs:
        print(a, kwargs[a])  

bar(name='one', age=27)
# name one
# age 27

Both idioms can be mixed with normal arguments to allow a set of fixed and some variable arguments:

def foo(kind, *args, bar=None, **kwargs):
    print(kind, args, bar, kwargs)

foo(123, 'a', 'b', apple='red')
# 123 ('a', 'b') None {'apple': 'red'}

It is also possible to use this the other way around:

def foo(a, b, c):
    print(a, b, c)

obj = {'b':10, 'c':'lee'}

foo(100, **obj)
# 100 10 lee

Another usage of the *l idiom is to unpack argument lists when calling a function.

def foo(bar, lee):
    print(bar, lee)

baz = [1, 2]

foo(*baz)
# 1 2

In Python 3 it is possible to use *l on the left side of an assignment (Extended Iterable Unpacking), though it gives a list instead of a tuple in this context:

first, *rest = [1, 2, 3, 4]
# first = 1
# rest = [2, 3, 4]

Also Python 3 adds a new semantic (refer PEP 3102):

def func(arg1, arg2, arg3, *, kwarg1, kwarg2):
    pass

Such function accepts only 3 positional arguments, and everything after * can only be passed as keyword arguments.

Note:

A Python dict, semantically used for keyword argument passing, is arbitrarily ordered. However, in Python 3.6+, keyword arguments are guaranteed to remember insertion order. "The order of elements in **kwargs now corresponds to the order in which keyword arguments were passed to the function." - What’s New In Python 3.6. In fact, all dicts in CPython 3.6 will remember insertion order as an implementation detail, and this becomes standard in Python 3.7.

Related Solutions

Double Star (**) and Star (*) in Python Function Calls – Meaning

A single star * unpacks a sequence or collection into positional arguments. Suppose we have

def add(a, b):
    return a + b

values = (1, 2)

Using the * unpacking operator, we can write s = add(*values), which will be equivalent to writing s = add(1, 2).

The double star ** does the same thing for a dictionary, providing values for named arguments:

values = { 'a': 1, 'b': 2 }
s = add(**values) # equivalent to add(a=1, b=2)

Both operators can be used for the same function call. For example, given:

def sum(a, b, c, d):
    return a + b + c + d

values1 = (1, 2)
values2 = { 'c': 10, 'd': 15 }

then s = add(*values1, **values2) is equivalent to s = sum(1, 2, c=10, d=15).

See also the relevant section of the tutorial in the Python documentation.

Similarly, * and ** can be used for parameters. Using * allows a function to accept any number of positional arguments, which will be collected into a single parameter:

def add(*values):
    s = 0
    for v in values:
        s = s + v
    return s

Now when the function is called like s = add(1, 2, 3, 4, 5), values will be the tuple (1, 2, 3, 4, 5) (which, of course, produces the result 15).

Similarly, a parameter marked with ** will receive a dict:

def get_a(**values):
    return values['a']

s = get_a(a=1, b=2)      # returns 1

this allows for specifying a large number of optional parameters without having to declare them.

Again, both can be combined:

def add(*values, **options):
    s = 0
    for i in values:
        s = s + i
    if "neg" in options:
        if options["neg"]:
            s = -s
    return s
        
s = add(1, 2, 3, 4, 5)            # returns 15
s = add(1, 2, 3, 4, 5, neg=True)  # returns -15
s = add(1, 2, 3, 4, 5, neg=False) # returns 15

Python Unpacking – How to Use Python’s Unpacking Operators * and **

Around 1992 (not sure about Python version). This is from the Grammar file of Python 1.0.1.

# 06-Apr-92:
#   Use only '*' for varargs list

# 31-Mar-92:
#   Tighten syntax for try statements

# 27-Feb-92:
#   Allow NEWLINE* after eval input

# 16-Jan-92:
#   Added '*' as alternative for '+' in varargs syntax
#   (Not sure which alternative is better yet.)

# 11-Jan-92:
#   Variable length argument list syntax added: def f(a, b, +rest): ...

Python 1.4+:

Keyword Arguments: Functions and methods written in Python can now be called using keyword arguments of the form keyword = value.

Python 1.6+

There's now special syntax that you can use instead of the apply() function. f(*args, **kwds) is equivalent to apply(f, args, kwds). You can also use variations f(a1, a2, *args, **kwds) and you can leave one or the other out: f(*args), f(**kwds).

Python <= 2.7:

Tuple parameter unpacking was removed in Python 3.0.

PEP 3113: Tuple parameter unpacking removed. You can no longer write def foo(a, (b, c)): .... Use def foo(a, b_c): b, c = b_c instead.

Python 3.0+

PEP 3132: Extended Iterable Unpacking. You can now write things like a, b, *rest = some_sequence. And even *rest, a = stuff. The rest object is always a (possibly empty) list; the right-hand side may be any iterable.

PEP 3102: Keyword-only arguments. Named parameters occurring after *args in the parameter list must be specified using keyword syntax in the call. You can also use a bare * in the parameter list to indicate that you don’t accept a variable-length argument list, but you do have keyword-only arguments

Python 3.5+

PEP 448, additional unpacking generalizations.

As far as I know there's no single page that lists all the syntax changes. Per version syntax changes are listed in the What's new in Python section or you could check the Grammar specification of each release to see the differences.

Best Answer

Note:

Related Solutions

Double Star (**) and Star (*) in Python Function Calls – Meaning

Python Unpacking – How to Use Python’s Unpacking Operators * and **

Related Question