Rename Theme to ColorScheme in GUI theming

Aligns the theming API with Qt's ColorScheme naming by renaming the enum, ThemeManager class, and related methods, signals, and attributes.

Author: kaamyashinde

src/ert/gui/theming/__init__.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
-from .manager import ThemeManager
-from .theme import Theme
+from .manager import ColorSchemeManager
+from .theme import ColorScheme
 
 __all__ = [
-    "Theme",
-    "ThemeManager",
+    "ColorScheme",
+    "ColorSchemeManager",
 ]

src/ert/gui/theming/manager.py

@@ -7,13 +7,14 @@
 from PyQt6.QtGui import QGuiApplication, QStyleHints
 from PyQt6.QtWidgets import QApplication
 
-from .theme import Theme, load_qss
+from .theme import ColorScheme, load_qss
 
 logger = logging.getLogger(__name__)
 
 _STYLE_HINTS_MISSING = "styleHints() unavailable; is a QGuiApplication running?"
 _QAPPLICATION_MISSING = (
-    "QApplication instance not found; construct a QApplication before applying a theme."
+    "QApplication instance not found; construct a QApplication before applying "
+    "a colour scheme."
 )
 
 _DARK_BASE_VALUE_THRESHOLD = 70
@@ -34,87 +35,78 @@ def _require_style_hints() -> QStyleHints:
     return hints
 
 
-def detect_system_theme() -> Theme:
-    """Return the OS-reported colour scheme, or fall back to a palette heuristic.
+def detect_system_color_scheme() -> ColorScheme:
 
-    Uses ``QGuiApplication.styleHints().colorScheme()`` on Qt 6.5+.  When the
-    style hint returns ``Unknown`` (or the platform integration does not
-    report a value), the base-colour brightness of the current application
-    palette is inspected instead.
-
-    A running ``QApplication`` (or at least a ``QGuiApplication``) must exist
-    before calling this function.
-    """
     hints = _require_style_hints()
     scheme = hints.colorScheme()
     if scheme == Qt.ColorScheme.Dark:
-        return Theme.DARK
+        return ColorScheme.DARK
     if scheme == Qt.ColorScheme.Light:
-        return Theme.LIGHT
+        return ColorScheme.LIGHT
     return _palette_fallback()
 
 
-def _palette_fallback() -> Theme:
+def _palette_fallback() -> ColorScheme:
     app = cast(QApplication | None, QApplication.instance())
     if app is None:
-        return Theme.LIGHT
+        return ColorScheme.LIGHT
     return (
-        Theme.DARK
+        ColorScheme.DARK
         if app.palette().base().color().value() < _DARK_BASE_VALUE_THRESHOLD
-        else Theme.LIGHT
+        else ColorScheme.LIGHT
     )
 
 
-class ThemeManager(QObject):
-    theme_changed = pyqtSignal(Theme)
+class ColorSchemeManager(QObject):
+    color_scheme_changed = pyqtSignal(ColorScheme)
 
     def __init__(self, parent: QObject | None = None) -> None:
         super().__init__(parent)
-        self._follows_system_theme: bool = True
-        self._current_theme: Theme = detect_system_theme()
+        self._follows_system_color_scheme: bool = True
+        self._current_color_scheme: ColorScheme = detect_system_color_scheme()
         hints = _require_style_hints()
         hints.colorSchemeChanged.connect(self._on_system_scheme_changed)
         self.apply_stylesheet_from_qss()
 
     @property
-    def current_theme(self) -> Theme:
-        return self._current_theme
+    def current_color_scheme(self) -> ColorScheme:
+        return self._current_color_scheme
 
     @property
     def follows_system(self) -> bool:
-        return self._follows_system_theme
+        return self._follows_system_color_scheme
 
-    def set_theme(self, theme: Theme) -> None:
-        """Pin the manager to ``theme`` and stop following the OS scheme."""
-        self._follows_system_theme = False
-        self._set_theme_internal(theme)
+    def set_color_scheme(self, color_scheme: ColorScheme) -> None:
+        """Pin the manager to ``color_scheme`` and stop following the OS scheme."""
+        self._follows_system_color_scheme = False
+        self._set_color_scheme_internal(color_scheme)
 
     def follow_system(self) -> None:
         """Resume following the OS colour scheme; re-syncs immediately."""
-        self._follows_system_theme = True
-        self._set_theme_internal(detect_system_theme())
+        self._follows_system_color_scheme = True
+        self._set_color_scheme_internal(detect_system_color_scheme())
 
     def apply_stylesheet_from_qss(self) -> None:
         app = cast(QApplication | None, QApplication.instance())
         if app is None:
             raise RuntimeError(_QAPPLICATION_MISSING)
         try:
