feat: Datetime(time_unit, time_zone) and Duration(time_unit) types

narwhals/_arrow/utils.py

@@ -46,9 +46,9 @@ def translate_dtype(dtype: Any) -> dtypes.DType:
     if pa.types.is_date32(dtype):
         return dtypes.Date()
     if pa.types.is_timestamp(dtype):
-        return dtypes.Datetime()
+        return dtypes.Datetime(time_unit=dtype.unit, time_zone=dtype.tz)
     if pa.types.is_duration(dtype):
-        return dtypes.Duration()
+        return dtypes.Duration(time_unit=dtype.unit)
     if pa.types.is_dictionary(dtype):
         return dtypes.Categorical()
     return dtypes.Unknown()  # pragma: no cover
@@ -86,11 +86,12 @@ def narwhals_to_native_dtype(dtype: dtypes.DType | type[dtypes.DType]) -> Any:
     if isinstance_or_issubclass(dtype, dtypes.Categorical):
         return pa.dictionary(pa.uint32(), pa.string())
     if isinstance_or_issubclass(dtype, dtypes.Datetime):
-        # Use Polars' default
-        return pa.timestamp("us")
+        time_unit = getattr(dtype, "time_unit", "us")
+        time_zone = getattr(dtype, "time_zone", None)
+        return pa.timestamp(time_unit, tz=time_zone)
     if isinstance_or_issubclass(dtype, dtypes.Duration):
-        # Use Polars' default
-        return pa.duration("us")
+        time_unit = getattr(dtype, "time_unit", "us")
+        return pa.duration(time_unit)
     if isinstance_or_issubclass(dtype, dtypes.Date):
         return pa.date32()
     msg = f"Unknown dtype: {dtype}"  # pragma: no cover

narwhals/_pandas_like/series.py

@@ -189,7 +189,9 @@ def cast(
         dtype: Any,
     ) -> Self:
         ser = self._native_series
-        dtype = narwhals_to_native_dtype(dtype, ser.dtype, self._implementation)
+        dtype = narwhals_to_native_dtype(
+            dtype, ser.dtype, self._implementation, self._backend_version
+        )
         return self._from_native_series(ser.astype(dtype))
 
     def item(self: Self, index: int | None = None) -> Any:

narwhals/_pandas_like/utils.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import re
 from typing import TYPE_CHECKING
 from typing import Any
 from typing import Iterable
+from typing import Literal
 from typing import TypeVar
 
 from narwhals.dependencies import get_cudf
@@ -221,6 +223,15 @@ def translate_dtype(column: Any) -> DType:
     from narwhals import dtypes
 
     dtype = column.dtype
+
+    pd_datetime_rgx = (
+        r"^datetime64\[(?P<time_unit>ms|us|ns)(?:, (?P<time_zone>[a-zA-Z\/]+))?\]$"
+    )
+    pa_datetime_rgx = r"^timestamp\[(?P<time_unit>ms|us|ns)(?:, tz=(?P<time_zone>[a-zA-Z\/]+))?\]\[pyarrow\]$"
+
+    pd_duration_rgx = r"^timedelta64\[(?P<time_unit>ms|us|ns)\]$"
+    pa_duration_rgx = r"^duration\[(?P<time_unit>ms|us|ns)\]\[pyarrow\]$"
+
     if str(dtype) in ("int64", "Int64", "Int64[pyarrow]", "int64[pyarrow]"):
         return dtypes.Int64()
     if str(dtype) in ("int32", "Int32", "Int32[pyarrow]", "int32[pyarrow]"):
@@ -264,16 +275,17 @@ def translate_dtype(column: Any) -> DType:
         return dtypes.Boolean()
     if str(dtype) in ("category",) or str(dtype).startswith("dictionary<"):
         return dtypes.Categorical()
