Python Keyword Parameter

A keyword argument is a value passed to a function by explicitly assigning it to a named parameter defined in the function signature. In Python semantics, a parameter is the named variable declared in the function definition, whereas an argument is the actual value bound to that parameter during invocation. Passing arguments by keyword binds the value to the parameter by its identifier rather than by its positional index.

def configure_server(host, port, protocol):
    # 'host', 'port', and 'protocol' are parameters
    pass


# Invocation using keyword arguments
configure_server(protocol="https", host="127.0.0.1", port=443)

Syntactic Rules and Evaluation

Order Independence Because the mapping is resolved via the parameter identifier, the order of keyword arguments in the invocation does not need to match the order of parameters defined in the function signature. Positional Precedence When mixing positional and keyword arguments in a single call, all positional arguments—including those provided via iterable unpacking (*iterable)—must strictly precede all keyword arguments. Violating this rule results in a SyntaxError.

# Valid: Standard positional precedes keyword
configure_server("127.0.0.1", protocol="https", port=443)

# Valid: Unpacked positional precedes keyword
configure_server(*["127.0.0.1", 443], protocol="https")

# Invalid: Standard positional follows keyword (Raises SyntaxError)

# configure_server(host="127.0.0.1", 443, protocol="https")

# Invalid: Unpacked positional follows keyword (Raises SyntaxError)

# configure_server(protocol="https", *["127.0.0.1", 443])

Parameter Uniqueness An identifier can only be bound once per function call. Passing a value positionally and subsequently attempting to bind the same parameter via a keyword argument raises a TypeError.

# Invalid: 'host' receives multiple values (Raises TypeError)

# configure_server("127.0.0.1", host="localhost", port=443, protocol="https")

Keyword-Only Parameters (`*`)

Python allows the definition of parameters that must be passed as keyword arguments. This is enforced by placing a bare asterisk (*) or a variadic positional parameter (*args) before the target parameters in the function signature.

def initialize_node(node_id, *, strict_mode, timeout):
    pass


# strict_mode and timeout must be passed by keyword
initialize_node(1024, strict_mode=True, timeout=30)

Positional-Only Parameters (`/`)

Conversely, Python 3.8 introduced the forward slash (/) to denote positional-only parameters. Any parameters defined before the / in the function signature cannot be passed as keyword arguments.

def calculate_hash(data, /, algorithm="sha256"):
    pass

# Valid: 'data' passed positionally
calculate_hash(b"payload", algorithm="md5")

# Invalid: 'data' passed as a keyword argument (Raises TypeError)

# calculate_hash(data=b"payload")

Variadic Keyword Parameters (`**kwargs`)

A function can accept an arbitrary number of keyword arguments by prefixing a parameter name with a double asterisk (**). During execution, Python packs these unmatched keyword arguments into a dictionary bound to that parameter identifier.

def build_profile(username, **attributes):
    # 'attributes' is evaluated as a dict: {'role': 'admin', 'active': True}
    pass

build_profile("sysadmin", role="admin", active=True)

Dictionary Unpacking

Existing dictionaries can be unpacked directly into keyword arguments during a function call using the ** operator. The dictionary keys must be valid strings. These keys must either match the function’s explicitly named parameters or, if the function signature includes a variadic keyword parameter (**kwargs), be captured by that variadic parameter.

config_dict = {"host": "10.0.0.1", "port": 8080, "protocol": "http"}


# Unpacks into: host="10.0.0.1", port=8080, protocol="http"
configure_server(**config_dict)


# With **kwargs, keys do not need to match explicitly named parameters
extra_attributes = {"role": "admin", "active": True}
build_profile("sysadmin", **extra_attributes)