seq-quince 0.1.1__py3-none-any.whl

seq_quince/config_manager.py

@@ -0,0 +1,129 @@
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+from seq_quince.loader import j2_yaml_loader
+from seq_quince.sequence import MoveStep, build_sequence
+from seq_quince.snapshot import SnapshotManager
+from seq_quince.tools import get_scheduler_config_dir, merge_replacements
+
+log = logging.getLogger("seq_quince.loader")
+
+#TODO: Expand macros
+#TODO: Templates with Jinja2
+#TODO: Defaults
+class SchedulerConfigManager:
+    def __init__(
+        self,
+        config_dir: Optional[str] = None,
+        replacements: Optional[Dict[str, str]] = None,
+        config_file: str = 'beamline.yaml',
+        preset_file: str = 'presets.yaml',
+        log_level: int = logging.INFO,
+    ):
+        log.setLevel(log_level)
+        self.replacements = replacements or {}
+        self.config_dir = (
+            config_dir or
+            os.environ.get("SCHEDULER_CONFIG_DIR") or
+            get_scheduler_config_dir()
+        )
+        log.info(f"Scheduler config directory: {self.config_dir}")
+        self.config_path = os.path.join(self.config_dir, config_file)
+        self.snapshot_manager = SnapshotManager(config_dir=self.config_dir, preset_file=preset_file, replacements=self.replacements)
+        self.config = self._load_config()
+        log.info(f"Scheduler config loaded: {self.config_path}")
+        self.devices_cfg = self.config.get("devices", [])
+        self.macros = self.config.get("macros", {})
+        self.presets = self.config.get("presets", {})
+        self.sequence = self.config.get("sequence", {})
+
+    def _load_config(self) -> Dict[str, Any]:
+        log.info(f"yaml_load: {self.config_path}, {self.replacements}")
+        cfg = j2_yaml_loader(self.config_path, self.replacements)
+        log.debug(f"cfg: {cfg}")
+        user_presets = self.snapshot_manager.load_snapshot()
+
+        # Merge presets: user_presets overrides cfg
+        cfg_presets = cfg.get("presets", {})
+        user_presets_only = user_presets.get("presets", {})
+        merged_presets = {**cfg_presets, **user_presets_only}
+
+        # Insert merged presets back into cfg
+        cfg["presets"] = merged_presets
+        log.debug(f"cfg merged: {cfg}")
+        return cfg
+
+    def get_device_configs(self) -> List[Dict[str, Any]]:
+        return self.devices_cfg
+
+    def create_devices(self, factory) -> Dict[str, Any]:
+        names = set()
+        for cfg in self.devices_cfg:
+            name = cfg.get("name")
+            if name in names:
+                raise ValueError(f"Duplicate device name '{name}' in config.")
+            names.add(name)
+        for cfg in self.devices_cfg:
+            merge_replacements(cfg, self.replacements)
+        devices = [factory.create(cfg) for cfg in self.devices_cfg]
+        return {d.name: d for d in devices}
+
+    def get_device_by_name(self, name: str) -> Optional[Dict[str, Any]]:
+        return next((cfg for cfg in self.devices_cfg if cfg.get("name") == name), None)
+
+    def get_preset(self, preset_name: str) -> Dict[str, Any]:
+        if preset_name not in self.presets:
+            raise ValueError(f"Preset '{preset_name}' not found in config.")
+        return self.presets[preset_name]
+
+    def get_sequence_config(self) -> Dict[str, Any]:
+        return self.sequence
+
+    def get_macros(self) -> Dict[str, str]:
+        return self.macros
+
+    def build_sequence_from_preset(
+        self,
+        preset_name: str,
+        devices: dict,
+        *,
+        default_grouping: str = "parallel",
+        build_sequence_func=None,  # allow for test/mock override
+    ) -> List["MoveStep"]:
+        """
+        Build a MoveStep sequence for a given preset using the provided devices dict.
+        """
+        # Get the preset mapping
+        preset = self.get_preset(preset_name)
+        if preset is None:
+            raise ValueError(f"Preset '{preset_name}' not found in config.")
+        # Use external or default build_sequence function
+        if build_sequence_func is None:
+            build_sequence_func = build_sequence
+        # Use the preset as the 'target'
+        return build_sequence_func(devices, preset, default_grouping=default_grouping)
+
+    # TODO: Implement a method to update full config (takes effact before device creation)
+    def update_preset_item(self, preset_name: str, device_name: str, updates: dict) -> None:
+        """
+        Update one device's preset entry with new values.
+        Example: update_preset_item('init', 'energy_scan', {'start': 355.0})
+        """
+        preset = self.presets.setdefault(preset_name, {})
+        device_preset = preset.setdefault(device_name, {})
+        if not isinstance(device_preset, dict):
+            raise TypeError(f"Preset entry for {device_name} in '{preset_name}' must be a dict.")
+        device_preset.update(updates)
+
+    def save_snapshot(self, name: str, structure: Dict[str, Dict[str, float]]) -> None:
+        self.snapshot_manager.save_snapshot(name, structure)
+
+    def save_config(self, path: Optional[str] = None) -> None:
+        path = path or self.config_path
+        # TODO: If you have self.replacements, replace macros before writing if needed
+        with open(path, "w") as f:
+            yaml.dump(self.config, f, default_flow_style=False)
+

seq_quince/device/device_abs.py

@@ -0,0 +1,96 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Type, TypeVar
+
+
+def get_param(config: Dict[str, Any], key: str, typ, default=None, required=False):
+    value = config.get(key, default)
+    if required and value is None:
+        raise ValueError(f"Missing required parameter: '{key}'")
+    if value is not None and not isinstance(value, typ):
+        try:
+            value = typ(value)
+        except (TypeError, ValueError) as e:
+            raise TypeError(
+                f"Parameter '{key}' expects type {typ.__name__} "
+                f"but got {value!r} ({e})"
+            ) from e
+    return value
+
+
+
+T = TypeVar("T", bound="DeviceABC")
+
+class DeviceABC(ABC):
+    """Abstract base class for devices."""
+
+    # init free configurable
+    # ------ Data & state ----------------------------------------------------
+    name: str                                  # human-readable identifier
+
+
+    @classmethod
+    @abstractmethod
+    def from_config_dict(cls: Type[T], config: Dict[str, Any]) -> T:
+        """
+        Create an instance of the device from a config dictionary.
+        """
+
+    # ------ Motion primitives ----------------------------------------------
+    # async def move_to_pose(self, pose: Dict[str, float]) -> None:
+    @abstractmethod
+    async def process(self, pose: Dict[str, float]) -> None:
+        """
+        Drive the device so every axis reaches the *pose* target (value in
+        engineering units).
+        Must raise error *only* after an orderly rollback has completed or is impossible.
+        """
+
+    @abstractmethod
+    async def snapshot(self) -> Dict[str, float]:
+        """Return the *current* read-back values for every axis."""
+
+    @property
+    @abstractmethod
+    def busy(self) -> bool:
+        """True while **any** axis is still moving or the device is faulted."""
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """
+        Best-effort immediate stop (e.g. user pressed Ctrl-C).  Must leave the
+        device in a recoverable, well-defined state.
+        """
+
+    async def close(self) -> None:
+        """
+        Release owned resources after operations settle; safe to repeat.
+        """
+        from seq_quince.device.lifecycle import close_resources
+
+        await close_resources(self)
+
+    def get_capability(self, name: str) -> Optional[Any]:
+        """Return the capability object by name, or None if not present."""
+        return None  # Default: no capability
+    def supports_rollback(self) -> bool:
+        """
+        Whether the scheduler should attempt rollback for this device.
+
+        Motion devices usually return True.
+        Wait-only / monitor-only devices should return False.
+        """
+        return True
+
+    def scheduler_timeout(self, pose: Optional[Dict[str, Any]] = None) -> Optional[float]:
+        """
+        Optional per-step timeout override used by Scheduler.
+
+        Return:
+          * None  -> inherit the scheduler's global step_timeout
+          * > 0   -> scheduler-enforced timeout in seconds
+          * <= 0  -> treated as disabled (no scheduler timeout)
+
+        The default is None, so the global timeout applies when configured.
+        """
+        return None
+

