make more args kw only (except 'dim')

[mathause]

• User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst

This makes many arguments keyword-only, except for dim to avoid da.weighted(...).mean("lat", "lon") (i.e. da.weighted(...).mean(dim="lat", skipna="lon")) which silently does the wrong thing. I am sure I forgot some and for some I was unsure so I left them as is.

Question: do we want an deprecation cycle? Currently it just errors for da.weighted(...).mean("dim", True). Might be nice to do it, however, @dcherian if I am not mistaken you did this without a deprecation in #5950, e.g. for da.mean etc.?

import numpy as np
import xarray as xr
air = xr.tutorial.open_dataset("air_temperature")
wgt = np.cos(np.deg2rad(air.lat))
air.weighted(wgt).mean("lat", "lon")

[max-sixty]

This is great, thanks @mathause .

From what I've seen in the wild, I do think we're going to get some breaks on some of these without a deprecation — e.g. I've rarely seen an n arg used for diff . What are your thoughts on the link that @gcaria posted in #5531? That might do the deprecation for us.

[mathause]

Sounds good - I'll add a deprecation.

We might also want to do this for https://github.com/pydata/xarray/blob/main/xarray/core/_reductions.py

[mathause]

Sounds good - I'll add a deprecation.

We might also want to do this for https://github.com/pydata/xarray/blob/main/xarray/core/_reductions.py

[dcherian]

We might also want to do this for https://github.com/pydata/xarray/blob/main/xarray/core/_reductions.py

👍 I lost track of it given that PR was open for so long. IIRC one issue is that the order of args was different forr Dataset.reduce vs DatasetGroupBy.reduce (cc @Illviljan)

[mathause]

From #5950 (comment)

Keyword-only and some had the 3rd position arg as keep_attrs and in other cases it was axis.

[Illviljan]

Yes, mypy found some issues with the ordering so moving to kwargs-only was my preferred solution.
It indeed was a breaking change but I didn't think keep_attrs, axis, etc were that popular arguments either so I was not expecting too many noticing the change, and maybe just a note in the whats new would've been sufficient.

[max-sixty]

I would vote to resurrect this! Deprecations are nice but I would vote to merge this without them given that it seems that we won't merge it with them... (We can do it on a minor release and announce it)

What do folks think?

[headtr1ck]

I'm ok with merging this.

Maybe relax it a bit for the diff method, I remember using n as a positional argument in the past (coming from Matlab).

Should get an entry in breaking changes in the what's new though.

[mathause]

Happy to revive this PR. We do have a @_deprecate_positional_args helper - I added this as well (IIRC it was added after opening this PR). I am sure we could make even more arguments positional but I should be doing my actual job ;-)

[mathause]

I think the failure is a fluke. Open/ close

[dcherian]

Thanks @mathause

Let's add a whats-new note and merge.

[headtr1ck]

Looks good now, thanks!