assert Bound correctness

pola-rs · Dec 20, 2021 · e689027 · e689027
1 parent f9077e4
commit e689027
Show file tree

Hide file tree

Showing 3 changed files with 60 additions and 1 deletion.
diff --git a/polars/polars-time/src/bounds.rs b/polars/polars-time/src/bounds.rs
@@ -30,6 +30,10 @@ impl<S: AsRef<[i64]>> From<S> for Bounds {
 
 impl Bounds {
     pub fn new(start: TimeNanoseconds, stop: TimeNanoseconds) -> Self {
+        assert!(
+            start < stop,
+            "boundary start must be smaller than stop; is your time column sorted in ascending order?"
+        );
         Bounds { start, stop }
     }
 

diff --git a/py-polars/polars/internals/frame.py b/py-polars/polars/internals/frame.py
@@ -2297,7 +2297,7 @@ def groupby_dynamic(
         time_column
             Column used to group based on the time window.
             Often to type Date/Datetime
-            This column must be sorted. If not the output will not make sense.
+            This column must be sorted in ascending order. If not the output will not make sense.
         every
             interval of the window
         period

diff --git a/py-polars/polars/internals/lazy_frame.py b/py-polars/polars/internals/lazy_frame.py
@@ -509,6 +509,61 @@ def groupby_dynamic(
         closed: str = "right",
         by: Optional[Union[str, tp.List[str], "pli.Expr", tp.List["pli.Expr"]]] = None,
     ) -> "LazyGroupBy":
+        """
+        Groups based on a time value. Time windows are calculated and rows are assigned to windows.
+        Different from a normal groupby is that a row can be member of multiple groups. The time window could
+        be seen as a rolling window, with a window size determined by dates/times instead of slots in the DataFrame.
+
+        A window is defined by:
+
+        - every: interval of the window
+        - period: length of the window
+        - offset: offset of the window
+
+        The `every`, `period` and `offset` arguments are created with
+        the following string language:
+
+        - 1ns   (1 nanosecond)
+        - 1us   (1 microsecond)
+        - 1ms   (1 millisecond)
+        - 1s    (1 second)
+        - 1m    (1 minute)
+        - 1h    (1 hour)
+        - 1d    (1 day)
+        - 1w    (1 week)
+        - 1mo   (1 calendar month)
+        - 1y    (1 calendar year)
+
+        Or combine them:
+        "3d12h4m25s" # 3 days, 12 hours, 4 minutes, and 25 seconds
+
+        .. warning::
+            This API is experimental and may change without it being considered a breaking change.
+
+        Parameters
+        ----------
+        time_column
+            Column used to group based on the time window.
+            Often to type Date/Datetime
+            This column must be sorted in ascending order. If not the output will not make sense.
+        every
+            interval of the window
+        period
+            length of the window, if None it is equal to 'every'
+        offset
+            offset of the window
+        truncate
+            truncate the time value to the window lower bound
+        include_boundaries
+            add the lower and upper bound of the window to the "_lower_bound" and "_upper_bound" columns
+        closed
+            Defines if the window interval is closed or not.
+            Any of {"left", "right", "both" "none"}
+        by
+            Also group by this column/these columns
+
+        """
+
         if period is None:
             period = every
         if offset is None: