feat(typing): Adds public altair.typing module

altair/__init__.py

@@ -634,6 +634,7 @@
     "to_json",
     "to_values",
     "topo_feature",
+    "typing",
     "utils",
     "v5",
     "value",
@@ -654,6 +655,7 @@ def __dir__():
 from altair.jupyter import JupyterChart
 from altair.expr import expr
 from altair.utils import AltairDeprecationWarning, parse_shorthand, Optional, Undefined
+from altair import typing
 
 
 def load_ipython_extension(ipython):

altair/typing.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import sys
+from typing import Any, Mapping, Union
+from typing_extensions import TypedDict
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+ChannelType: TypeAlias = Union[str, Mapping[str, Any], Any]
+
+
+class EncodeKwds(TypedDict, total=False):
+    """
+    Reference implementation from [comment code block](https://github.com/pola-rs/polars/pull/17995#issuecomment-2263609625).
+
+    Aiming to define more specific `ChannelType`, without being exact.
+
+    This would be generated alongside `tools.generate_schema_wrapper._create_encode_signature`
+    """
+
+    angle: ChannelType
+    color: ChannelType
+    column: ChannelType
+    description: ChannelType
+    detail: ChannelType | list[Any]
+    facet: ChannelType
+    fill: ChannelType
+    fillOpacity: ChannelType
+    href: ChannelType
+    key: ChannelType
+    latitude: ChannelType
+    latitude2: ChannelType
+    longitude: ChannelType
+    longitude2: ChannelType
+    opacity: ChannelType
+    order: ChannelType | list[Any]
+    radius: ChannelType
+    radius2: ChannelType
+    row: ChannelType
+    shape: ChannelType
+    size: ChannelType
+    stroke: ChannelType
+    strokeDash: ChannelType
+    strokeOpacity: ChannelType
+    strokeWidth: ChannelType
+    text: ChannelType
+    theta: ChannelType
+    theta2: ChannelType
+    tooltip: ChannelType | list[Any]
+    url: ChannelType
+    x: ChannelType
+    x2: ChannelType
+    xError: ChannelType
+    xError2: ChannelType
+    xOffset: ChannelType
+    y: ChannelType
+    y2: ChannelType
+    yError: ChannelType
+    yError2: ChannelType
+    yOffset: ChannelType

altair/vegalite/v5/schema/channels.py

@@ -30905,7 +30905,7 @@ def encode(
         color: Optional[str | Color | Map | ColorDatum | ColorValue] = Undefined,
         column: Optional[str | Column | Map] = Undefined,
         description: Optional[str | Description | Map | DescriptionValue] = Undefined,
-        detail: Optional[str | Detail | Map | list] = Undefined,
+        detail: Optional[OneOrSeq[str | Detail | Map]] = Undefined,
         facet: Optional[str | Facet | Map] = Undefined,
         fill: Optional[str | Fill | Map | FillDatum | FillValue] = Undefined,
         fillOpacity: Optional[
@@ -30924,7 +30924,7 @@ def encode(
         opacity: Optional[
             str | Opacity | Map | OpacityDatum | OpacityValue
         ] = Undefined,
-        order: Optional[str | Order | Map | list | OrderValue] = Undefined,
+        order: Optional[OneOrSeq[str | Order | Map | OrderValue]] = Undefined,
         radius: Optional[str | Radius | Map | RadiusDatum | RadiusValue] = Undefined,
         radius2: Optional[
             str | Radius2 | Map | Radius2Datum | Radius2Value
@@ -30945,7 +30945,7 @@ def encode(
         text: Optional[str | Text | Map | TextDatum | TextValue] = Undefined,
         theta: Optional[str | Theta | Map | ThetaDatum | ThetaValue] = Undefined,
         theta2: Optional[str | Theta2 | Map | Theta2Datum | Theta2Value] = Undefined,
-        tooltip: Optional[str | Tooltip | Map | list | TooltipValue] = Undefined,
+        tooltip: Optional[OneOrSeq[str | Tooltip | Map | TooltipValue]] = Undefined,
         url: Optional[str | Url | Map | UrlValue] = Undefined,
         x: Optional[str | X | Map | XDatum | XValue] = Undefined,
         x2: Optional[str | X2 | Map | X2Datum | X2Value] = Undefined,

tools/generate_schema_wrapper.py

@@ -884,22 +884,21 @@ def _create_encode_signature(
         # for more background.
         union_types = ["str", field_class_name, "Map"]
         docstring_union_types = ["str", rst_syntax_for_class(field_class_name), "Dict"]
+        tp_inner: str = " | ".join(chain(union_types, datum_and_value_class_names))
         if info.supports_arrays:
             # We could be more specific about what types are accepted in the list
             # but then the signatures would get rather long and less useful
             # to a user when it shows up in their IDE.
-            union_types.append("list")
             docstring_union_types.append("List")
 
-        union_types = union_types + datum_and_value_class_names
+            # NOTE: Currently triggered only for `detail`, `order`, `tooltip`
+            # I think the `tooltip` one especially we should be more specific
+            tp_inner = f"OneOrSeq[{tp_inner}]"
+
+        signature_args.append(f"{channel}: Optional[{tp_inner}] = Undefined")
         docstring_union_types = docstring_union_types + [
             rst_syntax_for_class(c) for c in datum_and_value_class_names
         ]
-
-        signature_args.append(
-            f"{channel}: Optional[Union[{', '.join(union_types)}]] = Undefined"
-        )
-
         docstring_parameters.extend(
             (
                 f"{channel} : {', '.join(docstring_union_types)}",