chore(python): Deprecate positional join args

[stinodego]

This is a PoC of sorts to deprecate positional arguments.

As an example, the function signature for join is as follows:

    def join(
        other,
        left_on = None,
        right_on = None,
        on = None,
        how = "inner",
        suffix = "_right",
    ) -> DataFrame:

I think the function signature below would make more sense, putting the most-used args first, and make others keyword-only:

    def join(
        other,
        on = None,
        how = "inner",
        *,
        left_on = None,
        right_on = None,
        suffix = "_right",
    ) -> DataFrame:

This is obviously a breaking change, but worse, this may silently break for people who have specified left_on and right_on positionally.

I came up with a way to detect such cases and throw a DeprecationWarning

I stole the decorator from Pandas (as suggested by @MarcoGorelli) and adapted it to our needs.

If you agree with this method of deprecating non-keyword arguments, I will go ahead and apply this to a bunch of other functions.

Changes:

• Add a decorator utility for deprecating non-keyword arguments.
• Use the decorator to deprecate positional arguments for the join method.

[ritchie46]

This is great. These things really enhance readability and maintainability. 👍

[timreuscher]

This one just really bit me, and the API reference doesn't have a decent example. In 0.16.4 I had something like this:

 df.join(other_df,vars1,vars2)

That worked great for me. I understand the reason for the change completely, but something like

 df.join(other_df,on=None,how='inner',left_on=vars1,right_on=vars2)

gives me an error for multiple values for argument 'how'. Like I said, is there an example for how this decorator works? I'm not really understanding how to work with the change.

[MarcoGorelli]

I can't reproduce this, could you show a reproducible example please?

In [31]: df.join(df2, on=None, how='inner', left_on=['a'], right_on=['b'])
Out[31]:
shape: (3, 3)
┌─────┬─────┬─────────┐
│ a   ┆ b   ┆ a_right │
│ --- ┆ --- ┆ ---     │
│ i64 ┆ i64 ┆ i64     │
╞═════╪═════╪═════════╡
│ 1   ┆ 1   ┆ 1       │
│ 1   ┆ 2   ┆ 1       │
│ 2   ┆ 3   ┆ 1       │
└─────┴─────┴─────────┘

[timreuscher]

I can't reproduce this, could you show a reproducible example please?

In [31]: df.join(df2, on=None, how='inner', left_on=['a'], right_on=['b'])
Out[31]:
shape: (3, 3)
┌─────┬─────┬─────────┐
│ a   ┆ b   ┆ a_right │
│ --- ┆ --- ┆ ---     │
│ i64 ┆ i64 ┆ i64     │
╞═════╪═════╪═════════╡
│ 1   ┆ 1   ┆ 1       │
│ 1   ┆ 2   ┆ 1       │
│ 2   ┆ 3   ┆ 1       │
└─────┴─────┴─────────┘

OK, sorry about that. That code does work. I had multiple joins in my code and the error was in the next join. That "*" really threw me off. My apologies.