Keyword-Only and Positional-Only

Concepts covered: Lambda

Python fills parameters from positional arguments strictly left to right and never asks what the values mean. A call that passes 2 integers in the wrong order runs cleanly and hands back a wrong integer. This refund helper takes an amount and a processing fee, and both are counts of cents.

def net_refund(amount_cents, fee_cents):
    return amount_cents - fee_cents

print(net_refund(2500, 25))
print(net_refund(25, 2500))

The first call returns 2475 and the second returns -2475. A reviewer reading net_refund(25, 2500) cannot tell which number is the fee, and Python raises nothing. The cure is to make the caller write the names.

Keyword-only: every parameter after *

A bare * in a signature closes the positional slots. Each parameter after it must be passed as name=value, and a positional value aimed at one of them raises TypeError before the body runs.

def net_refund(*, amount_cents, fee_cents):
    return amount_cents - fee_cents

print(net_refund(amount_cents=2500, fee_cents=25))
print(net_refund(fee_cents=25, amount_cents=2500))

try:
    net_refund(2500, 25)
except TypeError as err:
    print("TypeError:", err)

Output:

2475
2475
TypeError: net_refund() takes 0 positional arguments but 2 were given

Named arguments may arrive in any order because Python matches them by name. The rule mirrors *args: a parameter written after *args can only be filled by keyword, since *args swallows every remaining positional value. A bare * keeps that rule and accepts no extra values. A keyword-only parameter with no default is still required, so net_refund(amount_cents=2500) fails with missing 1 required keyword-only argument: 'fee_cents'.

Positional-only: every parameter before /

A / works the other way. Parameters to its left can only be filled by position, so no call site ever writes their names. Because no caller depends on those names, you can rename the parameters later without breaking anything, and the name stays free inside **kwargs, which matters when callers pass arbitrary labels.

def add_labels(event_id, /, **labels):
    for key, value in labels.items():
        print(event_id, key, value)

add_labels("evt_1", event_id="legacy_42", region="eu")

Output:

evt_1 event_id legacy_42
evt_1 region eu

Without the /, the keyword event_id="legacy_42" would collide with the positional "evt_1", and Python would raise add_labels() got multiple values for argument 'event_id'. With it, the label lands in labels beside region.

All 3 zones in a single signature

Where the parameter sitsHow the caller passes itWhen to choose it
Before `/`By position onlyThe name is internal and may change
Between `/` and `*`By position or by nameOrdinary parameters with no special risk
After `*`By name onlyValues a reader could swap or misread
def charge(account_id, /, amount_cents, *, currency):
    print(account_id, amount_cents, currency)

charge("acct_9", 1200, currency="usd")
charge("acct_9", amount_cents=1200, currency="usd")

try:
    charge(account_id="acct_9", amount_cents=1200, currency="usd")
except TypeError as err:
    print("TypeError:", err)

try:
    charge("acct_9", 1200, "usd")
except TypeError as err:
    print("TypeError:", err)

Output:

acct_9 1200 usd
acct_9 1200 usd
TypeError: charge() got some positional-only arguments passed as keyword arguments: 'account_id'
TypeError: charge() takes 2 positional arguments but 3 were given

The first 2 calls differ only in how amount_cents arrives, and the middle zone accepts it either way. Naming account_id breaks the / rule. Passing "usd" as a third positional value breaks the * rule: the signature has 2 positional slots, and Python reports 3 values for them.

Which call to export_table runs without raising TypeError?

def export_table(table, /, path, *, fmt, overwrite=False):
    print(table, path, fmt, overwrite)

About this lesson

This section is part of the Functions: Advanced lesson on DataDriven, the home of data engineering. Lessons cover SQL, Python, Spark, data modeling and pipeline architecture, and each section pairs its explanation with worked examples and practice you run as you go.