feat(typing): Fully annotate api.py (#3508)

* ci(ruff): Add `ANN` rules for `api.py` only

To highlight all the missing annotations to fix and autofix `None` return

* feat(typing): Complete annotations for most `api` functions

Excluding `*args` on `ChartType` wrappers. They need to be defined in alignment in multiple places, which is more complex

* feat(typing): Annotate more expr/params in `api`

* feat(typing): Various changes to enforce `dict[str, Any]` instead of `dict`

Among these, many locations already assume `str` keys in the implementation - without checking

* feat(typing): Misc minor method annotations

* feat(typing): Use `ChartType` in all `ChartType` dunder methods

* fix(ruff): Ignore some `ANN` rules that won't be fixed

* chore: add pyright ignore from #3492

* feat(typing): Improve `ChartType` constructor/factory annotations

* feat(typing): Annotate remaining functions in `api`

* feat(typing): Complete `RepeatChart` annotations

* fix(typing): Resolve Liskov violations

```
altair\vegalite\v5\api.py:4368: error: Argument 1 of "__iadd__" is incompatible with "__add__" of supertype "TopLevelMixin"; supertype defines the argument type as "Chart | RepeatChart | ConcatChart | HConcatChart | VConcatChart | FacetChart | LayerChart"  [override]         def __iadd__(self, other: LayerChart | Chart) -> Self:                            ^~~~~~~~~~~~~~~~~~~~~~~~~ altair\vegalite\v5\api.py:4368: note: This violates the Liskov substitution principle altair\vegalite\v5\api.py:4368: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#incompatible-overrides altair\vegalite\v5\api.py:4376: error: Argument 1 of "__add__" is incompatible with supertype "TopLevelMixin"; supertype defines the argument type as "Chart | RepeatChart | ConcatChart | HConcatChart | VConcatChart | FacetChart | LayerChart"  [override]         def __add__(self, other: LayerChart | Chart) -> Self:                           ^~~~~~~~~~~~~~~~~~~~~~~~~ altair\vegalite\v5\api.py:4376: note: This violates the Liskov substitution principle altair\vegalite\v5\api.py:4376: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#incompatible-overrides
```

* chore(typing): Update more `dict` -> `dict[str, Any]`

* style(ruff): fix whitespace

* chore: Remove TODO fixed in #3480

* fix(typing): Enable `ANN003` and fix all in `api`

* fix(typing): Enable `ANN002` and fix all in `api`

* chore(ruff): Add note on `ANN`

This could later be extended to other modules, but for now `api` is complete.

* fix(typing): Add missing `FacetChart` annotations

To align with the other `ChartType`s

altair/expr/core.py

@@ -1,5 +1,9 @@
 from __future__ import annotations
-from typing import Any
+
+from typing import Any, Union, Dict
+
+from typing_extensions import TypeAlias
+
 from ..utils import SchemaBase
 
 
@@ -232,3 +236,6 @@ def __init__(self, group, name) -> None:
 
     def __repr__(self) -> str:
         return f"{self.group}[{self.name!r}]"
+
+
+IntoExpression: TypeAlias = Union[bool, None, str, OperatorMixin, Dict[str, Any]]

altair/utils/_transformed_data.py

@@ -30,6 +30,7 @@
 
 if TYPE_CHECKING:
     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]]
@@ -154,9 +155,7 @@ def transformed_data(chart, row_limit=None, exclude=None):
 # The same error appeared when trying it with Protocols for the concat and layer charts.
 # This function is only used internally and so we accept this inconsistency for now.
 def name_views(
-    chart: Chart | FacetChart | LayerChart | HConcatChart | VConcatChart | ConcatChart,
-    i: int = 0,
-    exclude: Iterable[str] | None = None,
+    chart: ChartType, i: int = 0, exclude: Iterable[str] | None = None
 ) -> list[str]:
     """
     Name unnamed chart views.
@@ -193,6 +192,7 @@ def name_views(
         else:
             return []
     else:
+        subcharts: list[Any]
         if isinstance(chart, _chart_class_mapping[LayerChart]):
             subcharts = chart.layer
         elif isinstance(chart, _chart_class_mapping[HConcatChart]):

altair/utils/_vegafusion_data.py

@@ -213,7 +213,7 @@ def compile_to_vegafusion_chart_state(
     return chart_state
 
 
-def compile_with_vegafusion(vegalite_spec: dict[str, Any]) -> dict:
+def compile_with_vegafusion(vegalite_spec: dict[str, Any]) -> dict[str, Any]:
     """
     Compile a Vega-Lite spec to Vega and pre-transform with VegaFusion.
 

altair/utils/compiler.py

@@ -1,11 +1,11 @@
-from typing import Callable
+from typing import Callable, Dict, Any
 from altair.utils import PluginRegistry
 
 # ==============================================================================
 # Vega-Lite to Vega compiler registry
 # ==============================================================================
-VegaLiteCompilerType = Callable[[dict], dict]
+VegaLiteCompilerType = Callable[[Dict[str, Any]], Dict[str, Any]]
 
 
-class VegaLiteCompilerRegistry(PluginRegistry[VegaLiteCompilerType, dict]):
+class VegaLiteCompilerRegistry(PluginRegistry[VegaLiteCompilerType, Dict[str, Any]]):
     pass