depr(python,rust!): Rename parameter by to group_by in DataFrame.upsample/group_by_dynamic/rolling

[MarcoGorelli]

This hasn't been fully discussed, but it's related to #10989 and it was pretty easy to F2-replace these. Sometimes, just opening a PR is the fastest way to make a decision, so... here this is 😄

In summary: by in Polars usually refers to which operation you do the operation by (e.g. in sort, it sorts by the by columns), and sometimes to which columns you group by before applying the operation. For example:

• df.upsample('a', '3d', by='b') means "group by 'b' and then upsample by column 'a' every 3 days"
• df.top_k(3, by='b') means "take the 3 rows where column 'b' is largest"

If an operation lets you group by certain columns before applying the operation, then I think it would be clearer to use group_by for that parameter.

This would open up the doors for df.top_k(3, by='b', group_by='a') (the by in top_k is already taken)

For readability, looking at the tests, I do think

out = df.rolling("times", period="5i", group_by=["groups"])

is clearer to read than

out = df.rolling("times", period="5i", by=["groups"])

The latter almost looks like it's rolling based on groups, whereas it's rolling based on 'times' grouped by 'groups'

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 80.94%. Comparing base (baacf3d) to head (8b13ee1).
Report is 147 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #14840      +/-   ##
==========================================
- Coverage   80.94%   80.94%   -0.01%     
==========================================
  Files        1327     1327              
  Lines      172081   172102      +21     
  Branches     2453     2453              
==========================================
+ Hits       139290   139305      +15     
- Misses      32320    32327       +7     
+ Partials      471      470       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[stinodego]

Thanks Marco, good move 👍