Python *args and **kwargs

3*args and **kwargs: explained step by step

Some functions need to accept a number of values you cannot know in advance. print("a", "b", "c") takes any number of items, and so does max(3, 9, 4). Python lets your own functions do the same with two special parameters, *args and **kwargs. The diagram above shows where each kind of argument ends up.

*args: any number of positional arguments

A parameter with one star collects every extra positional argument into a tuple. Inside the function you loop over it, index it or pass it to sum() like any other tuple. If the caller passes nothing extra, you get an empty tuple, never an error.

def sum_all(*numbers):
    print(type(numbers).__name__, numbers)
    total = 0
    for n in numbers:
        total += n
    return total

print(sum_all(4, 6, 10))
print(sum_all())

The name args is only a habit. The star is what matters, so choose a name that says what the values are, such as *numbers or *messages.

**kwargs: any number of keyword arguments

A parameter with two stars collects every extra keyword argument into a dictionary. The keys are the argument names (as strings) and the values are what the caller passed. With no extra keywords, you get an empty dictionary.

def build_tag(name, text="", **attributes):
    attrs = "".join(f' {key}="{value}"' for key, value in attributes.items())
    return f"<{name}{attrs}>{text}</{name}>"

print(build_tag("a", "Docs", href="/docs", target="_blank"))
print(build_tag("p", "Hello"))

name and text are matched first. Only the keyword arguments that match no named parameter (href and target) land in attributes. This is how a function can accept options it has never heard of.

Combining them: the order matters

When a def line mixes several kinds of parameters, they must appear in this order:

1. normal parameters,
2. parameters with defaults,
3. *args,
4. keyword-only parameters (anything after *args can only be given by name),
5. **kwargs, always last.

def log(level, *messages, sep=" ", **context):
    text = sep.join(messages)
    extra = ", ".join(f"{key}={value}" for key, value in context.items())
    return f"[{level}] {text}" + (f" ({extra})" if extra else "")

print(log("INFO", "Server", "started"))
print(log("WARN", "Disk", "almost", "full", sep="-", host="web1", free="3%"))

Here level takes the first value, messages swallows the rest of the positional ones, sep can only be given by name, and context collects everything else.

Unpacking when you call

The same stars work in a call, in the opposite direction. * spreads a list, tuple or other iterable into separate positional arguments. ** spreads a dictionary into keyword arguments. You can use both, and more than once, in the same call.

def make_url(host, path, secure=True):
    scheme = "https" if secure else "http"
    return f"{scheme}://{host}/{path}"

parts = ["example.com", "docs"]
options = {"secure": False}
print(make_url(*parts))
print(make_url(*parts, **options))
print(make_url(**{"host": "example.com", "path": "login"}))

Unpacking is also the only way to pass a keyword that is a reserved word. You cannot write class="btn", but **{"class": "btn"} works fine.

Forwarding arguments to another function

A common job for *args and **kwargs is a wrapper: a function that adds something and hands every other argument to a second function unchanged. It does not need to know what the second function accepts.

def make_price(amount, currency="USD", decimals=2):
    return f"{currency} {amount:.{decimals}f}"

def labelled(label, *args, **kwargs):
    return label + ": " + make_price(*args, **kwargs)

print(labelled("Total", 49.5))
print(labelled("Total", 49.4, currency="EUR", decimals=0))

If make_price gains a new option tomorrow, labelled already supports it. Decorators, which come later, are built on exactly this pattern.

When not to use them

Flexible parameters hide what a function expects. A reader cannot see the options in the def line, and a typo such as hreff="/docs" is accepted silently because **attributes takes any name. If the set of inputs is fixed and known, write ordinary named parameters. Reach for *args and **kwargs when you really do not know the inputs (collecting values, wrapping other functions, passing options through).

Errors to recognise

• SyntaxError: positional argument follows keyword argument: in a call, put positional arguments first.
• TypeError: ... got multiple values for argument 'x': a name was filled twice, for example by a positional value and again by **options.
• TypeError: ... argument after * must be an iterable: you wrote *5 or *None; only lists, tuples and other iterables can be spread.
• SyntaxError: arguments cannot follow var-keyword argument: **kwargs has to be the last parameter in the def.