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-error/src/lib.rs

@@ -504,6 +504,19 @@ on startup."#.trim_start())
             ComputeError: "`strptime` / `to_datetime` was called with no format and no time zone, but a time zone is part of the data.\n\nThis was previously allowed but led to unpredictable and erroneous results. Give a format string, set a time zone or perform the operation eagerly on a Series instead of on an Expr."
         )
     };
+    (item_agg_count_not_one = $n:expr) => {
+        if $n == 0 {
+            polars_err!(ComputeError:
+                "aggregation 'item' expected a single value, got none"
+            )
+        } else if $n > 1 {
+            polars_err!(ComputeError:
+                "aggregation 'item' expected a single value, got {} values", $n
+            )
+        } else {
+            unreachable!()
+        }
+    };
 }
 
 #[macro_export]

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

@@ -125,6 +125,10 @@ impl PhysicalExpr for AggregationExpr {
             } else {
                 s.tail(Some(1))
             }),
+            GroupByMethod::Item => Ok(match s.len() {
+                1 => s,
+                n => polars_bail!(item_agg_count_not_one = n),
+            }),
             GroupByMethod::Sum => parallel_op_columns(
                 |s| s.sum_reduce().map(|sc| sc.into_column(s.name().clone())),
                 s,
@@ -332,6 +336,19 @@ 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() {
+                        match gc {
+                            None | Some(1) => continue,
+                            Some(n) => {
+                                polars_bail!(item_agg_count_not_one = n);
+                            },
+                        }
+                    }
+                    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,