Keyword only args for arguments like "drop"

[max-sixty]

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

A method like .reset_index has a signature .reset_index(dims_or_levels, drop=False).

This means that passing .reset_index("x", "y") is actually like passing .reset_index("x", True), which is silent and confusing.

Describe the solution you'd like
Move to kwarg-only arguments for these; like .reset_index(dims_or_levels, *, drop=False).

But we probably need a deprecation cycle, which will require some work.

Describe alternatives you've considered
Not have a deprecation cycle? I imagine it's fairly rare to not pass the kwarg.

[dcherian]

👍 We should do something similar with all the decoding stuff in open_dataset and open_mfdataset (I think there's an issue for this).

[max-sixty]

Would we be happy to do without a deprecation cycle? I would vote lightly yes. (though partly because I think that would mean we did it sooner — if someone was up for doing the deprecation code then that switches it).

[gcaria]

This is done neatly in pandas with a decorator (see here) that takes care of the deprecation.

Would it be fine to just implement the same in xarray?

[max-sixty]

For sure @gcaria ! Thanks for finding that

[dcherian]

There's also a decorator by @hmaarrfk here.

Discussed in this comment: dask/dask#8934 (comment)

[mathause]

Both look good - but adding an intermittent dependency seems a bit heavy...

[hmaarrfk]

I think in my readme i suggest vedoring the code.

Happy to give you a license for it so you don't need to credit me in addition to your own license.

[mathause]

I just discovered the scikit-learns decorator to deprecate positional args - see scikit-learn/scikit-learn#13311 - and now have a preference for this one. It seems the simplest and does not need any input as it reads the keyword-only args from the signature (could potentially add the version of the deprecation).

@_deprecate_positional_args
def f1(a, b, *, c=1, d=1):
    pass

and at the end of the deprecation period you only need to do

-@_deprecate_positional_args
def f1(a, b, *, c=1, d=1):
    pass

[mathause]

I just realized that @hmaarrfk's decorator works similarly, but it also has some bells and whistles we probably don't need..?

[hmaarrfk]

These decorators are kinda fun to write and are quite taylored to a certain release philosophy.

It might be warranted to just write your own ;)