What does a bare asterisk do in a Python parameter list? (What are "keyword-only" parameters?)

Question

What does a bare asterisk in the parameters of a function do?

When I looked at the pickle module, I see this:

pickle.dump(obj, file, protocol=None, *, fix_imports=True)

I know about a single and double asterisks preceding parameters (for variable number of parameters), but this precedes nothing. And I'm pretty sure this has nothing to do with pickle. That's probably just an example of this happening. I only learned its name when I sent this to the interpreter:

>>> def func(*):
...     pass
...
  File "<stdin>", line 1
SyntaxError: named arguments must follow bare *

If it matters, I'm on python 3.3.0.

Related: [Bare forward slash in Python function definition?](https://stackoverflow.com/q/56514297/5353461) — Tom Hale, Jun 09 '19 at 13:07
for an explanation with code example see: https://stackoverflow.com/a/14298976/1601580 — Charlie Parker, Oct 29 '21 at 18:31

score 418 · Accepted Answer · edited May 23 '17 at 11:55

418

Bare * is used to force the caller to use named arguments - so you cannot define a function with * as an argument when you have no following keyword arguments.

See this answer or Python 3 documentation for more details.

edited May 23 '17 at 11:55

Community

1
1

answered Jan 13 '13 at 08:50

Kimvais

38,306
16
108
142

for an explanation with code example see: https://stackoverflow.com/a/14298976/1601580 – Charlie Parker Oct 29 '21 at 18:31
1

But why `def foo(a, *, **kwargs)` returns the same syntax error? – ado sar Apr 02 '23 at 10:39
@ado sar: interesting. i just found this discussion on it: https://bugs.python.org/issue2613 – outa Apr 18 '23 at 11:57

score 119 · Answer 2 · edited Sep 02 '16 at 04:25

119

While the original answer answers the question completely, just adding a bit of related information. The behaviour for the single asterisk derives from PEP-3102. Quoting the related section:

The second syntactical change is to allow the argument name to
be omitted for a varargs argument. The meaning of this is to
allow for keyword-only arguments for functions that would not
otherwise take a varargs argument:

    def compare(a, b, *, key=None):
        ...

In simple english, it means that to pass the value for key, you will need to explicitly pass it as key="value".

edited Sep 02 '16 at 04:25

martineau

119,623
25
170
301

answered Sep 02 '16 at 04:16

Anshul Goyal

73,278
37
149
186

5

Oh, that makes things much clearer. So actually having an argument * is just like having an argument args*, but since you haven't named it anything, its only effect is probably to quietly gobble up all the remaining positional arguments, in order to force the remaining arguments to be keyword-only. – Stephen Apr 25 '18 at 17:19
18

@Stephen I too originally thought, the effect of bare `*` is to gobble up remaining positional arguments, but that's not the case. Passing extra positional arguments than the function expects, gives an error of this kind: `foo() takes exactly 1 positional argument (2 given)` – Ajay M May 27 '18 at 01:49
I would add the PEP example before "As a convenient shortcut, we can simply omit the 'ignore' name, meaning 'don't allow any positional arguments beyond this point'." That equivalent example made it clear and concrete what it does. – Horror Vacui Aug 31 '20 at 03:32

laycat · Answer 3 · 2018-10-22T19:25:27.013

def func(*, a, b):
    print(a)
    print(b)

func("gg") # TypeError: func() takes 0 positional arguments but 1 was given
func(a="gg") # TypeError: func() missing 1 required keyword-only argument: 'b'
func(a="aa", b="bb", c="cc") # TypeError: func() got an unexpected keyword argument 'c'
func(a="aa", b="bb", "cc") # SyntaxError: positional argument follows keyword argument
func(a="aa", b="bb") # aa, bb

the above example with **kwargs

def func(*, a, b, **kwargs):
    print(a)
    print(b)
    print(kwargs)

func(a="aa",b="bb", c="cc") # aa, bb, {'c': 'cc'}

score 68 · Answer 4 · answered Nov 25 '19 at 04:12

Semantically, it means the arguments following it are keyword-only, so you will get an error if you try to provide an argument without specifying its name. For example:

>>> def f(a, *, b):
...     return a + b
...
>>> f(1, 2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: f() takes 1 positional argument but 2 were given
>>> f(1, b=2)
3

Pragmatically, it means you have to call the function with a keyword argument. It's usually done when it would be hard to understand the purpose of the argument without the hint given by the argument's name.

Compare e.g. sorted(nums, reverse=True) vs. if you wrote sorted(nums, True). The latter would be much less readable, so the Python developers chose to make you to write it the former way.

score 29 · Answer 5 · answered Nov 01 '19 at 13:14

Suppose you have function:

def sum(a,key=5):
    return a + key

You can call this function in 2 ways:

sum(1,2) or sum(1,key=2)

Suppose you want function sum to be called only using keyword arguments.

You add * to the function parameter list to mark the end of positional arguments.

So function defined as:

def sum(a,*,key=5):
    return a + key

may be called only using sum(1,key=2)

What does a bare asterisk do in a Python parameter list? (What are "keyword-only" parameters?)

5 Answers5

Linked

Related