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

crates/polars-core/src/frame/group_by/mod.rs

@@ -875,6 +875,7 @@ pub enum GroupByMethod {
     Mean,
     First,
     Last,
+    Item,
     Sum,
     Groups,
     NUnique,
@@ -897,6 +898,7 @@ impl Display for GroupByMethod {
             Mean => "mean",
             First => "first",
             Last => "last",
+            Item => "item",
             Sum => "sum",
             Groups => "groups",
             NUnique => "n_unique",
@@ -922,6 +924,7 @@ pub fn fmt_group_by_column(name: &str, method: GroupByMethod) -> PlSmallStr {
         Mean => format_pl_smallstr!("{name}_mean"),
         First => format_pl_smallstr!("{name}_first"),
         Last => format_pl_smallstr!("{name}_last"),
+        Item => format_pl_smallstr!("{name}_item"),
         Sum => format_pl_smallstr!("{name}_sum"),
         Groups => PlSmallStr::from_static("groups"),
         NUnique => format_pl_smallstr!("{name}_n_unique"),

crates/polars-expr/src/expressions/aggregation.rs

@@ -125,6 +125,19 @@ impl PhysicalExpr for AggregationExpr {
             } else {
                 s.tail(Some(1))
             }),
+            GroupByMethod::Item => Ok(match s.len() {
+                0 => {
+                    return Err(polars_err!(ComputeError:
+                        "aggregation 'item' expected a single value, got none"
+                    ));
+                },
+                1 => s.slice(0, 1),
+                n => {
+                    return Err(polars_err!(ComputeError:
+                        "aggregation 'item' expected a single value, got {n} values"
+                    ));
+                },
+            }),
             GroupByMethod::Sum => parallel_op_columns(
                 |s| s.sum_reduce().map(|sc| sc.into_column(s.name().clone())),
                 s,
@@ -332,6 +345,27 @@ impl PhysicalExpr for AggregationExpr {
                     let agg_s = s.agg_last(&groups);
                     AggregatedScalar(agg_s.with_name(keep_name))
                 },
+                GroupByMethod::Item => {
+                    let (s, groups) = ac.get_final_aggregation();
+                    for gc in groups.group_count().iter() {
+                        if let Some(n) = gc
+                            && n == 0
+                        {
+                            return Err(polars_err!(ComputeError:
+                                "aggregation 'item' expected a single value, got none"
+                            ));
+                        }
+                        if let Some(n) = gc
+                            && n > 1
+                        {
+                            return Err(polars_err!(ComputeError:
+                                "aggregation 'item' expected a single value, got {n} values"
+                            ));
+                        }
+                    }
+                    let agg_s = s.agg_first(&groups);
+                    AggregatedScalar(agg_s.with_name(keep_name))
+                },
                 GroupByMethod::NUnique => {
                     let (s, groups) = ac.get_final_aggregation();
                     let agg_s = s.agg_n_unique(&groups);

crates/polars-expr/src/planner.rs

@@ -378,6 +378,7 @@ fn create_physical_expr_inner(
                         I::NUnique(_) => GBM::NUnique,
                         I::First(_) => GBM::First,
                         I::Last(_) => GBM::Last,
+                        I::Item(_) => GBM::Item,
                         I::Mean(_) => GBM::Mean,
                         I::Implode(_) => GBM::Implode,
                         I::Quantile { .. } => unreachable!(),

crates/polars-expr/src/reduce/convert.rs

@@ -11,7 +11,7 @@ use crate::reduce::bitwise::{
     new_bitwise_and_reduction, new_bitwise_or_reduction, new_bitwise_xor_reduction,
 };
 use crate::reduce::count::{CountReduce, NullCountReduce};
-use crate::reduce::first_last::{new_first_reduction, new_last_reduction};
+use crate::reduce::first_last::{new_first_reduction, new_item_reduction, new_last_reduction};
 use crate::reduce::len::LenReduce;
 use crate::reduce::mean::new_mean_reduction;
 use crate::reduce::min_max::{new_max_reduction, new_min_reduction};
@@ -51,6 +51,7 @@ pub fn into_reduction(
             },
             IRAggExpr::First(input) => (new_first_reduction(get_dt(*input)?), *input),
             IRAggExpr::Last(input) => (new_last_reduction(get_dt(*input)?), *input),
+            IRAggExpr::Item(input) => (new_item_reduction(get_dt(*input)?), *input),
             IRAggExpr::Count {
                 input,
                 include_nulls,