Python Argument Unpacking

Intermediate

Python can unpack a collection at the moment you call a function. * supplies positional arguments from an iterable, while ** supplies keyword arguments from a mapping. This is the caller-side counterpart to the *args and **kwargs parameter forms already taught in Function Parameter Kinds.

Unpack an iterable into positional arguments

Place * before an iterable in a function call. Python expands its items as separate positional arguments.

1
2
3
4
5

def distance(x, y):
    return (x * x + y * y) ** 0.5

point = (3, 4)
print(distance(*point))

Unpack a mapping into keyword arguments

Place ** before a mapping in a function call. Its string keys are matched to parameters by name.

1
2
3
4
5
6

def connect(host, port, secure):
    protocol = "https" if secure else "http"
    print(f"{protocol}://{host}:{port}")

settings = {"host": "example.com", "port": 443, "secure": True}
connect(**settings)

Combine explicit arguments and unpacking

A call can combine ordinary positional arguments, *iterable, ordinary keyword arguments, and **mapping when the resulting arguments satisfy the function signature.

1
2
3
4
5
6
7

def build_url(scheme, host, path, secure=False):
    prefix = "https" if secure else scheme
    return f"{prefix}://{host}/{path}"

parts = ["example.com", "docs"]
options = {"secure": True}
print(build_url("http", *parts, **options))

Multiple iterable unpackings

A function call can contain more than one * unpacking. Python treats the produced items as additional positional arguments in the call.

1
2
3
4
5
6

def show(first, second, third, fourth):
    print(first, second, third, fourth)

left = ["A", "B"]
right = ["C", "D"]
show(*left, *right)

Multiple mapping unpackings

A call can also contain multiple ** mappings. Each mapping supplies additional keyword arguments; a parameter must not receive two values.

1
2
3
4
5
6

def profile(name, role, active):
    print(name, role, active)

identity = {"name": "Ada"}
status = {"role": "engineer", "active": True}
profile(**identity, **status)

The value must have the right kind

The operand after * must be iterable. The operand after ** must be a mapping whose keys are strings for a function call. If unpacking supplies an argument that conflicts with another value, Python raises a TypeError.

1
2
3
4
5
6
7
8

def add(left, right):
    return left + right

values = [10, 5]
print(add(*values))

options = {"left": 10, "right": 5}
print(add(**options))

Use unpacking when the data is already grouped

Argument unpacking is most useful when a list, tuple, or mapping already represents the arguments you need to pass. It avoids manually copying each value into a call and keeps the connection between the data structure and the function signature visible.

1
2
3
4
5
6

def rectangle_area(width, height):
    return width * height

measurements = (12, 7)
area = rectangle_area(*measurements)
print(area)