docs: Explain aggregation & sorting of lists

[cr7pt0gr4ph7]

Extend the documentation about lists to show how to use .list.eval in combination with aggregation functions and sort_by to process the list elements.

Also fixes the objectively false statement [...] we can also use pl.all() to refer to all of the elements of the list..

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.08%. Comparing base (20ebc64) to head (729803e).
⚠️ Report is 15 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #25260      +/-   ##
==========================================
+ Coverage   81.92%   82.08%   +0.15%     
==========================================
  Files        1712     1711       -1     
  Lines      237225   237160      -65     
  Branches     3011     3013       +2     
==========================================
+ Hits       194358   194683     +325     
+ Misses      42094    41704     -390     
  Partials      773      773              

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cr7pt0gr4ph7]

Note to reviewers: The current build failure is due to unrelated problems being detected by markdown-link-check, and is not related to the changes in this PR, which is ready for review (and potentially merging).

I've created a separate PR #25314 that fixes the link errors.

Update: Link errors should be fixed now that PR #25314 has been merged.

[coastalwhite]

Thank you for the contribution. Small nit.

[coastalwhite]

If possible, this should reference list.agg as that makes more sense for aggregations.

[cr7pt0gr4ph7]

Good point, I didn't even know about list.agg. OTOH, what's even the point of having both list.agg and list.eval if the latter can do everything the former can? Dataframes also only have DataFrame.select, which is used for both use cases.

I'm mainly asking so I can explain the differences (if any) here.

---

Update: I've created a separate issue for this discussion:

• docs: Explain differences between list.eval and list.agg #25336

[cr7pt0gr4ph7]

@coastalwhite Thanks for the suggestion (and the clarification in #25336). I've now modified the explanation by first showing the result of using eval for aggregations, and then showing why it makes sense to use agg instead in those cases.

I've incorporated a slightly modified version of your statement from #25336, and hope that's okay for you:

The list.agg and list.eval expressions are exactly the same, except one difference. If the evaluation expression is statically determined to return only one value, it will automatically explode the list into the inner values. This matches what .group_by(...).agg(...) does, hence the name.