docs(python): improve docstring of (Expr|Series).map_elements

[KDruzhkin]

Mention:
col("col_name").struct.field("field_name").native_method().

(Follow-up on #15887).

[MarcoGorelli]

nice

just thinking out loud - this extracts just that field, so it feels a bit different from the other items on the list. 🤔 thinking if there's a better way

[KDruzhkin]

#16082

[KDruzhkin]

I think, the design space here is different from e.g. pandas DataFrames because of immutability. Instead of updating the frame in-place, we (at least conceptually) create a copy of the original frame with some parts modified.

When immutability meets deep nesting... I heard, there are exotic solutions, e.g. lenses.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.40%. Comparing base (8bc1019) to head (9be3e60).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #16079   +/-   ##
=======================================
  Coverage   81.40%   81.40%           
=======================================
  Files        1409     1409           
  Lines      184519   184519           
  Branches     2961     2961           
=======================================
+ Hits       150206   150209    +3     
+ Misses      33798    33795    -3     
  Partials      515      515           

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

[MarcoGorelli]

struct.with_fields has been added, fancy updating to use that?

[KDruzhkin]

struct.with_fields has been added, fancy updating to use that?

Thought of it. But the names are not local to the struct, and this expression is too heavy for a docstring:

pl.col("col_name").struct.with_fields(
    pl.col("col_name").struct.field("field_name").sqrt()
)

[KDruzhkin]

#16395

[KDruzhkin]

struct.with_fields has been added, fancy updating to use that?

Done. Had to use blockquotes >>> to fit the examples.

[MarcoGorelli]

thanks! just left a comment about the reference to with_columns / with_fields, but the content looks good, definitely good to hammer home the message here IMO, this is probably the #1 most misused Polars method

[MarcoGorelli]

could these be links? something like

:meth:`DataFrame.with_columns`

and something similar for with_fields

I can't remember the exact syntax, you may need to build the documentation locally to check it works

[KDruzhkin]

[MarcoGorelli]

this is causing a doctest failure - I'd suggest, either remove it (you're already linking to these methods above) or use a codeblock

[KDruzhkin]

Done.