decorator to deprecate positional arguments

[mathause]

• [x] Supersedes #6403, see also #5531
• [x] 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.

def mean(dim, skipna=None, keep_attrs=None):
    pass

@_deprecate_positional_args("v0.1.0")
def mean(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")
def func(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]

:+1: put it on the meeting agenda for today