Migrating to keyword only arguments

[DRMacIver]

Keyword only arguments are lovely and with the upcoming dropping of Python 2 support (😻 😻 😻 ) we can start actually using them in our APIs.

My proposed plan:

1. All strategies should move to keyword only arguments for everything that currently takes a default argument.
2. We should have a deprecation path where all of the existing arguments can be passed positionally with the name realname_deprecated. This emits a deprecation warning but otherwise does the right thing. We can handle this essentially transparently with a decorator.
3. We update the guide to strongly encourage the use of keyword only arguments for most strategies, and that strategies should have at most one or two positional arguments.

Because we do all of this backwards compatibly we don't need to (and shouldn't) do this in Hypothesis 4.0, which can be a pure deprecation release, but it would be nice to have the details of the plan fully fleshes out by the time 4.0 lands so we can do it soon afterwards.

It would be particularly good to note any exceptions where we shouldn't have arguments as keyword only.

[alexwlchan]

I had a quick skim through https://hypothesis.readthedocs.io/en/latest/data.html

All look good to go with keyword only arguments, save hypothesis.strategies.runner(default=not_set), which I think would be less bad to allow positional but is still basically fine.

[Zac-HD]

Sounds great! I'd apply the "defaults = kwonly" principle to everything, not just strategies, and use *__realname_deprecated so that tab-completion engines can tell they shouldn't suggest it.

I've also been looking at refactoring tools that would let us ship an upgrade script to automatically fix any uses. Nothing specific yet, but the principle would be great ("automatically upgrade any automatically fixable deprecation"). We'll see.

As an exception to the "has default = kwonly" principle, I'd argue that for numeric strategies min_value and max_value should be positional-or-keyword; the ergonomics of integers(1, 10) are too good to lose and it's perfectly clear what that means... though the four boolean flags to floats() can all go kwonly.

[Zac-HD]

scikit-learn is doing something similar, and reading their proposal made me realise that it's easier to define the function with real kwonly arguments and have the decorator create the compat form than vice-versa.