seq_quince/device/extensions.py

@@ -0,0 +1,211 @@
+"""Load explicitly exported devices from SEQ_QUINCE_DEVICE_PATH directories."""
+
+import hashlib
+import importlib.util
+import inspect
+import os
+import sys
+from importlib.abc import ExecutionLoader
+from importlib.machinery import ModuleSpec
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Dict, List, Mapping, Set, Tuple, Type
+
+from seq_quince.device.device_abs import DeviceABC
+
+
+class DeviceExtensionError(RuntimeError):
+    """An extension could not be imported or registered."""
+
+
+class DeviceExtensionLoader:
+    """
+    Finds additional external device implementations. 
+    One thread at a time can perform registry operations.
+    """
+
+    def __init__(self) -> None:
+        self._loaded_paths: Set[Path] = set()
+        self._loading = False
+
+    def load(self, registry: Mapping[str, Type[DeviceABC]]) -> Dict[str, Type[DeviceABC]]:
+        """Return validated additions, without modifying *registry*."""
+        if self._loading:
+            raise DeviceExtensionError(
+                "Recursive device extension discovery: extension imports must "
+                "not create devices or query the factory during discovery"
+            )
+        self._loading = True
+        try:
+            return self._load(registry)
+        finally:
+            self._loading = False
+
+    def _load(self, registry: Mapping[str, Type[DeviceABC]]) -> Dict[str, Type[DeviceABC]]:
+        roots = self._new_roots()
+        if not roots:
+            return {}
+        additions: Dict[str, Type[DeviceABC]] = {}
+        sources: Dict[str, Path] = {}
+        namespaces = [self._namespace(root) for root in roots]
+        previous_modules = {
+            name: module
+            for name, module in sys.modules.copy().items()
+            if self._belongs_to(name, namespaces)
+        }
+        try:
+            # associate each extension directory with its corresponding Python module
+            for root, namespace in zip(roots, namespaces):
+                self._create_namespace(root, namespace)
+                for entry, is_package in self._entries(root):
+                    module = self._import_entry(entry, namespace, is_package)
+                    if "DEVICE_CLASSES" not in vars(module):
+                        continue
+                    exports = vars(module)["DEVICE_CLASSES"]
+                    for name, device_cls in self._validate_exports(exports, entry):
+                        if name in registry or name in additions:
+                            source = (
+                                str(sources[name]) if name in additions
+                                else self._class_source(registry[name])
+                            )
+                            raise DeviceExtensionError(
+                                f"Duplicate device type {name!r} in extension "
+                                f"'{entry}'; already registered by '{source}'"
+                            )
+                        additions[name] = device_cls
+                        sources[name] = entry
+        except BaseException:
+            # Roll back only our module namespaces, including imported helpers.
+            # Preserve KeyboardInterrupt/SystemExit while cleaning up as well.
+            for name in list(sys.modules):
+                if self._belongs_to(name, namespaces):
+                    del sys.modules[name]
+            sys.modules.update(previous_modules)
+            raise
+
+        self._loaded_paths.update(roots)
+        return additions
+
+    def _new_roots(self) -> List[Path]:
+        roots: List[Path] = []
+        seen: Set[Path] = set()
+        for value in os.environ.get("SEQ_QUINCE_DEVICE_PATH", "").split(os.pathsep):
+            if not value:
+                continue
+            root = Path(os.path.realpath(os.path.expanduser(value)))
+            if root in seen or root in self._loaded_paths:
+                continue
+            if not root.is_dir():
+                raise DeviceExtensionError(
+                    f"SEQ_QUINCE_DEVICE_PATH entry '{value}' is not a directory "
+                    f"(resolved to '{root}')"
+                )
+            seen.add(root)
+            roots.append(root)
+        return roots
+
+    @staticmethod
+    def _namespace(root: Path) -> str:
+        digest = hashlib.sha256(os.fsencode(str(root))).hexdigest()
+        return "_seq_quince_device_extensions_" + digest
+
+    @staticmethod
+    def _belongs_to(name: str, namespaces: List[str]) -> bool:
+        return any(name == prefix or name.startswith(prefix + ".")
+                   for prefix in namespaces)
+
+    @staticmethod
+    def _create_namespace(root: Path, namespace: str) -> None:
+        if namespace in sys.modules:
+            return
+        module = ModuleType(namespace)
+        spec = ModuleSpec(namespace, loader=None, is_package=True)
+        spec.submodule_search_locations = [str(root)]
+        module.__spec__ = spec
+        module.__package__ = namespace
+        module.__path__ = [str(root)]
+        sys.modules[namespace] = module
+
+    @staticmethod
+    def _entries(root: Path) -> List[Tuple[Path, bool]]:
+        """ Cheks if each path is a package directory """
+        try:
+            children = sorted(root.iterdir())
+            entries: List[Tuple[Path, bool]] = []
+            names: Set[str] = set()
+            for entry in children:
+                if entry.name.startswith(("_", ".")):
+                    continue
+                is_package = entry.is_dir() and (entry / "__init__.py").is_file()
+                if not is_package and not (entry.is_file() and entry.suffix == ".py"):
+                    continue
+                name = entry.name if is_package else entry.stem
+                if not name.isidentifier():
+                    raise DeviceExtensionError(f"Extension '{entry}' must have a valid Python module name")
+                if name in names:
+                    raise DeviceExtensionError(
+                        f"Ambiguous extension module name {name!r} in '{root}' "
+                        "(both a Python file and package directory exist)"
+                    )
+                names.add(name)
+                entries.append((entry, is_package))
+            return entries
+        except OSError as exc:
+            raise DeviceExtensionError(f"Cannot scan extension directory '{root}': {exc}") from exc
+
+    @staticmethod
+    def _import_entry(entry: Path, namespace: str, is_package: bool) -> ModuleType:
+        """ Loads a Python file or package from a given path and returns the module object """
+        name = entry.name if is_package else entry.stem
+        module_name = namespace + "." + name
+        if module_name in sys.modules:
+            return sys.modules[module_name]
+        source = entry / "__init__.py" if is_package else entry
+        try:
+            # import both, files and directories
+            spec = importlib.util.spec_from_file_location(
+                module_name, str(source),
+                submodule_search_locations=[str(entry)] if is_package else None,
+            )
+            if spec is None or not isinstance(spec.loader, ExecutionLoader):  # for pyright: SourceFileLoader provides the methods expected from an ExecutionLoader
+                raise ImportError(f"Cannot create an executable import specification for '{source}'")
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module   # register loaded module
+            spec.loader.exec_module(module) # Execute the code of the module object
+            parent = sys.modules[namespace] # seq_quince.device.extensions
+            setattr(parent, name, module)
+            return module
+        except Exception as exc:
+            raise DeviceExtensionError(
+                f"Cannot import device extension '{source}': "
+                f"{type(exc).__name__}: {exc}"
+            ) from exc
+
+    @staticmethod
+    def _validate_exports(
+        exports: Any, entry: Path
+    ) -> List[Tuple[str, Type[DeviceABC]]]:
+        if not isinstance(exports, Mapping):
+            raise DeviceExtensionError(f"DEVICE_CLASSES in extension '{entry}' must be a mapping")
+        validated: List[Tuple[str, Type[DeviceABC]]] = []
+        for name, device_cls in exports.items():
+            if not isinstance(name, str) or not name.strip():
+                raise DeviceExtensionError(
+                    f"DEVICE_CLASSES key {name!r} in extension '{entry}' "
+                    "must be a nonempty string"
+                )
+            if (not inspect.isclass(device_cls)
+                    or not issubclass(device_cls, DeviceABC)
+                    or inspect.isabstract(device_cls)):
+                raise DeviceExtensionError(
+                    f"DEVICE_CLASSES[{name!r}] in extension '{entry}' "
+                    "must be a concrete DeviceABC subclass"
+                )
+            validated.append((name, device_cls))
+        return validated
+
+    @staticmethod
+    def _class_source(device_cls: Type[DeviceABC]) -> str:
+        module = sys.modules.get(device_cls.__module__)
+        source = getattr(module, "__file__", device_cls.__module__)
+        return f"{source} ({device_cls.__name__})"

