refactor: alt.themes -> alt.theme.themes

altair/__init__.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 # ruff: noqa
 __version__ = "5.5.0dev"
 
@@ -617,7 +619,6 @@
     "mixins",
     "param",
     "parse_shorthand",
-    "register_theme",
     "renderers",
     "repeat",
     "sample",
@@ -627,7 +628,6 @@
     "sequence",
     "sphere",
     "theme",
-    "themes",
     "to_csv",
     "to_json",
     "to_values",
@@ -653,10 +653,29 @@ def __dir__():
 from altair.jupyter import JupyterChart
 from altair.expr import expr
 from altair.utils import AltairDeprecationWarning, parse_shorthand, Undefined
-from altair import typing
+from altair import typing, theme
+from typing import Any as _Any
 
 
 def load_ipython_extension(ipython):
     from altair._magics import vegalite
 
     ipython.register_magic_function(vegalite, "cell")
+
+
+def __getattr__(name: str) -> _Any:
+    from altair.utils.deprecation import deprecated_warn
+
+    if name == "themes":
+        deprecated_warn(
+            "Most of the `ThemeRegistry` API is accessible via `altair.theme`.\n"
+            "See the updated User Guide for further details:\n"
+            "https://altair-viz.github.io/user_guide/customization.html#chart-themes",
+            version="5.5.0",
+            alternative="altair.theme.themes",
+            stacklevel=3,
+        )
+        return theme.themes
+    else:
+        msg = f"module {__name__!r} has no attribute {name!r}"
+        raise AttributeError(msg)

altair/theme.py

