{"title":"Keyword Arguments","description":"","content":"Every Python function call passes arguments either by position (the order they appear) or by name (`parameter=value`). Named calls survive refactors, document the call site, and let you skip parameters that have defaults. Python also provides a way to require named calls (keyword-only parameters) and a way to forbid them (positional-only parameters), so function signatures can be shaped around how they should be used. This lesson covers the call-site choice, the rules for mixing positional and keyword arguments, and the two markers (`*` and `/`) that pin down which kind a parameter accepts.\n\n---\n\n# Two Ways to Pass an Argument\n\nA function defined with regular parameters accepts both positional and keyword calls. Take this small order-pricing function:\n\n\n```python\ndef price_order(quantity, unit_price, discount):\n return quantity * unit_price * (1 - discount)\n\n# Positional: arguments match parameters by order.\nprint(price_order(3, 29.99, 0.10))\n\n# Keyword: arguments match parameters by name.\nprint(price_order(quantity=3, unit_price=29.99, discount=0.10))\n\n# Mixed: positional first, then keyword.\nprint(price_order(3, 29.99, discount=0.10))\n```\n\n\nAll three calls produce the same value. The first call relies on the reader to know that the first argument is the quantity, the second is the price, and the third is the discount. The second call says so explicitly. The third call mixes the two: positional for the first two, keyword for the last.\n\nThe positional version is shorter, and for a function with two or three obvious parameters that's often fine. The keyword version is longer but reads on its own. `price_order(3, 29.99, 0.10)` requires knowing the signature to understand it. `price_order(quantity=3, unit_price=29.99, discount=0.10)` explains itself at the call site.\n\nA keyword call also lets you pass arguments in any order, because Python matches by name instead of position:\n\n\n```python\ndef price_order(quantity, unit_price, discount):\n return quantity * unit_price * (1 - discount)\n\n# Order doesn't matter when using keywords.\nprint(price_order(discount=0.10, unit_price=29.99, quantity=3))\nprint(price_order(unit_price=29.99, quantity=3, discount=0.10))\n```\n\n\nThe values land in the right slots regardless of the order at the call site. That flexibility matters less than it sounds (a consistent order still aids readability), but it's the foundation for the rules that follow.\n\n---\n\n# Mixing Positional and Keyword Arguments\n\nThe two styles can mix in one call, with one rule: **positional arguments come first, keyword arguments come last**. Once a `name=value` appears, every argument after it has to be a keyword too.\n\n\n```python\ndef add_to_cart(customer, product, quantity, gift_wrap):\n return f\"{customer} bought {quantity}x {product} (wrap={gift_wrap})\"\n\n# Allowed: positional first, then keyword.\nprint(add_to_cart(\"alice\", \"Wireless Mouse\", quantity=2, gift_wrap=True))\n\n# Allowed: all positional.\nprint(add_to_cart(\"alice\", \"Wireless Mouse\", 2, True))\n\n# Allowed: all keyword.\nprint(add_to_cart(customer=\"alice\", product=\"Wireless Mouse\", quantity=2, gift_wrap=True))\n```\n\n\nThe order between positional arguments still matches the parameter order. `\"alice\"` lands in `customer` because it's first; `\"Wireless Mouse\"` lands in `product` because it's second. The keyword arguments fill in by name, so `quantity=2` and `gift_wrap=True` can appear in either order without changing the result.\n\nPutting a positional after a keyword is a `SyntaxError`:\n\n\n```python\ndef add_to_cart(customer, product, quantity, gift_wrap):\n return f\"{customer} bought {quantity}x {product} (wrap={gift_wrap})\"\n\nprint(add_to_cart(\"alice\", product=\"Wireless Mouse\", 2, True))\n```\n\n\nThe parser flags it before the program runs. The fix is to either move the positional before the keyword (`add_to_cart(\"alice\", \"Wireless Mouse\", 2, True)`) or convert it to a keyword (`add_to_cart(\"alice\", product=\"Wireless Mouse\", quantity=2, gift_wrap=True)`).\n\nA subtler error happens when the same parameter is passed twice, once positionally and once by name:\n\n\n```python\ndef add_to_cart(customer, product, quantity, gift_wrap):\n return f\"{customer} bought {quantity}x {product}\"\n\nprint(add_to_cart(\"alice\", \"Wireless Mouse\", 2, customer=\"bob\"))\n```\n\n\n`\"alice\"` already filled `customer` positionally, and then `customer=\"bob\"` tried to fill it again. Python raises an error rather than picking one. The fix is straightforward: don't bind the same parameter twice.\n\n---\n\n# Why Use Keyword Arguments\n\nThree things make keyword arguments more than a stylistic choice.\n\nThe first is **readability at the call site**. A function with two or three parameters that all mean obvious things can stand a positional call. A function with five booleans cannot. Compare these:\n\n\n```python\ndef process_order(items, customer, address, gift_wrap, express, signature_required):\n pass\n\n# Positional: which True is which?\nprocess_order([\"Mouse\"], \"alice\", \"123 Main St\", True, False, True)\n\n# Keyword: every flag explains itself.\nprocess_order(\n items=[\"Mouse\"],\n customer=\"alice\",\n address=\"123 Main St\",\n gift_wrap=True,\n express=False,\n signature_required=True,\n)\n```\n\n\nThe positional version is shorter by a wide margin, but it can't be read without the signature in front of you. Booleans, in particular, are a magnet for keyword-argument style: `gift_wrap=True` says what's on; a bare `True` doesn't.\n\nThe second is **refactoring safety**. If a function reorders its parameters in a new version, every positional call has to change with it. Keyword calls keep working as long as the names stay stable.\n\n\n```python\n# Old version of the API.\ndef price_order(quantity, unit_price, discount):\n return quantity * unit_price * (1 - discount)\n\n# Positional callers locked in the order: quantity, price, discount.\nprint(price_order(3, 29.99, 0.10))\n\n# New version: discount is now the second parameter.\ndef price_order(quantity, discount, unit_price):\n return quantity * unit_price * (1 - discount)\n\n# Positional caller is now wrong (silently): 29.99 became the discount.\nprint(price_order(3, 29.99, 0.10))\n\n# Keyword caller still works.\nprint(price_order(quantity=3, discount=0.10, unit_price=29.99))\n```\n\n\nThe positional call still runs but produces a nonsense number because the second argument is now a discount, not a price. The keyword call doesn't depend on order, so it survives the change.\n\nThe third is **skipping parameters with defaults**. When some parameters have defaults, keyword calls let the caller set only the ones that matter and leave the rest alone.\n\n\n```python\ndef place_order(customer, items, delivery=\"standard\", gift_wrap=False, express=False):\n return f\"{customer}: {items}, delivery={delivery}, gift_wrap={gift_wrap}, express={express}\"\n\n# Skip both gift_wrap and delivery, only set express.\nprint(place_order(\"alice\", [\"Wireless Mouse\"], express=True))\n\n# Set just gift_wrap.\nprint(place_order(\"bob\", [\"USB Cable\"], gift_wrap=True))\n```\n\n\nWithout keyword arguments, every default to keep would need an explicit placeholder, as in older languages. With keywords, set what's meant and leave the rest.\n\nKeyword argument dispatch is slightly slower per call than positional dispatch (Python has to match names against the signature), but the difference is well under a microsecond and rarely matters. Pick the style that reads, not the one that's measurably faster.\n\n---\n\n# Keyword-Only Parameters\n\nSome functions have parameters that shouldn't be passed by position. Boolean flags, configuration knobs, and rarely-set options usually fall in this group. Python lets such parameters be marked as **keyword-only**: parameters the caller is required to pass by name, even when they have defaults.\n\nThe marker is a single `*` in the parameter list. Every parameter to the right of the `*` is keyword-only.\n\n\n```python\ndef place_order(customer, items, *, delivery=\"standard\", gift_wrap=False):\n return f\"{customer}: {items}, delivery={delivery}, gift_wrap={gift_wrap}\"\n\n# Allowed: delivery and gift_wrap are passed by name.\nprint(place_order(\"alice\", [\"Wireless Mouse\"], delivery=\"express\", gift_wrap=True))\n\n# Positional is fine for the parameters before the *.\nprint(place_order(\"bob\", [\"USB Cable\"]))\n```\n\n\nThe `*` doesn't bind to a parameter itself; it's a marker that says \"no more positional arguments past here\". `customer` and `items` are still ordinary parameters and can be passed positionally or by name. `delivery` and `gift_wrap` can only be passed by name.\n\nPassing a keyword-only parameter positionally is an error:\n\n\n```python\ndef place_order(customer, items, *, delivery=\"standard\", gift_wrap=False):\n pass\n\nplace_order(\"alice\", [\"Wireless Mouse\"], \"express\", True)\n```\n\n\nThe function accepts exactly two positional arguments (`customer` and `items`). The other two arguments have to come in by name. The error message points at \"2 positional arguments\", which is exactly what the `*` enforces.\n\nAny parameter that sits **between** `*args` and `**kwargs` is also keyword-only, because all the positional slots are already absorbed by `*args`. The bare `*` is the same idea without collecting anything; it's a fence.\n\n\n```python\ndef log_event(event_type, *items, level=\"INFO\", target=\"stdout\"):\n return f\"[{level}->{target}] {event_type}: {items}\"\n\nprint(log_event(\"add_to_cart\", \"Wireless Mouse\", \"USB Cable\", level=\"DEBUG\"))\nprint(log_event(\"clear_cart\", target=\"syslog\"))\n```\n\n\n`*items` collects extra positionals, and `level` and `target` sit after it, so they're keyword-only. The call site reads cleanly: the items come first, the named options come after.\n\nKeyword-only parameters have one other property: they don't need defaults. A keyword-only parameter without a default is a **required keyword argument**, meaning the caller has to pass it by name and can't omit it.\n\n\n```python\ndef transfer_funds(from_account, to_account, *, amount):\n return f\"transfer {amount} from {from_account} to {to_account}\"\n\nprint(transfer_funds(\"checking\", \"savings\", amount=100))\n\n# Missing amount: TypeError.\nprint(transfer_funds(\"checking\", \"savings\"))\n```\n\n\nRequired keyword arguments are a useful pattern when omitting a value would be dangerous (transferring zero by accident) or when the argument's meaning is ambiguous without its name (`amount=100` versus `100`). The function refuses to run unless the caller is explicit.\n\n\n```mermaid\nflowchart LR\n Call[\"place_order('alice', ['Mouse'],
delivery='express',
gift_wrap=True)\"]:::cyan\n\n Pos1[\"customer
'alice'
(positional or keyword)\"]:::orange\n Pos2[\"items
['Mouse']
(positional or keyword)\"]:::orange\n Star[\"* marker
(no parameter here)\"]:::red\n KW1[\"delivery
'express'
(keyword-only)\"]:::green\n KW2[\"gift_wrap
True
(keyword-only)\"]:::green\n\n Call --> Pos1\n Call --> Pos2\n Call --> Star\n Call --> KW1\n Call --> KW2\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThe orange parameters accept either style. The red `*` is the fence (not a real parameter). The green parameters can only come in by name.\n\n---\n\n# Positional-Only Parameters\n\nThe opposite marker is `/`, which makes the parameters to its **left** positional-only. The caller cannot pass them by name. This was added in Python 3.8 by PEP 570.\n\n\n```python\ndef cart_total(prices, /):\n return sum(prices)\n\nprint(cart_total([29.99, 14.99, 9.99]))\n\n# Keyword call: TypeError.\nprint(cart_total(prices=[29.99, 14.99, 9.99]))\n```\n\n\nThe `/` is a marker, not a parameter. Everything to its left is positional-only. The first call works because it passes the list positionally. The second call uses the name `prices`, which Python rejects because that name isn't part of the public interface.\n\nThere are three reasons to use this.\n\nThe first is **mirroring built-ins**. Built-in functions like `len`, `abs`, `pow`, and `divmod` accept positional arguments only, and they always have. `len(obj=mylist)` isn't valid because the `obj` name isn't part of the contract. PEP 570 gave pure-Python functions the same ability, so a library can write a function that behaves like a built-in.\n\nThe second is **allowing parameter renames**. If a parameter is positional-only, the function can rename it in a new version without breaking any caller, since the old name was never visible at call sites. This matters for library maintainers cleaning up parameter names without forcing a breaking change.\n\n\n```python\n# Version 1\ndef discount(p, /, rate):\n return p * (1 - rate)\n\n# Version 2: parameter renamed from `p` to `price`.\ndef discount(price, /, rate):\n return price * (1 - rate)\n\n# Every caller of version 1 used positional for the first arg.\n# Version 2 still works for them, because the name was never visible.\nprint(discount(100, rate=0.10))\n```\n\n\nThe third is **freeing the name for `**kwargs`**. If a function takes `**kwargs` and one of its real parameters has a common name like `name` or `id`, callers might want to pass `name=\"alice\"` as part of the kwargs. Marking the real parameter positional-only lets the same call work for both purposes.\n\n\n```python\ndef tag_resource(name, /, **attributes):\n return {\"name\": name, \"attributes\": attributes}\n\nprint(tag_resource(\"Wireless Mouse\", color=\"black\", weight=120))\n\n# Pass another `name` into the kwargs; the positional-only parameter doesn't conflict.\nprint(tag_resource(\"Wireless Mouse\", color=\"black\", name=\"primary\"))\n```\n\n\nWithout `/`, the second call would bind `name=\"primary\"` to the parameter and crash because `\"Wireless Mouse\"` already filled it. With `/`, the parameter `name` is positional-only and the keyword `name` in the call ends up inside `**attributes` cleanly.\n\nPositional-only is a library-design tool, not something for everyday application code. For a function called from one or two places in the same codebase, regular parameters are fine. For a published API with external callers, `/` provides the freedom to refactor parameter names later.\n\nThe `/` has no runtime cost. It's a compile-time marker. The interpreter uses it to decide which call shapes are legal, but once the function runs, positional-only parameters are regular local names.\n\n---\n\n# The Full Parameter Signature\n\nCombining the two markers gives the most general shape of a Python function signature. From left to right:\n\n1. Positional-only parameters (before `/`).\n2. The `/` marker.\n3. Parameters that accept either style (after `/` and before `*`).\n4. `*args` (or a bare `*` to mark the rest as keyword-only).\n5. Keyword-only parameters (after `*` or `*args`).\n6. `**kwargs`.\n\nNot every signature uses all the slots, and most don't. A typical function might use slots 3 and 5; a library API might use 1, 3, 5, and 6. The order is fixed; slots can be omitted but not reordered.\n\nA contrived but legal signature that uses every slot:\n\n\n```python\ndef make_order(customer, /, items, *, delivery=\"standard\", **options):\n return {\n \"customer\": customer,\n \"items\": items,\n \"delivery\": delivery,\n \"options\": options,\n }\n\nprint(make_order(\"alice\", items=[\"Wireless Mouse\"]))\nprint(make_order(\"alice\", [\"Wireless Mouse\"], delivery=\"express\", gift_wrap=True))\n```\n\n\nReading this signature: `customer` is positional-only (before `/`), `items` can be passed either way (between `/` and `*`), `delivery` is keyword-only with a default (after `*`), and `**options` collects any other keyword arguments. The two calls show the shape: `customer` always comes in positionally, `items` can be either, `delivery` is always named, and extra named arguments fall through to `options`.\n\nMost signatures don't need this much machinery. Use the markers when:\n\n- A parameter should require a name at the call site (use `*` and put it after).\n- A parameter should forbid a name at the call site (use `/` and put it before).\n- The code is a library API where parameter renames or `**kwargs` collisions are a real concern.\n\nFor everyday application code, regular parameters with sensible defaults cover the vast majority of cases.\n\n\n```mermaid\nflowchart LR\n Start[\"def f(\"]:::cyan\n Pos[\"pos_only
(positional only)\"]:::orange\n Slash[\"/ marker\"]:::red\n Both[\"both
(positional or keyword)\"]:::green\n Args[\"*args
or bare *\"]:::red\n KWonly[\"kw_only
(keyword only)\"]:::orange\n Kwargs[\"**kwargs\"]:::teal\n End[\")\"]:::cyan\n\n Start --> Pos --> Slash --> Both --> Args --> KWonly --> Kwargs --> End\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram shows the order Python expects. Any of the boxes can be omitted, but the ones kept must appear in this sequence.\n\n---\n\n# Defaults Interact with Keyword Calls\n\nA default doesn't change whether a parameter is positional, keyword, or both. The position in the signature decides that. But defaults make keyword calls more powerful, because the caller can set only the ones that matter and leave the rest at their defaults.\n\n\n```python\ndef place_order(customer, items, delivery=\"standard\", gift_wrap=False, express=False):\n return f\"{customer}: {items}, delivery={delivery}, gift_wrap={gift_wrap}, express={express}\"\n\n# Set only the third positional default.\nprint(place_order(\"alice\", [\"Wireless Mouse\"], \"express\"))\n\n# Set only the third by name. Cleaner.\nprint(place_order(\"alice\", [\"Wireless Mouse\"], delivery=\"express\"))\n\n# Set only the second non-required default. Impossible without keywords.\nprint(place_order(\"alice\", [\"Wireless Mouse\"], gift_wrap=True))\n```\n\n\nThe first two calls produce identical output. Both set `delivery` to `\"express\"`, but the keyword version reads better and would survive a parameter reorder. The third call sets only `gift_wrap`, which is the third default; without keywords, `\"standard\"` would need to be passed explicitly for `delivery` first.\n\nFor a function with many defaults, keyword calls keep most calls short. Few callers pass all six parameters; most pass two or three with the ones that matter, and the defaults fill the rest.\n\nDefaults and keyword calls work together: defaults make parameters optional, and keyword calls skip the optional ones cleanly.\n\n---\n\n# Forwarding via `**kwargs`\n\n`**kwargs` collects arbitrary keyword arguments. It's also the standard way to forward keyword arguments to another function without listing them out. This pattern shows up in wrapper functions, decorators, and any code that passes options through to a delegate.\n\n\n```python\ndef place_order_logged(customer, items, **options):\n print(f\"placing order for {customer} with options {options}\")\n return place_order(customer, items, **options)\n\ndef place_order(customer, items, delivery=\"standard\", gift_wrap=False):\n return f\"{customer}: {items}, delivery={delivery}, gift_wrap={gift_wrap}\"\n\nprint(place_order_logged(\"alice\", [\"Wireless Mouse\"], delivery=\"express\", gift_wrap=True))\n```\n\n\n`place_order_logged` doesn't need to know which options `place_order` supports. It collects them all into `options`, then unpacks them with `**options` when calling the real function. If `place_order` adds a new option (`signature_required`, say), the wrapper keeps working without any code change.\n\nThe forwarding pattern works because keyword arguments match by name. A positional-only forwarder would have to know the exact parameter order, and any change to `place_order` would break it. Keyword forwarding survives signature changes as long as the names stay stable.\n\nForwarding with `**kwargs` builds a dict per call. For most code this is invisible. For a function called in a tight inner loop, the wrapper adds a small constant overhead per call; profile before assuming it matters.\n\nOne catch with forwarding: if the wrapper and the delegate share a parameter name, it can't be passed twice. This produces a `TypeError: got multiple values for keyword argument`. The fix: ensure each keyword binds to exactly one parameter, either by filtering the dict or by changing one of the function signatures.\n\n---\n\n# API Design Considerations\n\nChoosing positional, keyword, or required-keyword shapes is part of designing a function's public face. A few patterns hold up well.\n\n**Booleans should be keyword-only.** A bare `True` or `False` at a call site is almost always opaque. `place_order(items, customer, True, False, True)` could mean anything. `place_order(items, customer, gift_wrap=True, express=False, signature_required=True)` reads like prose. For a function with two or more booleans, mark them keyword-only with `*`.\n\n\n```python\n# Hard to read.\ndef place_order(items, customer, gift_wrap, express, signature_required):\n pass\n\n# Easier to read at the call site.\ndef place_order(items, customer, *, gift_wrap=False, express=False, signature_required=False):\n pass\n```\n\n\n**Required parameters with no obvious order should be keyword-only.** If a function has three parameters of the same type (three floats, three strings), the call site doesn't show what each one means. Forcing keywords makes the meaning explicit.\n\n\n```python\n# `set_bounds(0.0, 100.0, 50.0)` is impossible to read.\ndef set_bounds(min, max, default):\n pass\n\n# `set_bounds(min=0.0, max=100.0, default=50.0)` is obvious.\ndef set_bounds(*, min, max, default):\n pass\n```\n\n\n**The first one or two parameters can be positional.** When a function operates on a primary value (a list, a customer, a request), letting that primary value be positional is fine. `cart_total(cart)` and `cart_total(items=cart)` are equally readable; the positional version is shorter.\n\n**Optional configuration belongs in keyword-only territory.** Anything that adjusts behavior rather than describing the main input is usually clearer as a keyword argument. Sort comparators, timeouts, retry counts, feature flags: pass them by name.\n\n**Use `/` only when there's a reason.** Most application code doesn't need positional-only parameters. Use `/` when publishing a library API that needs the freedom to rename parameters later, or when a parameter name collides with something that belongs in `**kwargs`.\n\nThese are guidelines, not laws. The standard library and most major Python libraries follow them loosely, with exceptions where the convention would be silly. The underlying principle is the same: shape the signature so that call sites read clearly without the signature in front of them.","pageType":"python"}

Keyword Arguments

Get Premium