docs(python): a user-guide chapter on pipes

[KDruzhkin]

A companion PR to #16461.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.47%. Comparing base (534b655) to head (bf717e6).
Report is 10 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #16462      +/-   ##
==========================================
- Coverage   81.50%   81.47%   -0.04%     
==========================================
  Files        1415     1416       +1     
  Lines      186600   186906     +306     
  Branches     3014     3026      +12     
==========================================
+ Hits       152097   152275     +178     
- Misses      33973    34098     +125     
- Partials      530      533       +3     

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

[stinodego]

Thanks, but I would approach this a bit differenly. See my comment in the linked issue:

It makes sense to add a dedicated section for pipe in the docs, as it's a useful tool for doing custom things. It happens more often that I point out "you can do this with pipe" and people didn't know that method existed.

Not sure I would call it 'debugging with pipe' though. It's useful for more than just debugging.

A "Pipe" page could be added to the "Transformations" section. This could showcase common patterns for using pipe. The schema assertion could be one, but a more important pattern is when you want to "name" some custom transformations and use them in a chaining fashion. We can include examples for Expr, DataFrame, and LazyFrame.

[KDruzhkin]

Thanks, but I would approach this a bit differenly. See my comment in the linked issue:

I will try to do it in a week.

[stinodego]

The issues mentioned in the "cookbook" issue are great examples for pipe, e.g. trapezoid / hypot:
#13064

[KDruzhkin]

@stinodego, in the previous comment you said,

A "Pipe" page could be added to the "Transformations" section.

I have tried to fit it there, but it doesn't belong.

Transformations: a short list of pre-defined elementary building blocks. User-defined functions with pipes: infinitely many and arbitrarily complex.

So I created a new top-level section. What do you think?

[KDruzhkin]

@MarcoGorelli, judging by #17707, @stinodego is taking a break from work on polars. Can you have a look at this?

(Mentioning you, because you have reviewed a couple of my previous PRs with documentation improvements.)