chore[python]: Consistent handling of head/tail (#4588)

py-polars/polars/internals/dataframe/frame.py

@@ -49,6 +49,7 @@
 from polars.utils import (
     _prepare_row_count_args,
     _process_null_values,
+    deprecated_alias,
     format_path,
     handle_projection_columns,
     is_bool_sequence,
@@ -2652,14 +2653,15 @@ def limit(self: DF, length: int = 5) -> DF:
         """
         return self.head(length)
 
-    def head(self: DF, length: int = 5) -> DF:
+    @deprecated_alias(length="n")
+    def head(self: DF, n: int = 5) -> DF:
         """
-        Get first N rows as DataFrame.
+        Get the first `n` rows.
 
         Parameters
         ----------
-        length
-            Length of the head.
+        n
+            Number of rows to return.
 
         Examples
         --------
@@ -2685,16 +2687,17 @@ def head(self: DF, length: int = 5) -> DF:
         └─────┴─────┴─────┘
 
         """
-        return self._from_pydf(self._df.head(length))
+        return self._from_pydf(self._df.head(n))
 
-    def tail(self: DF, length: int = 5) -> DF:
+    @deprecated_alias(length="n")
+    def tail(self: DF, n: int = 5) -> DF:
         """
-        Get last N rows as DataFrame.
+        Get the last `n` rows.
 
         Parameters
         ----------
-        length
-            Length of the tail.
+        n
+            Number of rows to return.
 
         Examples
         --------
@@ -2720,7 +2723,7 @@ def tail(self: DF, length: int = 5) -> DF:
         └─────┴─────┴─────┘
 
         """
-        return self._from_pydf(self._df.tail(length))
+        return self._from_pydf(self._df.tail(n))
 
     def drop_nulls(self: DF, subset: str | list[str] | None = None) -> DF:
         """

py-polars/polars/internals/dataframe/groupby.py

@@ -295,12 +295,12 @@ def agg(self, aggs: pli.Expr | Sequence[pli.Expr]) -> pli.DataFrame:
 
     def head(self, n: int = 5) -> DF:
         """
-        Return first n rows of each group.
+        Get the first `n` rows of each group.
 
         Parameters
         ----------
         n
-            Number of values of the group to select
+            Number of rows to return.
 
         Examples
         --------
@@ -359,12 +359,12 @@ def head(self, n: int = 5) -> DF:
 
     def tail(self, n: int = 5) -> DF:
         """
-        Return last n rows of each group.
+        Get the last `n` rows of each group.
 
         Parameters
         ----------
         n
-            Number of values of the group to select
+            Number of rows to return.
 
         Examples
         --------

py-polars/polars/internals/expr/expr.py

@@ -3197,9 +3197,14 @@ def take_every(self, n: int) -> Expr:
         """
         return wrap_expr(self._pyexpr.take_every(n))
 
-    def head(self, n: int | Expr | None = None) -> Expr:
+    def head(self, n: int = 10) -> Expr:
         """
-        Take the first n values.
+        Get the first `n` rows.
+
+        Parameters
+        ----------
+        n
+            Number of rows to return.
 
         Examples
         --------
@@ -3221,9 +3226,14 @@ def head(self, n: int | Expr | None = None) -> Expr:
         """
         return wrap_expr(self._pyexpr.head(n))
 
-    def tail(self, n: int | None = None) -> Expr:
+    def tail(self, n: int = 10) -> Expr:
         """
-        Take the last n values.
+        Get the last `n` rows.
+
+        Parameters
+        ----------
+        n
+            Number of rows to return.
 
         Examples
         --------

py-polars/polars/internals/expr/list.py

@@ -535,12 +535,12 @@ def slice(self, offset: int, length: int) -> pli.Expr:
 
     def head(self, n: int = 5) -> pli.Expr:
         """
-        Slice the head of every sublist
+        Slice the first `n` values of every sublist.
 
         Parameters
         ----------
         n
-            How many values to take in the slice.
+            Number of values to return for each sublist.
 
         Examples
         --------
@@ -558,12 +558,12 @@ def head(self, n: int = 5) -> pli.Expr:
 
     def tail(self, n: int = 5) -> pli.Expr:
         """
-        Slice the tail of every sublist
+        Slice the last `n` values of every sublist.
 
         Parameters
         ----------
         n
-            How many values to take in the slice.
+            Number of values to return for each sublist.
 
         Examples
         --------

py-polars/polars/internals/lazy_functions.py

@@ -552,25 +552,25 @@ def last(column: str | pli.Series | None = None) -> pli.Expr:
 
 
 @overload
-def head(column: str, n: int | None) -> pli.Expr:
+def head(column: str, n: int = 10) -> pli.Expr:
     ...
 
 
 @overload
-def head(column: pli.Series, n: int | None) -> pli.Series:
+def head(column: pli.Series, n: int = 10) -> pli.Series:
     ...
 
 
-def head(column: str | pli.Series, n: int | None = None) -> pli.Expr | pli.Series:
+def head(column: str | pli.Series, n: int = 10) -> pli.Expr | pli.Series:
     """
-    Get the first n rows of an Expression.
+    Get the first `n` rows.
 
     Parameters
     ----------
     column
         Column name or Series.
     n
-        Number of rows to take.
+        Number of rows to return.
 
     """
     if isinstance(column, pli.Series):
@@ -579,25 +579,25 @@ def head(column: str | pli.Series, n: int | None = None) -> pli.Expr | pli.Serie
 
 
 @overload
-def tail(column: str, n: int | None) -> pli.Expr:
+def tail(column: str, n: int = 10) -> pli.Expr:
     ...
 
 
 @overload
-def tail(column: pli.Series, n: int | None) -> pli.Series:
+def tail(column: pli.Series, n: int = 10) -> pli.Series:
     ...
 
 
-def tail(column: str | pli.Series, n: int | None = None) -> pli.Expr | pli.Series:
+def tail(column: str | pli.Series, n: int = 10) -> pli.Expr | pli.Series:
     """
-    Get the last n rows of an Expression.
+    Get the last `n` rows.
 
     Parameters
     ----------
     column
         Column name or Series.
     n
-        Number of rows to take.
+        Number of rows to return.
 
     """
     if isinstance(column, pli.Series):

py-polars/polars/internals/lazyframe/frame.py

@@ -1842,17 +1842,17 @@ def limit(self: LDF, n: int = 5) -> LDF:
         Parameters
         ----------
         n
-            Number of rows.
+            Number of rows to return.
 
         """
         return self.slice(0, n)
 
     def head(self: LDF, n: int = 5) -> LDF:
         """
-        Get the first `n` rows of the DataFrame.
+        Get the first `n` rows.
 
         .. note::
-            Consider using the :func:`fetch` operation when you only want to test your
+            Consider using the :func:`fetch` operation if you only want to test your
             query. The :func:`fetch` operation will load the first `n` rows at the scan
             level, whereas the :func:`head`/:func:`limit` are applied at the end.
 
@@ -1862,7 +1862,7 @@ def head(self: LDF, n: int = 5) -> LDF:
         Parameters
         ----------
         n
-            Number of rows.
+            Number of rows to return.
 
         """
         return self.limit(n)

py-polars/polars/internals/lazyframe/groupby.py

@@ -58,12 +58,12 @@ def agg(self, aggs: pli.Expr | Sequence[pli.Expr]) -> LDF:
 
     def head(self, n: int = 5) -> LDF:
         """
-        Return first n rows of each group.
+        Get the first `n` rows of each group.
 
         Parameters
         ----------
         n
-            Number of values of the group to select
+            Number of rows to return.
 
         Examples
         --------
@@ -115,12 +115,12 @@ def head(self, n: int = 5) -> LDF:
 
     def tail(self, n: int = 5) -> LDF:
         """
-        Return last n rows of each group.
+        Get the last `n` rows of each group.
 
         Parameters
         ----------
         n
-            Number of values of the group to select
+            Number of rows to return.
 
         Examples
         --------

py-polars/polars/internals/series/list.py

@@ -226,12 +226,12 @@ def slice(self, offset: int, length: int) -> pli.Series:
 
     def head(self, n: int = 5) -> pli.Series:
         """
-        Slice the head of every sublist
+        Slice the first `n` values of every sublist.
 
         Parameters
         ----------
         n
-            How many values to take in the slice.
+            Number of values to return for each sublist.
 
         Examples
         --------
@@ -248,12 +248,12 @@ def head(self, n: int = 5) -> pli.Series:
 
     def tail(self, n: int = 5) -> pli.Series:
         """
-        Slice the tail of every sublist
+        Slice the last `n` values of every sublist.
 
         Parameters
         ----------
         n
-            How many values to take in the slice.
+            Number of values to return for each sublist.
 
         Examples
         --------

py-polars/polars/internals/series/series.py

@@ -53,6 +53,7 @@
     _date_to_pl_date,
     _datetime_to_pl_timestamp,
     _ptr_to_numpy,
+    deprecated_alias,
     is_bool_sequence,
     is_int_sequence,
     range_to_slice,
@@ -1484,14 +1485,15 @@ def filter(self, predicate: Series | list[bool]) -> Series:
             predicate = Series("", predicate)
         return wrap_s(self._s.filter(predicate._s))
 
-    def head(self, length: int | None = None) -> Series:
+    @deprecated_alias(length="n")
+    def head(self, n: int = 10) -> Series:
         """
-        Get first N elements as Series.
+        Get the first `n` rows.
 
         Parameters
         ----------
-        length
-            Length of the head.
+        n
+            Number of rows to return.
 
         Examples
         --------
@@ -1505,16 +1507,17 @@ def head(self, length: int | None = None) -> Series:
         ]
 
         """
-        return wrap_s(self._s.head(length))
+        return self.to_frame().select(pli.col(self.name).head(n)).to_series()
 
-    def tail(self, length: int | None = None) -> Series:
+    @deprecated_alias(length="n")
+    def tail(self, n: int = 10) -> Series:
         """
-        Get last N elements as Series.
+        Get the last `n` rows.
 
         Parameters
         ----------
-        length
-            Length of the tail.
+        n
+            Number of rows to return.
 
         Examples
         --------
@@ -1528,7 +1531,7 @@ def tail(self, length: int | None = None) -> Series:
         ]
 
         """
-        return wrap_s(self._s.tail(length))
+        return self.to_frame().select(pli.col(self.name).tail(n)).to_series()
 
     def take_every(self, n: int) -> Series:
         """

py-polars/src/series.rs

@@ -558,14 +558,6 @@ impl PySeries {
         (&self.series % &other.series).into()
     }
 
-    pub fn head(&self, length: Option<usize>) -> Self {
-        (self.series.head(length)).into()
-    }
-
-    pub fn tail(&self, length: Option<usize>) -> Self {
-        (self.series.tail(length)).into()
-    }
-
     pub fn sort(&mut self, reverse: bool) -> Self {
         PySeries::new(self.series.sort(reverse))
     }