-    if str(dtype).startswith("datetime64"):
-        # TODO(Unassigned): different time units and time zones
-        return dtypes.Datetime()
-    if str(dtype).startswith("timedelta64") or str(dtype).startswith("duration"):
-        # TODO(Unassigned): different time units
-        return dtypes.Duration()
-    if str(dtype).startswith("timestamp["):
-        # pyarrow-backed datetime
-        # TODO(Unassigned): different time units and time zones
-        return dtypes.Datetime()
+    if (match_ := re.match(pd_datetime_rgx, str(dtype))) or (
+        match_ := re.match(pa_datetime_rgx, str(dtype))
+    ):
+        dt_time_unit: Literal["us", "ns", "ms"] = match_.group("time_unit")  # type: ignore[assignment]
+        dt_time_zone: str | None = match_.group("time_zone")
+        return dtypes.Datetime(dt_time_unit, dt_time_zone)
+    if (match_ := re.match(pd_duration_rgx, str(dtype))) or (
+        match_ := re.match(pa_duration_rgx, str(dtype))
+    ):
+        du_time_unit: Literal["us", "ns", "ms"] = match_.group("time_unit")  # type: ignore[assignment]
+        return dtypes.Duration(du_time_unit)
     if str(dtype) == "date32[day][pyarrow]":
         return dtypes.Date()
     if str(dtype) == "object":
@@ -321,7 +333,10 @@ def get_dtype_backend(dtype: Any, implementation: Implementation) -> str:
 
 
 def narwhals_to_native_dtype(  # noqa: PLR0915
-    dtype: DType | type[DType], starting_dtype: Any, implementation: Implementation
+    dtype: DType | type[DType],
+    starting_dtype: Any,
+    implementation: Implementation,
+    backend_version: tuple[int, ...],
 ) -> Any:
     from narwhals import dtypes
 
