feat: Support datetime.(date|datetime) as a SchemaBase parameter

altair/utils/schemapi.py

@@ -4,6 +4,7 @@
 
 import contextlib
 import copy
+import datetime as dt
 import inspect
 import json
 import sys
@@ -502,6 +503,34 @@ def _from_array_like(obj: Iterable[Any], /) -> list[Any]:
         return list(obj)
 
 
+def _from_date_datetime(obj: dt.date | dt.datetime, /) -> dict[str, Any]:
+    """
+    Parse native `datetime.(date|datetime)` into a `DateTime`_ schema.
+
+    .. _DateTime:
+        https://vega.github.io/vega-lite/docs/datetime.html
+    """
+    result: dict[str, Any] = {"year": obj.year, "month": obj.month, "date": obj.day}
+    if isinstance(obj, dt.datetime):
+        if obj.time() != dt.time.min:
+            us = obj.microsecond
+            ms = us if us == 0 else us // 1_000
+            result.update(
+                hours=obj.hour, minutes=obj.minute, seconds=obj.second, milliseconds=ms
+            )
+        if tzinfo := obj.tzinfo:
+            if tzinfo is dt.timezone.utc:
+                result["utc"] = True
+            else:
+                msg = (
+                    f"Unsupported timezone {tzinfo!r}.\n"
+                    "Only `'UTC'` or naive (local) datetimes are permitted.\n"
+                    "See https://altair-viz.github.io/user_guide/generated/core/altair.DateTime.html"
+                )
+                raise TypeError(msg)
+    return result
+
+
 def _todict(obj: Any, context: dict[str, Any] | None, np_opt: Any, pd_opt: Any) -> Any:  # noqa: C901
     """Convert an object to a dict representation."""
     if np_opt is not None:
@@ -532,6 +561,8 @@ def _todict(obj: Any, context: dict[str, Any] | None, np_opt: Any, pd_opt: Any)
         return pd_opt.Timestamp(obj).isoformat()
     elif _is_iterable(obj, exclude=(str, bytes)):
         return _todict(_from_array_like(obj), context, np_opt, pd_opt)
+    elif isinstance(obj, dt.date):
+        return _from_date_datetime(obj)
     else:
         return obj
 

altair/vegalite/v5/api.py

@@ -30,7 +30,7 @@
 from .data import data_transformers
 from .display import VEGA_VERSION, VEGAEMBED_VERSION, VEGALITE_VERSION, renderers
 from .schema import SCHEMA_URL, channels, core, mixins
-from .schema._typing import Map
+from .schema._typing import Map, PrimitiveValue_T
 from .theme import themes
 
 if sys.version_info >= (3, 14):
@@ -88,6 +88,7 @@
         SingleDefUnitChannel_T,
         SingleTimeUnit_T,
         StackOffset_T,
+        Temporal,
     )
     from .schema.channels import Column, Facet, Row
     from .schema.core import (
@@ -539,10 +540,8 @@ def check_fields_and_encodings(parameter: Parameter, field_name: str) -> bool:
 ```
 """
 
-_LiteralValue: TypeAlias = Union[str, bool, float, int]
-"""Primitive python value types."""
 
-_FieldEqualType: TypeAlias = Union[_LiteralValue, Map, Parameter, SchemaBase]
+_FieldEqualType: TypeAlias = Union[PrimitiveValue_T, Map, Parameter, SchemaBase]
 """Permitted types for equality checks on field values:
 
 - `datum.field == ...`
@@ -633,7 +632,7 @@ class _ConditionExtra(TypedDict, closed=True, total=False):  # type: ignore[call
     param: Parameter | str
     test: _TestPredicateType
     value: Any
-    __extra_items__: _StatementType | OneOrSeq[_LiteralValue]
+    __extra_items__: _StatementType | OneOrSeq[PrimitiveValue_T]
 
 
 _Condition: TypeAlias = _ConditionExtra
@@ -1438,7 +1437,9 @@ def selection(type: Optional[SelectionType_T] = Undefined, **kwds: Any) -> Param
 
 def selection_interval(
     name: str | None = None,
-    value: Optional[Any] = Undefined,
+    value: Optional[
+        PrimitiveValue_T | Temporal | SchemaBase | Sequence[SchemaBase | Map] | Map
+    ] = Undefined,
     bind: Optional[Binding | str] = Undefined,
     empty: Optional[bool] = Undefined,
     expr: Optional[str | Expr | Expression] = Undefined,
@@ -1551,7 +1552,9 @@ def selection_interval(
 
 def selection_point(
     name: str | None = None,
-    value: Optional[Any] = Undefined,
+    value: Optional[
+        PrimitiveValue_T | Temporal | SchemaBase | Sequence[SchemaBase | Map] | Map
+    ] = Undefined,
     bind: Optional[Binding | str] = Undefined,
     empty: Optional[bool] = Undefined,
     expr: Optional[Expr] = Undefined,

altair/vegalite/v5/schema/_typing.py

@@ -6,6 +6,7 @@
 import re
 import sys
 from collections.abc import Mapping, Sequence
+from datetime import date, datetime
 from typing import Annotated, Any, Generic, Literal, TypeVar, Union, get_args
 
 if sys.version_info >= (3, 14):  # https://peps.python.org/pep-0728/
@@ -87,6 +88,7 @@
     "StepFor_T",
     "StrokeCap_T",
     "StrokeJoin_T",
+    "Temporal",
     "TextBaseline_T",
     "TextDirection_T",
     "TimeInterval_T",
@@ -198,6 +200,8 @@ class PaddingKwds(TypedDict, total=False):
     top: float
 
 
+Temporal: TypeAlias = Union[date, datetime]
+
 VegaThemes: TypeAlias = Literal[
     "carbong10",
     "carbong100",