Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Statements and Keywords

*args, **kwargs and parameters

Reference for Python function parameters: positional, keyword-only and positional-only parameters, defaults, *args, **kwargs and argument unpacking.

A Python function can declare several kinds of parameters, and each kind controls how callers may pass values. Plain parameters accept positional or keyword arguments, *args collects extra positional arguments into a tuple, and **kwargs collects extra keyword arguments into a dictionary.

The names args and kwargs are only conventions. What matters is the * and ** in front of them. The same symbols also work in calls, where they unpack a sequence or a mapping into arguments.

Python
def show(a, b=2, /, c=3, *args, d, e=5, **kwargs):
    ...
# a, b: positional-only | c: normal | *args | d, e: keyword-only | **kwargs

Try it

Python Collecting extra arguments

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Unpacking in calls and special markers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Syntax

Python
def f(pos_only, /, normal, *args, kw_only, **kwargs): ...

f(1, 2, 3, 4, kw_only=5, extra=6)
f(*sequence, **mapping)
Form Description
name Normal parameter: may be passed by position or by keyword.
name=default Parameter with a default value, used when the caller omits it. Must come after parameters without defaults, except keyword-only ones.
name, / Everything before / is positional-only (Python 3.8+).
*args Collects any extra positional arguments into a tuple.
* (alone) Marks everything after it as keyword-only, without collecting anything.
**kwargs Collects any extra keyword arguments into a dict. Must be last.

Order of parameters: positional-only, /, normal, *args (or bare *), keyword-only, **kwargs.

Raises: TypeError when an argument is missing, repeated, unexpected or passed the wrong way (for example a positional-only name used as a keyword).

Usage notes

  • args is a tuple, kwargs is a dict. Both are new objects for each call, so changing them does not affect the caller's data.
  • Keyword-only parameters after *args or a bare * make call sites self-explanatory (connect(host, timeout=5)) and let you add options later without breaking old calls.
  • Positional-only parameters (before /) free you to rename them later and allow names like a to appear in **kwargs without a clash.
  • Mutable defaults are shared. A default such as items=[] is created once, when def runs. Use None and create the list inside the function.
  • Unpacking in calls with * accepts any iterable, ** any mapping with string keys. Duplicate keyword names raise TypeError.
  • Forwarding. Wrappers commonly accept *args, **kwargs and pass them on unchanged. This is how decorators avoid knowing the wrapped signature.
  • Too much flexibility hurts. A function that takes only *args, **kwargs hides its interface from readers and tools; prefer explicit parameters when you can.
  • Unpacking in displays ([*a, *b], {**x, **y}) works since Python 3.5; later keys win in dictionary merges.