Python Positional-Only Arguments Explained

Python introduced positional-only arguments in version 3.8. These arguments cannot be passed using keywords. They improve function clarity and prevent naming conflicts. This feature is part of Python's evolving syntax, like the Python Walrus Operator Explained and Python Match Case: Simplified Switch Statement.

Syntax and Basic Example

Positional-only parameters are defined using a slash (/) in the function signature. Parameters before the slash are positional-only. Parameters after can be positional or keyword.

def greet(name, /):
    # 'name' is positional-only
    print(f"Hello, {name}!")
    
greet("Alice")  # Works
greet(name="Alice")  # Raises TypeError
    

Hello, Alice!
Traceback (most recent call last):
  File "example.py", line 5, in <module>
greet(name="Alice")  # Raises TypeError
TypeError: greet() got some positional-only arguments passed as keyword arguments: 'name'
    

Mixing with Other Argument Types

Functions can combine positional-only, positional-or-keyword, and keyword-only arguments. The slash separates positional-only from others.

def example(pos_only, /, pos_or_kw, *, kw_only):
    # 'pos_only' is positional-only
    # 'pos_or_kw' accepts positional or keyword
    # 'kw_only' must be keyword
    print(f"Positional-only: {pos_only}")
    print(f"Positional-or-keyword: {pos_or_kw}")
    print(f"Keyword-only: {kw_only}")

example("pos", 42, kw_only="value")  # Works
# example(pos_only="pos", pos_or_kw=42, kw_only="value")  # Fails
    

Positional-only: pos
Positional-or-keyword: 42
Keyword-only: value
    

Common Errors and Pitfalls

Using a keyword for a positional-only argument raises a TypeError. Always pass these arguments positionally. For example:

def calculate(a, b, /):
    return a + b

calculate(a=5, b=3)  # Error
    

Traceback (most recent call last):
  File "example.py", line 3, in <module>
calculate(a=5, b=3)
TypeError: calculate() got some positional-only arguments passed as keyword arguments: 'a' and 'b'
    

Use Cases and Best Practices

Positional-only arguments are useful for functions with many parameters. They avoid conflicts with parameter names in calling code. For example, math functions like math.pow(base, exp, /) use them for clarity. They also improve performance slightly by avoiding keyword parsing. When designing APIs, use positional-only parameters for required values and keyword-only for optional ones. This pattern aligns with features like Python Chained Comparisons Explained for readable code.

Conclusion

Positional-only arguments enhance Python's flexibility. They enforce positional passing, reduce naming conflicts, and improve performance. By mastering this feature, you write cleaner, more maintainable functions. Combine them with other Python features like Python Operator Precedence for robust code.