Asking a detailed guideline to forece parameters as positional-only, positional- or keyword-argument, and keyword only when using *args and **kwargs

https://docs.python.org/3/tutorial/controlflow.html#special-parameters

def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
      -----------    ----------     ----------
        |             |                  |
        |        Positional or keyword   |
        |                                - Keyword only
         -- Positional only

According to the reference, / and * indicate the kind of parameter by how the arguments may be passed to the function: positional-only, positional-or-keyword, and keyword-only.

It is clear how to use it when I use normal positional arguments or keyword arguments. However, when I use *args or **kwargs together, it becomes very complicated to me.

for example,

def func(a, *args, /):  # SyntaxError: / must be ahead of *
    pass

This code raise SyntaxError: / must be ahead of * although it is clear that a and args is positional parameters. I know / is unnecessary here, but what I am wondering is why the Error message is SyntaxError: / must be ahead of *. I used * for to point out *args, not independent *.

def func(a, /, *args):  # No error!?
    pass

However, this code works without Error although *args is indicated as positioal- or keyword- arguments as it follows / (*args cannot take keyword arguments!). I think this should raise Error such as SyntaxEror: *args cannot take keyword argument.

In addition,

def func(*, **kwargs):  # SyntaxError: named arguments must follow bare *
     pass

This code raise SyntaxError: named arguments must follow bare *. I know in the function, * is unnecessary, but the error message says named arguments must follow bare * although the named arguments **kwargs is already following *.

I think I am missing something. So, it would very appreciate if anyone explain more detailed guideline to use / and * when using *args or **kwargs.

The answer to this question is really simple: The error messages are weird, however, what works and what does not is really logical.
Keep in mind that, if you are using a mixture of tabs and spaces, you can get an error: invalid constant. The parser is not always able to see why something does not work. Also, you kind of misunderstand how / works.

*args eats up all positional arguments
**kwargs eats up all keyword arguments.

So, if you define a function like this:

def func(a, *args, /):  # SyntaxError: / must be ahead of *
    pass

You're doing the same thing twice. / prohibits any more locational arguments, but *args already eats up all of them, so the slash is not needed.

Same goes for *, **kwargs. * just not needed.
This, however, does work:

def hello(*, hello: str = "Hello", **kwargs):
    print(kwargs)

At this point, the * is needed, as otherwise hello could be passed positionally. This, therefore also works. The parser just checks if there is a definition to take variables after the *, and **kwargs does not, and this is not seen as a bug, because there is no need to use it that way.

Lastly, I agree that this:

def func(a, /, *args):  # No error!?
    pass

Is weird code, but it does work:

the / prohibits anything in front of it to be passed as a keyword, and * mandates anything after it to be taken as a keyword. You can pass positional arguments after a /, and *args will eat those up.

This is perfectly valid python:

def hello(a, /, *args):
    print(args)
    print(a)

hello("a", "b")
>>> ('b',)
>>> a

So, this is the order:

(positional, only, /, positional or keyword, [*args or *], keyword only, **kwargs)

Where, if you specify a * and then **kwargs without anything in between, it throws an additional error, because the * was not needed.

The error messages you get are indeed a bit weird, but it does all check out.

I hope that helps.