feat(typing): Adds dedicated Optional alias for `Union[..., Undefin…

…edType]`

`typing.Optional` is deprecated and is no longer needed in `altair`. The new alias improves the readability of generated signatures, by reducing noise (repeating `UndefinedType`) and clearly grouping together the options for an argument.

altair/utils/schemapi.py

@@ -19,6 +19,7 @@
     Literal,
     Sequence,
     TypeVar,
+    Union,
     overload,
     List,
     Dict,
@@ -743,6 +744,18 @@ def __repr__(self) -> str:
 
 
 Undefined = UndefinedType()
+T = TypeVar("T")
+Optional: TypeAlias = Union[T, UndefinedType]
+"""One of the sepcified types, or the `Undefined` singleton.
+
+
+Examples
+--------
+```py
+MaybeDictOrStr: TypeAlias = Optional[dict[str, Any] | str]
+LongerDictOrStr: TypeAlias = dict[str, Any] | str | UndefinedType
+```
+"""
 
 
 class SchemaBase:
@@ -1044,11 +1057,11 @@ def _default_wrapper_classes(cls) -> Iterator[type[SchemaBase]]:
 
     @classmethod
     def from_dict(
-        cls: type[T],
+        cls: type[TSchemaBase],
         dct: dict[str, Any],
         validate: bool = True,
         _wrapper_classes: Iterable[type[SchemaBase]] | None = None,
-    ) -> T:
+    ) -> TSchemaBase:
         """Construct class from a dictionary representation
 
         Parameters
@@ -1152,7 +1165,7 @@ def __dir__(self) -> list[str]:
         return sorted(chain(super().__dir__(), self._kwds))
 
 
-T = TypeVar("T", bound=SchemaBase)
+TSchemaBase = TypeVar("TSchemaBase", bound=SchemaBase)
 
 
 def _is_dict(obj: Any | dict[Any, Any]) -> TypeIs[dict[Any, Any]]:
@@ -1224,21 +1237,21 @@ def _freeze(val):
     @overload
     def from_dict(
         self,
-        dct: T,
+        dct: TSchemaBase,
         tp: Literal[None] = ...,
         schema: Literal[None] = ...,
         rootschema: Literal[None] = ...,
         default_class: Any = ...,
-    ) -> T: ...
+    ) -> TSchemaBase: ...
     @overload
     def from_dict(
         self,
         dct: dict[str, Any],
         tp: Literal[None] = ...,
         schema: Any = ...,
         rootschema: Literal[None] = ...,
-        default_class: type[T] = ...,
-    ) -> T: ...
+        default_class: type[TSchemaBase] = ...,
+    ) -> TSchemaBase: ...
     @overload
     def from_dict(
         self,
@@ -1252,30 +1265,30 @@ def from_dict(
     def from_dict(
         self,
         dct: dict[str, Any],
-        tp: type[T],
+        tp: type[TSchemaBase],
         schema: Literal[None] = ...,
         rootschema: Literal[None] = ...,
         default_class: Any = ...,
-    ) -> T: ...
+    ) -> TSchemaBase: ...
     @overload
     def from_dict(
         self,
         dct: dict[str, Any] | list[dict[str, Any]],
-        tp: type[T],
+        tp: type[TSchemaBase],
         schema: dict[str, Any],
         rootschema: dict[str, Any] | None = ...,
         default_class: Any = ...,
     ) -> Never: ...
     def from_dict(
         self,
-        dct: dict[str, Any] | list[dict[str, Any]] | T,
-        tp: type[T] | None = None,
+        dct: dict[str, Any] | list[dict[str, Any]] | TSchemaBase,
+        tp: type[TSchemaBase] | None = None,
         schema: dict[str, Any] | None = None,
         rootschema: dict[str, Any] | None = None,
         default_class: Any = _passthrough,
-    ) -> T:
+    ) -> TSchemaBase:
         """Construct an object from a dict representation"""
-        target_tp: type[T]
+        target_tp: type[TSchemaBase]
         current_schema: dict[str, Any]
         if isinstance(dct, SchemaBase):
             return dct  # type: ignore[return-value]
@@ -1372,7 +1385,7 @@ def __call__(self, *args: Any, **kwargs: Any):
         return obj
 
 
-def with_property_setters(cls: type[T]) -> type[T]:
+def with_property_setters(cls: type[TSchemaBase]) -> type[TSchemaBase]:
     """
     Decorator to add property setters to a Schema class.
     """

altair/vegalite/v5/api.py

@@ -11,8 +11,8 @@
 from typing import Union, cast, Any, Iterable, Literal, IO, TYPE_CHECKING
 from typing_extensions import TypeAlias
 
-from .schema import core, channels, mixins, Undefined, UndefinedType, SCHEMA_URL
-
+from .schema import core, channels, mixins, Undefined, SCHEMA_URL
+from altair.utils.schemapi import UndefinedType
 from .data import data_transformers
 from ... import utils
 from ...expr import core as _expr_core