@@ -425,15 +440,32 @@ def narwhals_to_native_dtype(  # noqa: PLR0915
         # convert to it?
         return "category"
     if isinstance_or_issubclass(dtype, dtypes.Datetime):
-        # TODO(Unassigned): different time units and time zones
+        dt_time_unit = getattr(dtype, "time_unit", "us")
+        dt_time_zone = getattr(dtype, "time_zone", None)
+
+        # Pandas does not support "ms" or "us" time units before version 1.5.0
+        # Let's overwrite with "ns"
+        if implementation is Implementation.PANDAS and backend_version < (
+            1,
+            5,
+            0,
+        ):  # pragma: no cover
+            dt_time_unit = "ns"
+
         if dtype_backend == "pyarrow-nullable":
-            return "timestamp[ns][pyarrow]"
-        return "datetime64[ns]"
+            tz_part = f", tz={dt_time_zone}" if dt_time_zone else ""
+            return f"timestamp[{dt_time_unit}{tz_part}][pyarrow]"
+        else:
+            tz_part = f", {dt_time_zone}" if dt_time_zone else ""
+            return f"datetime64[{dt_time_unit}{tz_part}]"
     if isinstance_or_issubclass(dtype, dtypes.Duration):
-        # TODO(Unassigned): different time units and time zones
-        if dtype_backend == "pyarrow-nullable":
-            return "duration[ns][pyarrow]"
-        return "timedelta64[ns]"
+        du_time_unit = getattr(dtype, "time_unit", "us")
+        return (
+            f"duration[{du_time_unit}][pyarrow]"
+            if dtype_backend == "pyarrow-nullable"
+            else f"timedelta64[{du_time_unit}]"
+        )
+
     if isinstance_or_issubclass(dtype, dtypes.Date):
         if dtype_backend == "pyarrow-nullable":
             return "date32[pyarrow]"

narwhals/_polars/utils.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from typing import Any
+from typing import Literal
 
 from narwhals import dtypes
 from narwhals.dependencies import get_polars
@@ -59,12 +60,15 @@ def translate_dtype(dtype: Any) -> dtypes.DType:
         return dtypes.Categorical()
     if dtype == pl.Enum:
         return dtypes.Enum()
-    if dtype == pl.Datetime:
-        return dtypes.Datetime()
-    if dtype == pl.Duration:
-        return dtypes.Duration()
     if dtype == pl.Date:
         return dtypes.Date()
+    if dtype == pl.Datetime or isinstance(dtype, pl.Datetime):
+        dt_time_unit: Literal["us", "ns", "ms"] = getattr(dtype, "time_unit", "us")
+        dt_time_zone = getattr(dtype, "time_zone", None)
+        return dtypes.Datetime(time_unit=dt_time_unit, time_zone=dt_time_zone)
+    if dtype == pl.Duration or isinstance(dtype, pl.Duration):
+        du_time_unit: Literal["us", "ns", "ms"] = getattr(dtype, "time_unit", "us")
+        return dtypes.Duration(time_unit=du_time_unit)
     return dtypes.Unknown()
 
 
@@ -103,10 +107,14 @@ def narwhals_to_native_dtype(dtype: dtypes.DType | type[dtypes.DType]) -> Any:
     if dtype == dtypes.Enum:
         msg = "Converting to Enum is not (yet) supported"
         raise NotImplementedError(msg)
-    if dtype == dtypes.Datetime:
-        return pl.Datetime()
-    if dtype == dtypes.Duration:
-        return pl.Duration()
     if dtype == dtypes.Date:
         return pl.Date()
+    if dtype == dtypes.Datetime or isinstance(dtype, dtypes.Datetime):
+        dt_time_unit = getattr(dtype, "time_unit", "us")
+        dt_time_zone = getattr(dtype, "time_zone", None)
+        return pl.Datetime(dt_time_unit, dt_time_zone)
+    if dtype == dtypes.Duration or isinstance(dtype, dtypes.Duration):
+        du_time_unit: Literal["us", "ns", "ms"] = getattr(dtype, "time_unit", "us")
+        return pl.Duration(time_unit=du_time_unit)
+
     return pl.Unknown()  # pragma: no cover

narwhals/dtypes.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+from datetime import timezone
 from typing import TYPE_CHECKING
+from typing import Literal
 
 if TYPE_CHECKING:
     from typing_extensions import Self
@@ -71,10 +73,97 @@ class Object(DType): ...
 class Unknown(DType): ...
 
 
-class Datetime(TemporalType): ...
-
-
-class Duration(TemporalType): ...
+class Datetime(TemporalType):
+    """
+    Data type representing a calendar date and time of day.
+
+    Arguments:
+        time_unit: Unit of time. Defaults to `'us'` (microseconds).
+        time_zone: Time zone string, as defined in zoneinfo (to see valid strings run
+            `import zoneinfo; zoneinfo.available_timezones()` for a full list).
+            When used to match dtypes, can set this to "*" to check for Datetime
+            columns that have any (non-null) timezone.
+
+    Notes:
+        Adapted from Polars implementation at:
+        https://github.com/pola-rs/polars/blob/py-1.7.1/py-polars/polars/datatypes/classes.py#L398-L457
+    """
+
+    def __init__(
+        self: Self,
+        time_unit: Literal["us", "ns", "ms"] = "us",
+        time_zone: str | timezone | None = None,
+    ) -> None:
+        if time_unit not in {"ms", "us", "ns"}:
+            msg = (
+                "invalid `time_unit`"
+                f"\n\nExpected one of {{'ns','us','ms'}}, got {time_unit!r}."
+            )
+            raise ValueError(msg)
+
+        if isinstance(time_zone, timezone):
+            time_zone = str(time_zone)
+
+        self.time_unit = time_unit
+        self.time_zone = time_zone
+
+    def __eq__(self: Self, other: object) -> bool:
+        # allow comparing object instances to class
+        if type(other) is type and issubclass(other, Datetime):
+            return True
+        elif isinstance(other, Datetime):
+            return self.time_unit == other.time_unit and self.time_zone == other.time_zone
+        else:
+            return False
+
+    def __hash__(self: Self) -> int:  # pragma: no cover
+        return hash((self.__class__, self.time_unit, self.time_zone))
+
+    def __repr__(self: Self) -> str:  # pragma: no cover
+        class_name = self.__class__.__name__
+        return f"{class_name}(time_unit={self.time_unit!r}, time_zone={self.time_zone!r})"
+
+
+class Duration(TemporalType):
+    """
+    Data type representing a time duration.
+
+    Arguments:
+        time_unit: Unit of time. Defaults to `'us'` (microseconds).
+
+    Notes:
+        Adapted from Polars implementation at:
+        https://github.com/pola-rs/polars/blob/py-1.7.1/py-polars/polars/datatypes/classes.py#L460-L502
+    """
+
+    def __init__(
+        self: Self,
+        time_unit: Literal["us", "ns", "ms"] = "us",
+    ) -> None:
+        if time_unit not in ("ms", "us", "ns"):
+            msg = (
+                "invalid `time_unit`"
+                f"\n\nExpected one of {{'ns','us','ms'}}, got {time_unit!r}."
+            )
+            raise ValueError(msg)
+
+        self.time_unit = time_unit
+
+    def __eq__(self: Self, other: object) -> bool:
+        # allow comparing object instances to class
+        if type(other) is type and issubclass(other, Duration):
+            return True
+        elif isinstance(other, Duration):
+            return self.time_unit == other.time_unit
+        else:
+            return False
+
+    def __hash__(self: Self) -> int:  # pragma: no cover
+        return hash((self.__class__, self.time_unit))
+
+    def __repr__(self: Self) -> str:  # pragma: no cover
+        class_name = self.__class__.__name__
+        return f"{class_name}(time_unit={self.time_unit!r})"
 
 
 class Categorical(DType): ...

narwhals/functions.py

@@ -13,6 +13,7 @@
 from narwhals.dataframe import LazyFrame
 from narwhals.translate import from_native
 from narwhals.utils import Implementation
+from narwhals.utils import parse_version
 from narwhals.utils import validate_laziness
 
 # Missing type parameters for generic type "DataFrame"
@@ -215,7 +216,10 @@ def new_series(
                 narwhals_to_native_dtype as pandas_like_narwhals_to_native_dtype,
             )
 
-            dtype = pandas_like_narwhals_to_native_dtype(dtype, None, implementation)
+            backend_version = parse_version(native_namespace.__version__)
+            dtype = pandas_like_narwhals_to_native_dtype(
+                dtype, None, implementation, backend_version
+            )
         native_series = native_namespace.Series(values, name=name, dtype=dtype)
 
     elif implementation is Implementation.PYARROW:
@@ -332,9 +336,10 @@ def from_dict(
                 narwhals_to_native_dtype as pandas_like_narwhals_to_native_dtype,
             )
 
+            backend_version = parse_version(native_namespace.__version__)
             schema = {
                 name: pandas_like_narwhals_to_native_dtype(
-                    schema[name], native_type, implementation
+                    schema[name], native_type, implementation, backend_version
                 )
                 for name, native_type in native_frame.dtypes.items()
             }

requirements-dev.txt

@@ -8,6 +8,7 @@ pyarrow
 pytest
 pytest-cov
 pytest-env
+pytz
 hypothesis
 scikit-learn
 typing_extensions

tests/dtypes_test.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from datetime import timezone
+from typing import Literal
+
+import pytest
+
+import narwhals.stable.v1 as nw
+
+
+@pytest.mark.parametrize("time_unit", ["us", "ns", "ms"])
+@pytest.mark.parametrize("time_zone", ["Europe/Rome", timezone.utc, None])
+def test_datetime_valid(
+    time_unit: Literal["us", "ns", "ms"], time_zone: str | timezone | None
+) -> None:
+    dtype = nw.Datetime(time_unit=time_unit, time_zone=time_zone)
+
+    assert dtype == nw.Datetime(time_unit=time_unit, time_zone=time_zone)
+    assert dtype == nw.Datetime
+
+    if time_zone:
+        assert dtype != nw.Datetime(time_unit=time_unit)
+    if time_unit != "ms":
+        assert dtype != nw.Datetime(time_unit="ms")
+
+
+@pytest.mark.parametrize("time_unit", ["abc", "s"])
+def test_datetime_invalid(time_unit: str) -> None:
+    with pytest.raises(ValueError, match="invalid `time_unit`"):
+        nw.Datetime(time_unit=time_unit)  # type: ignore[arg-type]
+
+
+@pytest.mark.parametrize("time_unit", ["us", "ns", "ms"])
+def test_duration_valid(time_unit: Literal["us", "ns", "ms"]) -> None:
+    dtype = nw.Duration(time_unit=time_unit)
+
+    assert dtype == nw.Duration(time_unit=time_unit)
+    assert dtype == nw.Duration
+
+    if time_unit != "ms":
+        assert dtype != nw.Duration(time_unit="ms")
+
+
+@pytest.mark.parametrize("time_unit", ["abc", "s"])
+def test_duration_invalid(time_unit: str) -> None:
+    with pytest.raises(ValueError, match="invalid `time_unit`"):
+        nw.Duration(time_unit=time_unit)  # type: ignore[arg-type]