feat: Add Expr.item to strictly extract a single value from an expression

[dsprenkels]

List of all changes

• Add Expr.item() to select the only item from an Expr. In other words: it is like Expr.first() but it will raise an error if Expr does not contain a single value
• Add List.item(), for lists
• Add DataFrame.item() on dataframes
• Add Series.item() on series
• Deprecate DataFrame.item() in favor of DataFrame.single() and DataFrame[row, col]
• Deprecate Series.item() in favor of Series.single() and Series[index]

Review suggestions

• Is single the correct name? Or should we consider another name?
  • Keeping the name item()
• Are all implementations covered in the tests?

Still Todo

• Add a note to the Expr.item docs that it does not take arguments, and that if the user wants item retrieval, they should use Expr.get

Fixes: #8689
Fixes: #21856
Related issue: #24475

[coastalwhite]

I think list.single() can be implemented with the same perf as list.agg(pl.element().single()).

[cmdlineluser]

Also fixes #21856 (the list variant)

[ritchie46]

If we decide to go with single, I think we should rename DataFrame.item as well. Or this should be called item. Not sure yet.

[codecov]

Codecov Report

❌ Patch coverage is 90.84507% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.82%. Comparing base (43a10fe) to head (2d0f941).
⚠️ Report is 7 commits behind head on main.

Files with missing lines	Patch %	Lines
.../polars-python/src/lazyframe/visitor/expr_nodes.rs	0.00%	4 Missing ⚠️
crates/polars-expr/src/reduce/first_last.rs	96.66%	3 Missing ⚠️
crates/polars-core/src/frame/group_by/mod.rs	0.00%	2 Missing ⚠️
crates/polars-plan/src/dsl/expr/mod.rs	0.00%	1 Missing ⚠️
crates/polars-plan/src/dsl/format.rs	0.00%	1 Missing ⚠️
...n/src/plans/conversion/dsl_to_ir/expr_expansion.rs	87.50%	1 Missing ⚠️
crates/polars-plan/src/plans/visitor/expr.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #24888      +/-   ##
==========================================
+ Coverage   81.76%   81.82%   +0.05%     
==========================================
  Files        1700     1700              
  Lines      233868   234045     +177     
  Branches     2997     2997              
==========================================
+ Hits       191219   191501     +282     
+ Misses      41884    41779     -105     
  Partials      765      765              

☔ 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.

[dsprenkels]

If we decide to go with single, I think we should rename DataFrame.item as well. Or this should be called item. Not sure yet.

@ritchie46 The inconvenient thing about .item() is that, at the moment, it does different things depending on the argument, which I'd propose renaming to get() and single().

[nameexhaustion]

Missed optimization - Single doesn't observe ordering - it only observes length.

It should be in a separate branch that just returns O::None (i.e. no observable orderings, since we are returning a scalar in the Ok(_) case).

[mcrumiller]

I am not a huge fan of single mainly because "single precision" is so commonly used.

I like into_value() or to_value(), both feel a little bit clearer. Not sure what others think of my ideas.

[cmdlineluser]

#24475 suggested the name .one() after more_itertools.one()

[mcrumiller]

#24475 suggested the name .one() after more_itertools.one()

The problem is that one() doesn't sound like it requires the sequence to already be a single value, just that you're only selecting one out, whereas to_value() implies that you can get a failure when you don't already have just a value.

[dsprenkels]

@MarcoGorelli It's more that there is a mismatch between DataFrame and Expr, where DataFrame.item() is used to index items, but for Expr it is Expr.get()

[coastalwhite]

nice, a few small changes.

[ritchie46]

Ai, this was merged a bit too early. :') Not a big deal, will work around it.