sli-ui-toolkit 0.2.7__py3-none-any.whl

sli_ui_toolkit/__init__.py

@@ -0,0 +1,72 @@
+"""Reusable PyQt toolkit primitives."""
+
+from sli_ui_toolkit._version import __version__
+from sli_ui_toolkit.config import FlyoutTimingConfig, configure_toolkit
+from sli_ui_toolkit.palettes import FLUENT_LIGHT, FLUENT_DARK
+from sli_ui_toolkit.core.logging import (
+    get_log_directory,
+    setup_logging,
+    setup_simple_logging,
+)
+from sli_ui_toolkit.i18n import (
+    ToolkitTranslationEvents,
+    TranslationManager,
+    configure_i18n,
+    emit_language_changed,
+    get_current_language,
+    tr,
+    translation_events,
+)
+from sli_ui_toolkit.utils.file_utils import get_unique_filepath
+from sli_ui_toolkit.utils.paths import resource_path
+from sli_ui_toolkit.workers.generic_worker import GenericWorker, WorkerSignals
+from sli_ui_toolkit.theme import ThemeManager
+from sli_ui_toolkit.widgets import (
+    Label,
+    LabelConfig,
+    LabelVariantSpec,
+    application_tooltips_enabled,
+    get_label_variant,
+    install_application_tooltips,
+    register_label_variant,
+    set_application_tooltips_enabled,
+)
+from sli_ui_toolkit.style import (
+    WidgetStyleTokens,
+    read_widget_style,
+    update_widget_style,
+)
+
+__all__ = [
+    "__version__",
+    "GenericWorker",
+    "WorkerSignals",
+    "ThemeManager",
+    "Label",
+    "LabelConfig",
+    "LabelVariantSpec",
+    "get_label_variant",
+    "register_label_variant",
+    "application_tooltips_enabled",
+    "install_application_tooltips",
+    "set_application_tooltips_enabled",
+    "WidgetStyleTokens",
+    "read_widget_style",
+    "update_widget_style",
+    "FlyoutTimingConfig",
+    "ToolkitTranslationEvents",
+    "TranslationManager",
+    "configure_i18n",
+    "configure_toolkit",
+    "emit_language_changed",
+    "get_log_directory",
+    "get_current_language",
+    "get_unique_filepath",
+    "resource_path",
+    "setup_logging",
+    "setup_simple_logging",
+    "tr",
+    "translation_events",
+    "FLUENT_LIGHT",
+    "FLUENT_DARK",
+]

sli_ui_toolkit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.7"

sli_ui_toolkit/config.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+@dataclass(slots=True)
+class FlyoutTimingConfig:
+    transient_auto_hide_delay_ms: int = 180
+    flyout_animation_duration_ms: int = 160
+    text_settings_flyout_animation_duration_ms: int = 180
+
+_timings = FlyoutTimingConfig()
+_overlay_resolver: Callable[[object | None], object | None] | None = None
+_rating_gesture_factory: Callable[..., object] | None = None
+_dragdrop_service_getter: Callable[[], object | None] | None = None
+
+def configure_toolkit(
+    *,
+    timings: FlyoutTimingConfig | None = None,
+    overlay_resolver: Callable[[object | None], object | None] | None = None,
+    rating_gesture_factory: Callable[..., object] | None = None,
+    dragdrop_service_getter: Callable[[], object | None] | None = None,
+) -> None:
+    global _timings, _overlay_resolver, _rating_gesture_factory, _dragdrop_service_getter
+    if timings is not None:
+        _timings = timings
+    if overlay_resolver is not None:
+        _overlay_resolver = overlay_resolver
+    if rating_gesture_factory is not None:
+        _rating_gesture_factory = rating_gesture_factory
+    if dragdrop_service_getter is not None:
+        _dragdrop_service_getter = dragdrop_service_getter
+
+def get_flyout_timings() -> FlyoutTimingConfig:
+    return _timings
+
+def resolve_overlay_layer(widget: object | None):
+    if _overlay_resolver is None:
+        return None
+    try:
+        return _overlay_resolver(widget)
+    except Exception:
+        return None
+
+def create_rating_gesture(**kwargs):
+    if _rating_gesture_factory is None:
+        return None
+    try:
+        return _rating_gesture_factory(**kwargs)
+    except Exception:
+        return None
+
+def get_dragdrop_service():
+    if _dragdrop_service_getter is None:
+        from sli_ui_toolkit.ui.services.dragdrop_service import ToolkitDragDropService
+
+        return ToolkitDragDropService.get_instance()
+    try:
+        return _dragdrop_service_getter()
+    except Exception:
+        from sli_ui_toolkit.ui.services.dragdrop_service import ToolkitDragDropService
+
+        return ToolkitDragDropService.get_instance()

sli_ui_toolkit/core/__init__.py

@@ -0,0 +1,7 @@
+from sli_ui_toolkit.core.logging import (
+    get_log_directory,
+    setup_logging,
+    setup_simple_logging,
+)
+
+__all__ = ["get_log_directory", "setup_logging", "setup_simple_logging"]

sli_ui_toolkit/core/logging.py

@@ -0,0 +1,99 @@
+import logging
+import os
+import sys
+
+def get_log_directory(app_name: str) -> str:
+    logger = logging.getLogger(app_name)
+
+    if sys.platform == "win32":
+        app_data_dir = os.getenv("APPDATA")
+        if not app_data_dir:
+            app_data_dir = os.path.expanduser("~")
+            logger.warning(
+                "Could not find APPDATA env variable, falling back to home directory."
+            )
+        return os.path.join(app_data_dir, app_name)
+
+    if sys.platform == "darwin":
+        return os.path.join(
+            os.path.expanduser("~/Library/Application Support"), app_name
+        )
+
+    xdg_data_home = os.getenv("XDG_DATA_HOME", os.path.expanduser("~/.local/share"))
+    return os.path.join(xdg_data_home, app_name)
+
+def setup_logging(
+    app_name: str, debug_enabled: bool = False, debug_env_var: str | None = None
+) -> None:
+    logger = logging.getLogger(app_name)
+
+    if debug_env_var:
+        suppress_debug = (
+            os.getenv(f"{debug_env_var.replace('_DEBUG', '_SUPPRESS_DEBUG')}", "0")
+            == "1"
+        )
+        if suppress_debug:
+            debug_enabled = False
+        elif os.getenv(debug_env_var, "0") == "1":
+            debug_enabled = True
+
+    level = logging.DEBUG if debug_enabled else logging.INFO
+
+    if logger.handlers:
+        logger.setLevel(level)
+        for handler in logger.handlers:
+            handler.setLevel(level)
+        return
+
+    logger.setLevel(level)
+    formatter = logging.Formatter(
+        "%(asctime)s - [%(levelname)s] - (%(filename)s:%(lineno)d) - %(message)s"
+    )
+
+    stream_handler = logging.StreamHandler(sys.stdout)
+    stream_handler.setFormatter(formatter)
+    stream_handler.setLevel(level)
+    logger.addHandler(stream_handler)
+
+    try:
+        log_dir = get_log_directory(app_name)
+        os.makedirs(log_dir, exist_ok=True)
+        log_file_path = os.path.join(log_dir, "log.txt")
+
+        file_handler = logging.FileHandler(log_file_path, mode="w", encoding="utf-8")
+        file_handler.setFormatter(formatter)
+        file_handler.setLevel(level)
+        logger.addHandler(file_handler)
+
+        logging.getLogger("markdown").setLevel(logging.WARNING)
+        logging.getLogger("markdown.extensions").setLevel(logging.WARNING)
+    except Exception:
+        logger.error(
+            "FATAL: Failed to set up file logger. Continuing with console-only logging.",
+            exc_info=True,
+        )
+
+def setup_simple_logging(app_name: str, level: int = logging.WARNING) -> None:
+    root_logger = logging.getLogger()
+    root_logger.setLevel(level)
+
+    for handler in root_logger.handlers[:]:
+        root_logger.removeHandler(handler)
+
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(level)
+    console_handler.setFormatter(formatter)
+
+    root_logger.addHandler(console_handler)
+
+    app_logger = logging.getLogger(app_name)
+    app_logger.setLevel(level)
+
+    logging.getLogger("markdown").setLevel(logging.WARNING)
+    logging.getLogger("markdown.extensions").setLevel(logging.WARNING)
+

