Better deprecation messages

[thomasaarholt]

Polars version checks

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of Polars.

Issue description

The API keeps changing, which is great (since its for the better!), but each change also adds some work to update code. I'm going to cheekily point out some challenges with #7784 (@MarcoGorelli, I'm just using yours because its the one I'm trying to fix in my code right now, nothing personal)

This message is a deprecation warning on the functionality of .pivot() from that PR:

In a future version of polars, the default `aggregate_function` will change from `'first'` to `None`. Please pass `'first'` to keep the current behaviour, or `None` to accept the new one.

Now, this particular case is a bit unusual because the new default is None, so instead we use a "NoDefault" as a temporary way to force the user to make a choice, which I agree with is a sensible decision.

My gripe is that:

1. the deprecation message doesn't say what the new default argument does ('first' implies it chooses the first value, None doesn't really imply anything, but I would have assumed that it led to all cell values being list, as happens with groupby, e.g. df.groupby("foo").agg("bar") in the below example).
2. I can't tell what None does, from the docstring or from the docstring code example:

import polars as pl
df = pl.DataFrame(
    {
        "foo": ["one", "one", "one", "two", "two", "two"],
        "bar": ["A", "B", "C", "A", "B", "C"],
        "baz": [1, 2, 3, 4, 5, 6],
    }
)
df1 = df.pivot(values="baz", index="foo", columns="bar", aggregate_function=None)
df2 = df.pivot(values="baz", index="foo", columns="bar", aggregate_function='first')
df1.frame_equal(df2) # True

So, in summary, I encourage us all to write verbose deprecation messages that rather give too much than too little information (these messages will be short-lived anyway, so they won't populate people's logs for long).

Reproducible example

.

Expected behavior

.

Installed versions

Replace this line with the output of pl.show_versions(), leave the backticks in place

[MarcoGorelli]

thanks @thomasaarholt for bringing this up - yeah you're right, it's not clear what None does. did you want to make a PR to clarify? I think None just needs adding to the description of the aggregate_function parameter

[MarcoGorelli]

closed by #9473