@@ -0,0 +1,266 @@
+"""Customizing chart configuration defaults."""
+
+from __future__ import annotations
+
+from functools import wraps as _wraps
+from typing import TYPE_CHECKING
+
+from altair.vegalite.v5.schema._config import (
+    AreaConfigKwds,
+    AutoSizeParamsKwds,
+    AxisConfigKwds,
+    AxisResolveMapKwds,
+    BarConfigKwds,
+    BindCheckboxKwds,
+    BindDirectKwds,
+    BindInputKwds,
+    BindRadioSelectKwds,
+    BindRangeKwds,
+    BoxPlotConfigKwds,
+    BrushConfigKwds,
+    CompositionConfigKwds,
+    ConfigKwds,
+    DateTimeKwds,
+    DerivedStreamKwds,
+    ErrorBandConfigKwds,
+    ErrorBarConfigKwds,
+    FeatureGeometryGeoJsonPropertiesKwds,
+    FormatConfigKwds,
+    GeoJsonFeatureCollectionKwds,
+    GeoJsonFeatureKwds,
+    GeometryCollectionKwds,
+    GradientStopKwds,
+    HeaderConfigKwds,
+    IntervalSelectionConfigKwds,
+    IntervalSelectionConfigWithoutTypeKwds,
+    LegendConfigKwds,
+    LegendResolveMapKwds,
+    LegendStreamBindingKwds,
+    LinearGradientKwds,
+    LineConfigKwds,
+    LineStringKwds,
+    LocaleKwds,
+    MarkConfigKwds,
+    MergedStreamKwds,
+    MultiLineStringKwds,
+    MultiPointKwds,
+    MultiPolygonKwds,
+    NumberLocaleKwds,
+    OverlayMarkDefKwds,
+    PaddingKwds,
+    PointKwds,
+    PointSelectionConfigKwds,
+    PointSelectionConfigWithoutTypeKwds,
+    PolygonKwds,
+    ProjectionConfigKwds,
+    ProjectionKwds,
+    RadialGradientKwds,
+    RangeConfigKwds,
+    RectConfigKwds,
+    ResolveKwds,
+    RowColKwds,
+    ScaleConfigKwds,
+    ScaleInvalidDataConfigKwds,
+    ScaleResolveMapKwds,
+    SelectionConfigKwds,
+    StepKwds,
+    StyleConfigIndexKwds,
+    ThemeConfig,
+    TickConfigKwds,
+    TimeIntervalStepKwds,
+    TimeLocaleKwds,
+    TitleConfigKwds,
+    TitleParamsKwds,
+    TooltipContentKwds,
+    TopLevelSelectionParameterKwds,
+    VariableParameterKwds,
+    ViewBackgroundKwds,
+    ViewConfigKwds,
+)
+from altair.vegalite.v5.theme import themes
+
+if TYPE_CHECKING:
+    import sys
+    from typing import Callable
+
+    if sys.version_info >= (3, 11):
+        from typing import LiteralString
+    else:
+        from typing_extensions import LiteralString
+    if sys.version_info >= (3, 10):
+        from typing import ParamSpec
+    else:
+        from typing_extensions import ParamSpec
+
+    from altair.utils.plugin_registry import Plugin
+
+    P = ParamSpec("P")
+
+__all__ = [
+    "AreaConfigKwds",
+    "AutoSizeParamsKwds",
+    "AxisConfigKwds",
+    "AxisResolveMapKwds",
+    "BarConfigKwds",
+    "BindCheckboxKwds",
+    "BindDirectKwds",
+    "BindInputKwds",
+    "BindRadioSelectKwds",
+    "BindRangeKwds",
+    "BoxPlotConfigKwds",
+    "BrushConfigKwds",
+    "CompositionConfigKwds",
+    "ConfigKwds",
+    "DateTimeKwds",
+    "DerivedStreamKwds",
+    "ErrorBandConfigKwds",
+    "ErrorBarConfigKwds",
+    "FeatureGeometryGeoJsonPropertiesKwds",
+    "FormatConfigKwds",
+    "GeoJsonFeatureCollectionKwds",
+    "GeoJsonFeatureKwds",
+    "GeometryCollectionKwds",
+    "GradientStopKwds",
+    "HeaderConfigKwds",
+    "IntervalSelectionConfigKwds",
+    "IntervalSelectionConfigWithoutTypeKwds",
+    "LegendConfigKwds",
+    "LegendResolveMapKwds",
+    "LegendStreamBindingKwds",
+    "LineConfigKwds",
+    "LineStringKwds",
+    "LinearGradientKwds",
+    "LocaleKwds",
+    "MarkConfigKwds",
+    "MergedStreamKwds",
+    "MultiLineStringKwds",
+    "MultiPointKwds",
+    "MultiPolygonKwds",
+    "NumberLocaleKwds",
+    "OverlayMarkDefKwds",
+    "PaddingKwds",
+    "PointKwds",
+    "PointSelectionConfigKwds",
+    "PointSelectionConfigWithoutTypeKwds",
+    "PolygonKwds",
+    "ProjectionConfigKwds",
+    "ProjectionKwds",
+    "RadialGradientKwds",
+    "RangeConfigKwds",
+    "RectConfigKwds",
+    "ResolveKwds",
+    "RowColKwds",
+    "ScaleConfigKwds",
+    "ScaleInvalidDataConfigKwds",
+    "ScaleResolveMapKwds",
+    "SelectionConfigKwds",
+    "StepKwds",
+    "StyleConfigIndexKwds",
+    "ThemeConfig",
+    "ThemeConfig",
+    "TickConfigKwds",
+    "TimeIntervalStepKwds",
+    "TimeLocaleKwds",
+    "TitleConfigKwds",
+    "TitleParamsKwds",
+    "TooltipContentKwds",
+    "TopLevelSelectionParameterKwds",
+    "VariableParameterKwds",
+    "ViewBackgroundKwds",
+    "ViewConfigKwds",
+    "enable",
+    "get",
+    "names",
+    "register",
+    "themes",
+    "unregister",
+]
+
+
+def register(
+    name: LiteralString, *, enable: bool
+) -> Callable[[Plugin[ThemeConfig]], Plugin[ThemeConfig]]:
+    """
+    Decorator for registering a theme function.
+
+    Parameters
+    ----------
+    name
+        Unique name assigned in ``alt.theme.themes``.
+    enable
+        Auto-enable the wrapped theme.
+
+    Examples
+    --------
+    Register and enable a theme::
+
+        import altair as alt
+        from altair import theme
+
+
+        @theme.register("param_font_size", enable=True)
+        def custom_theme() -> theme.ThemeConfig:
+            sizes = 12, 14, 16, 18, 20
+            return {
+                "autosize": {"contains": "content", "resize": True},
+                "background": "#F3F2F1",
+                "config": {
+                    "axisX": {"labelFontSize": sizes[1], "titleFontSize": sizes[1]},
+                    "axisY": {"labelFontSize": sizes[1], "titleFontSize": sizes[1]},
+                    "font": "'Lato', 'Segoe UI', Tahoma, Verdana, sans-serif",
+                    "headerColumn": {"labelFontSize": sizes[1]},
+                    "headerFacet": {"labelFontSize": sizes[1]},
+                    "headerRow": {"labelFontSize": sizes[1]},
+                    "legend": {"labelFontSize": sizes[0], "titleFontSize": sizes[1]},
+                    "text": {"fontSize": sizes[0]},
+                    "title": {"fontSize": sizes[-1]},
+                },
+                "height": {"step": 28},
+                "width": 350,
+            }
+
+    Until another theme has been enabled, all charts will use defaults set in ``custom_theme``::
+
+        from vega_datasets import data
+
+        source = data.stocks()
+        lines = (
+            alt.Chart(source, title=alt.Title("Stocks"))
+            .mark_line()
+            .encode(x="date:T", y="price:Q", color="symbol:N")
+        )
+        lines.interactive(bind_y=False)
+
+    """
+
+    # HACK: See for `LiteralString` requirement in `name`
+    # https://github.com/vega/altair/pull/3526#discussion_r1743350127
+    def decorate(func: Plugin[ThemeConfig], /) -> Plugin[ThemeConfig]:
+        themes.register(name, func)
+        if enable:
+            themes.enable(name)
+
+        @_wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> ThemeConfig:
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorate
+
+
+def unregister(name: LiteralString) -> Plugin[ThemeConfig] | None:
+    """
+    Remove and return a previously registered theme.
+
+    Parameters
+    ----------
+    name
+        Unique name assigned in ``alt.theme.themes``.
+    """
+    return themes.register(name, None)
+
+
+enable = themes.enable
+get = themes.get
+names = themes.names

