lightfall-utils 0.1.0__py3-none-any.whl

lightfall_utils/log_buffer.py

@@ -0,0 +1,231 @@
+"""In-process ring buffer of recent log records.
+
+Provides a thread-safe singleton that captures all log records (at the
+configured level and above) into a bounded deque for diagnostics tooling
+to look back at what happened in the moments before something unexpected.
+
+Captures the full tail (DEBUG/INFO/WARNING/ERROR) for comprehensive logging
+inspection and diagnostics.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import deque
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from loguru import Record
+
+
+_LEVEL_NO = {
+    "TRACE": 5,
+    "DEBUG": 10,
+    "INFO": 20,
+    "SUCCESS": 25,
+    "WARNING": 30,
+    "ERROR": 40,
+    "CRITICAL": 50,
+}
+
+
+@dataclass(frozen=True)
+class LogRecord:
+    """A captured log record.
+
+    Attributes:
+        timestamp: When the record was emitted (UTC).
+        level: Log level name (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+        level_no: Numeric level from loguru (DEBUG=10 ... CRITICAL=50).
+        name: Logger name (typically the module path).
+        function: Function where the record was emitted.
+        line: Line number where the record was emitted.
+        thread: Thread name.
+        message: The formatted log message.
+        exception_info: Formatted exception traceback, if any.
+    """
+
+    timestamp: datetime
+    level: str
+    level_no: int
+    name: str
+    function: str
+    line: int
+    thread: str
+    message: str
+    exception_info: str | None = None
+
+
+class LogBuffer:
+    """Singleton ring buffer of recent loguru records.
+
+    Install once at application startup (after :func:`configure_logging`)
+    via :meth:`install`. Subsequent calls are no-ops. Use
+    :meth:`get_records` to retrieve filtered tails.
+    """
+
+    DEFAULT_MAX_RECORDS = 10_000
+    DEFAULT_LEVEL = "DEBUG"
+
+    _instance: LogBuffer | None = None
+    _instance_lock = threading.Lock()
+
+    def __new__(cls) -> LogBuffer:
+        if cls._instance is None:
+            with cls._instance_lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self) -> None:
+        if self._initialized:
+            return
+        self._initialized = True
+
+        self._records: deque[LogRecord] = deque(maxlen=self.DEFAULT_MAX_RECORDS)
+        self._buffer_lock = threading.Lock()
+        self._sink_id: int | None = None
+
+    @classmethod
+    def get_instance(cls) -> LogBuffer:
+        """Return the LogBuffer singleton."""
+        return cls()
+
+    def install(
+        self,
+        level: str = DEFAULT_LEVEL,
+        max_records: int = DEFAULT_MAX_RECORDS,
+    ) -> None:
+        """Install the loguru sink. Safe to call multiple times.
+
+        Args:
+            level: Minimum log level to capture (TRACE/DEBUG/INFO/...).
+            max_records: Ring buffer capacity. The oldest record is
+                evicted when full.
+        """
+        if self._sink_id is not None:
+            return
+
+        from loguru import logger
+
+        if max_records != self._records.maxlen:
+            with self._buffer_lock:
+                self._records = deque(self._records, maxlen=max_records)
+
+        self._sink_id = logger.add(
+            self._sink,
+            level=level,
+            format="{message}",
+        )
+
+    def uninstall(self) -> None:
+        """Remove the loguru sink. Primarily useful for testing."""
+        if self._sink_id is None:
+            return
+
+        from loguru import logger
+
+        logger.remove(self._sink_id)
+        self._sink_id = None
+
+    def clear(self) -> None:
+        """Drop all captured records."""
+        with self._buffer_lock:
+            self._records.clear()
+
+    def __len__(self) -> int:
+        with self._buffer_lock:
+            return len(self._records)
+
+    def get_records(
+        self,
+        *,
+        level: str | None = None,
+        since: datetime | None = None,
+        since_seconds: float | None = None,
+        contains: str | None = None,
+        name_prefix: str | None = None,
+        max_count: int | None = None,
+    ) -> list[LogRecord]:
+        """Return a filtered tail of recent records, newest first.
+
+        Args:
+            level: Minimum level filter (e.g. ``"WARNING"`` returns
+                WARNING/ERROR/CRITICAL only). Case-insensitive.
+            since: Return records with timestamp >= this datetime
+                (UTC; naive datetimes are treated as UTC).
+            since_seconds: Return records emitted within the last N
+                seconds. Mutually exclusive with ``since``; if both are
+                given, the more restrictive one wins.
+            contains: Case-insensitive substring filter on the message.
+            name_prefix: Return only records whose logger name starts
+                with this prefix (e.g. ``"myapp.devices"``).
+            max_count: Cap on returned records. None = unbounded.
+        """
+        min_level_no = _LEVEL_NO.get(level.upper(), 0) if level else 0
+
+        cutoffs: list[datetime] = []
+        if since is not None:
+            cutoffs.append(since if since.tzinfo else since.replace(tzinfo=UTC))
+        if since_seconds is not None:
+            cutoffs.append(datetime.now(UTC) - timedelta(seconds=float(since_seconds)))
+        cutoff = max(cutoffs) if cutoffs else None
+
+        contains_lc = contains.lower() if contains else None
+
+        with self._buffer_lock:
+            records = list(self._records)
+
+        out: list[LogRecord] = []
+        for rec in reversed(records):
+            if rec.level_no < min_level_no:
+                continue
+            if cutoff is not None and rec.timestamp < cutoff:
+                continue
+            if name_prefix is not None and not rec.name.startswith(name_prefix):
+                continue
+            if contains_lc is not None and contains_lc not in rec.message.lower():
+                continue
+            out.append(rec)
+            if max_count is not None and len(out) >= max_count:
+                break
+        return out
+
+    def _sink(self, message) -> None:
+        record: Record = message.record
+
+        exception_info: str | None = None
+        if record["exception"] is not None:
+            exc = record["exception"]
+            if exc.traceback:
+                import traceback
+
+                exception_info = "".join(
+                    traceback.format_exception(exc.type, exc.value, exc.traceback)
+                )
+
+        thread = record.get("thread")
+        thread_name = thread.name if thread is not None else ""
+
+        log_record = LogRecord(
+            timestamp=datetime.now(UTC),
+            level=record["level"].name,
+            level_no=record["level"].no,
+            name=record["name"] or "",
+            function=record["function"] or "",
+            line=record["line"] or 0,
+            thread=thread_name,
+            message=record["message"],
+            exception_info=exception_info,
+        )
+
+        with self._buffer_lock:
+            self._records.append(log_record)
+
+
+def get_log_buffer() -> LogBuffer:
+    """Convenience accessor for the LogBuffer singleton."""
+    return LogBuffer.get_instance()

lightfall_utils/logging.py

@@ -0,0 +1,235 @@
+"""Logging abstraction module.
+
+Provides centralized logging configuration and timing utilities built on loguru.
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+import time
+from collections import defaultdict
+from collections.abc import Generator, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from loguru import Record
+
+__all__ = [
+    "logger",
+    "configure_logging",
+    "log_time",
+    "get_cumulative_stats",
+    "reset_cumulative_stats",
+]
+
+# Thread-safe cumulative timing storage
+_timing_lock = threading.Lock()
+_cumulative_time: dict[str, int] = defaultdict(int)
+_cumulative_count: dict[str, int] = defaultdict(int)
+_application_start_time = time.perf_counter_ns()
+
+# Track whether logging has been configured
+_configured = False
+
+
+# Module-name prefixes muted at DEBUG level; set via configure_logging().
+_mute_debug_modules: tuple[str, ...] = ()
+
+
+def _third_party_filter(record: Record) -> bool:
+    """Filter out DEBUG messages from noisy third-party modules."""
+    if record["level"].no <= 10:  # DEBUG = 10
+        name = record["name"] or ""
+        return not any(name.startswith(mod) for mod in _mute_debug_modules)
+    return True
+
+
+def _default_format(record: Record) -> str:
+    """Default log format."""
+    level_colors = {
+        "TRACE": "dim",
+        "DEBUG": "cyan",
+        "INFO": "green",
+        "SUCCESS": "bold green",
+        "WARNING": "yellow",
+        "ERROR": "red",
+        "CRITICAL": "bold red",
+    }
+    color = level_colors.get(record["level"].name, "")
+    return (
+        "<dim>{time:YYYY-MM-DD HH:mm:ss.SSS}</dim> | "
+        f"<{color}>{{level: <8}}</{color}> | "
+        "<dim>{thread.name}</dim> | "
+        "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
+        "{message}\n{exception}"
+    )
+
+
+def configure_logging(
+    *,
+    level: str = "INFO",
+    log_file: Path | str | None = None,
+    rotation: str = "10 MB",
+    retention: str = "1 week",
+    console: bool = True,
+    colorize: bool = True,
+    format_string: str | None = None,
+    mute_debug_modules: Sequence[str] = (),
+) -> None:
+    """Configure logging for the application.
+
+    This should be called once at application startup. Subsequent calls
+    will reconfigure logging.
+
+    Args:
+        level: Minimum log level to display (TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL).
+        log_file: Optional path to a log file. If provided, logs will also be written to file.
+        rotation: When to rotate the log file (e.g., "10 MB", "1 day", "00:00").
+        retention: How long to keep old log files (e.g., "1 week", "10 days").
+        console: Whether to log to the console (stderr).
+        colorize: Whether to use colors in console output.
+        format_string: Custom format string. If None, uses the default format.
+        mute_debug_modules: Module-name prefixes whose DEBUG/TRACE records are
+            dropped (for noisy third-party libraries).
+    """
+    global _configured, _mute_debug_modules
+    _mute_debug_modules = tuple(mute_debug_modules)
+
+    # Remove all existing handlers
+    logger.remove()
+
+    fmt = format_string if format_string else _default_format
+
+    if console and sys.stderr is not None:
+        logger.add(
+            sys.stderr,
+            level=level,
+            format=fmt,
+            colorize=colorize,
+            filter=_third_party_filter,
+        )
+
+    if log_file:
+        log_path = Path(log_file)
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        logger.add(
+            log_path,
+            level=level,
+            format=fmt,
+            rotation=rotation,
+            retention=retention,
+            compression="gz",
+            filter=_third_party_filter,
+        )
+
+    _configured = True
+    logger.debug("Logging configured with level={}", level)
+
+
+@contextmanager
+def log_time(
+    *args: Any,
+    level: str | int = "INFO",
+    cumulative_key: str = "",
+    precision: int = 3,
+) -> Generator[None, None, None]:
+    """Context manager to log the elapsed time of a code block.
+
+    Args:
+        *args: Message components to log (joined with spaces).
+        level: Log level for the timing message.
+        cumulative_key: If provided, accumulates timing statistics under this key.
+            Use get_cumulative_stats() to retrieve aggregated data.
+        precision: Decimal places for millisecond display.
+
+    Yields:
+        None
+
+    Example:
+        with log_time("Processing data"):
+            process_data()
+
+        with log_time("Database query", cumulative_key="db_queries"):
+            run_query()
+    """
+    start = time.perf_counter_ns()
+    try:
+        yield
+    finally:
+        elapsed_ns = time.perf_counter_ns() - start
+        elapsed_ms = elapsed_ns / 1e6
+
+        message_parts = [str(arg) for arg in args]
+
+        if cumulative_key:
+            with _timing_lock:
+                _cumulative_time[cumulative_key] += elapsed_ns
+                _cumulative_count[cumulative_key] += 1
+                total_ms = _cumulative_time[cumulative_key] / 1e6
+                count = _cumulative_count[cumulative_key]
+                avg_ms = total_ms / count
+                app_elapsed = time.perf_counter_ns() - _application_start_time
+                profile_pct = (_cumulative_time[cumulative_key] / app_elapsed) * 100
+
+            message_parts.append(
+                f"[elapsed: {elapsed_ms:.{precision}f} ms | "
+                f"cumulative: {total_ms:.{precision}f} ms | "
+                f"avg: {avg_ms:.{precision}f} ms | "
+                f"calls: {count} | "
+                f"profile: {profile_pct:.1f}%]"
+            )
+        else:
+            message_parts.append(f"[elapsed: {elapsed_ms:.{precision}f} ms]")
+
+        logger.log(level, " ".join(message_parts))
+
+
+def get_cumulative_stats(key: str | None = None) -> dict[str, dict[str, float]]:
+    """Get cumulative timing statistics.
+
+    Args:
+        key: Specific key to retrieve. If None, returns all statistics.
+
+    Returns:
+        Dictionary mapping keys to their statistics:
+        - total_ms: Total accumulated time in milliseconds
+        - count: Number of calls
+        - avg_ms: Average time per call in milliseconds
+        - profile_pct: Percentage of application runtime
+    """
+    with _timing_lock:
+        app_elapsed = time.perf_counter_ns() - _application_start_time
+
+        def make_stats(k: str) -> dict[str, float]:
+            total_ns = _cumulative_time[k]
+            count = _cumulative_count[k]
+            return {
+                "total_ms": total_ns / 1e6,
+                "count": float(count),
+                "avg_ms": (total_ns / 1e6 / count) if count > 0 else 0.0,
+                "profile_pct": (total_ns / app_elapsed * 100) if app_elapsed > 0 else 0.0,
+            }
+
+        if key is not None:
+            return {key: make_stats(key)}
+        return {k: make_stats(k) for k in _cumulative_time}
+
+
+def reset_cumulative_stats(key: str | None = None) -> None:
+    """Reset cumulative timing statistics.
+
+    Args:
+        key: Specific key to reset. If None, resets all statistics.
+    """
+    with _timing_lock:
+        if key is not None:
+            _cumulative_time.pop(key, None)
+            _cumulative_count.pop(key, None)
+        else:
+            _cumulative_time.clear()
+            _cumulative_count.clear()

lightfall_utils/qt_affinity.py

@@ -0,0 +1,92 @@
+"""Qt thread-affinity assertions.
+
+Helpers to catch the classic Qt failure mode of touching GUI objects from
+a worker thread. Extracted from Lightfall's crash diagnostics.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+__all__ = ["assert_gui_thread", "assert_object_thread", "gui_thread_only"]
+
+
+def assert_gui_thread(obj: Any | None = None) -> None:
+    """Raise ``RuntimeError`` if not running on the QApplication's thread.
+
+    Args:
+        obj: Optional QObject. If supplied, its ``thread()`` is included
+            in the error message — useful when a widget appears to belong
+            to the wrong thread.
+    """
+    from PySide6.QtCore import QCoreApplication, QThread
+
+    app = QCoreApplication.instance()
+    if app is None:
+        # No QApplication yet — affinity isn't meaningful. Be permissive.
+        return
+
+    current = QThread.currentThread()
+    gui_thread = app.thread()
+    if current is gui_thread:
+        return
+
+    py_thread = threading.current_thread()
+    parts = [
+        f"GUI thread assertion failed: called from "
+        f"{py_thread.name!r} (QThread={current!r}), "
+        f"expected GUI thread (QThread={gui_thread!r})",
+    ]
+    if obj is not None:
+        try:
+            obj_thread = obj.thread()
+            parts.append(f"; object {obj!r}.thread()={obj_thread!r}")
+        except Exception as e:
+            parts.append(f"; object thread() raised: {e!r}")
+
+    raise RuntimeError("".join(parts))
+
+
+def assert_object_thread(obj: Any) -> None:
+    """Raise ``RuntimeError`` if the current thread is not ``obj.thread()``.
+
+    The mirror of ``assert_gui_thread`` for QObjects that legitimately
+    live on a non-GUI thread (a worker, a background QObject moved to
+    a QThread, etc).
+    """
+    from PySide6.QtCore import QThread
+
+    obj_thread = obj.thread()
+    current = QThread.currentThread()
+    if current is obj_thread:
+        return
+
+    py_thread = threading.current_thread()
+    raise RuntimeError(
+        f"Object-thread assertion failed: called from "
+        f"{py_thread.name!r} (QThread={current!r}), "
+        f"expected {obj!r}.thread()={obj_thread!r}"
+    )
+
+
+def gui_thread_only(func: F) -> F:
+    """Wrap a method/slot so it raises if called off the GUI thread.
+
+    The wrapped callable is otherwise unchanged — ``@Slot`` decorators
+    can be stacked above or below.
+    """
+
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        # Pass the receiver (first positional, when wrapping a bound method)
+        # to assert_gui_thread so its thread() is included in the error.
+        receiver = args[0] if args else None
+        assert_gui_thread(receiver)
+        return func(*args, **kwargs)
+
+    return wrapper  # type: ignore[return-value]

lightfall_utils/theming/__init__.py

@@ -0,0 +1,30 @@
+"""Semantic design tokens, theme registry, and QSS generation."""
+
+from lightfall_utils.theming.manager import (
+    DARKBLUE_COLORS,
+    LIGHT_COLORS,
+    SLATE_COLORS,
+    BeamlineTheme,
+    Theme,
+    ThemeColors,
+    ThemeManager,
+    scaled_pt,
+    scaled_px,
+)
+from lightfall_utils.theming.provider import ThemeDefinition, ThemeProvider
+from lightfall_utils.theming.registry import ThemeRegistry
+
+__all__ = [
+    "BeamlineTheme",
+    "DARKBLUE_COLORS",
+    "LIGHT_COLORS",
+    "SLATE_COLORS",
+    "Theme",
+    "ThemeColors",
+    "ThemeDefinition",
+    "ThemeManager",
+    "ThemeProvider",
+    "ThemeRegistry",
+    "scaled_pt",
+    "scaled_px",
+]