docs(python): Remove y and mo from join_asof

pola-rs · Sep 30, 2024 · 211ab61 · 211ab61
1 parent 71a8b05
commit 211ab61
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 9 deletions.
diff --git a/py-polars/polars/_utils/convert.py b/py-polars/polars/_utils/convert.py
@@ -24,6 +24,7 @@
     US_PER_SECOND,
 )
 from polars.dependencies import _ZONEINFO_AVAILABLE, zoneinfo
+from polars.exceptions import InvalidOperationError
 
 if TYPE_CHECKING:
     from datetime import date, tzinfo
@@ -40,9 +41,18 @@ def parse_as_duration_string(td: None) -> None: ...
 def parse_as_duration_string(td: timedelta | str) -> str: ...
 
 
-def parse_as_duration_string(td: timedelta | str | None) -> str | None:
+def parse_as_duration_string(
+    td: timedelta | str | None, raise_on_dynamic_length=False
+) -> str | None:
     """Parse duration input as a Polars duration string."""
     if td is None or isinstance(td, str):
+        if raise_on_dynamic_length:
+            if "y" in td:
+                msg = "Only fixed length durations supported. year not supported"
+                raise InvalidOperationError(msg)
+            elif "mo" in td:
+                msg = "Only fixed length durations supported. month not supported"
+                raise InvalidOperationError(msg)
         return td
     return _timedelta_to_duration_string(td)
 

diff --git a/py-polars/polars/dataframe/frame.py b/py-polars/polars/dataframe/frame.py
@@ -6669,9 +6669,7 @@ def join_asof(
                 - 1h    (1 hour)
                 - 1d    (1 calendar day)
                 - 1w    (1 calendar week)
-                - 1mo   (1 calendar month)
                 - 1q    (1 calendar quarter)
-                - 1y    (1 calendar year)
 
                 Or combine them:
                 "3d12h4m25s" # 3 days, 12 hours, 4 minutes, and 25 seconds
@@ -6681,6 +6679,9 @@ def join_asof(
                 "calendar week", "calendar month", "calendar quarter", and
                 "calendar year".
 
+                Note that only fixed length tolerances are accepted. Months and years
+                are not supported.
+
         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/lazyframe/frame.py b/py-polars/polars/lazyframe/frame.py
@@ -4109,9 +4109,7 @@ def join_asof(
                 - 1h    (1 hour)
                 - 1d    (1 calendar day)
                 - 1w    (1 calendar week)
-                - 1mo   (1 calendar month)
                 - 1q    (1 calendar quarter)
-                - 1y    (1 calendar year)
 
                 Or combine them:
                 "3d12h4m25s" # 3 days, 12 hours, 4 minutes, and 25 seconds
@@ -4121,6 +4119,9 @@ def join_asof(
                 "calendar week", "calendar month", "calendar quarter", and
                 "calendar year".
 
+                Note that only fixed length tolerances are accepted. Months and years
+                are not supported.
+
         allow_parallel
             Allow the physical plan to optionally evaluate the computation of both
             DataFrames up to the join in parallel.
@@ -4362,10 +4363,10 @@ def join_asof(
 
         tolerance_str: str | None = None
         tolerance_num: float | int | None = None
-        if isinstance(tolerance, str):
-            tolerance_str = tolerance
-        elif isinstance(tolerance, timedelta):
-            tolerance_str = parse_as_duration_string(tolerance)
+        if isinstance(tolerance, (timedelta, str)):
+            tolerance_str = parse_as_duration_string(
+                tolerance, raise_on_dynamic_length=True
+            )
         else:
             tolerance_num = tolerance