altair/typing/__init__.py

@@ -46,13 +46,9 @@
     "ChartType",
     "EncodeKwds",
     "Optional",
-    "ThemeConfig",
     "is_chart_type",
-    "theme",
 ]
 
-from altair.typing import theme
-from altair.typing.theme import ThemeConfig
 from altair.utils.schemapi import Optional
 from altair.vegalite.v5.api import ChartType, is_chart_type
 from altair.vegalite.v5.schema.channels import (

altair/utils/plugin_registry.py

@@ -39,7 +39,7 @@ def __str__(self):
         return f"No {self.name!r} entry point found in group {self.group!r}"
 
 
-class PluginEnabler:
+class PluginEnabler(Generic[PluginT, R]):
     """
     Context manager for enabling plugins.
 
@@ -51,21 +51,23 @@ class PluginEnabler:
         # plugins back to original state
     """
 
-    def __init__(self, registry: PluginRegistry, name: str, **options):
-        self.registry: PluginRegistry = registry
+    def __init__(
+        self, registry: PluginRegistry[PluginT, R], name: str, **options: Any
+    ) -> None:
+        self.registry: PluginRegistry[PluginT, R] = registry
         self.name: str = name
         self.options: dict[str, Any] = options
         self.original_state: dict[str, Any] = registry._get_state()
         self.registry._enable(name, **options)
 
-    def __enter__(self) -> PluginEnabler:
+    def __enter__(self) -> PluginEnabler[PluginT, R]:
         return self
 
     def __exit__(self, typ: type, value: Exception, traceback: TracebackType) -> None:
         self.registry._set_state(self.original_state)
 
     def __repr__(self) -> str:
-        return f"{self.registry.__class__.__name__}.enable({self.name!r})"
+        return f"{type(self.registry).__name__}.enable({self.name!r})"
 
 
 class PluginRegistry(Generic[PluginT, R]):
@@ -211,7 +213,9 @@ def _enable(self, name: str, **options) -> None:
             self._global_settings[key] = options.pop(key)
         self._options = options
 
-    def enable(self, name: str | None = None, **options) -> PluginEnabler:
+    def enable(
+        self, name: str | None = None, **options: Any
+    ) -> PluginEnabler[PluginT, R]:
         """
         Enable a plugin by name.