VMware ESXi and vSphere Cluster Management

Python Keyword Arguments in Functions

Learn how Python keyword arguments match values to parameter names, differ from positional arguments, work with defaults, and cause common TypeError messages.

What Is a Keyword Argument?

A function is reusable code that can be invoked with a function call. A function definition declares the function's name and its parameters. A parameter is a named variable that receives a value. An argument is the value supplied when the function is called.

A keyword argument supplies a value by writing the target parameter's name, an equals sign, and the value:

parameter_name=value

For example:

def describe_me(name, gender):
    print('My name:', name)
    print('My gender:', gender)

describe_me(name='Tuna', gender='M')

In the function definition, name and gender are parameters. In the function call, 'Tuna' and 'M' are argument values. The expressions name='Tuna' and gender='M' are keyword arguments because they identify the destination parameter by name.

Matching Arguments to Parameters by Name

Python associates a keyword argument with the parameter whose name appears before the equals sign. The keyword must exactly match a valid parameter name in the called function, including spelling, capitalization, and underscores.

def describe_me(name, gender):
    print(name, gender)

describe_me(gender='M', name='Tuna')

Although the call lists gender first, Python sends 'M' to gender and 'Tuna' to name. Matching is based on names, not positions.

Keyword Argument Order Does Not Matter

When arguments are written as keywords, their order can differ from the parameter order in the function definition. These calls assign values in the same way:

def describe_me(name, gender):
    print(name, gender)

describe_me(name='Tuna', gender='M')
describe_me(gender='M', name='Tuna')

Both calls set name to 'Tuna' and gender to 'M'. Reordering keyword arguments does not change their destinations.

Keyword Arguments Versus Positional Arguments

A positional argument is matched to a parameter according to its position in the call. In this example, the first value goes to name and the second value goes to gender:

def describe_me(name, gender):
    print(name, gender)

describe_me('Tuna', 'M')

The equivalent keyword-based call is:

describe_me(name='Tuna', gender='M')

Positional calls are concise, but keyword calls show what each value means. This is especially useful when several parameters have similar types, such as multiple strings, numbers, or Boolean values.

Feature	Positional argument	Keyword argument
How Python matches the value	By the value's position in the call	By the parameter name before `=`
Does call order matter?	Yes; values must follow parameter order	Keyword arguments may be reordered
Typical syntax	`function(value1, value2)`	`function(first=value1, second=value2)`
Readability	Can be less clear with many similar values	Often self-documenting because names describe values
Common mistakes	Using the wrong order or omitting a required value	Misspelling a parameter or assigning it twice

Keyword arguments are not automatically required. Ordinary parameters can generally receive values positionally or by keyword. The function declaration can impose special restrictions, such as keyword-only or positional-only parameters, but those are separate features.

Mixing Positional and Keyword Arguments

You may combine both forms in one call. The rule is simple: positional arguments must come first, followed by keyword arguments.

def introduce(name, city, language):
    print(name, city, language)

introduce('Tuna', city='Ankara', language='Python')

Here, 'Tuna' is matched positionally with name. The other two values are matched by their parameter names.

This ordering is valid:

introduce('Tuna', city='Ankara', language='Python')

This ordering is invalid:

introduce(name='Tuna', 'Ankara', language='Python')

Once a keyword argument appears, a later bare value would be a positional argument after a keyword argument. Python reports this as a syntax error. Convert the later value to a keyword argument or move it before the keyword arguments.

Call pattern	Valid?	Reason
All positional arguments	Yes	Values are matched in parameter order.
All keyword arguments	Yes	Values are matched by parameter name.
Positional arguments followed by keyword arguments	Yes	This is the permitted mixed order.
Keyword arguments followed by positional arguments	No	A positional argument cannot follow a keyword argument.
The same parameter supplied twice	No	One parameter cannot receive two argument values.

Keyword Arguments and Default Parameter Values

A default parameter value is a fallback value used when the caller does not provide an argument for that parameter.

def create_profile(name, role='student', active=True):
    print(name, role, active)

create_profile('Tuna')
# Tuna student True

The call omits role and active, so both defaults are used. A keyword argument can selectively override one default while leaving the others unchanged:

create_profile('Tuna', active=False)
# Tuna student False

The positional value 'Tuna' supplies name. The keyword argument supplies False to active. Because role is omitted, it keeps its default value of 'student'.

This is one of the most useful reasons to use keyword arguments. Without keywords, changing a later optional parameter may require explicitly supplying every earlier optional parameter:

create_profile('Tuna', 'student', False)

The keyword version communicates the intent more clearly and remains easier to maintain if the function has several optional settings:

create_profile('Tuna', active=False)

Common Call-Time Errors

Unexpected Keyword Argument

An unexpected keyword argument occurs when the call uses a name that the function does not accept.

def describe_me(name, gender):
    print(name, gender)

describe_me(name='Tuna', sex='M')

sex is not a parameter in this definition, so Python raises a TypeError similar to:

TypeError: describe_me() got an unexpected keyword argument 'sex'

Check the definition and use the exact parameter name, including its spelling and underscores.

Multiple Values for One Argument

A parameter receives multiple values when it is supplied once positionally and again by keyword:

def describe_me(name, gender):
    print(name, gender)

describe_me('Tuna', name='Ada', gender='M')

The first positional value already supplies name. The keyword name='Ada' tries to supply it a second time. Python raises an error similar to:

TypeError: describe_me() got multiple values for argument 'name'

Supply each parameter only once. Use either 'Tuna' positionally or name='Ada' by keyword.

Missing Required Arguments

A parameter without a default is required. The caller must supply a value for it either positionally or by keyword.

def introduce(name, city, language):
    print(name, city, language)

introduce(name='Tuna', city='Ankara')

The call does not supply language, so Python raises a TypeError indicating that a required argument is missing. Provide the missing value or define an appropriate default if the function design allows it.

Positional Argument After a Keyword Argument

This call has invalid ordering:

introduce(name='Tuna', 'Ankara', language='Python')

Python reports a syntax error similar to:

SyntaxError: positional argument follows keyword argument

Move the positional value before all keywords:

introduce('Tuna', city='Ankara', language='Python')

Alternatively, make every supplied value explicit:

introduce(name='Tuna', city='Ankara', language='Python')

Unexpected Values Caused by Positional Order

Positional arguments do not describe their destination. If their order is wrong, the function can receive valid values in the wrong parameters:

def schedule(day, month):
    print(day, month)

schedule(12, 3)

Python assigns 12 to day and 3 to month because of position. If the intended values are less obvious, use keywords:

schedule(day=12, month=3)

When troubleshooting unexpected results, check the documented parameter order or replace ambiguous positional arguments with explicit keywords.

Designing Readable Function Calls

Descriptive parameter names help both the function author and the caller. A call such as create_profile('Tuna', active=False) explains what False means without requiring the reader to look up the parameter order.

Keyword calls can make code self-documenting, especially for:

Functions with many parameters.
Parameters that have similar data types.
Optional settings with useful defaults.
Boolean flags whose meaning may not be obvious from True or False.

Use positional arguments when the order is obvious and the call is short. Use keyword arguments when clarity is more important than brevity. Neither style is universally required for ordinary parameters.

Quick Reference

A parameter is a named variable in a function definition.
An argument is a value supplied in a function call.
A keyword argument uses the form parameter_name=value.
A keyword must exactly match an accepted parameter name.
Positional arguments are matched by order.
Keyword arguments are matched by name and may be written in any order.
In a mixed call, place positional arguments before keyword arguments.
Omitted parameters with defaults keep their default values.
Required parameters must receive exactly one value.
Descriptive parameter names make keyword-based calls clearer.

Practice Example

def send_message(recipient, message, urgent=False, copies=0):
    print(recipient, message, urgent, copies)

send_message('Tuna', 'Meeting at 10')
send_message(message='Meeting at 10', recipient='Tuna')
send_message('Tuna', 'Meeting at 10', copies=2)
send_message('Tuna', 'Meeting at 10', urgent=True, copies=2)

In the first call, all values are positional. In the second, both values are keywords and appear in reverse parameter order. In the third, the first two values are positional and the later optional parameter is changed by keyword. In the fourth, all required values are positional and both optional settings are explicitly named.