sli_ui_toolkit/i18n.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from PyQt6.QtCore import QObject, pyqtSignal
+
+logger = logging.getLogger(__name__)
+
+class ToolkitTranslationEvents(QObject):
+    language_changed = pyqtSignal(str)
+
+def _deep_merge(
+    base: dict[str, Any],
+    incoming: dict[str, Any],
+    source: str,
+    *,
+    warn_on_override: bool,
+) -> None:
+    for key, value in incoming.items():
+        if key not in base:
+            base[key] = value
+            continue
+
+        if isinstance(base[key], dict) and isinstance(value, dict):
+            _deep_merge(base[key], value, source, warn_on_override=warn_on_override)
+            continue
+
+        if warn_on_override:
+            logger.warning("Translation key override for '%s' from %s", key, source)
+        base[key] = value
+
+def _resolve_dotted_key(data: dict[str, Any], dotted_key: str) -> str:
+    current: Any = data
+    for part in dotted_key.split("."):
+        if not isinstance(current, dict) or part not in current:
+            return dotted_key
+        current = current[part]
+
+    return current if isinstance(current, str) else dotted_key
+
+class TranslationManager:
+    _instance: TranslationManager | None = None
+
+    def __new__(cls) -> TranslationManager:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._translations: dict[str, Any] = {}
+            cls._instance._cache: dict[str, dict[str, Any]] = {}
+            cls._instance._current_lang = "en"
+            cls._instance._events = ToolkitTranslationEvents()
+            cls._instance._i18n_root: Path | None = None
+            cls._instance._extra_roots: list[Path] = []
+        return cls._instance
+
+    def set_i18n_root(self, path: str | Path) -> None:
+        self._i18n_root = Path(path)
+        self._extra_roots = []
+        self._cache.clear()
+        self._translations = {}
+
+    def add_i18n_root(self, path: str | Path) -> None:
+        self._extra_roots.append(Path(path))
+        self._cache.clear()
+
+    def _load_tree(self, lang_dir: Path) -> dict[str, Any]:
+        translations: dict[str, Any] = {}
+        json_files = sorted(lang_dir.rglob("*.json"))
+
+        if not json_files:
+            logger.warning("No translation files found in %s", lang_dir)
+            return translations
+
+        for file_path in json_files:
+            try:
+                file_data = json.loads(file_path.read_text(encoding="utf-8"))
+            except Exception as exc:
+                logger.error("Failed to load translation file %s: %s", file_path, exc)
+                continue
+
+            if not isinstance(file_data, dict):
+                logger.warning("Skipping non-object translation file: %s", file_path)
+                continue
+
+            _deep_merge(
+                translations,
+                file_data,
+                file_path.relative_to(lang_dir).as_posix(),
+                warn_on_override=True,
+            )
+
+        return translations
+
+    def _build_language_pack(self, lang_code: str) -> dict[str, Any]:
+        if self._i18n_root is None:
+            logger.error("i18n root not configured — call configure_i18n(i18n_root=...)")
+            return {}
+
+        base_path = self._i18n_root
+        fallback_dir = base_path / "en"
+        requested_dir = base_path / lang_code
+
+        if not fallback_dir.is_dir():
+            logger.error("Fallback translation directory not found: %s", fallback_dir)
+            return {}
+
+        translations = self._load_tree(fallback_dir)
+
+        if lang_code != "en":
+            if not requested_dir.is_dir():
+                logger.warning(
+                    "Translation directory not found: %s. Falling back to EN.",
+                    requested_dir,
+                )
+            else:
+                _deep_merge(
+                    translations,
+                    self._load_tree(requested_dir),
+                    requested_dir.relative_to(base_path).as_posix(),
+                    warn_on_override=False,
+                )
+
+        for extra_root in self._extra_roots:
+            fallback_dir = extra_root / "en"
+            if fallback_dir.is_dir():
+                _deep_merge(
+                    translations,
+                    self._load_tree(fallback_dir),
+                    fallback_dir.relative_to(extra_root).as_posix(),
+                    warn_on_override=False,
+                )
+            if lang_code != "en":
+                lang_dir = extra_root / lang_code
+                if lang_dir.is_dir():
+                    _deep_merge(
+                        translations,
+                        self._load_tree(lang_dir),
+                        lang_dir.relative_to(extra_root).as_posix(),
+                        warn_on_override=False,
+                    )
+
+        return translations
+
+    def load_language(self, lang_code: str) -> None:
+        requested_lang = lang_code or "en"
+
+        if requested_lang == self._current_lang:
+            return
+
+        cached = self._cache.get(requested_lang)
+        if cached is None:
+            cached = self._build_language_pack(requested_lang)
+            self._cache[requested_lang] = cached
+
+        self._translations = cached
+        self._current_lang = requested_lang
+        self._events.language_changed.emit(requested_lang)
+
+    def get(self, text: str, *args: Any, **kwargs: Any) -> str:
+        translated = _resolve_dotted_key(self._translations, text)
+
+        if args or kwargs:
+            try:
+                return translated.format(*args, **kwargs)
+            except Exception:
+                return translated
+        return translated
+
+_manager = TranslationManager()
+
+def configure_i18n(
+    *,
+    i18n_root: str | Path | None = None,
+    translator: Callable[[str, str | None], str] | None = None,
+    language_provider: Callable[[], str] | None = None,
+    events: ToolkitTranslationEvents | None = None,
+) -> None:
+    if i18n_root is not None:
+        _manager.set_i18n_root(i18n_root)
+    if events is not None:
+        _manager._events = events
+
+def translation_events() -> ToolkitTranslationEvents:
+    return _manager._events
+
+def emit_language_changed(lang_code: str) -> None:
+    translation_events().language_changed.emit(str(lang_code or "en"))
+
+def get_current_language(default: str = "en") -> str:
+    return getattr(_manager, "_current_lang", default) or default
+
+def tr(key: str, language: str | None = None, default: str | None = None, *args: Any, **kwargs: Any) -> str:
+    lang = language or get_current_language()
+    _manager.load_language(lang)
+    result = _manager.get(key, *args, **kwargs)
+    if result == key and default is not None:
+        return default
+    return result
+
+
+class TranslationsBinder:
+    """Re-applies translated strings to widgets on language change.
+
+    The engine is widget-agnostic: it stores callbacks parameterized by
+    `lang_code` and invokes them on `apply(lang_code)`. Apps register
+    bindings declaratively via `bind_text/bind_tooltip/bind_placeholder/
+    bind_setter` or escape to `bind_callback` for composite or conditional
+    updates.
+
+    `tr_func` defaults to the toolkit's `tr`; pass a custom translator
+    to bind against a different translation namespace.
+    """
+
+    def __init__(self, tr_func: Callable[..., str] | None = None):
+        self._tr = tr_func or tr
+        self._bindings: list[Callable[[str], None]] = []
+
+    def bind_text(self, widget, key: str, *, suffix: str = "") -> "TranslationsBinder":
+        self._bindings.append(
+            lambda lang: widget.setText(self._tr(key, lang) + suffix)
+        )
+        return self
+
+    def bind_tooltip(self, widget, key: str) -> "TranslationsBinder":
+        self._bindings.append(
+            lambda lang: widget.setToolTip(self._tr(key, lang))
+        )
+        return self
+
+    def bind_placeholder(self, widget, key: str) -> "TranslationsBinder":
+        self._bindings.append(
+            lambda lang: widget.setPlaceholderText(self._tr(key, lang))
+        )
+        return self
+
+    def bind_setter(self, widget, setter: str, key: str, *, suffix: str = "") -> "TranslationsBinder":
+        self._bindings.append(
+            lambda lang: getattr(widget, setter)(self._tr(key, lang) + suffix)
+        )
+        return self
+
+    def bind_callback(self, fn: Callable[[str], None]) -> "TranslationsBinder":
+        """Register an arbitrary callback ``fn(lang_code)`` for composite or
+        conditional updates that don't fit the simple setter pattern."""
+        self._bindings.append(fn)
+        return self
+
+    def apply(self, lang_code: str) -> None:
+        for binding in self._bindings:
+            binding(lang_code)

