fix: pl.from_epoch was lossy for fractional values

Author: alexander-beedie

py-polars/src/polars/functions/lazy.py

@@ -23,7 +23,7 @@
 from polars._utils.unstable import issue_unstable_warning, unstable
 from polars._utils.various import extend_bool, qualified_type_name
 from polars._utils.wrap import wrap_df, wrap_expr, wrap_s
-from polars.datatypes import DTYPE_TEMPORAL_UNITS, Date, Datetime, Int64
+from polars.datatypes import DTYPE_TEMPORAL_UNITS, Date, Datetime
 from polars.datatypes._parse import parse_into_datatype_expr
 from polars.lazyframe.opt_flags import (
     DEFAULT_QUERY_OPT_FLAGS,
@@ -2567,10 +2567,8 @@ def from_epoch(
     Depending on the `time_unit` provided, this function will return a different dtype:
 
     - time_unit="d" returns pl.Date
-    - time_unit="s" returns pl.Datetime["us"] (pl.Datetime's default)
-    - time_unit="ms" returns pl.Datetime["ms"]
-    - time_unit="us" returns pl.Datetime["us"]
     - time_unit="ns" returns pl.Datetime["ns"]
+    - otherwise returns pl.Datetime["us"] (Polars' default unit)
 
     Parameters
     ----------
@@ -2581,18 +2579,35 @@ def from_epoch(
 
     Examples
     --------
-    >>> df = pl.DataFrame({"timestamp": [1666683077, 1666683099]}).lazy()
-    >>> df.select(pl.from_epoch(pl.col("timestamp"), time_unit="s")).collect()
+    Convert from integer seconds:
+
+    >>> df = pl.LazyFrame({"ts": [1666683077, 1666683099]})
+    >>> df.select(pl.from_epoch(pl.col("ts"), time_unit="s")).collect()
     shape: (2, 1)
     ┌─────────────────────┐
-    │ timestamp           │
+    │ ts                  │
     │ ---                 │
     │ datetime[μs]        │
     ╞═════════════════════╡
     │ 2022-10-25 07:31:17 │
     │ 2022-10-25 07:31:39 │
     └─────────────────────┘
 
+    Convert from fractional seconds:
+
+    >>> df = pl.LazyFrame({"ts": [-609066.723456, 1066445333.8888, 3405071999.987654]})
+    >>> df.select(pl.from_epoch(pl.col("ts"), time_unit="s")).collect()
+    shape: (3, 1)
+    ┌────────────────────────────┐
+    │ ts                         │
+    │ ---                        │
+    │ datetime[μs]               │
+    ╞════════════════════════════╡
+    │ 1969-12-24 22:48:53.276544 │
+    │ 2003-10-18 02:48:53.888800 │
+    │ 2077-11-25 13:19:59.987654 │
+    └────────────────────────────┘
+
     The function can also be used in an eager context by passing a Series.
 
     >>> s = pl.Series([12345, 12346])
@@ -2612,7 +2627,9 @@ def from_epoch(
     if time_unit == "d":
         return column.cast(Date)
     elif time_unit == "s":
-        return (column.cast(Int64) * 1_000_000).cast(Datetime("us"))
+        return (column * 1_000_000).cast(Datetime("us"))
+    elif time_unit == "ms":
+        return (column * 1_000).cast(Datetime("us"))
     elif time_unit in DTYPE_TEMPORAL_UNITS:
         return column.cast(Datetime(time_unit))
     else:

py-polars/tests/unit/lazyframe/test_lazyframe.py

@@ -1262,10 +1262,11 @@ def test_from_epoch(input_dtype: PolarsDataType) -> None:
     exp_dt = datetime(2006, 5, 17, 15, 34, 4)
     expected = pl.DataFrame(
         [
+            # 'd' → Date, 'ns' → Datetime('ns'), otherwise → Datetime('us')
             pl.Series("timestamp_d", [date(2006, 5, 17)]),
-            pl.Series("timestamp_s", [exp_dt]),  # s is no Polars dtype, defaults to us
-            pl.Series("timestamp_ms", [exp_dt]).cast(pl.Datetime("ms")),
-            pl.Series("timestamp_us", [exp_dt]),  # us is Polars Datetime default
+            pl.Series("timestamp_s", [exp_dt]),
+            pl.Series("timestamp_ms", [exp_dt]),
+            pl.Series("timestamp_us", [exp_dt]),
             pl.Series("timestamp_ns", [exp_dt]).cast(pl.Datetime("ns")),
         ]
     )