-            stylesheet = load_qss(self._current_theme)
+            stylesheet = load_qss(self._current_color_scheme)
         except (OSError, UnicodeDecodeError):
             logger.exception(
-                "Failed to load QSS for theme '%s'; keeping previous styling.",
-                self._current_theme.value,
+                "Failed to load QSS for colour scheme '%s'; keeping previous styling.",
+                self._current_color_scheme.value,
             )
             return
         app.setStyleSheet(stylesheet)
 
     def _on_system_scheme_changed(self, _scheme: Qt.ColorScheme) -> None:
-        if self._follows_system_theme:
-            self._set_theme_internal(detect_system_theme())
+        if self._follows_system_color_scheme:
+            self._set_color_scheme_internal(detect_system_color_scheme())
 
-    def _set_theme_internal(self, theme: Theme) -> None:
-        if theme == self._current_theme:
+    def _set_color_scheme_internal(self, color_scheme: ColorScheme) -> None:
+        if color_scheme == self._current_color_scheme:
             return
-        self._current_theme = theme
+        self._current_color_scheme = color_scheme
         self.apply_stylesheet_from_qss()
-        self.theme_changed.emit(theme)
+        self.color_scheme_changed.emit(color_scheme)

src/ert/gui/theming/theme.py

@@ -6,8 +6,8 @@
 _THEMES_SUBPATH = "resources/gui/themes"
 
 
-class Theme(Enum):
-    """Identifier for a visual theme shipped with the ERT GUI.
+class ColorScheme(Enum):
+    """Identifier for a visual colour scheme shipped with the ERT GUI.
 
     The value is used as the base filename of the corresponding QSS file
     under ``src/ert/gui/resources/gui/themes/``.
@@ -17,10 +17,10 @@ class Theme(Enum):
     DARK = "dark"
 
 
-def load_qss(theme: Theme) -> str:
-    resource = files("ert.gui").joinpath(f"{_THEMES_SUBPATH}/{theme.value}.qss")
+def load_qss(color_scheme: ColorScheme) -> str:
+    resource = files("ert.gui").joinpath(f"{_THEMES_SUBPATH}/{color_scheme.value}.qss")
     if not resource.is_file():
         raise FileNotFoundError(
-            f"QSS file for theme '{theme.value}' not found at {resource}"
+            f"QSS file for colour scheme '{color_scheme.value}' not found at {resource}"
         )
     return resource.read_text(encoding="utf-8")

tests/ert/unit_tests/gui/theming/test_qss_loading.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from ert.gui.theming import Theme
+from ert.gui.theming import ColorScheme
 from ert.gui.theming import theme as theme_module
 from ert.gui.theming.theme import load_qss
 
@@ -20,17 +20,21 @@ def joinpath(self, _name: str) -> _MissingResource:
         return _MissingResource()
 
 
-@pytest.mark.parametrize("theme", list(Theme))
-def test_that_qss_file_is_loaded_for_each_theme(theme: Theme) -> None:
-    content = load_qss(theme)
-    assert content.strip(), f"QSS for {theme.value} theme must not be empty"
+@pytest.mark.parametrize("color_scheme", list(ColorScheme))
+def test_that_qss_file_is_loaded_for_each_color_scheme(
+    color_scheme: ColorScheme,
+) -> None:
+    content = load_qss(color_scheme)
+    assert content.strip(), (
+        f"QSS for {color_scheme.value} colour scheme must not be empty"
+    )
     assert "QWidget" in content, (
-        f"QSS for {theme.value} theme should style QWidget as a baseline"
+        f"QSS for {color_scheme.value} colour scheme should style QWidget as a baseline"
     )
 
 
 def test_that_dark_and_light_qss_differ() -> None:
