docs(python, rust): clean up inconsistencies in duration string langu…

…age (pola-rs#9551)
c-peters · Jul 14, 2023 · cf17ec8 · cf17ec8
1 parent 2775ed2
commit cf17ec8
Show file tree

Hide file tree

Showing 7 changed files with 157 additions and 45 deletions.
diff --git a/polars/polars-time/src/upsample.rs b/polars/polars-time/src/upsample.rs
@@ -27,16 +27,21 @@ pub trait PolarsUpsample {
     /// - 1s    (1 second)
     /// - 1m    (1 minute)
     /// - 1h    (1 hour)
-    /// - 1d    (1 day)
-    /// - 1w    (1 week)
+    /// - 1d    (1 calendar day)
+    /// - 1w    (1 calendar week)
     /// - 1mo   (1 calendar month)
+    /// - 1q    (1 calendar quarter)
     /// - 1y    (1 calendar year)
     /// - 1i    (1 index count)
     /// Or combine them:
     /// "3d12h4m25s" # 3 days, 12 hours, 4 minutes, and 25 seconds
     /// Suffix with `"_saturating"` to saturate dates with days too
     /// large for their month to the last day of the month (e.g.
     /// 2022-02-29 to 2022-02-28).
+    /// By "calendar day", we mean the corresponding time on the next
+    /// day (which may not be 24 hours, depending on daylight savings).
+    /// Similarly for "calendar week", "calendar month", "calendar quarter",
+    /// and "calendar year".
     fn upsample<I: IntoVec<String>>(
         &self,
         by: I,
@@ -62,13 +67,21 @@ pub trait PolarsUpsample {
     /// - 1s    (1 second)
     /// - 1m    (1 minute)
     /// - 1h    (1 hour)
-    /// - 1d    (1 day)
-    /// - 1w    (1 week)
+    /// - 1d    (1 calendar day)
+    /// - 1w    (1 calendar week)
     /// - 1mo   (1 calendar month)
+    /// - 1q    (1 calendar quarter)
     /// - 1y    (1 calendar year)
     /// - 1i    (1 index count)
     /// Or combine them:
     /// "3d12h4m25s" # 3 days, 12 hours, 4 minutes, and 25 seconds
+    /// Suffix with `"_saturating"` to saturate dates with days too
+    /// large for their month to the last day of the month (e.g.
+    /// 2022-02-29 to 2022-02-28).
+    /// By "calendar day", we mean the corresponding time on the next
+    /// day (which may not be 24 hours, depending on daylight savings).
+    /// Similarly for "calendar week", "calendar month", "calendar quarter",
+    /// and "calendar year".
     fn upsample_stable<I: IntoVec<String>>(
         &self,
         by: I,

diff --git a/polars/polars-time/src/windows/duration.rs b/polars/polars-time/src/windows/duration.rs
@@ -92,13 +92,19 @@ impl Duration {
     /// * `d`:  day
     /// * `w`:  week
     /// * `mo`: calendar month
+    /// * `q`: calendar quarter
     /// * `y`:  calendar year
     /// * `i`:  index value (only for {Int32, Int64} dtypes)
     ///
     /// Suffix with `"_saturating"` to indicate that dates too large for
     /// their month should saturate at the largest date (e.g. 2022-02-29 -> 2022-02-28)
     /// instead of erroring.
     ///
+    /// By "calendar day", we mean the corresponding time on the next
+    /// day (which may not be 24 hours, depending on daylight savings).
+    /// Similarly for "calendar week", "calendar month", "calendar quarter",
+    /// and "calendar year".
+    ///
     /// # Panics
     /// If the given str is invalid for any reason.
     pub fn parse(duration: &str) -> Self {

diff --git a/py-polars/polars/dataframe/frame.py b/py-polars/polars/dataframe/frame.py
@@ -4721,8 +4721,8 @@ def groupby_rolling(
         - 1s    (1 second)
         - 1m    (1 minute)
         - 1h    (1 hour)
-        - 1d    (1 day)
-        - 1w    (1 week)
+        - 1d    (1 calendar day)
+        - 1w    (1 calendar week)
         - 1mo   (1 calendar month)
         - 1q    (1 calendar quarter)
         - 1y    (1 calendar year)
@@ -4735,6 +4735,10 @@ def groupby_rolling(
         their month should saturate at the largest date (e.g. 2022-02-29 -> 2022-02-28)
         instead of erroring.
 
+        By "calendar day", we mean the corresponding time on the next day (which may
+        not be 24 hours, due to daylight savings). Similarly for "calendar week",
+        "calendar month", "calendar quarter", and "calendar year".
+
         In case of a groupby_rolling on an integer column, the windows are defined by:
 
         - **"1i"      # length 1**
@@ -4857,10 +4861,10 @@ def groupby_dynamic(
         - 1s    (1 second)
         - 1m    (1 minute)
         - 1h    (1 hour)
-        - 1d    (1 day)
-        - 1w    (1 week)
+        - 1d    (1 calendar day)
+        - 1w    (1 calendar week)
         - 1mo   (1 calendar month)
-        - 1q    (1 quarter)
+        - 1q    (1 calendar quarter)
         - 1y    (1 calendar year)
         - 1i    (1 index count)
 
@@ -4871,6 +4875,10 @@ def groupby_dynamic(
         their month should saturate at the largest date (e.g. 2022-02-29 -> 2022-02-28)
         instead of erroring.
 
+        By "calendar day", we mean the corresponding time on the next day (which may
+        not be 24 hours, due to daylight savings). Similarly for "calendar week",
+        "calendar month", "calendar quarter", and "calendar year".
+
         In case of a groupby_dynamic on an integer column, the windows are defined by:
 
         - "1i"      # length 1
@@ -5174,8 +5182,8 @@ def upsample(
         - 1s    (1 second)
         - 1m    (1 minute)
         - 1h    (1 hour)
-        - 1d    (1 day)
-        - 1w    (1 week)
+        - 1d    (1 calendar day)
+        - 1w    (1 calendar week)
         - 1mo   (1 calendar month)
         - 1q    (1 calendar quarter)
         - 1y    (1 calendar year)
@@ -5189,6 +5197,10 @@ def upsample(
         their month should saturate at the largest date (e.g. 2022-02-29 -> 2022-02-28)
         instead of erroring.
 
+        By "calendar day", we mean the corresponding time on the next day (which may
+        not be 24 hours, due to daylight savings). Similarly for "calendar week",
+        "calendar month", "calendar quarter", and "calendar year".
+
         Parameters
         ----------
         time_column
@@ -5329,8 +5341,8 @@ def join_asof(
                 - 1s    (1 second)
                 - 1m    (1 minute)
                 - 1h    (1 hour)
-                - 1d    (1 day)
-                - 1w    (1 week)
+                - 1d    (1 calendar day)
+                - 1w    (1 calendar week)
                 - 1mo   (1 calendar month)
                 - 1q    (1 calendar quarter)
                 - 1y    (1 calendar year)
@@ -5343,6 +5355,11 @@ def join_asof(
                 their month should saturate at the largest date
                 (e.g. 2022-02-29 -> 2022-02-28) instead of erroring.
 
+                By "calendar day", we mean the corresponding time on the next day
+                (which may not be 24 hours, due to daylight savings). Similarly for
+                "calendar week", "calendar month", "calendar quarter", and
+                "calendar year".
+
         allow_parallel
             Allow the physical plan to optionally evaluate the computation of both
             DataFrames up to the join in parallel.

diff --git a/py-polars/polars/expr/datetime.py b/py-polars/polars/expr/datetime.py
@@ -62,11 +62,9 @@ def truncate(
         - 1s  # 1 second
         - 1m  # 1 minute
         - 1h  # 1 hour
-        - 1d  # 1 day
+        - 1d  # 1 calendar day
         - 1w  # 1 calendar week
         - 1mo # 1 calendar month
-        - 1mo_saturating # same as above, but saturates to the last day of the month
-          if the target date does not exist
         - 1q  # 1 calendar quarter
         - 1y  # 1 calendar year
 
@@ -78,6 +76,10 @@ def truncate(
         their month should saturate at the largest date (e.g. 2022-02-29 -> 2022-02-28)
         instead of erroring.
 
+        By "calendar day", we mean the corresponding time on the next day (which may
+        not be 24 hours, due to daylight savings). Similarly for "calendar week",
+        "calendar month", "calendar quarter", and "calendar year".
+
         Returns
         -------
         Date/Datetime series
@@ -186,7 +188,7 @@ def round(
         1s   # 1 second
         1m   # 1 minute
         1h   # 1 hour
-        1d   # 1 day
+        1d   # 1 calendar day
         1w   # 1 calendar week
         1mo  # 1 calendar month
         1q   # 1 calendar quarter
@@ -198,6 +200,10 @@ def round(
         their month should saturate at the largest date (e.g. 2022-02-29 -> 2022-02-28)
         instead of erroring.
 
+        By "calendar day", we mean the corresponding time on the next day (which may
+        not be 24 hours, due to daylight savings). Similarly for "calendar week",
+        "calendar month", "calendar quarter", and "calendar year".
+
         Returns
         -------
         Date/Datetime series
@@ -1802,8 +1808,8 @@ def offset_by(self, by: str) -> Expr:
             - 1s    (1 second)
             - 1m    (1 minute)
             - 1h    (1 hour)
-            - 1d    (1 day)
-            - 1w    (1 week)
+            - 1d    (1 calendar day)
+            - 1w    (1 calendar week)
             - 1mo   (1 calendar month)
             - 1q    (1 calendar quarter)
             - 1y    (1 calendar year)
@@ -1813,6 +1819,10 @@ def offset_by(self, by: str) -> Expr:
         their month should saturate at the largest date (e.g. 2022-02-29 -> 2022-02-28)
         instead of erroring.
 
+        By "calendar day", we mean the corresponding time on the next day (which may
+        not be 24 hours, due to daylight savings). Similarly for "calendar week",
+        "calendar month", "calendar quarter", and "calendar year".
+
         Returns
         -------
         Date/Datetime expression