From 564ba1c8b3339e1d854ff1e2a9ba88430ba8bbce Mon Sep 17 00:00:00 2001
From: Stijn de Gooijer <stijndegooijer@gmail.com>
Date: Sat, 21 Oct 2023 17:28:42 +0200
Subject: [PATCH] Rename periods to n

---
 py-polars/polars/dataframe/frame.py | 26 +++++++++++++-------------
 py-polars/polars/expr/expr.py       | 16 +++++++++-------
 py-polars/polars/expr/list.py       | 14 +++++++++-----
 py-polars/polars/lazyframe/frame.py | 26 ++++++++++++++------------
 py-polars/polars/series/list.py     | 10 +++++++---
 py-polars/polars/series/series.py   | 22 ++++++++++++----------
 6 files changed, 64 insertions(+), 50 deletions(-)

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).
 
         """