depr(python,rust!): Rename dt.seconds to dt.total_seconds (likewise for days, hours, minutes, milliseconds, microseconds, and nanoseconds)

docs/src/python/user-guide/transformations/time-series/rolling.py

@@ -31,7 +31,7 @@
 
 out = df.group_by_dynamic("time", every="1mo", period="1mo", closed="left").agg(
     pl.col("time").cumcount().reverse().head(3).alias("day/eom"),
-    ((pl.col("time") - pl.col("time").first()).last().dt.days() + 1).alias(
+    ((pl.col("time") - pl.col("time").first()).last().dt.total_days() + 1).alias(
         "days_in_month"
     ),
 )

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

@@ -44,6 +44,13 @@ The following methods are available under the `expr.dt` attribute.
     Expr.dt.time
     Expr.dt.timestamp
     Expr.dt.to_string
+    Expr.dt.total_days
+    Expr.dt.total_hours
+    Expr.dt.total_microseconds
+    Expr.dt.total_milliseconds
+    Expr.dt.total_minutes
+    Expr.dt.total_nanoseconds
+    Expr.dt.total_seconds
     Expr.dt.truncate
     Expr.dt.week
     Expr.dt.weekday

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

@@ -48,6 +48,13 @@ The following methods are available under the `Series.dt` attribute.
     Series.dt.time
     Series.dt.timestamp
     Series.dt.to_string
+    Series.dt.total_days
+    Series.dt.total_hours
+    Series.dt.total_microseconds
+    Series.dt.total_milliseconds
+    Series.dt.total_minutes
+    Series.dt.total_nanoseconds
+    Series.dt.total_seconds
     Series.dt.truncate
     Series.dt.week
     Series.dt.weekday

py-polars/polars/expr/datetime.py

@@ -9,7 +9,10 @@
 from polars.utils._parse_expr_input import parse_as_expression
 from polars.utils._wrap import wrap_expr
 from polars.utils.convert import _timedelta_to_pl_duration
-from polars.utils.deprecation import rename_use_earliest_to_ambiguous
+from polars.utils.deprecation import (
+    deprecate_renamed_function,
+    rename_use_earliest_to_ambiguous,
+)
 
 if TYPE_CHECKING:
     from datetime import timedelta
@@ -1454,9 +1457,9 @@ def replace_time_zone(
             self._pyexpr.dt_replace_time_zone(time_zone, ambiguous._pyexpr)
         )
 
-    def days(self) -> Expr:
+    def total_days(self) -> Expr:
         """
-        Extract the days from a Duration type.
+        Extract the total days from a Duration type.
 
         Returns
         -------
@@ -1476,7 +1479,7 @@ def days(self) -> Expr:
         >>> df.select(
         ...     [
         ...         pl.col("date"),
-        ...         pl.col("date").diff().dt.days().alias("days_diff"),
+        ...         pl.col("date").diff().dt.total_days().alias("days_diff"),
         ...     ]
         ... )
         shape: (3, 2)
@@ -1493,9 +1496,9 @@ def days(self) -> Expr:
         """
         return wrap_expr(self._pyexpr.duration_days())
 
-    def hours(self) -> Expr:
+    def total_hours(self) -> Expr:
         """
-        Extract the hours from a Duration type.
+        Extract the total hours from a Duration type.
 
         Returns
         -------
@@ -1515,7 +1518,7 @@ def hours(self) -> Expr:
         >>> df.select(
         ...     [
         ...         pl.col("date"),
-        ...         pl.col("date").diff().dt.hours().alias("hours_diff"),
+        ...         pl.col("date").diff().dt.total_hours().alias("hours_diff"),
         ...     ]
         ... )
         shape: (4, 2)
@@ -1533,9 +1536,9 @@ def hours(self) -> Expr:
         """
         return wrap_expr(self._pyexpr.duration_hours())
 
-    def minutes(self) -> Expr:
+    def total_minutes(self) -> Expr:
         """
-        Extract the minutes from a Duration type.
+        Extract the total minutes from a Duration type.
 
         Returns
         -------
@@ -1555,7 +1558,7 @@ def minutes(self) -> Expr:
         >>> df.select(
         ...     [
         ...         pl.col("date"),
-        ...         pl.col("date").diff().dt.minutes().alias("minutes_diff"),
+        ...         pl.col("date").diff().dt.total_minutes().alias("minutes_diff"),
         ...     ]
         ... )
         shape: (4, 2)
@@ -1573,9 +1576,9 @@ def minutes(self) -> Expr:
         """
         return wrap_expr(self._pyexpr.duration_minutes())
 
-    def seconds(self) -> Expr:
+    def total_seconds(self) -> Expr:
         """
-        Extract the seconds from a Duration type.
+        Extract the total seconds from a Duration type.
 
         Returns
         -------
@@ -1596,10 +1599,8 @@ def seconds(self) -> Expr:
         ...     }
         ... )
         >>> df.select(
-        ...     [
-        ...         pl.col("date"),
-        ...         pl.col("date").diff().dt.seconds().alias("seconds_diff"),
-        ...     ]
+        ...     pl.col("date"),
+        ...     pl.col("date").diff().dt.total_seconds().alias("seconds_diff"),
         ... )
         shape: (5, 2)
         ┌─────────────────────┬──────────────┐
@@ -1617,9 +1618,9 @@ def seconds(self) -> Expr:
         """
         return wrap_expr(self._pyexpr.duration_seconds())
 
-    def milliseconds(self) -> Expr:
+    def total_milliseconds(self) -> Expr:
         """
-        Extract the milliseconds from a Duration type.
+        Extract the total milliseconds from a Duration type.
 
         Returns
         -------
@@ -1640,10 +1641,8 @@ def milliseconds(self) -> Expr:
         ...     }
         ... )
         >>> df.select(
-        ...     [
-        ...         pl.col("date"),
-        ...         pl.col("date").diff().dt.milliseconds().alias("milliseconds_diff"),
-        ...     ]
+        ...     pl.col("date"),
+        ...     milliseconds_diff=pl.col("date").diff().dt.total_milliseconds(),
         ... )
         shape: (1_001, 2)
         ┌─────────────────────────┬───────────────────┐
@@ -1665,9 +1664,9 @@ def milliseconds(self) -> Expr:
         """
         return wrap_expr(self._pyexpr.duration_milliseconds())
 
-    def microseconds(self) -> Expr:
+    def total_microseconds(self) -> Expr:
         """
-        Extract the microseconds from a Duration type.
+        Extract the total microseconds from a Duration type.
 
         Returns
         -------
@@ -1688,10 +1687,8 @@ def microseconds(self) -> Expr:
         ...     }
         ... )
         >>> df.select(
-        ...     [
-        ...         pl.col("date"),
-        ...         pl.col("date").diff().dt.microseconds().alias("microseconds_diff"),
-        ...     ]
+        ...     pl.col("date"),
+        ...     microseconds_diff=pl.col("date").diff().dt.total_microseconds(),
         ... )
         shape: (1_001, 2)
         ┌─────────────────────────┬───────────────────┐
@@ -1713,9 +1710,9 @@ def microseconds(self) -> Expr:
         """
         return wrap_expr(self._pyexpr.duration_microseconds())
 
-    def nanoseconds(self) -> Expr:
+    def total_nanoseconds(self) -> Expr:
         """
-        Extract the nanoseconds from a Duration type.
+        Extract the total nanoseconds from a Duration type.
 
         Returns
         -------
@@ -1736,10 +1733,8 @@ def nanoseconds(self) -> Expr:
         ...     }
         ... )
         >>> df.select(
-        ...     [
-        ...         pl.col("date"),
-        ...         pl.col("date").diff().dt.nanoseconds().alias("nanoseconds_diff"),
-        ...     ]
+        ...     pl.col("date"),
+        ...     nanoseconds_diff=pl.col("date").diff().dt.total_nanoseconds(),
         ... )
         shape: (1_001, 2)
         ┌─────────────────────────┬──────────────────┐
@@ -2018,3 +2013,80 @@ def dst_offset(self) -> Expr:
         └─────────────────────────────┴──────────────┘
         """
         return wrap_expr(self._pyexpr.dt_dst_offset())
+
+    @deprecate_renamed_function("total_days", version="0.19.13")
+    def days(self) -> Expr:
+        """
+        Extract the total days from a Duration type.
+
+        .. deprecated:: 0.19.13
+            Use :meth:`total_days` instead.
+
+        """
+        return self.total_days()
+
+    @deprecate_renamed_function("total_hours", version="0.19.13")
+    def hours(self) -> Expr:
+        """
+        Extract the total hours from a Duration type.
+
+        .. deprecated:: 0.19.13
+            Use :meth:`total_hours` instead.
+
+        """
+        return self.total_hours()
+
+    @deprecate_renamed_function("total_minutes", version="0.19.13")
+    def minutes(self) -> Expr:
+        """
+        Extract the total minutes from a Duration type.
+
+        .. deprecated:: 0.19.13
+            Use :meth:`total_minutes` instead.
+
+        """
+        return self.total_minutes()
+
+    @deprecate_renamed_function("total_seconds", version="0.19.13")
+    def seconds(self) -> Expr:
+        """
+        Extract the total seconds from a Duration type.
+
+        .. deprecated:: 0.19.13
+            Use :meth:`total_seconds` instead.
+
+        """
+        return self.total_seconds()
+
+    @deprecate_renamed_function("total_milliseconds", version="0.19.13")
+    def milliseconds(self) -> Expr:
+        """
+        Extract the total milliseconds from a Duration type.
+
+        .. deprecated:: 0.19.13
+            Use :meth:`total_milliseconds` instead.
+
+        """
+        return self.total_milliseconds()
+
+    @deprecate_renamed_function("total_microseconds", version="0.19.13")
+    def microseconds(self) -> Expr:
+        """
+        Extract the total microseconds from a Duration type.
+
+        .. deprecated:: 0.19.13
+            Use :meth:`total_microseconds` instead.
+
+        """
+        return self.total_microseconds()
+
+    @deprecate_renamed_function("total_nanoseconds", version="0.19.13")
+    def nanoseconds(self) -> Expr:
+        """
+        Extract the total nanoseconds from a Duration type.
+
+        .. deprecated:: 0.19.13
+            Use :meth:`total_nanoseconds` instead.
+
+        """
+        return self.total_nanoseconds()