Introduction: Positional-Only and Keyword-Only Parameters in Python
A function can normally receive an argument by position or by using the parameter name. This gives the caller flexibility in how the function is called.
Sometimes, however, a function should control this flexibility. A parameter may need to accept a value only by position, or it may need to require the parameter name.
Python provides positional-only and keyword-only parameters for these situations. A positional-only parameter must be passed by position, while a keyword-only parameter must be passed by keyword.
Python uses the / and * symbols to define these rules in a function definition. The following sections explain positional-only and keyword-only parameters in Python, including how each parameter type works and how they can be combined with other parameter types.
Important: Positional and keyword arguments describe how an argument is passed, while positional-only and keyword-only parameters define how an argument is allowed to be passed.
A] Positional-Only Parameters in Python
Definition: A positional-only parameter is a parameter that Python allows only as a positional argument.
➤ It must receive its value through its position in the function call.
➤ You cannot pass it using its parameter name.
For example, the following function makes name positional-only:
def greet(name, /):
print("Hello,", name)Explanation: The name parameter is written before the /, so Python treats it as positional-only. This means the value for name must be passed by position when calling the function.
The / Syntax
Python uses / in a function definition to mark the end of positional-only parameters. Parameters written before / are positional-only.
def greet(name, /):
print("Hello,", name)Explanation: Here, name appears before /, so it is positional-only.
The / does not create a parameter. It only tells Python that the parameters before it must be passed positionally.
Passing Positional-Only Arguments
Pass a positional-only argument by placing its value in the correct position in the function call.
Example
def greet(name, /):
print("Hello,", name)
greet("Alice")
# Output:
Hello, AliceExplanation: Here, "Alice" is passed by position, so it is assigned to the positional-only parameter name.
What Happens When a Positional-Only Parameter Is Passed by Keyword?
Python raises a TypeError if you try to pass a positional-only parameter using its name.
Example
def greet(name, /):
print("Hello,", name)
greet(name="Alice")
# Error:
TypeErrorExplanation: Here, name="Alice" is a keyword argument. The parameter name is positional-only, so Python does not allow this call.
Pass the value by position instead:
greet("Alice")When to Use Positional-Only Parameters
Use positional-only parameters when callers should pass a value by position rather than by parameter name.
They can also help keep a function’s parameter names from becoming part of the calling interface. This can make it easier to change an internal parameter name later without changing existing calls.
B] Keyword-Only Parameters in Python
Definition: A keyword-only parameter is a parameter that Python allows only as a keyword argument.
➤ It must receive its value using the parameter name in the function call.
➤ Python does not allow the value to be passed by position.
For example, the following function makes age keyword-only:
def introduce(name, *, age):
print("Name:", name)
print("Age:", age)Explanation: Here, name can be passed by position or by keyword, while age must be passed by keyword.
The * Syntax
Python uses a standalone * to mark the beginning of keyword-only parameters.
When *args is used, parameters written after *args are also keyword-only.
def introduce(name, *, age):
print("Name:", name)
print("Age:", age)Explanation: Here, name appears before *, so it is a regular parameter. The * marks the end of regular parameters. The age parameter appears after *, so it is keyword-only.
The * in this form does not collect arguments. It only marks the parameters that must be passed by keyword.
Passing Keyword-Only Arguments
Pass a keyword-only argument by writing the parameter name followed by = and its value.
Example
def introduce(name, *, age):
print("Name:", name)
print("Age:", age)
introduce("Alice", age=25)
# Output:
Name: Alice
Age: 25Explanation: Here, "Alice" is passed positionally to name. The age=25 argument is passed by keyword to the keyword-only parameter age.
What Happens When a Keyword-Only Parameter Is Passed Positionally?
Python raises a TypeError if you pass a keyword-only parameter by position.
Example
def introduce(name, *, age):
print("Name:", name)
print("Age:", age)
introduce("Alice", 25)
# Error:
TypeErrorExplanation: Here, 25 is passed by position. The age parameter is keyword-only, so Python does not allow this call.
Pass the value with its parameter name instead:
introduce("Alice", age=25)When to Use Keyword-Only Parameters
Use keyword-only parameters when a function has optional settings or values that should be clear in the function call.
def send_message(message, *, priority, language):
print(message)
print(priority)
print(language)
send_message(
"Your order is ready.",
priority="High",
language="English"
)Explanation: The parameter names make the purpose of "High" and "English" clear. Passing them positionally would make the call harder to understand.
Common Mistakes With Positional-only and Keyword-only Parameters in Python
The rules of positional-only and keyword-only parameters in Python are simple, but it is easy to pass an argument in the wrong way. Python raises a TypeError when a positional-only parameter is passed by keyword or a keyword-only parameter is passed by position.
The following links take you directly to each common mistake:
1. Passing a Positional-Only Parameter by Keyword
A positional-only parameter must receive its value by position. Passing it with its parameter name is not allowed.
Error: Passing a Positional-Only Parameter by Keyword
def greet(name, /):
print("Hello,", name)
greet(name="Alice")
# Error:
TypeErrorExplanation: Here, name is positional-only, but the function call passes it as a keyword argument.
Correct: Passing the Parameter by Position
Pass the value by position instead of using the parameter name.
greet("Alice")Explanation: Here, "Alice" is passed by position, so the function call follows the rule for the positional-only parameter.
2. Passing a Keyword-Only Parameter by Position
A keyword-only parameter must receive its value using its parameter name.
Error: Passing a Keyword-Only Parameter by Position
def introduce(name, *, age):
print(name, age)
introduce("Alice", 25)
# Error:
TypeError
Explanation: Here, age is keyword-only, but 25 is passed by position.
Correct: Passing the Parameter by Keyword
Use the parameter name when passing a value to a keyword-only parameter.
introduce("Alice", age=25)
Explanation: Here, age=25 passes the value using the parameter name, so the function call follows the keyword-only rule.
3. Confusing / and *
The / and * symbols control different parts of a function definition. Confusing their roles can lead to incorrect parameter rules.
Example: Understanding / and *
def func(a, /, b, *, c):
passais positional-only.bis a regular parameter.cis keyword-only.
Explanation: The / marks the end of positional-only parameters, while * marks the beginning of keyword-only parameters.
Correct: Using / and * for Their Intended Rules
Use / after the positional-only parameters and * before the keyword-only parameters.
def func(a, /, b, *, c):
pass
Explanation: In this definition, a must be passed by position, b can be passed by position or keyword, and c must be passed by keyword.
4. Assuming a Default Value Changes the Passing Rule
A default value makes a parameter optional, but it does not change how the parameter must be passed.
Error: Passing a Positional-Only Parameter by Keyword
def greet(name="Guest", /):
print("Hello,", name)
greet(name="Alice")
# Error:
TypeError
Explanation: The default value makes name optional, but / still makes it positional-only. Therefore, a supplied value must still be passed by position.
Correct: Passing the Positional-Only Parameter by Position
greet("Alice")
Explanation: Here, "Alice" is passed by position, so the call follows the positional-only rule.
Example: Default Value With a Keyword-Only Parameter
The same principle applies to keyword-only parameters. A default value makes the parameter optional, but it does not remove the requirement to use its parameter name when a value is supplied.
def greet(*, name="Guest"):
print("Hello,", name)
greet(name="Alice")
Explanation: Here, the default value makes name optional, but it remains keyword-only because it appears after *.
Key Takeaways: Positional-only and keyword-only parameters
Here are the key takeaways to remember about positional-only and keyword-only parameters in Python and how they control the way callers pass arguments:
- Parameters before
/are positional-only. - Positional-only parameters must be passed by position.
- Parameters after a standalone
*or*argsare keyword-only. - Keyword-only parameters must be passed using their parameter names.
- The
/symbol marks the end of the positional-only section. - A standalone
*or*argsmarks the beginning of the keyword-only section. - A default value does not change a parameter’s passing rule.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.