lightfall-utils 0.1.0__py3-none-any.whl

lightfall_utils/__init__.py

@@ -0,0 +1,3 @@
+"""Shared Qt/EPICS infrastructure for ALS control applications."""
+
+from lightfall_utils._version import __version__  # noqa: F401

lightfall_utils/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

lightfall_utils/ca/__init__.py

@@ -0,0 +1,9 @@
+"""Channel Access via caproto, bridged to Qt signals.
+
+Requires the ``ca`` extra: ``pip install lightfall-utils[ca]``.
+"""
+
+from lightfall_utils.ca.context import SharedContext
+from lightfall_utils.ca.pv import PV
+
+__all__ = ["SharedContext", "PV"]

lightfall_utils/ca/context.py

@@ -0,0 +1,100 @@
+"""
+Shared CA context management for the application.
+
+Provides a singleton-like shared context that widgets can use to connect to PVs.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING
+
+from caproto.threading.client import Context
+
+if TYPE_CHECKING:
+    from caproto.threading.client import PV as CaprotoPV
+
+
+class SharedContext:
+    """
+    Manages a shared caproto threading context for all widgets.
+
+    This class provides a singleton pattern for the CA context to avoid
+    creating multiple contexts and to share connections efficiently.
+
+    Attributes:
+        context: The underlying caproto threading Context instance.
+
+    Example:
+        >>> ctx = SharedContext.get_instance()
+        >>> pv = ctx.get_pv("MY:PV:NAME")
+    """
+
+    _instance: SharedContext | None = None
+    _lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._context: Context | None = None
+        self._pvs: dict[str, CaprotoPV] = {}
+
+    @classmethod
+    def get_instance(cls) -> SharedContext:
+        """
+        Get the singleton SharedContext instance.
+
+        Returns:
+            The shared context instance.
+        """
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    @property
+    def context(self) -> Context:
+        """
+        Get the underlying caproto Context, creating it if necessary.
+
+        Returns:
+            The caproto threading Context.
+        """
+        if self._context is None:
+            self._context = Context()
+        return self._context
+
+    def get_pv(self, pv_name: str) -> CaprotoPV:
+        """
+        Get or create a PV connection.
+
+        Args:
+            pv_name: The name of the PV to connect to.
+
+        Returns:
+            The caproto PV object.
+        """
+        if pv_name not in self._pvs:
+            (pv,) = self.context.get_pvs(pv_name)
+            self._pvs[pv_name] = pv
+        return self._pvs[pv_name]
+
+    def clear(self) -> None:
+        """
+        Clear all cached PVs and reset the context.
+
+        Useful for testing or when reconfiguring the connection.
+        """
+        self._pvs.clear()
+        self._context = None
+
+    @classmethod
+    def reset(cls) -> None:
+        """
+        Reset the singleton instance entirely.
+
+        Primarily used for testing to ensure a clean state.
+        """
+        with cls._lock:
+            if cls._instance is not None:
+                cls._instance.clear()
+            cls._instance = None

lightfall_utils/ca/pv.py

@@ -0,0 +1,307 @@
+"""
+PV wrapper that bridges caproto to Qt signals.
+
+Provides a Qt-friendly interface to EPICS PVs with signals for value changes.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from PySide6.QtCore import QObject, Qt, Signal, Slot
+
+from lightfall_utils.qt_affinity import gui_thread_only
+
+
+class PV(QObject):
+    """
+    A Qt-aware wrapper around a caproto PV.
+
+    Emits Qt signals when the PV value changes, making it easy to connect
+    to widget slots for automatic UI updates.
+
+    Attributes:
+        pv_name: The EPICS PV name this object represents.
+        connected: Whether the PV is currently connected.
+        value: The current PV value.
+
+    Signals:
+        value_changed: Emitted when the PV value changes. Carries the new value.
+        connection_changed: Emitted when connection state changes. Carries bool.
+        metadata_changed: Emitted when PV metadata changes (units, limits, etc).
+
+    Example:
+        >>> pv = PV("MY:PV:NAME")
+        >>> pv.value_changed.connect(my_label.setText)
+        >>> pv.connect()
+    """
+
+    value_changed = Signal(object)
+    connection_changed = Signal(bool)
+    metadata_changed = Signal(dict)
+
+    # Internal signals for thread-safe updates from caproto callbacks
+    _value_received = Signal(object)
+    _connection_ready = Signal(bool)
+
+    def __init__(
+        self,
+        pv_name: str,
+        parent: QObject | None = None,
+        auto_connect: bool = False,
+    ) -> None:
+        """
+        Initialize a PV wrapper.
+
+        Args:
+            pv_name: The EPICS PV name to connect to.
+            parent: Optional Qt parent object.
+            auto_connect: If True, connect immediately on creation.
+        """
+        super().__init__(parent)
+        self._pv_name = pv_name
+        self._connected = False
+        self._value: Any = None
+        self._metadata: dict[str, Any] = {}
+        self._caproto_pv = None
+        self._subscription = None
+
+        # Connect internal signals for thread-safe updates
+        self._value_received.connect(
+            self._handle_value_received, Qt.ConnectionType.QueuedConnection
+        )
+        self._connection_ready.connect(
+            self._handle_connection_ready, Qt.ConnectionType.QueuedConnection
+        )
+
+        if auto_connect:
+            self.connect_pv()
+
+    @property
+    def pv_name(self) -> str:
+        """The EPICS PV name."""
+        return self._pv_name
+
+    @property
+    def connected(self) -> bool:
+        """Whether the PV is currently connected."""
+        return self._connected
+
+    @property
+    def value(self) -> Any:
+        """The current PV value."""
+        return self._value
+
+    @property
+    def metadata(self) -> dict[str, Any]:
+        """
+        PV metadata including units, limits, precision, enum strings, etc.
+
+        Returns:
+            Dictionary with keys like 'units', 'lower_limit', 'upper_limit',
+            'precision', 'enum_strings', etc. depending on the PV type.
+        """
+        return self._metadata.copy()
+
+    def connect_pv(self) -> None:
+        """
+        Establish connection to the PV and start monitoring.
+
+        This method is safe to call multiple times - it will only connect once.
+        Connection is performed in a background thread to avoid blocking the GUI.
+        """
+        if self._caproto_pv is not None:
+            return
+
+        # Start connection in background thread to avoid blocking
+        thread = threading.Thread(target=self._connect_pv_blocking, daemon=True)
+        thread.start()
+
+    def _connect_pv_blocking(self) -> None:
+        """
+        Blocking connection logic - runs in background thread.
+        """
+        from lightfall_utils.ca.context import SharedContext
+
+        ctx = SharedContext.get_instance()
+        self._caproto_pv = ctx.get_pv(self._pv_name)
+
+        # Wait for connection with timeout
+        try:
+            self._caproto_pv.wait_for_connection(timeout=5.0)
+            # Signal main thread that connection succeeded
+            self._connection_ready.emit(True)
+        except TimeoutError:
+            self._connection_ready.emit(False)
+
+    @Slot(bool)
+    @gui_thread_only
+    def _handle_connection_ready(self, connected: bool) -> None:
+        """
+        Handle connection completion in the main Qt thread.
+
+        Args:
+            connected: Whether connection succeeded.
+        """
+        self._connected = connected
+        self.connection_changed.emit(connected)
+
+        if not connected:
+            return
+
+        # Read initial value and metadata
+        self._read_metadata()
+        self._read_initial_value()
+
+        # Subscribe to value changes
+        self._subscription = self._caproto_pv.subscribe(data_type="time")
+        self._subscription.add_callback(self._on_value_change)
+
+    def disconnect_pv(self) -> None:
+        """
+        Disconnect from the PV and stop monitoring.
+        """
+        if self._subscription is not None:
+            self._subscription.clear()
+            self._subscription = None
+
+        self._caproto_pv = None
+        self._connected = False
+        self.connection_changed.emit(False)
+
+    def put(self, value: Any, wait: bool = False, timeout: float = 5.0) -> None:
+        """
+        Write a value to the PV.
+
+        Args:
+            value: The value to write.
+            wait: If True, block until the write completes.
+            timeout: Timeout in seconds if wait is True.
+
+        Raises:
+            RuntimeError: If PV is not connected.
+        """
+        if not self._connected or self._caproto_pv is None:
+            raise RuntimeError(f"PV {self._pv_name} is not connected")
+
+        self._caproto_pv.write(value, wait=wait, timeout=timeout)
+
+    def _on_value_change(self, sub: Any, response: Any) -> None:
+        """
+        Callback for PV value changes from caproto subscription.
+
+        This runs in a caproto background thread, so we use a queued
+        signal connection to safely update the Qt main thread.
+
+        Args:
+            sub: The subscription object.
+            response: The caproto subscription response.
+        """
+        value = response.data
+        # Handle array vs scalar
+        if hasattr(value, "__len__") and len(value) == 1:
+            value = value[0]
+        # Emit to internal signal which is queued to main thread
+        self._value_received.emit(value)
+
+    @Slot(object)
+    @gui_thread_only
+    def _handle_value_received(self, value: Any) -> None:
+        """
+        Handle value update in the main Qt thread.
+
+        Args:
+            value: The new PV value.
+        """
+        self._value = value
+        self.value_changed.emit(value)
+
+    def _read_metadata(self) -> None:
+        """
+        Read and cache PV metadata (units, limits, etc).
+        """
+        if self._caproto_pv is None:
+            return
+
+        try:
+            # Read with control data type to get metadata
+            result = self._caproto_pv.read(data_type="control")
+
+            metadata: dict[str, Any] = {}
+
+            # Metadata is in result.metadata for caproto
+            meta = getattr(result, "metadata", None)
+            if meta is None:
+                meta = result
+
+            # Extract common metadata fields
+            if hasattr(meta, "units"):
+                units = meta.units
+                metadata["units"] = units.decode() if isinstance(units, bytes) else units
+
+            if hasattr(meta, "lower_ctrl_limit"):
+                metadata["lower_limit"] = meta.lower_ctrl_limit
+
+            if hasattr(meta, "upper_ctrl_limit"):
+                metadata["upper_limit"] = meta.upper_ctrl_limit
+
+            if hasattr(meta, "precision"):
+                metadata["precision"] = meta.precision
+
+            if hasattr(meta, "enum_strings"):
+                metadata["enum_strings"] = [
+                    s.decode() if isinstance(s, bytes) else s
+                    for s in meta.enum_strings
+                    if s  # Filter out empty strings
+                ]
+
+            self._metadata = metadata
+            self.metadata_changed.emit(metadata)
+
+        except Exception:
+            # Metadata read failed - continue without it
+            pass
+
+    def _read_initial_value(self) -> None:
+        """
+        Read and emit the initial PV value.
+        """
+        if self._caproto_pv is None:
+            return
+
+        try:
+            result = self._caproto_pv.read()
+            value = result.data
+            # Handle array vs scalar
+            if hasattr(value, "__len__") and len(value) == 1:
+                value = value[0]
+            self._value = value
+            self.value_changed.emit(value)
+        except Exception:
+            # Initial read failed - subscription will provide value
+            pass
+
+    def get_introspection_data(self) -> dict[str, Any]:
+        """
+        Get detailed introspection data for this PV.
+
+        This method is designed to support Claude MCP tools that inspect
+        the widget tree. It provides all relevant information about the
+        PV in a structured format.
+
+        Returns:
+            Dictionary containing:
+                - pv_name: The EPICS PV name
+                - connected: Connection status
+                - value: Current value
+                - metadata: All cached metadata
+                - type: String representation of the value type
+        """
+        return {
+            "pv_name": self._pv_name,
+            "connected": self._connected,
+            "value": self._value,
+            "value_type": type(self._value).__name__ if self._value is not None else None,
+            "metadata": self._metadata,
+        }

