When should I use positional-only, keyword-only, and ordinary parameters?
Quick answer
Use ordinary parameters when callers may provide a value either by position or by name. Choose positional-only when the parameter name should not be part of the calling interface, and keyword-only when naming an option makes calls clearer. In a function definition, / marks preceding parameters positional-only and * marks following parameters keyword-only. [S1]
The question, the details, the next step.
I’m writing a function with a required item, a required count, and an optional reverse setting. How do I choose parameter styles?
Decide what you want callers to rely on: a value’s position, its name, or either. For this example, suppose the item’s name need not be part of the interface, count is useful either by position or name, and reverse should be named so its role is clear. You could write:
def process(item, /, count, *, reverse=False):
...The slash makes item positional-only, count is ordinary (positional-or-keyword), and the star makes reverse keyword-only. [S1] This is one design choice, not a requirement for every function with these arguments.
Which calls would that signature allow or reject?
These calls are allowed by the signature:
process("report", 3)
process("report", count=3)
process("report", 3, reverse=True)They show count provided either by position or by name, and reverse provided by name. These are rejected:
process(item="report", count=3)
process("report", 3, True)The first tries to pass the positional-only item by name; the second passes the keyword-only reverse by position. [S1] These examples describe the call interface, not what process does internally.
When would positional-only be a better choice than leaving a parameter ordinary?
Use positional-only when callers should supply a value by position rather than depend on its parameter name, or when the order is the intended interface. [S1] For example, if naming the inputs is not useful for a particular function, you might choose:
def combine(left, right, /):
...That choice rules out calls such as combine(left=..., right=...). If names help make calls clearer, ordinary parameters allow callers to use either positions or names instead. The point is to choose the interface that fits the function, not to add markers automatically.
What quick rule can I use when reviewing a signature?
Ask whether each parameter should be supplied by position, by name, or either. Use positional-only when its name should not be part of the interface; use keyword-only when naming an option improves clarity; leave it ordinary when both call styles are useful. [S1]
For the example, the rationale could be:
item: positional-only — position is enough
count: ordinary — either form is useful
reverse: keyword-only — make the option explicit by nameThese are design reasons, not Python requirements. When changing an existing signature, review the calls you intend to support so the interface remains suitable for its callers.
A practical checklist
Decide whether each parameter should be passed by position, name, or either.
Use
/when preceding parameters should be positional-only.Use
*when following parameters should be keyword-only.Leave parameters ordinary when both call styles are useful.
Review intended call forms before changing a signature.
A few more useful answers
Can an ordinary parameter be passed by position or name?
Yes. Ordinary parameters are positional-or-keyword. [S1]
Does `*` make every parameter keyword-only?
It makes the parameters that follow it keyword-only; parameters before it are not changed by that marker. [S1]
Does the syntax determine which style I should choose?
No. It defines the permitted call forms. Choose a style based on which names and positions you want callers to rely on.
Sources
References used for this guide.
- [S1] Python tutorial: positional-only, positional-or-keyword, and keyword-only parameters docs.python.org · Checked