Variadic Keyword Parameter

A variadic keyword parameter allows a Python function to accept an arbitrary number of named arguments that are not explicitly defined in the function signature. Denoted by the double asterisk prefix (**), this parameter captures extraneous keyword arguments passed by the caller and packs them into a standard Python dictionary (dict).

While the parameter is conventionally named **kwargs, the double asterisk (**) is the actual syntactic operator; the identifier itself can be any valid Python variable name.

Syntax and Mechanics

When a function is invoked with keyword arguments that do not match any explicitly declared positional-or-keyword or keyword-only parameters, the Python interpreter intercepts them. It creates a dictionary where the keys are the argument names (as strings) and the values are the passed objects, and binds this dictionary to the variadic parameter.

def inspect_parameters(standard_arg, **kwargs):
    print(type(kwargs))
    print(kwargs)


# 'standard_arg' binds to 1.

# 'alpha' and 'beta' are packed into the **kwargs dictionary.
inspect_parameters(1, alpha="A", beta="B")


# Output:

# <class 'dict'>

# {'alpha': 'A', 'beta': 'B'}

Signature Constraints and Ordering

The Python parser enforces strict ordering rules for function signatures. The variadic keyword parameter must be the absolute last parameter defined in the function signature.

Since Python 3.8, the complete and strictly enforced parameter order is:

1. Positional-only arguments (denoted by /)
2. Positional-or-keyword arguments
3. Variadic positional arguments (*args)
4. Keyword-only arguments
5. Variadic keyword arguments (**kwargs)

# Correct ordering
def valid_signature(pos_only, /, pos_or_kw, *args, kw_only, **kwargs):
    pass


# SyntaxError: invalid syntax
def invalid_signature(**kwargs, pos_arg):
    pass

Additionally, a function signature may only contain exactly one variadic keyword parameter. Attempting to define multiple ** parameters will result in a SyntaxError.

Name Collision and Binding Rules

If a caller passes a keyword argument that matches the name of an explicitly defined positional-or-keyword or keyword-only parameter, the Python interpreter binds the value to that explicit parameter.

However, keyword arguments cannot bind to positional-only parameters (/) or the variadic positional parameter (*args). If a caller passes a keyword argument that shares a name with a positional-only parameter or the *args parameter, the interpreter treats it as unmatched and packs it into the **kwargs dictionary.

If a caller passes multiple keyword arguments with the exact same name, the interpreter raises a SyntaxError before the function executes.

def collision_check(pos_only, /, pos_or_kw, *args, **kwargs):
    print(f"Positional-only: {pos_only}")
    print(f"Positional-or-keyword: {pos_or_kw}")
    print(f"Variadic positional: {args}")
    print(f"Variadic keyword: {kwargs}")


# 'pos_only' is passed positionally.

# 'pos_or_kw' is matched by keyword.

# The keyword arguments 'pos_only' and 'args' cannot bind to the explicit parameters,

# so they are packed into kwargs.
collision_check(1, pos_or_kw=2, pos_only=3, args=4, extra=5)


# Output:

# Positional-only: 1

# Positional-or-keyword: 2

# Variadic positional: ()

# Variadic keyword: {'pos_only': 3, 'args': 4, 'extra': 5}

Argument Unpacking (Caller Side)

The ** operator functions inversely on the caller side. When invoking a function, prefixing a dictionary with ** unpacks its key-value pairs into individual keyword arguments. The keys in the dictionary must be strings, and they must align with the target function’s signature (unless the target function also implements a variadic keyword parameter).

def target_function(x, y, z):
    return x + y + z

payload = {'x': 10, 'y': 20, 'z': 30}


# The dictionary is unpacked into x=10, y=20, z=30
result = target_function(**payload) 

Master Python with Deep Grasping Methodology!

Learn More