diff --git a/py-polars/polars/dataframe/frame.py b/py-polars/polars/dataframe/frame.py index ffc8f0f4223e..8a4e9cc429f0 100644 --- a/py-polars/polars/dataframe/frame.py +++ b/py-polars/polars/dataframe/frame.py @@ -7456,13 +7456,14 @@ def partition_by( return partitions - def shift(self, periods: int) -> Self: + @deprecate_renamed_parameter("periods", "n", version="0.19.11") + def shift(self, n: int = 1) -> Self: """ - Shift values by the given period. + Shift values by the given number of places. Parameters ---------- - periods + n Number of places to shift (may be negative). See Also @@ -7478,7 +7479,7 @@ def shift(self, periods: int) -> Self: ... "ham": ["a", "b", "c"], ... } ... ) - >>> df.shift(periods=1) + >>> df.shift(1) shape: (3, 3) ┌──────┬──────┬──────┐ │ foo ┆ bar ┆ ham │ @@ -7489,7 +7490,7 @@ def shift(self, periods: int) -> Self: │ 1 ┆ 6 ┆ a │ │ 2 ┆ 7 ┆ b │ └──────┴──────┴──────┘ - >>> df.shift(periods=-1) + >>> df.shift(-1) shape: (3, 3) ┌──────┬──────┬──────┐ │ foo ┆ bar ┆ ham │ @@ -7502,22 +7503,23 @@ def shift(self, periods: int) -> Self: └──────┴──────┴──────┘ """ - return self._from_pydf(self._df.shift(periods)) + return self._from_pydf(self._df.shift(n)) + @deprecate_renamed_parameter("periods", "n", version="0.19.11") def shift_and_fill( self, fill_value: int | str | float, *, - periods: int = 1, + n: int = 1, ) -> DataFrame: """ - Shift the values by a given period and fill the resulting null values. + Shift values by the given number of places and fill the resulting null values. Parameters ---------- fill_value fill None values with this value. - periods + n Number of places to shift (may be negative). Examples @@ -7529,7 +7531,7 @@ def shift_and_fill( ... "ham": ["a", "b", "c"], ... } ... ) - >>> df.shift_and_fill(periods=1, fill_value=0) + >>> df.shift_and_fill(n=1, fill_value=0) shape: (3, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ @@ -7543,9 +7545,7 @@ def shift_and_fill( """ return ( - self.lazy() - .shift_and_fill(fill_value=fill_value, periods=periods) - .collect(_eager=True) + self.lazy().shift_and_fill(fill_value=fill_value, n=n).collect(_eager=True) ) def is_duplicated(self) -> Series: diff --git a/py-polars/polars/expr/expr.py b/py-polars/polars/expr/expr.py index 05eb15530917..13023ca5a248 100644 --- a/py-polars/polars/expr/expr.py +++ b/py-polars/polars/expr/expr.py @@ -2351,13 +2351,14 @@ def take( indices_lit = parse_as_expression(indices) # type: ignore[arg-type] return self._from_pyexpr(self._pyexpr.take(indices_lit)) - def shift(self, periods: int = 1) -> Self: + @deprecate_renamed_parameter("periods", "n", version="0.19.11") + def shift(self, n: int = 1) -> Self: """ Shift the values by a given period. Parameters ---------- - periods + n Number of places to shift (may be negative). Examples @@ -2377,13 +2378,14 @@ def shift(self, periods: int = 1) -> Self: └─────┴─────────────┘ """ - return self._from_pyexpr(self._pyexpr.shift(periods)) + return self._from_pyexpr(self._pyexpr.shift(n)) + @deprecate_renamed_parameter("periods", "n", version="0.19.11") def shift_and_fill( self, fill_value: IntoExpr, *, - periods: int = 1, + n: int = 1, ) -> Self: """ Shift the values by a given period and fill the resulting null values. @@ -2392,13 +2394,13 @@ def shift_and_fill( ---------- fill_value Fill None values with the result of this expression. - periods + n Number of places to shift (may be negative). Examples -------- >>> df = pl.DataFrame({"foo": [1, 2, 3, 4]}) - >>> df.with_columns(foo_shifted=pl.col("foo").shift_and_fill("a", periods=1)) + >>> df.with_columns(foo_shifted=pl.col("foo").shift_and_fill("a", n=1)) shape: (4, 2) ┌─────┬─────────────┐ │ foo ┆ foo_shifted │ @@ -2413,7 +2415,7 @@ def shift_and_fill( """ fill_value = parse_as_expression(fill_value, str_as_lit=True) - return self._from_pyexpr(self._pyexpr.shift_and_fill(periods, fill_value)) + return self._from_pyexpr(self._pyexpr.shift_and_fill(n, fill_value)) def fill_null( self, diff --git a/py-polars/polars/expr/list.py b/py-polars/polars/expr/list.py index 88c4cb993402..3fd23e52132b 100644 --- a/py-polars/polars/expr/list.py +++ b/py-polars/polars/expr/list.py @@ -7,7 +7,10 @@ from polars import functions as F from polars.utils._parse_expr_input import parse_as_expression from polars.utils._wrap import wrap_expr -from polars.utils.deprecation import deprecate_renamed_function +from polars.utils.deprecation import ( + deprecate_renamed_function, + deprecate_renamed_parameter, +) if TYPE_CHECKING: from datetime import date, datetime, time @@ -712,13 +715,14 @@ def diff(self, n: int = 1, null_behavior: NullBehavior = "ignore") -> Expr: """ return wrap_expr(self._pyexpr.list_diff(n, null_behavior)) - def shift(self, periods: int | IntoExprColumn = 1) -> Expr: + @deprecate_renamed_parameter("periods", "n", version="0.19.11") + def shift(self, n: int | IntoExprColumn = 1) -> Expr: """ Shift values by the given period. Parameters ---------- - periods + n Number of places to shift (may be negative). Examples @@ -733,8 +737,8 @@ def shift(self, periods: int | IntoExprColumn = 1) -> Expr: ] """ - periods = parse_as_expression(periods) - return wrap_expr(self._pyexpr.list_shift(periods)) + n = parse_as_expression(n) + return wrap_expr(self._pyexpr.list_shift(n)) def slice( self, offset: int | str | Expr, length: int | str | Expr | None = None diff --git a/py-polars/polars/lazyframe/frame.py b/py-polars/polars/lazyframe/frame.py index 784c2afa7583..097d9693d72c 100644 --- a/py-polars/polars/lazyframe/frame.py +++ b/py-polars/polars/lazyframe/frame.py @@ -4206,13 +4206,14 @@ def reverse(self) -> Self: """ return self._from_pyldf(self._ldf.reverse()) - def shift(self, periods: int) -> Self: + @deprecate_renamed_parameter("periods", "n", version="0.19.11") + def shift(self, n: int = 1) -> Self: """ - Shift the values by a given period. + Shift values by the given number of places. Parameters ---------- - periods + n Number of places to shift (may be negative). Examples @@ -4223,7 +4224,7 @@ def shift(self, periods: int) -> Self: ... "b": [2, 4, 6], ... } ... ) - >>> lf.shift(periods=1).collect() + >>> lf.shift(1).collect() shape: (3, 2) ┌──────┬──────┐ │ a ┆ b │ @@ -4234,7 +4235,7 @@ def shift(self, periods: int) -> Self: │ 1 ┆ 2 │ │ 3 ┆ 4 │ └──────┴──────┘ - >>> lf.shift(periods=-1).collect() + >>> lf.shift(-1).collect() shape: (3, 2) ┌──────┬──────┐ │ a ┆ b │ @@ -4247,22 +4248,23 @@ def shift(self, periods: int) -> Self: └──────┴──────┘ """ - return self._from_pyldf(self._ldf.shift(periods)) + return self._from_pyldf(self._ldf.shift(n)) + @deprecate_renamed_parameter("periods", "n", version="0.19.11") def shift_and_fill( self, fill_value: Expr | int | str | float, *, - periods: int = 1, + n: int = 1, ) -> Self: """ - Shift the values by a given period and fill the resulting null values. + Shift values by the given number of places and fill the resulting null values. Parameters ---------- fill_value fill None values with the result of this expression. - periods + n Number of places to shift (may be negative). Examples @@ -4273,7 +4275,7 @@ def shift_and_fill( ... "b": [2, 4, 6], ... } ... ) - >>> lf.shift_and_fill(fill_value=0, periods=1).collect() + >>> lf.shift_and_fill(fill_value=0, n=1).collect() shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ @@ -4284,7 +4286,7 @@ def shift_and_fill( │ 1 ┆ 2 │ │ 3 ┆ 4 │ └─────┴─────┘ - >>> lf.shift_and_fill(periods=-1, fill_value=0).collect() + >>> lf.shift_and_fill(fill_value=0, n=-1).collect() shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ @@ -4299,7 +4301,7 @@ def shift_and_fill( """ if not isinstance(fill_value, pl.Expr): fill_value = F.lit(fill_value) - return self._from_pyldf(self._ldf.shift_and_fill(periods, fill_value._pyexpr)) + return self._from_pyldf(self._ldf.shift_and_fill(n, fill_value._pyexpr)) def slice(self, offset: int, length: int | None = None) -> Self: """ diff --git a/py-polars/polars/series/list.py b/py-polars/polars/series/list.py index 6387362d04e9..3efff0a36bc0 100644 --- a/py-polars/polars/series/list.py +++ b/py-polars/polars/series/list.py @@ -5,7 +5,10 @@ from polars import functions as F from polars.series.utils import expr_dispatch from polars.utils._wrap import wrap_s -from polars.utils.deprecation import deprecate_renamed_function +from polars.utils.deprecation import ( + deprecate_renamed_function, + deprecate_renamed_parameter, +) if TYPE_CHECKING: from datetime import date, datetime, time @@ -385,13 +388,14 @@ def diff(self, n: int = 1, null_behavior: NullBehavior = "ignore") -> Series: """ - def shift(self, periods: int | IntoExprColumn = 1) -> Series: + @deprecate_renamed_parameter("periods", "n", version="0.19.11") + def shift(self, n: int | IntoExprColumn = 1) -> Series: """ Shift values by the given period. Parameters ---------- - periods + n Number of places to shift (may be negative). Examples diff --git a/py-polars/polars/series/series.py b/py-polars/polars/series/series.py index 90591799cdf2..c5a5f07e030f 100644 --- a/py-polars/polars/series/series.py +++ b/py-polars/polars/series/series.py @@ -5082,14 +5082,20 @@ def map_elements( self._s.apply_lambda(function, pl_return_dtype, skip_nulls) ) - def shift(self, periods: int = 1) -> Series: + @deprecate_renamed_parameter("periods", "n", version="0.19.11") + def shift(self, n: int = 1) -> Series: """ Shift the values by a given period. + Parameters + ---------- + n + Number of places to shift (may be negative). + Examples -------- >>> s = pl.Series("a", [1, 2, 3]) - >>> s.shift(periods=1) + >>> s.shift(1) shape: (3,) Series: 'a' [i64] [ @@ -5097,7 +5103,7 @@ def shift(self, periods: int = 1) -> Series: 1 2 ] - >>> s.shift(periods=-1) + >>> s.shift(-1) shape: (3,) Series: 'a' [i64] [ @@ -5106,18 +5112,14 @@ def shift(self, periods: int = 1) -> Series: null ] - Parameters - ---------- - periods - Number of places to shift (may be negative). - """ + @deprecate_renamed_parameter("periods", "n", version="0.19.11") def shift_and_fill( self, fill_value: int | Expr, *, - periods: int = 1, + n: int = 1, ) -> Series: """ Shift the values by a given period and fill the resulting null values. @@ -5126,7 +5128,7 @@ def shift_and_fill( ---------- fill_value Fill None values with the result of this expression. - periods + n Number of places to shift (may be negative). """