refactor: alt.themes -> alt.theme

altair/typing/__init__.py

@@ -51,6 +51,7 @@
     "theme",
 ]
 
+# TODO: Remove `theme`, `ThemeConfig` imports
 from altair.typing import theme
 from altair.typing.theme import ThemeConfig
 from altair.utils.schemapi import Optional

altair/typing/theme.py

@@ -1 +1,2 @@
+# TODO: Remove module
 from altair.vegalite.v5.schema._config import *  # noqa: F403

altair/utils/theme.py

@@ -19,6 +19,8 @@
 
 ThemeType = Plugin[ThemeConfig]
 
+# NOTE: Parameterising type vars, overriding `enable`
+
 
 # HACK: See for `LiteralString` requirement in `name`
 # https://github.com/vega/altair/pull/3526#discussion_r1743350127

altair/vegalite/v5/__init__.py

@@ -21,4 +21,6 @@
     renderers,
 )
 from .schema import *
+
+# NOTE: `theme` contents -> `vegalite.v5`
 from .theme import register_theme, themes

altair/vegalite/v5/api.py

@@ -31,6 +31,8 @@
 from .display import VEGA_VERSION, VEGAEMBED_VERSION, VEGALITE_VERSION, renderers
 from .schema import SCHEMA_URL, channels, core, mixins
 from .schema._typing import Map
+
+# NOTE: Relative themes import
 from .theme import themes
 
 if sys.version_info >= (3, 14):
@@ -1901,6 +1903,8 @@ def to_dict(  # noqa: C901
                 vegalite_spec["$schema"] = SCHEMA_URL
 
             # apply theme from theme registry
+
+            # NOTE: Single use of `themes`
             if theme := themes.get():
                 vegalite_spec = utils.update_nested(theme(), vegalite_spec, copy=True)
             else:

altair/vegalite/v5/theme.py

@@ -53,6 +53,8 @@ def __repr__(self) -> str:
 # themes that will be auto-detected. Explicit registration is also
 # allowed by the PluginRegistry API.
 ENTRY_POINT_GROUP: Final = "altair.vegalite.v5.theme"
+
+# NOTE: `themes` def has an entry point group
 themes = ThemeRegistry(entry_point_group=ENTRY_POINT_GROUP)
 
 themes.register(

doc/user_guide/customization.rst

@@ -710,6 +710,9 @@ outside the chart itself; For example, the container may be a ``<div>`` element
 
 Chart Themes
 ------------
+..
+    _comment: First mention of alt.themes
+
 Altair makes available a theme registry that lets users apply chart configurations
 globally within any Python session. This is done via the ``alt.themes`` object.
 
@@ -838,6 +841,9 @@ fill unless otherwise specified:
 
 If you want to restore the default theme, use:
 
+..
+    _comment: Last mention of alt.themes
+
 .. altair-plot::
    :output: none
 

tests/vegalite/v5/test_api.py

@@ -1286,6 +1286,7 @@ def test_LookupData():
 def test_themes():
     chart = alt.Chart("foo.txt").mark_point()
 
+    # NOTE: Only other tests using `alt.themes`
     with alt.themes.enable("default"):
         assert chart.to_dict()["config"] == {
             "view": {"continuousWidth": 300, "continuousHeight": 300}

tests/vegalite/v5/test_theme.py

@@ -5,6 +5,8 @@
 import pytest
 
 import altair.vegalite.v5 as alt
+
+# NOTE: Imports assuming existing structure
 from altair.typing import ThemeConfig
 from altair.vegalite.v5.schema._config import ConfigKwds
 from altair.vegalite.v5.schema._typing import is_color_hex
@@ -26,6 +28,7 @@ def chart() -> alt.Chart:
 
 def test_vega_themes(chart) -> None:
     for theme in VEGA_THEMES:
+        # NOTE: Assuming this is available in `alt.___`
         with alt.themes.enable(theme):
             dct = chart.to_dict()
         assert dct["usermeta"] == {"embedOptions": {"theme": theme}}

tools/generate_api_docs.py

@@ -134,6 +134,11 @@ def type_hints() -> list[str]:
     return sorted(s for s in iter_objects(alt.typing) if s in alt.typing.__all__)
 
 
+# TODO: Currently only the `TypedDict`(s) are visible (only via `alt.typing.___`)
+# Related: https://github.com/vega/altair/issues/3607
+def theme() -> list[str]: ...
+
+
 def lowlevel_wrappers() -> list[str]:
     objects = sorted(iter_objects(alt.schema.core, restrict_to_subclass=alt.SchemaBase))  # type: ignore[attr-defined]
     # The names of these two classes are also used for classes in alt.channels. Due to

tools/update_init_file.py

@@ -126,6 +126,8 @@ def _is_relevant(attr: t.Any, name: str, /) -> bool:
     ):
         return False
     elif ismodule(attr):
+        # TODO: Exclude `v5.theme` as it will collide with `alt.theme`
+
         # Only include modules which are part of Altair. This excludes built-in
         # modules (they do not have a __file__ attribute), standard library,
         # and third-party packages.