seq_quince/device/factory.py

@@ -0,0 +1,75 @@
+from threading import RLock
+from typing import Any, Dict, List, Type
+
+from seq_quince.device.device_abs import DeviceABC
+from seq_quince.device.extensions import DeviceExtensionLoader
+from seq_quince.device.lifecycle import own_device
+from seq_quince.device_concrete.actuator import ActuatorDevice
+from seq_quince.device_concrete.hexapod import HexapodDevice
+from seq_quince.device_concrete.mono_zero_order import MonoZeroOrderDevice
+from seq_quince.device_concrete.ophyd_motor import OphydMotorDevice
+from seq_quince.device_concrete.scan import ScanDevice
+from seq_quince.device_concrete.sequence import SequenceDevice
+from seq_quince.device_concrete.sim import SimDevice
+from seq_quince.device_concrete.toggle import ToggleDevice
+from seq_quince.device_concrete.wait_condition import WaitConditionDevice
+
+DEVICE_REGISTRY: Dict[str, Type[DeviceABC]] = {
+    "OphydMotorDevice": OphydMotorDevice,
+    "ScanDevice": ScanDevice,
+    "ToggleDevice": ToggleDevice,
+    "SequenceDevice": SequenceDevice,
+    "ActuatorDevice": ActuatorDevice,
+    "HexapodDevice": HexapodDevice,
+    "SimDevice": SimDevice,
+    "MonoZeroOrderDevice": MonoZeroOrderDevice,
+    "WaitConditionDevice": WaitConditionDevice,
+}
+
+_extension_loader = DeviceExtensionLoader()
+_registry_lock = RLock()
+
+# ---- Factory Class ---------------------------------------------------------
+
+class DeviceFactory:
+    @classmethod
+    def load_extensions(cls) -> None:
+        """
+        Register devices exported by new SEQ_QUINCE_DEVICE_PATH directories.
+
+        Discovery happens automatically during creation and type listing. This
+        method also lets callers check extensions before creating any devices.
+        """
+        with _registry_lock:
+            DEVICE_REGISTRY.update(_extension_loader.load(DEVICE_REGISTRY))
+
+    @classmethod
+    def register(cls, name: str, device_cls: Type[DeviceABC]) -> None:
+        # Preserve the existing explicit-registration replacement behavior.
+        with _registry_lock:
+            DEVICE_REGISTRY[name] = device_cls
+
+    @classmethod
+    def create(cls, config: Dict[str, Any]) -> DeviceABC:
+        """Create a device from config dict. Must include 'type' key."""
+        device_type = config.get("type")
+        if not device_type:
+            raise ValueError("Device config missing required key: 'type'")
+
+        with _registry_lock:
+            cls.load_extensions()
+            device_cls = DEVICE_REGISTRY.get(device_type)
+            if not device_cls:
+                raise ValueError(f"Unknown device type '{device_type}'. Available: {list(DEVICE_REGISTRY.keys())}")
+
+        # Use the device's own config loader
+        device = device_cls.from_config_dict(config)
+        own_device(device)
+        return device
+
+    @classmethod
+    def available_types(cls) -> List[str]:
+        with _registry_lock:
+            cls.load_extensions()
+            return list(DEVICE_REGISTRY.keys())
+