Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~4 min readPython
#python functions#function arguments#keyword arguments#default parameters
Illustration of Python function parameters showing positional, keyword, default, and variable-length arguments.

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:

python
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.

python
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.

python
def add_item(item, items=[]): items.append(item) return items

The 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:

python
def add_item(item, items=None): if items is None: items = [] items.append(item) return items

This 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.

python
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.

python
def compare(a, b, /, *, key=None): pass

Here 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:

python
def bad(a, *args, **kwargs, b): # invalid: **kwargs must be last pass

The valid version keeps b before **kwargs. Because b appears after *args, it is automatically keyword-only:

python
def good(a, *args, b, **kwargs): pass

Similarly, **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 tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.