sli_ui_toolkit/icons.py

@@ -0,0 +1,56 @@
+from collections.abc import Callable
+from typing import Any
+
+from PyQt6.QtGui import QIcon
+
+from sli_ui_toolkit.ui.services.icon_service import (
+    IconService,
+    get_icon_by_name,
+    get_icon_service,
+)
+from sli_ui_toolkit.ui.managers.icon_manager import get_icon_by_path, get_themed_icon
+
+_icon_resolver: Callable[[Any], QIcon] | None = None
+_named_icons: dict[str, Any] = {}
+
+def configure_icon_resolver(
+    resolver: Callable[[Any], QIcon] | None,
+    *,
+    named_icons: dict[str, Any] | None = None,
+) -> None:
+    global _icon_resolver, _named_icons
+    _icon_resolver = resolver
+    _named_icons = dict(named_icons or {})
+
+def resolve_icon(icon: Any) -> QIcon:
+    if icon is None:
+        return QIcon()
+    if isinstance(icon, QIcon):
+        return icon
+    if isinstance(icon, str):
+        mapped = _named_icons.get(icon)
+        if mapped is not None:
+            if _icon_resolver is not None:
+                return _icon_resolver(mapped)
+            return get_icon_by_name(getattr(mapped, "value", mapped))
+        return get_icon_by_name(icon)
+    if _icon_resolver is not None:
+        return _icon_resolver(icon)
+    value = getattr(icon, "value", None)
+    if isinstance(value, str):
+        return get_icon_by_name(value)
+    return QIcon()
+
+def get_named_icon(name: str) -> Any:
+    return _named_icons.get(name)
+
+__all__ = [
+    "IconService",
+    "configure_icon_resolver",
+    "get_icon_by_name",
+    "get_icon_by_path",
+    "get_icon_service",
+    "get_named_icon",
+    "get_themed_icon",
+    "resolve_icon",
+]

sli_ui_toolkit/managers.py

@@ -0,0 +1,13 @@
+from sli_ui_toolkit.ui.managers import (
+    AnchoredFlyoutAutoHide,
+    DelayedActionTimer,
+    FlyoutManager,
+    ThemeManager,
+)
+
+__all__ = [
+    "AnchoredFlyoutAutoHide",
+    "DelayedActionTimer",
+    "FlyoutManager",
+    "ThemeManager",
+]