feat(typing): Adds public altair.typing module (#3515)

* feat(typing): Create `altair.typing`

#3514

* chore: Add comment on `tooltip` annotation

Trying to trigger some places to add github comments - for actual threads

* feat(typing): Add reference impl `EncodeKwds` from comment

* feat(typing): Use `OneOrSeq[tps]` instead of `Union[*tps, list]` in `.encode()`

* build: run `generate-schema-wrapper`

* wip: generate `typed_dict_args`

* refactor: Simplify `tools`, remove redundant code

Pushing this mid-refactor of `_create_encode_signature`.
Currently 0 changes to generated code

* refactor: finish removing `altair_classes_prefix`

* feat: `_create_encode_signature()` -> `EncodingArtifacts`

Refactored, moved comments into docs, parameterised globals

* build: run `generate-schema-wrapper`

* feat(typing): Provide a public export for `_EncodeKwds`

* Add docstring to _EncodeKwds

* Rewrite EncodeArtifacts dataclass as a function

* Fix ruff issue due to old local ruff version

* Change generate_encoding_artifacts to an iterator

* docs: run `generate-schema-wrapper` with `indent_level=4`

I prefer the original, but this is to clarify #3515 (comment)

* feat(typing): Move `ChartType`, `is_chart_type` to `alt.typing`

These aren't introduced until `5.4.0`, so this is keeps the top-level from growing +2

#3515 (comment)

* revert(ruff): Restore original ('RUF001`) line

1eb466d

* Add type aliases for each channel

* Format

* Use Union instead of | for compatibility with Py <3.10

* Add channel type aliases to typing module. Add 'Type hints' section to API references in docs. Remove is_chart_type from 'API' docs section as it's now in typing. Rename '_EncodeKwds' to 'EncodeKwds'

* chore(ruff): Remove unused `F401` ignore

Would have only been needed before adding an `__all__`

* feat(typing): Move `Optional` export to `typing`

Updates all references, docs, `ruff` rule

* refactor: Move blank line append to `indent_docstring`

If this is needed for every call, it belongs in the function itself

* docs(typing): Remove empty type list from `EncodeKwds`

* refactor: Renaming, grouping, reducing repetition

* refactor: More tidying up, annotating, reformat

* docs: Reference aliases in `generate_encoding_artifacts`

* Use full type hints instead of type alias in signatures for typeddict and encode method

* Rename 'Type hints' to 'Typing'

* Ruff fix

---------

Co-authored-by: Stefan Binder <binder_stefan@outlook.com>

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]]

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",