Python Function Parameters: Syntax and Usage
Learn how Python function parameters work: positional, keyword, default, *args, **kwargs, and ordering rules for clean, maintainable function signatures.

When you define a function in Python, the parameter list determines how callers supply data. The way Python binds arguments to parameters affects not only syntax but also API design, error handling, and maintainability. Choosing the right parameter style can prevent subtle bugs and make your functions easier to use.
Positional Parameters and Their Order
The most basic parameter style is positional. Each parameter is matched to the argument by its position in the call. Consider this function:
def greet(name, greeting):
return f"{greeting}, {name}!"Calling greet("Alice", "Hello") works as expected. The first argument goes to name, the second to greeting. The order is fixed: swapping the arguments produces "Alice, Hello!" instead of "Hello, Alice!". Positional parameters are simple and fast, but they force callers to remember the exact order. For functions with many parameters, this becomes error-prone. The reader must check the function definition to know what each position means.
Keyword Arguments and Caller Flexibility
Python allows callers to pass arguments by name using keyword syntax. The same greet function can be called as greet(greeting="Hi", name="Bob"). The order of keyword arguments does not matter because each value is explicitly assigned to a parameter. This improves readability at the call site, especially when a function has several parameters with clear meanings.
def create_user(name, age, active=True):
# ...
pass
create_user(age=30, name="Carol", active=False)Keyword arguments also make it easier to skip optional parameters. If a function has defaults, callers can specify only the ones they need. However, mixing positional and keyword arguments requires care. Positional arguments must come before any keyword argument in a call, otherwise Python raises a SyntaxError.
Default Parameter Values and the Mutable Default Trap
Default parameter values let you define optional arguments without requiring the caller to pass them. They are evaluated once at function definition time, not on every call. This works fine for immutable values like integers, strings, or tuples, but it causes a classic bug when the default is a mutable object such as a list or dictionary.
def add_item(item, items=[]):
items.append(item)
return itemsThe default list items is created once and shared across all calls that omit the argument. Calling add_item("a") then add_item("b") returns ['a', 'b'] on the second call, even though the caller might expect a fresh list each time. The fix is to use None as the default and create a new mutable inside the function:
def add_item(item, items=None):
if items is None:
items = []
items.append(item)
return itemsThis pattern ensures each call gets its own list unless the caller explicitly passes one. The same applies to dictionaries, sets, and any other mutable type used as a default.
Variable-Length Parameters: *args and **kwargs
Sometimes a function needs to accept an arbitrary number of arguments. The *args parameter collects extra positional arguments into a tuple, and **kwargs collects extra keyword arguments into a dictionary. The names args and kwargs are conventions, not language requirements.
def log(level, *messages, **metadata):
print(level, messages, metadata)
log("INFO", "start", "end", user="alice", retries=3)Inside the function, messages is ("start", "end") and metadata is {"user": "alice", "retries": 3}. This pattern is common in decorators, wrappers, and functions that pass arguments through to another callable. However, *args and **kwargs reduce the clarity of the signature because the caller cannot see what parameters are actually accepted. Use them when flexibility is more important than explicit documentation, and validate the contents carefully.
Keyword-Only and Positional-Only Parameters
Python allows you to enforce how parameters are passed. Parameters after a bare * are keyword-only, meaning callers must use their name. Parameters before a / are positional-only, meaning callers cannot use their name. This syntax is useful for API design.
def compare(a, b, /, *, key=None):
passHere a and b are positional-only, so compare(a=1, b=2) is invalid. The key parameter is keyword-only, so compare(1, 2, key=len) works but compare(1, 2, len) does not. Positional-only parameters are often used when parameter order is meaningful and you want to keep parameter names out of the public API. Keyword-only parameters are useful for optional flags that should not be confused with positional data. This feature requires Python 3.8 or later for the / syntax.
Parameter Ordering Rules and Common Mistakes
The order of parameters in a function definition is not arbitrary. Python enforces a specific sequence: positional-only parameters, then positional-or-keyword parameters, then *args, then keyword-only parameters, then **kwargs. A common mistake is putting a parameter after **kwargs, because **kwargs must always be last. For example, the following definition is invalid:
def bad(a, *args, **kwargs, b): # invalid: **kwargs must be last
passThe valid version keeps b before **kwargs. Because b appears after *args, it is automatically keyword-only:
def good(a, *args, b, **kwargs):
passSimilarly, **kwargs cannot be placed before *args: *args collects extra positional arguments, and **kwargs must come last because it collects all remaining keyword arguments.
Maintainability and Runtime Considerations
Parameter style directly affects API stability. Adding a new optional parameter at the end of the signature is backward-compatible: existing calls still work. Removing a required parameter breaks every caller. Changing a positional parameter to keyword-only can also break code that relied on positional passing. When designing a public function, prefer keyword-only parameters for options that are likely to change or that have low readability as positional arguments.
Runtime cost is rarely a concern with parameter handling; in CPython, argument binding is implemented in C and is highly optimized. The real cost is in code clarity and error prevention. A function with too many positional parameters becomes hard to call correctly. A function that relies heavily on *args and **kwargs may hide bugs until runtime. Choose the parameter style that makes the function's contract obvious to the caller, and document any unusual ordering or constraints. The signature is the first thing a developer reads, so it should communicate intent as clearly as possible.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.