decorator to deprecate positional arguments

[mathause]

• Supersedes make more args kw only (except 'dim') #6403, see also Keyword only args for arguments like "drop" #5531
• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst

Adds a helper function to deprecate positional arguments. IMHO this offers a good trade-off between magic and complexity. (As mentioned this was adapted from scikit-learn).

edit: I suggest to actually deprecate positional arguments in another PR.

[hmaarrfk]

Are the functions you are considering using this functions that never had keyword arguments before? When I wrote a similar decorator before i had an explicit list of arguments that were allowed to be converted.

[headtr1ck]

Do you think that you can get it to work with static typing?

[mathause]

Are the functions you are considering using this functions that never had keyword arguments before? When I wrote a similar decorator before i had an explicit list of arguments that were allowed to be converted.

No, I want to consider arguments that have default values.

defmean(dim, skipna=None, keep_attrs=None):
pass@_deprecate_positional_args("v0.1.0")defmean(dim, *, skipna=None, keep_attrs=None):
pass

Or do I missunderstand your question?

Do you think that you can get it to work with static typing?

I think functools.wraps also attaches the annotations?

[mathause]

I just realized that there is a bug in the decorator for "keyword-only arguments without a default". I wonder if I should fix this or just disallow this pattern, i.e. the following does currently not work properly:

@_deprecate_positional_args("v0.1.0")deffunc(a, *, b):
pass

but I am not sure how helpful it is.

EDIT: It now raises a TypeError for this case.

[mathause]

I also just realized, that we made many arguments keyword-only without deprecation (e.g. xr.Dataset.mean) - but that should not stop us from using this - there are still a lot of instances where it could be helpful.

[mathause]

Any objections to merge this as is?

[dcherian]

👍 put it on the meeting agenda for today

[shoyer]

are these print statements intentional?

[dcherian]

@mathause I think you missed these print statements?

[mathause]

Thanks! Will fix them in a follow up!

[shoyer]

I would suggest keeping the original copyright notice at the top of the this file.