feat(rust, python) rename 'tz' to 'time_zone' in convert_time_zone an…

…d replace_time_zone (#6784)

Co-authored-by: MarcoGorelli <>

polars/polars-core/src/chunked_array/temporal/datetime.rs

@@ -142,8 +142,8 @@ impl DatetimeChunked {
     }
 
     #[cfg(feature = "timezones")]
-    pub fn replace_time_zone(&self, tz: Option<&str>) -> PolarsResult<DatetimeChunked> {
-        match (self.time_zone(), tz) {
+    pub fn replace_time_zone(&self, time_zone: Option<&str>) -> PolarsResult<DatetimeChunked> {
+        match (self.time_zone(), time_zone) {
             (Some(from), Some(to)) => {
                 let chunks = self
                     .downcast_iter()
@@ -316,16 +316,16 @@ impl DatetimeChunked {
 
     /// Change the underlying [`TimeZone`]. This does not modify the data.
     #[cfg(feature = "timezones")]
-    pub fn set_time_zone(&mut self, tz: TimeZone) -> PolarsResult<()> {
-        validate_time_zone(tz.to_string())?;
-        self.2 = Some(Datetime(self.time_unit(), Some(tz)));
+    pub fn set_time_zone(&mut self, time_zone: TimeZone) -> PolarsResult<()> {
+        validate_time_zone(time_zone.to_string())?;
+        self.2 = Some(Datetime(self.time_unit(), Some(time_zone)));
         Ok(())
     }
     #[cfg(feature = "timezones")]
-    pub fn convert_time_zone(mut self, tz: TimeZone) -> PolarsResult<Self> {
+    pub fn convert_time_zone(mut self, time_zone: TimeZone) -> PolarsResult<Self> {
         match self.time_zone() {
             Some(_) => {
-                self.set_time_zone(tz)?;
+                self.set_time_zone(time_zone)?;
                 Ok(self)
             }
             _ => Err(PolarsError::ComputeError(

polars/polars-lazy/polars-plan/src/dsl/dt.rs

@@ -67,12 +67,12 @@ impl DateLikeNameSpace {
 
     /// Change the underlying [`TimeZone`] of the [`Series`]. This does not modify the data.
     #[cfg(feature = "timezones")]
-    pub fn convert_time_zone(self, tz: TimeZone) -> Expr {
+    pub fn convert_time_zone(self, time_zone: TimeZone) -> Expr {
         self.0.map(
             move |s| match s.dtype() {
                 DataType::Datetime(_, Some(_)) => {
                     let mut ca = s.datetime().unwrap().clone();
-                    ca.set_time_zone(tz.clone())?;
+                    ca.set_time_zone(time_zone.clone())?;
                     Ok(Some(ca.into_series()))
                 }
                 _ => Err(PolarsError::ComputeError(
@@ -218,10 +218,10 @@ impl DateLikeNameSpace {
     }
 
     #[cfg(feature = "timezones")]
-    pub fn replace_time_zone(self, tz: Option<TimeZone>) -> Expr {
+    pub fn replace_time_zone(self, time_zone: Option<TimeZone>) -> Expr {
         self.0
             .map_private(FunctionExpr::TemporalExpr(TemporalFunction::CastTimezone(
-                tz,
+                time_zone,
             )))
     }
 

polars/polars-lazy/polars-plan/src/dsl/function_expr/datetime.rs

@@ -137,9 +137,9 @@ pub(super) fn round(s: &Series, every: &str, offset: &str) -> PolarsResult<Serie
     }
 }
 #[cfg(feature = "timezones")]
-pub(super) fn replace_timezone(s: &Series, tz: Option<&str>) -> PolarsResult<Series> {
+pub(super) fn replace_timezone(s: &Series, time_zone: Option<&str>) -> PolarsResult<Series> {
     let ca = s.datetime()?;
-    ca.replace_time_zone(tz).map(|ca| ca.into_series())
+    ca.replace_time_zone(time_zone).map(|ca| ca.into_series())
 }
 
 #[cfg(feature = "timezones")]

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

@@ -5,7 +5,7 @@
 
 import polars.internals as pli
 from polars.datatypes import DTYPE_TEMPORAL_UNITS, Date, Int32
-from polars.utils import _timedelta_to_pl_duration, redirect
+from polars.utils import _timedelta_to_pl_duration, deprecated_alias, redirect
 
 if TYPE_CHECKING:
     from polars.internals.type_aliases import EpochTimeUnit, TimeUnit
@@ -1160,13 +1160,14 @@ def cast_time_unit(self, tu: TimeUnit) -> pli.Expr:
         """
         return pli.wrap_expr(self._pyexpr.dt_cast_time_unit(tu))
 
-    def convert_time_zone(self, tz: str) -> pli.Expr:
+    @deprecated_alias(tz="time_zone")
+    def convert_time_zone(self, time_zone: str) -> pli.Expr:
         """
         Convert to given time zone for a Series of type Datetime.
 
         Parameters
         ----------
-        tz
+        time_zone
             Time zone for the `Datetime` Series.
 
         Examples
@@ -1201,9 +1202,10 @@ def convert_time_zone(self, tz: str) -> pli.Expr:
         │ 2020-05-01 00:00:00 UTC ┆ 2020-05-01 01:00:00 BST     │
         └─────────────────────────┴─────────────────────────────┘
         """
-        return pli.wrap_expr(self._pyexpr.dt_convert_time_zone(tz))
+        return pli.wrap_expr(self._pyexpr.dt_convert_time_zone(time_zone))
 
-    def replace_time_zone(self, tz: str | None) -> pli.Expr:
+    @deprecated_alias(tz="time_zone")
+    def replace_time_zone(self, time_zone: str | None) -> pli.Expr:
         """
         Replace time zone for a Series of type Datetime.
 
@@ -1212,7 +1214,7 @@ def replace_time_zone(self, tz: str | None) -> pli.Expr:
 
         Parameters
         ----------
-        tz
+        time_zone
             Time zone for the `Datetime` Series. Pass `None` to unset time zone.
 
         Examples
@@ -1250,7 +1252,7 @@ def replace_time_zone(self, tz: str | None) -> pli.Expr:
         └─────────────────────────────┴────────────────────────────────┘
 
         """
-        return pli.wrap_expr(self._pyexpr.dt_replace_time_zone(tz))
+        return pli.wrap_expr(self._pyexpr.dt_replace_time_zone(time_zone))
 
     def days(self) -> pli.Expr:
         """

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

@@ -5,7 +5,7 @@
 
 import polars.internals as pli
 from polars.internals.series.utils import expr_dispatch
-from polars.utils import _to_python_datetime, redirect
+from polars.utils import _to_python_datetime, deprecated_alias, redirect
 
 if TYPE_CHECKING:
     from polars.internals.type_aliases import EpochTimeUnit, TimeUnit
@@ -917,13 +917,14 @@ def cast_time_unit(self, tu: TimeUnit) -> pli.Series:
 
         """
 
-    def convert_time_zone(self, tz: str) -> pli.Series:
+    @deprecated_alias(tz="time_zone")
+    def convert_time_zone(self, time_zone: str) -> pli.Series:
         """
         Convert to given time zone for a Series of type Datetime.
 
         Parameters
         ----------
-        tz
+        time_zone
             Time zone for the `Datetime` Series.
 
         Examples
@@ -950,8 +951,15 @@ def convert_time_zone(self, tz: str) -> pli.Series:
             2020-05-01 01:00:00 BST
         ]
         """
+        return (
+            pli.wrap_s(self._s)
+            .to_frame()
+            .select(pli.col(self._s.name()).dt.convert_time_zone(time_zone))
+            .to_series()
+        )
 
-    def replace_time_zone(self, tz: str | None) -> pli.Series:
+    @deprecated_alias(tz="time_zone")
+    def replace_time_zone(self, time_zone: str | None) -> pli.Series:
         """
         Replace time zone for a Series of type Datetime.
 
@@ -960,7 +968,7 @@ def replace_time_zone(self, tz: str | None) -> pli.Series:
 
         Parameters
         ----------
-        tz
+        time_zone
             Time zone for the `Datetime` Series. Pass `None` to unset time zone.
 
         Examples
@@ -1023,6 +1031,12 @@ def replace_time_zone(self, tz: str | None) -> pli.Series:
         ]
 
         """
+        return (
+            pli.wrap_s(self._s)
+            .to_frame()
+            .select(pli.col(self._s.name()).dt.replace_time_zone(time_zone))
+            .to_series()
+        )
 
     def days(self) -> pli.Series:
         """