feat(typing): Adds public altair.typing module

altair/__init__.py

@@ -50,7 +50,6 @@
     "ChainedWhen",
     "Chart",
     "ChartDataType",
-    "ChartType",
     "Color",
     "ColorDatum",
     "ColorDef",
@@ -301,7 +300,6 @@
     "Opacity",
     "OpacityDatum",
     "OpacityValue",
-    "Optional",
     "Order",
     "OrderFieldDef",
     "OrderOnlyDef",
@@ -611,7 +609,6 @@
     "expr",
     "graticule",
     "hconcat",
-    "is_chart_type",
     "jupyter",
     "layer",
     "limit_rows",
@@ -634,6 +631,7 @@
     "to_json",
     "to_values",
     "topo_feature",
+    "typing",
     "utils",
     "v5",
     "value",
@@ -653,7 +651,8 @@ def __dir__():
 from altair.vegalite.v5.schema.core import Dict
 from altair.jupyter import JupyterChart
 from altair.expr import expr
-from altair.utils import AltairDeprecationWarning, parse_shorthand, Optional, Undefined
+from altair.utils import AltairDeprecationWarning, parse_shorthand, Undefined
+from altair import typing
 
 
 def load_ipython_extension(ipython):

altair/typing.py

@@ -0,0 +1,96 @@
+"""Public types to ease integrating with `altair`."""
+
+from __future__ import annotations
+
+__all__ = [
+    "ChannelAngle",
+    "ChannelColor",
+    "ChannelColumn",
+    "ChannelDescription",
+    "ChannelDetail",
+    "ChannelFacet",
+    "ChannelFill",
+    "ChannelFillOpacity",
+    "ChannelHref",
+    "ChannelKey",
+    "ChannelLatitude",
+    "ChannelLatitude2",
+    "ChannelLongitude",
+    "ChannelLongitude2",
+    "ChannelOpacity",
+    "ChannelOrder",
+    "ChannelRadius",
+    "ChannelRadius2",
+    "ChannelRow",
+    "ChannelShape",
+    "ChannelSize",
+    "ChannelStroke",
+    "ChannelStrokeDash",
+    "ChannelStrokeOpacity",
+    "ChannelStrokeWidth",
+    "ChannelText",
+    "ChannelTheta",
+    "ChannelTheta2",
+    "ChannelTooltip",
+    "ChannelUrl",
+    "ChannelX",
+    "ChannelX2",
+    "ChannelXError",
+    "ChannelXError2",
+    "ChannelXOffset",
+    "ChannelY",
+    "ChannelY2",
+    "ChannelYError",
+    "ChannelYError2",
+    "ChannelYOffset",
+    "ChartType",
+    "EncodeKwds",
+    "Optional",
+    "is_chart_type",
+]
+
+from altair.utils.schemapi import Optional
+from altair.vegalite.v5.api import ChartType, is_chart_type
+from altair.vegalite.v5.schema.channels import (
+    ChannelAngle,
+    ChannelColor,
+    ChannelColumn,
+    ChannelDescription,
+    ChannelDetail,
+    ChannelFacet,
+    ChannelFill,
+    ChannelFillOpacity,
+    ChannelHref,
+    ChannelKey,
+    ChannelLatitude,
+    ChannelLatitude2,
+    ChannelLongitude,
+    ChannelLongitude2,
+    ChannelOpacity,
+    ChannelOrder,
+    ChannelRadius,
+    ChannelRadius2,
+    ChannelRow,
+    ChannelShape,
+    ChannelSize,
+    ChannelStroke,
+    ChannelStrokeDash,
+    ChannelStrokeOpacity,
+    ChannelStrokeWidth,
+    ChannelText,
+    ChannelTheta,
+    ChannelTheta2,
+    ChannelTooltip,
+    ChannelUrl,
+    ChannelX,
+    ChannelX2,
+    ChannelXError,
+    ChannelXError2,
+    ChannelXOffset,
+    ChannelY,
+    ChannelY2,
+    ChannelYError,
+    ChannelYError2,
+    ChannelYOffset,
+    EncodeKwds,
+)

altair/utils/_transformed_data.py

@@ -31,8 +31,8 @@
 from altair.utils.schemapi import Undefined
 
 if TYPE_CHECKING:
+    from altair.typing import ChartType
     from altair.utils.core import DataFrameLike
-    from altair.vegalite.v5.api import ChartType
 
 Scope: TypeAlias = Tuple[int, ...]
 FacetMapping: TypeAlias = Dict[Tuple[str, Scope], Tuple[str, Scope]]
@@ -452,7 +452,7 @@ def get_facet_mapping(group: dict[str, Any], scope: Scope = ()) -> FacetMapping:
                         group, facet_data, scope
                     )
                     if definition_scope is not None:
-                        facet_mapping[(facet_name, group_scope)] = (
+                        facet_mapping[facet_name, group_scope] = (
                             facet_data,
                             definition_scope,
                         )

altair/utils/schemapi.py

@@ -44,7 +44,7 @@
 
     from referencing import Registry
 
-    from altair import ChartType
+    from altair.typing import ChartType
 
     if sys.version_info >= (3, 13):
         from typing import TypeIs
@@ -777,7 +777,7 @@ def __repr__(self) -> str:
 The parameters ``short``, ``long`` accept the same range of types::
 
     # ruff: noqa: UP006, UP007
-    from altair import Optional
+    from altair.typing import Optional
 
     def func_1(
         short: Optional[str | bool | float | dict[str, Any] | SchemaBase] = Undefined,
@@ -786,10 +786,12 @@ def func_1(
         ] = Undefined,
     ): ...
 
-This is distinct from `typing.Optional <https://typing.readthedocs.io/en/latest/spec/historical.html#union-and-optional>`__ as ``altair.Optional`` treats ``None`` like any other type::
+This is distinct from `typing.Optional <https://typing.readthedocs.io/en/latest/spec/historical.html#union-and-optional>`__.
+
+``altair.typing.Optional`` treats ``None`` like any other type::
 
     # ruff: noqa: UP006, UP007
-    from altair import Optional
+    from altair.typing import Optional
 
     def func_2(
         short: Optional[str | float | dict[str, Any] | None | SchemaBase] = Undefined,

altair/vegalite/v5/api.py

@@ -145,7 +145,6 @@
     "ChainedWhen",
     "Chart",
     "ChartDataType",
-    "ChartType",
     "ConcatChart",
     "DataType",
     "FacetChart",
@@ -174,7 +173,6 @@
     "condition",
     "graticule",
     "hconcat",
-    "is_chart_type",
     "layer",
     "mixins",
     "param",