API: keywords only arguments

Is your feature request related to a problem? Please describe.

Keywords only arguments are arguably clearer and allow easier refactoring on our side. When adding a new feature, we are already thinking about using * to declare keyword only arguments.

Describe the solution you’d like.

scikit-learn already went through this process and with their v1 coming up, the whole code base is already keywords-only arguments. Hence, if accepted, I propose we follow the same path.

They did it in two phases:

1. Deprecation phase with a wrapper: it takes a function and look at which arguments are keywords only. If you call the function using a positional argument instead of a keyword only argument (if f(a, *, b) and you do f(1, 2) instead of f(1, b=2)) then it will raise a deprecation warning. The function will still be working as the keyword arguments would not be enforced yet. The wrapper will convert the positional argument into a keyword argument.
2. Remove the wrapper: after the deprecation cycle, remove the wrapper and we are done.

xref https://github.com/scikit-learn/scikit-learn/issues/15005

[rgommers]

+1 for using in new code, keyword-only args are very helpful.

For existing code, I don’t think we can do it for the whole code base - too painful. We could look at it for a specific submodule if there’s a good reason for it I think (for example, we want to add more keyword arguments and the order of arguments is becoming quite odd).

[h-vetinari]

OK cool. The scikit helper is also much prettier than the one I hacked together.

I think it would be good idea to have something of a standing policy that if we’re touching the signature of a function in a way that needs a deprecation cycle (e.g. remove/rename a keyword) to also use that to turn the keywords into keyword-only arguments, but for now I’ll just try to remember that when I come across a case.