lightfall_utils/caproto_shutdown.py

@@ -0,0 +1,89 @@
+"""Stop caproto's user-callback thread pools cleanly at application shutdown.
+
+Each connected caproto virtual circuit owns a *non-daemon*
+``ThreadPoolExecutor`` (``user_callback_executor``) that runs user
+subscription/read/write callbacks. ``concurrent.futures`` registers an
+``atexit`` hook that joins every executor's worker threads at interpreter
+shutdown, so a callback still in flight there stalls exit -- the reason
+host applications may install a force-exit watchdog. Draining these
+executors (without tearing down sockets) lets the process exit on its own.
+
+``get_caproto_context`` never *creates* a context: at shutdown we only want
+the one caproto already built, not a fresh one (which would spawn threads).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from lightfall_utils.logging import logger
+
+__all__ = ["get_caproto_context", "drain_callback_executors", "disconnect_context"]
+
+
+def get_caproto_context() -> Any | None:
+    """Return caproto's already-created shared Context, or ``None``.
+
+    Returns ``None`` when caproto isn't installed, its threading control layer
+    was never used, or anything goes wrong. Never creates a new context (that
+    would spin up broadcaster/selector threads during shutdown).
+    """
+    try:
+        from caproto.threading.pyepics_compat import _make_context
+
+        # _make_context is functools.lru_cache(1). Only return a context if one
+        # was actually built (currsize > 0) so we never construct one here.
+        if _make_context.cache_info().currsize == 0:
+            return None
+        return _make_context()
+    except Exception:
+        return None
+
+
+def drain_callback_executors(ctx: Any | None) -> int:
+    """Shut down every circuit's user-callback ``ThreadPoolExecutor``.
+
+    Uses ``wait=False, cancel_futures=True``: queued callbacks are dropped and
+    no new work is accepted, so the non-daemon worker threads finish and stop
+    blocking interpreter exit. Does **not** touch sockets, so it cannot trigger
+    the socket-teardown crash that a full ``Context.disconnect()`` is suspected
+    of. Returns the number of executors drained. Never raises.
+    """
+    if ctx is None:
+        return 0
+    drained = 0
+    try:
+        circuit_managers = getattr(ctx, "circuit_managers", None) or {}
+        for cm in list(circuit_managers.values()):
+            executor = getattr(cm, "user_callback_executor", None)
+            if executor is None:
+                continue
+            try:
+                executor.shutdown(wait=False, cancel_futures=True)
+                drained += 1
+            except Exception as e:
+                logger.warning("Failed to shut down a caproto callback executor: {}", e)
+    except Exception as e:
+        logger.warning("Draining caproto callback executors failed: {}", e)
+    return drained
+
+
+def disconnect_context(ctx: Any | None) -> bool:
+    """Fully disconnect a caproto ``Context`` (circuits + sockets + selector).
+
+    This is the thorough teardown -- besides draining the callback executors it
+    also stops caproto's selector/circuit threads before interpreter
+    finalization, which the drain path deliberately leaves running. The socket
+    teardown here is what has historically been suspected of a Windows access
+    violation, so callers gate this behind an opt-in. Returns ``True`` if
+    ``disconnect()`` was invoked. Never raises at the Python level (a hard
+    native crash, if it really happens, cannot be caught here).
+    """
+    if ctx is None:
+        return False
+    try:
+        ctx.disconnect(wait=False)
+        return True
+    except Exception as e:
+        logger.warning("caproto Context.disconnect() failed: {}", e)
+        return False

lightfall_utils/config/__init__.py

@@ -0,0 +1,12 @@
+"""Priority-layered configuration with pydantic validation."""
+
+from lightfall_utils.config.layers import ConfigLayer, ConfigPriority, LayeredConfig
+from lightfall_utils.config.manager import ConfigManager, PermissiveModel
+
+__all__ = [
+    "ConfigLayer",
+    "ConfigPriority",
+    "LayeredConfig",
+    "ConfigManager",
+    "PermissiveModel",
+]