feat[python]: Add Expr.limit alias (#4597)

py-polars/docs/source/reference/expression.rst

@@ -202,6 +202,7 @@ Manipulation/ selection
     Expr.head
     Expr.inspect
     Expr.interpolate
+    Expr.limit
     Expr.lower_bound
     Expr.rechunk
     Expr.reinterpret

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

@@ -2617,42 +2617,20 @@ def slice(self: DF, offset: int, length: int | None = None) -> DF:
             length = self.height - offset + length
         return self._from_pydf(self._df.slice(offset, length))
 
-    def limit(self: DF, length: int = 5) -> DF:
+    @deprecated_alias(length="n")
+    def limit(self: DF, n: int = 5) -> DF:
         """
-        Get first N rows as DataFrame.
+        Get the first `n` rows.
 
-        See Also
-        --------
-        head, tail, slice
+        Alias for :func:`head`.
 
         Parameters
         ----------
-        length
-            Amount of rows to take.
-
-        Examples
-        --------
-        >>> df = pl.DataFrame(
-        ...     {
-        ...         "foo": [1, 2, 3],
-        ...         "bar": [6, 7, 8],
-        ...         "ham": ["a", "b", "c"],
-        ...     }
-        ... )
-        >>> df.limit(2)
-        shape: (2, 3)
-        ┌─────┬─────┬─────┐
-        │ foo ┆ bar ┆ ham │
-        │ --- ┆ --- ┆ --- │
-        │ i64 ┆ i64 ┆ str │
-        ╞═════╪═════╪═════╡
-        │ 1   ┆ 6   ┆ a   │
-        ├╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌┤
-        │ 2   ┆ 7   ┆ b   │
-        └─────┴─────┴─────┘
+        n
+            Number of rows to return.
 
         """
-        return self.head(length)
+        return self.head(n)
 
     @deprecated_alias(length="n")
     def head(self: DF, n: int = 5) -> DF:

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

@@ -3260,6 +3260,20 @@ def tail(self, n: int = 10) -> Expr:
         """
         return wrap_expr(self._pyexpr.tail(n))
 
+    def limit(self, n: int = 10) -> Expr:
+        """
+        Get the first `n` rows.
+
+        Alias for :func:`head`.
+
+        Parameters
+        ----------
+        n
+            Number of rows to return.
+
+        """
+        return self.head(n)
+
     def pow(self, exponent: int | float | pli.Series | Expr) -> Expr:
         """
         Raise expression to the power of exponent.

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

@@ -1832,44 +1832,45 @@ def slice(self: LDF, offset: int, length: int | None = None) -> LDF:
 
     def limit(self: LDF, n: int = 5) -> LDF:
         """
-        Limit the LazyFrame to the first `n` rows.
+        Get the first `n` rows.
 
-        .. note::
-            Consider using the :func:`fetch` operation when 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.
+        Alias for :func:`head`.
 
         Parameters
         ----------
         n
             Number of rows to return.
 
+        Notes
+        -----
+        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.
+
         """
-        return self.slice(0, n)
+        return self.head(n)
 
     def head(self: LDF, n: int = 5) -> LDF:
         """
         Get the first `n` rows.
 
-        .. note::
-            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.
-
-        This operation instead loads all the rows and only applies the ``head`` at the
-        end.
-
         Parameters
         ----------
         n
             Number of rows to return.
 
+        Notes
+        -----
+        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.
+
         """
-        return self.limit(n)
+        return self.slice(0, n)
 
     def tail(self: LDF, n: int = 5) -> LDF:
         """
-        Get the last `n` rows of the DataFrame.
+        Get the last `n` rows.
 
         Parameters
         ----------

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

@@ -1326,28 +1326,20 @@ def cumprod(self, reverse: bool = False) -> Series:
 
         """
 
-    def limit(self, num_elements: int = 10) -> Series:
+    @deprecated_alias(num_elements="n")
+    def limit(self, n: int = 10) -> Series:
         """
-        Take n elements from this Series.
+        Get the first `n` rows.
+
+        Alias for :func:`head`.
 
         Parameters
         ----------
-        num_elements
-            Amount of elements to take.
-
-        Examples
-        --------
-        >>> s = pl.Series("a", [1, 2, 3])
-        >>> s.limit(2)
-        shape: (2,)
-        Series: 'a' [i64]
-        [
-                1
-                2
-        ]
+        n
+            Number of rows to return.
 
         """
-        return wrap_s(self._s.limit(num_elements))
+        return self.to_frame().select(pli.col(self.name).limit(n)).to_series()
 
     def slice(self, offset: int, length: int | None = None) -> Series:
         """

py-polars/src/series.rs

@@ -480,11 +480,6 @@ impl PySeries {
         self.series.n_chunks()
     }
 
-    pub fn limit(&self, num_elements: usize) -> Self {
-        let series = self.series.limit(num_elements);
-        series.into()
-    }
-
     pub fn slice(&self, offset: i64, length: Option<usize>) -> Self {
         let series = self
             .series