-    assert load_qss(Theme.DARK) != load_qss(Theme.LIGHT)
+    assert load_qss(ColorScheme.DARK) != load_qss(ColorScheme.LIGHT)
 
 
 def test_that_load_qss_raises_file_not_found_when_theme_file_is_missing(
@@ -39,4 +43,4 @@ def test_that_load_qss_raises_file_not_found_when_theme_file_is_missing(
     monkeypatch.setattr(theme_module, "files", lambda _pkg: _MissingPackage())
 
     with pytest.raises(FileNotFoundError, match="dark"):
-        load_qss(Theme.DARK)
+        load_qss(ColorScheme.DARK)

tests/ert/unit_tests/gui/theming/test_theme_detection.py

@@ -4,9 +4,12 @@
 from PyQt6.QtCore import Qt
 from PyQt6.QtGui import QColor, QGuiApplication, QPalette
 
-from ert.gui.theming import Theme
+from ert.gui.theming import ColorScheme
 from ert.gui.theming import manager as manager_module
-from ert.gui.theming.manager import _DARK_BASE_VALUE_THRESHOLD, detect_system_theme
+from ert.gui.theming.manager import (
+    _DARK_BASE_VALUE_THRESHOLD,
+    detect_system_color_scheme,
+)
 
 
 def _palette_with_base_value(value: int) -> QPalette:
@@ -23,7 +26,7 @@ def test_that_detection_returns_dark_when_style_hints_report_dark(
         "colorScheme",
         lambda: Qt.ColorScheme.Dark,
     )
-    assert detect_system_theme() == Theme.DARK
+    assert detect_system_color_scheme() == ColorScheme.DARK
 
 
 def test_that_detection_returns_light_when_style_hints_report_light(
@@ -34,7 +37,7 @@ def test_that_detection_returns_light_when_style_hints_report_light(
         "colorScheme",
         lambda: Qt.ColorScheme.Light,
     )
-    assert detect_system_theme() == Theme.LIGHT
+    assert detect_system_color_scheme() == ColorScheme.LIGHT
 
 
 def test_that_detection_falls_back_to_palette_when_scheme_is_unknown(
@@ -48,7 +51,7 @@ def test_that_detection_falls_back_to_palette_when_scheme_is_unknown(
     # With the default Qt palette used in tests the base colour is white
     # (value 255), which is above ``_DARK_BASE_VALUE_THRESHOLD`` in
     # ``_palette_fallback``, so the fallback path must resolve to LIGHT.
-    assert detect_system_theme() == Theme.LIGHT
+    assert detect_system_color_scheme() == ColorScheme.LIGHT
 
 
 def test_that_require_style_hints_raises_when_style_hints_are_unavailable(
@@ -67,34 +70,32 @@ def test_that_palette_fallback_returns_light_when_no_qapplication_exists(
     monkeypatch.setattr(
         manager_module.QApplication, "instance", staticmethod(lambda: None)
     )
-    assert manager_module._palette_fallback() == Theme.LIGHT
-
-
-def test_that_palette_fallback_returns_dark_when_base_value_is_below_threshold(
-    qtbot, monkeypatch
-) -> None:
-    app = manager_module.QApplication.instance()
-    monkeypatch.setattr(
-        app, "palette", lambda: _palette_with_base_value(_DARK_BASE_VALUE_THRESHOLD - 1)
-    )
-    assert manager_module._palette_fallback() == Theme.DARK
-
-
-def test_that_palette_fallback_returns_light_when_base_value_is_above_threshold(
-    qtbot, monkeypatch
+    assert manager_module._palette_fallback() == ColorScheme.LIGHT
+
+
+@pytest.mark.parametrize(
+    ("base_value", "expected_scheme"),
+    [
+        pytest.param(
+            _DARK_BASE_VALUE_THRESHOLD - 1,
+            ColorScheme.DARK,
+            id="returns-dark-when-base-value-is-below-threshold",
+        ),
+        pytest.param(
+            _DARK_BASE_VALUE_THRESHOLD + 1,
+            ColorScheme.LIGHT,
+            id="returns-light-when-base-value-is-above-threshold",
+        ),
+        pytest.param(
+            _DARK_BASE_VALUE_THRESHOLD,
+            ColorScheme.LIGHT,
+            id="returns-light-when-base-value-equals-threshold",
+        ),
+    ],
+)
+def test_that_palette_fallback_resolves_scheme_from_base_value_threshold(
+    qtbot, monkeypatch, base_value, expected_scheme
 ) -> None:
     app = manager_module.QApplication.instance()
-    monkeypatch.setattr(
-        app, "palette", lambda: _palette_with_base_value(_DARK_BASE_VALUE_THRESHOLD + 1)
-    )
-    assert manager_module._palette_fallback() == Theme.LIGHT
-
-
-def test_that_palette_fallback_returns_light_when_base_value_equals_threshold(
-    qtbot, monkeypatch
-) -> None:
-    app = manager_module.QApplication.instance()
-    monkeypatch.setattr(
-        app, "palette", lambda: _palette_with_base_value(_DARK_BASE_VALUE_THRESHOLD)
-    )
-    assert manager_module._palette_fallback() == Theme.LIGHT
+    monkeypatch.setattr(app, "palette", lambda: _palette_with_base_value(base_value))
+    assert manager_module._palette_fallback() == expected_scheme