docs(python): redirect tz_localize

py-polars/docs/source/reference/expressions/timeseries.rst

@@ -36,7 +36,6 @@ The following methods are available under the `expr.dt` attribute.
     Expr.dt.strftime
     Expr.dt.timestamp
     Expr.dt.truncate
-    Expr.dt.tz_localize
     Expr.dt.week
     Expr.dt.weekday
     Expr.dt.with_time_unit

py-polars/docs/source/reference/series/timeseries.rst

@@ -40,7 +40,6 @@ The following methods are available under the `Series.dt` attribute.
     Series.dt.strftime
     Series.dt.timestamp
     Series.dt.truncate
-    Series.dt.tz_localize
     Series.dt.week
     Series.dt.weekday
     Series.dt.with_time_unit

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

@@ -1,17 +1,17 @@
 from __future__ import annotations
 
-import warnings
 from datetime import time, timedelta
 from typing import TYPE_CHECKING
 
 import polars.internals as pli
 from polars.datatypes import DTYPE_TEMPORAL_UNITS, Date, Int32
-from polars.utils import _timedelta_to_pl_duration
+from polars.utils import _timedelta_to_pl_duration, redirect
 
 if TYPE_CHECKING:
     from polars.internals.type_aliases import EpochTimeUnit, TimeUnit
 
 
+@redirect({"tz_localize": "cast_time_zone"})
 class ExprDateTimeNameSpace:
     """Namespace for datetime related expressions."""
 
@@ -1246,59 +1246,6 @@ def cast_time_zone(self, tz: str | None) -> pli.Expr:
         """
         return pli.wrap_expr(self._pyexpr.dt_cast_time_zone(tz))
 
-    def tz_localize(self, tz: str) -> pli.Expr:
-        """
-        Localize tz-naive Datetime Series to tz-aware Datetime Series.
-
-        This method takes a naive Datetime Series and makes this time zone aware.
-        It does not move the time to another time zone.
-
-        .. deprecated:: 0.16.3
-            `with_column` will be removed in favor of the more generic `with_columns`
-            in version 0.18.0.
-
-        Parameters
-        ----------
-        tz
-            Time zone for the `Datetime` Series.
-
-        Examples
-        --------
-        >>> from datetime import datetime
-        >>> df = pl.DataFrame(
-        ...     {
-        ...         "date": pl.date_range(
-        ...             datetime(2020, 3, 1), datetime(2020, 5, 1), "1mo"
-        ...         ),
-        ...     }
-        ... )
-        >>> df.select(
-        ...     [
-        ...         pl.col("date"),
-        ...         pl.col("date")
-        ...         .dt.tz_localize(tz="Europe/Amsterdam")
-        ...         .alias("tz_localized"),
-        ...     ]
-        ... )
-        shape: (3, 2)
-        ┌─────────────────────┬────────────────────────────────┐
-        │ date                ┆ tz_localized                   │
-        │ ---                 ┆ ---                            │
-        │ datetime[μs]        ┆ datetime[μs, Europe/Amsterdam] │
-        ╞═════════════════════╪════════════════════════════════╡
-        │ 2020-03-01 00:00:00 ┆ 2020-03-01 00:00:00 CET        │
-        │ 2020-04-01 00:00:00 ┆ 2020-04-01 00:00:00 CEST       │
-        │ 2020-05-01 00:00:00 ┆ 2020-05-01 00:00:00 CEST       │
-        └─────────────────────┴────────────────────────────────┘
-        """
-        warnings.warn(
-            "`tz_localize` has been deprecated in favor of `cast_time_zone`."
-            " This method will be removed in version 0.18.0",
-            category=DeprecationWarning,
-            stacklevel=2,
-        )
-        return pli.wrap_expr(self._pyexpr.dt_tz_localize(tz))
-
     def days(self) -> pli.Expr:
         """
         Extract the days from a Duration type.

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

@@ -1,18 +1,18 @@
 from __future__ import annotations
 
-import warnings
 from datetime import date, datetime, time, timedelta
 from typing import TYPE_CHECKING
 
 import polars.internals as pli
 from polars.internals.series.utils import expr_dispatch
-from polars.utils import _to_python_datetime
+from polars.utils import _to_python_datetime, redirect
 
 if TYPE_CHECKING:
     from polars.internals.type_aliases import EpochTimeUnit, TimeUnit
     from polars.polars import PySeries
 
 
+@redirect({"tz_localize": "cast_time_zone"})
 @expr_dispatch
 class DateTimeNameSpace:
     """Series.dt namespace."""
@@ -1018,35 +1018,6 @@ def cast_time_zone(self, tz: str | None) -> pli.Series:
 
         """
 
-    def tz_localize(self, tz: str) -> pli.Series:
-        """
-        Localize tz-naive Datetime Series to tz-aware Datetime Series.
-
-        This method takes a naive Datetime Series and makes this time zone aware.
-        It does not move the time to another time zone.
-
-        .. deprecated:: 0.16.3
-            `with_column` will be removed in favor of the more generic `with_columns`
-            in version 0.18.0.
-
-        Parameters
-        ----------
-        tz
-            Time zone for the `Datetime` Series.
-        """
-        warnings.warn(
-            "`tz_localize` has been deprecated in favor of `cast_time_zone`."
-            " This method will be removed in version 0.18.0",
-            category=DeprecationWarning,
-            stacklevel=2,
-        )
-        return (
-            pli.wrap_s(self._s)
-            .to_frame()
-            .select(pli.col(self._s.name()).dt.tz_localize(tz))
-            .to_series()
-        )
-
     def days(self) -> pli.Series:
         """
         Extract the days from a Duration type.

py-polars/tests/unit/test_datelike.py

@@ -1850,22 +1850,14 @@ def test_cast_time_zone_from_naive() -> None:
 
 
 @pytest.mark.parametrize("time_zone", ["UTC", "Africa/Abidjan"])
-def test_tz_localize_from_utc(time_zone: str) -> None:
-    ts_utc = (
+def test_tz_localize_from_tz_aware(time_zone: str) -> None:
+    tz_aware = (
         pl.Series(["2018-10-28"]).str.strptime(pl.Datetime).dt.cast_time_zone(time_zone)
     )
-    err_msg = (
-        "^Cannot localize a tz-aware datetime. Consider using "
-        "'dt.with_time_zone' or 'dt.cast_time_zone'$"
-    )
-    deprecation_msg = (
-        "`tz_localize` has been deprecated in favor of `cast_time_zone`."
-        " This method will be removed in version 0.18.0"
-    )
-    with pytest.raises(ComputeError, match=err_msg), pytest.warns(
-        DeprecationWarning, match=deprecation_msg
-    ):
-        ts_utc.dt.tz_localize("America/Maceio")
+    deprecation_msg = "please use `.cast_time_zone` instead"
+    with pytest.warns(DeprecationWarning, match=deprecation_msg):
+        # ignoring as this is being redirected and will be removed anyway
+        tz_aware.dt.tz_localize("America/Maceio")  # type: ignore[attr-defined]
 
 
 def test_unlocalize() -> None: