> From Ezio's original post: '''
> If a function has optional arguments but it doesn't accept keyword 
> arguments, the "func([arg1])" notation is used instead. ... The 
> notation "func([arg=default])" should never be used, and "func([arg])" 
> should be used only when keyword args are not accepted.
> '''
>
> In the following, I give objections to this PO (position only) rule and > suggest an alternative ND (no default) rule: use 'name=default' when
> there is a default and '[name]' when there is not'.

Maybe we should try to keep it simple and just document the signature of the function.
Everything that can not be described in the signature can be explained by words.

I tried to write down all the combinations of optional/non optional, with/without default, works/doesn't work with keywords to see how to represent them, but it started being a bit messy.  The "problematic" combinations (for example a function that accepts an optional arguments with no default but that doesn't work with keywords) seem quite rare, and for them we could just write down what's special about them.

There are two more cases that could be solved with a specific notation though:
1) optional arg, with default, doesn't work with keywords (e.g. range, startswith):
   func(arg1)
   func(arg1, arg2)
   *arg2* defaults to <default>.
2) optional arg, with no default, that works only with keywords:
   func(arg1, *, arg2)

The keyword-only *, and the multiple signatures "tricks" can also be used for other similar cases.

func(arg1, **kwargs) can be used for functions that accept kwargs without expecting any specific value; if the values are known and have defaults they could be included in the signature (even if the default is like foo = kwargs.get('foo', default)).

This should cover most of the cases, it only uses valid Python syntax and avoids potentially confusing [].