docs(python): Improve pl.when documentation

[zundertj]

Inspired by #7725

• clarify behaviour chained when-thens
• note that otherwise is optional

The See-Also section does not really work well, see the ref page here: https://pola-rs.github.io/polars/py-polars/html/reference/expressions/api/polars.when.html#polars.when

Because we do not explicitly expose the WhenThen and WhenThenThen objects. Should we just remove that, and simply focus on documenting everything through pl.when? That would be my preference.

[stinodego]

Because we do not explicitly expose the WhenThen and WhenThenThen objects. Should we just remove that, and simply focus on documenting everything through pl.when? That would be my preference.

Yes! That would be great.

[stevenlis]

I propose we add an example of if..elif..else in the doc. Here's an example:

import polars as pl
df = pl.DataFrame(
    {'a': ['T', 'T', 'T', 'T', None],
     'b': ['D', 'D', 'D', 'F', None]}
)

# this .when() chain ...
df.with_columns(
    pl.when(pl.col('a') == 'T').then('T')
    .when(pl.col('b') == 'F').then('F')
    .otherwise('C').alias('c')
)

# ... is equal to this:
new_col_c = []
for row in df.to_dicts():
    if row['a'] == 'T':
        new_col_c.append('T')
    elif row['b'] == 'F':
        new_col_c.append('F')
    else:
        new_col_c.append('C')

print(pl.Series(new_col_c))

[zundertj]

Because we do not explicitly expose the WhenThen and WhenThenThen objects. Should we just remove that, and simply focus on documenting everything through pl.when? That would be my preference.

Yes! That would be great.

I have removed the See Also links, because they are not referring to objects you really deal with as an end-user. I have, however, kept in the docstrings on the class methods when, then, otherwise, useful in IDE's.

[zundertj]

@StevenLi-DS : we have such an example? We dont have the fully written out Python alternative code, but I think I have added enough text to clarify what happens?

[stevenlis]

@zundertj I think the docstrings and the doc are clear now. Thx. Maybe it's better to be inserted somewhere in the user guide. anyway... i don't know.

[ritchie46]

Nice!