feat: Adds 4 missing carbon themes, provide autocomplete (#3516)

* style: Sort `VEGA_THEMES` alphabetically

* feat: Add missing `carbon...` themes

Examples https://vega.github.io/vega-themes/?theme=carbonwhite

Related vega/vega-themes#587

* feat(typing): Support autocomplete for `themes.enable(name)`

And provide link to `vega-themes` playground

* chore: Fix `PluginRegistery` comment typo

* Add comments

---------

Co-authored-by: Stefan Binder <[email protected]>

altair/utils/theme.py

@@ -1,11 +1,49 @@
 """Utilities for registering and working with themes."""
 
-from typing import Callable
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Callable
 
 from .plugin_registry import PluginRegistry
 
+if sys.version_info >= (3, 11):
+    from typing import LiteralString
+else:
+    from typing_extensions import LiteralString
+
+if TYPE_CHECKING:
+    from altair.utils.plugin_registry import PluginEnabler
+    from altair.vegalite.v5.theme import _ThemeName
+
 ThemeType = Callable[..., dict]
 
 
 class ThemeRegistry(PluginRegistry[ThemeType, dict]):
-    pass
+    def enable(
+        self, name: LiteralString | _ThemeName | None = None, **options
+    ) -> PluginEnabler:
+        """
+        Enable a theme by name.
+
+        This can be either called directly, or used as a context manager.
+
+        Parameters
+        ----------
+        name : string (optional)
+            The name of the theme to enable. If not specified, then use the
+            current active name.
+        **options :
+            Any additional parameters will be passed to the theme as keyword
+            arguments
+
+        Returns
+        -------
+        PluginEnabler:
+            An object that allows enable() to be used as a context manager
+
+        Notes
+        -----
+        Default `vega` themes can be previewed at https://vega.github.io/vega-themes/
+        """
+        return super().enable(name, **options)

altair/vegalite/v5/theme.py

@@ -2,21 +2,54 @@
 
 from __future__ import annotations
 
-from typing import Final
+from typing import TYPE_CHECKING, Final, Literal
 
 from altair.utils.theme import ThemeRegistry
 
+if TYPE_CHECKING:
+    import sys
+
+    if sys.version_info >= (3, 10):
+        from typing import TypeAlias
+    else:
+        from typing_extensions import TypeAlias
+
+    # If you add a theme here, also add it in `VEGA_THEMES` below.
+    _ThemeName: TypeAlias = Literal[
+        "default",
+        "carbonwhite",
+        "carbong10",
+        "carbong90",
+        "carbong100",
+        "dark",
+        "excel",
+        "fivethirtyeight",
+        "ggplot2",
+        "googlecharts",
+        "latimes",
+        "opaque",
+        "powerbi",
+        "quartz",
+        "urbaninstitute",
+        "vox",
+    ]
+
+# If you add a theme here, also add it in `_ThemeName` above.
 VEGA_THEMES = [
-    "ggplot2",
-    "quartz",
-    "vox",
-    "fivethirtyeight",
+    "carbonwhite",
+    "carbong10",
+    "carbong90",
+    "carbong100",
     "dark",
-    "latimes",
-    "urbaninstitute",
     "excel",
+    "fivethirtyeight",
+    "ggplot2",
     "googlecharts",
+    "latimes",
     "powerbi",
+    "quartz",
+    "urbaninstitute",
+    "vox",
 ]
 
 
@@ -38,7 +71,7 @@ def __repr__(self) -> str:
 
 # The entry point group that can be used by other packages to declare other
 # themes that will be auto-detected. Explicit registration is also
-# allowed by the PluginRegistery API.
+# allowed by the PluginRegistry API.
 ENTRY_POINT_GROUP: Final = "altair.vegalite.v5.theme"
 themes = ThemeRegistry(entry_point_group=ENTRY_POINT_GROUP)