refactor(python): Deprecate non-keyword args for some functions

[stinodego]

Keyword-only strategy

My philosophy for marking arguments as keyword-only is as follows, roughly in order of priority:

1. If parameters clash, at least one of the parameters should be keyword-only.

• Example: join(left_on, right_on, on) -> either on must be keyword-only, or left_on and right_on.
• Reason: We want to avoid syntax like join(None, None, "a")

2. Boolean flags should always be keyword-only

• Example: sort(reverse=False, nulls_last=False)
• Reason 1: positional syntax is not very readable here, e.g. sort(True, False) -> which flags mean what?
• Reason 2: flag parameters are relatively prone to re-ordering - this will not be breaking if the args are keyword-only

3. Keyword arguments that are rarely used or only used for very specific use cases should be keyword-only

• Example: read_csv(sample_size=1024)
• Reason: These arguments are more subject to reordering, renaming, or removal than other parameters. Having them keyword-only makes this easier to do.

4. Arguments after "single or sequence" arguments should be keyword-only

• Example: unique(subset, keep, maintain_order) -> keep and maintain_order will be keyword-only
• Reason 1: stops users from accidentally passing list arguments to subsequent arguments, e.g. unique("a", "b") -> "b" will be passed to keep
• Reason 2: Allows the option to adopt *args syntax, see More ergonomic way to pass multiple columns to select/with_columns/groupby/...  #6451 for examples.

5. Newly added flags or experimental args should be keyword-only

• Example: to_dummies(separator) (recent addition)
• Reason: We don't always get it right straight away. It's easier to change or deprecate arguments when they are keyword-only.

Bonus. Arguments that do not match these criteria SHOULD NOT BE KEYWORD-ONLY.

• Example: join(other, on, how, *, left_on, right_on)
• Reason: There are valid use cases for positional arguments. -> For example, when arguments are passed as variables, the duplication can get ugly: join(other, on=on, how=how). Let users decide their preferred syntax in this case (keyword or positional).
• If keyword-only arguments do not concretely help the user or the Polars developers, they should not be used.

Your input here is very welcome!

Changes

With this in mind, I made deprecation changes to the following functions/methods:

• to_dummies
• unique
• concat_str
• struct
• join_asof
• map
• apply
• cumfold
• arg_sort_by
• arg_sort
• pivot

Next steps

There are definitely more to do. I figured I'd open this PR to run my 'philosphy' by you, and then do another pass with whatever strategy we come up with together.

I've also spotted quite a few parameter renaming opportunities, I'll do that next.

And then after that, I will do another PR where I remove the deprecations and apply the breaking changes. That can sit for a while until we go for 0.17.0.

[ritchie46]

This seems a good improvement to me. 👍

[stinodego]

All right, I'll go ahead and merge this and check the rest of the API for candidates according to the guidelines set out in this post.

If any issues pop up, the deprecations are easily reversed. Worst case scenario, some users will rewrite their stuff to use keyword arguments unnecessarily.