apsbits 1.0.0rc2__py3-none-any.whl

apsbits/utils/context_aware.py

@@ -0,0 +1,187 @@
+"""
+Minimalist configuration system following the 'configs convention'.
+
+Core principle: Configuration always lives in the 'configs' subdirectory
+of wherever startup.py is located.
+"""
+
+import inspect
+import pathlib
+from functools import lru_cache
+from typing import Any
+from typing import Dict
+from typing import Optional
+
+import yaml
+
+
+class ConfigError(Exception):
+    """Base exception for configuration errors."""
+
+    pass
+
+
+class StartupConfig:
+    """Configuration provider following the configs-subdirectory convention."""
+
+    CONFIG_FILENAMES = [
+        "iconfig.yml",
+        "config.yml",
+        "iconfig.yaml",
+        "config.yaml",
+        "config.toml",
+        "ifconfig.toml",
+    ]
+
+    def __init__(self):
+        """Initialize the configuration."""
+        self._config = None
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a configuration value with an optional default."""
+        return self.config.get(key, default)
+
+    def __getitem__(self, key: str) -> Any:
+        """Dictionary-style access to configuration."""
+        try:
+            return self.config[key]
+        except KeyError:
+            raise KeyError(f"Missing required config key: '{key}'") from None
+
+    def __contains__(self, key: str) -> bool:
+        """Support for 'in' operator."""
+        return key in self.config
+
+    def __repr__(self) -> str:
+        """Create a helpful string representation."""
+        startup_name = self.startup_path.parent.name if self.startup_path else "unknown"
+        config_file = self.config_file.name if self.config_file else "none"
+        return f"<Config: {startup_name}/configs/{config_file}>"
+
+    @property
+    def config(self) -> Dict:
+        """Get the configuration dictionary, loading it if necessary."""
+        if self._config is None:
+            self._config = self._load_config()
+        return self._config
+
+    def to_dict(self) -> Dict:
+        """Convert config to a regular dictionary for serialization."""
+        return dict(self.config)
+
+    @property
+    @lru_cache(maxsize=1)  # noqa B019
+    def startup_path(self) -> Optional[pathlib.Path]:
+        """Find the startup.py that's being executed."""
+        # First check main module
+        startup = self._find_startup_in_main()
+        if startup:
+            return startup
+
+        # Then check call stack
+        return self._find_startup_in_stack()
+
+    @property
+    def configs_dir(self) -> Optional[pathlib.Path]:
+        """Get the configs directory path."""
+        if not self.startup_path:
+            return None
+        return self.startup_path.parent / "configs"
+
+    @property
+    @lru_cache(maxsize=1)  # noqa B019
+    def config_file(self) -> Optional[pathlib.Path]:
+        """Find the active config file."""
+        if not self.configs_dir or not self.configs_dir.exists():
+            return None
+
+        # Try each filename in order
+        for filename in self.CONFIG_FILENAMES:
+            path = self.configs_dir / filename
+            if path.exists():
+                return path
+
+        return None
+
+    def resolve_path(self, filename: str) -> Optional[pathlib.Path]:
+        """Resolve a filename relative to the configs directory."""
+        if not self.configs_dir:
+            return None
+        return self.configs_dir / filename
+
+    def _find_startup_in_main(self) -> Optional[pathlib.Path]:
+        """Check if the main module is startup.py."""
+        import sys
+
+        main_module = sys.modules.get("__main__")
+        if main_module and hasattr(main_module, "__file__"):
+            path = pathlib.Path(main_module.__file__).resolve()
+            if path.name == "startup.py":
+                return path
+        return None
+
+    def _find_startup_in_stack(self) -> Optional[pathlib.Path]:
+        """Search the call stack for a startup.py file."""
+        for frame_info in inspect.stack():
+            module = inspect.getmodule(frame_info.frame)
+            if not module or not hasattr(module, "__file__"):
+                continue
+
+            path = pathlib.Path(module.__file__).resolve()
+
+            # Direct match if this is startup.py
+            if path.name == "startup.py":
+                return path
+
+            # Check if there's a startup.py in the same directory
+            startup_path = path.parent / "startup.py"
+            if startup_path.exists():
+                return startup_path
+
+        return None
+
+    def _load_config(self) -> Dict:
+        """Load the configuration file."""
+        if not self.config_file:
+            return {}
+
+        try:
+            with open(self.config_file) as f:
+                return yaml.safe_load(f) or {}
+        except Exception:
+            return {}
+
+
+# Create a single instance
+_config = StartupConfig()
+
+# Public API - Simple and clean
+
+
+def get(key: str, default: Any = None) -> Any:
+    """Get a configuration value with an optional default."""
+    return _config.get(key, default)
+
+
+def get_dict() -> Dict:
+    """Get the entire configuration as a dictionary (for serialization)."""
+    return _config.to_dict()
+
+
+def resolve_path(filename: str) -> pathlib.Path:
+    """Resolve a filename relative to the configs directory."""
+    path = _config.resolve_path(filename)
+    if not path:
+        raise ConfigError(f"Cannot resolve '{filename}': No startup.py found")
+    return path
+
+
+def get_configs_dir() -> pathlib.Path:
+    """Get the path to the configs directory."""
+    if not _config.configs_dir:
+        raise ConfigError("No configs directory found (No startup.py detected)")
+    return _config.configs_dir
+
+
+# For backward compatibility
+iconfig = _config

apsbits/utils/controls_setup.py

@@ -0,0 +1,113 @@
+"""
+EPICS & ophyd related setup
+===========================
+
+.. autosummary::
+    ~oregistry
+    ~set_control_layer
+    ~set_timeouts
+    ~epics_scan_id_source
+    ~connect_scan_id_pv
+"""
+
+import logging
+
+import ophyd
+from ophyd.signal import EpicsSignalBase
+from ophydregistry import Registry
+
+from apsbits.utils.config_loaders import iconfig
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+re_config = iconfig.get("RUN_ENGINE", {})
+
+DEFAULT_CONTROL_LAYER = "PyEpics"
+DEFAULT_TIMEOUT = 60  # default used next...
+ophyd_config = iconfig.get("OPHYD", {})
+
+
+def epics_scan_id_source(_md):
+    """
+    Callback function for RunEngine.  Returns *next* scan_id to be used.
+
+    * Ignore metadata dictionary passed as argument.
+    * Get current scan_id from PV.
+    * Apply lower limit of zero.
+    * Increment (so that scan_id numbering starts from 1).
+    * Set PV with new value.
+    * Return new value.
+
+    Exception will be raised if PV is not connected when next
+    ``bps.open_run()`` is called.
+    """
+    scan_id_epics = oregistry.find(name="scan_id_epics")
+    new_scan_id = max(scan_id_epics.get(), 0) + 1
+    scan_id_epics.put(new_scan_id)
+    return new_scan_id
+
+
+def connect_scan_id_pv(RE, pv: str = None):
+    """
+    Define a PV to use for the RunEngine's `scan_id`.
+    """
+    from ophyd import EpicsSignal
+
+    pv = pv or re_config.get("SCAN_ID_PV")
+    if pv is None:
+        return
+
+    try:
+        scan_id_epics = EpicsSignal(pv, name="scan_id_epics")
+    except TypeError:  # when Sphinx substitutes EpicsSignal with _MockModule
+        return
+    logger.info("Using EPICS PV %r for RunEngine 'scan_id'", pv)
+
+    # Setup the RunEngine to call epics_scan_id_source()
+    # which uses the EPICS PV to provide the scan_id.
+    RE.scan_id_source = epics_scan_id_source
+
+    scan_id_epics.wait_for_connection()
+    try:
+        RE.md["scan_id_pv"] = scan_id_epics.pvname
+        RE.md["scan_id"] = scan_id_epics.get()  # set scan_id from EPICS
+    except TypeError:
+        pass  # Ignore PersistentDict errors that only raise when making the docs
+
+
+def set_control_layer(control_layer: str = DEFAULT_CONTROL_LAYER):
+    """
+    Communications library between ophyd and EPICS Channel Access.
+
+    Choices are: PyEpics (default) or caproto.
+
+    OPHYD_CONTROL_LAYER is an application of "lessons learned."
+
+    Only used in a couple rare cases where PyEpics code was failing.
+    It's defined here since it was difficult to find how to do this
+    in the ophyd documentation.
+    """
+
+    control_layer = ophyd_config.get("CONTROL_LAYER", control_layer)
+    ophyd.set_cl(control_layer.lower())
+
+    logger.info("using ophyd control layer: %r", ophyd.cl.name)
+
+
+def set_timeouts():
+    """Set default timeout for all EpicsSignal connections & communications."""
+    if not EpicsSignalBase._EpicsSignalBase__any_instantiated:
+        # Only BEFORE any EpicsSignalBase (or subclass) are created!
+        timeouts = ophyd_config.get("TIMEOUTS", {})
+        EpicsSignalBase.set_defaults(
+            auto_monitor=True,
+            timeout=timeouts.get("PV_READ", DEFAULT_TIMEOUT),
+            write_timeout=timeouts.get("PV_WRITE", DEFAULT_TIMEOUT),
+            connection_timeout=iconfig.get("PV_CONNECTION", DEFAULT_TIMEOUT),
+        )
+
+
+oregistry = Registry(auto_register=True)
+"""Registry of all ophyd-style Devices and Signals."""
+oregistry.warn_duplicates = False

apsbits/utils/create_new_instrument.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""
+Create a new instrument from a fixed template.
+
+Copies the template directory and updates pyproject.toml and .templatesyncignore.
+"""
+
+__version__ = "1.0.0"
+
+import argparse
+import re
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+try:
+    import toml
+except ImportError:
+    print("Missing 'toml' package. Install with: pip install toml")
+    sys.exit(1)
+
+
+def copy_instrument(template_dir: Path, destination_dir: Path) -> None:
+    """
+    Copy template directory to the destination.
+    """
+    shutil.copytree(str(template_dir), str(destination_dir))
+
+
+def update_pyproject(
+    pyproject_path: Path, instrument_name: str, instrument_path: Path
+) -> None:
+    """
+    Update pyproject.toml with the new instrument.
+
+    Adds the instrument to [tool.instruments] and also to [tool.setuptools.package-dir].
+    """
+    with pyproject_path.open("r", encoding="utf-8") as file:
+        config: dict[str, Any] = toml.load(file)
+
+    config.setdefault("tool", {})
+    # Update instruments section
+    config["tool"].setdefault("instruments", {})
+
+    relative_path: str = str(
+        instrument_path.resolve().relative_to(pyproject_path.parent.resolve())
+    )
+    config["tool"]["instruments"][instrument_name] = {"path": relative_path}
+
+    # Update package-dir section
+    setuptools_config: dict[str, Any] = config["tool"].setdefault("setuptools", {})
+    pkg_dir: dict[str, str] = setuptools_config.setdefault("package-dir", {})
+    pkg_dir[instrument_name] = relative_path
+
+    with pyproject_path.open("w", encoding="utf-8") as file:
+        toml.dump(config, file)
+
+
+def update_templatesyncignore(relative_path: str) -> None:
+    """
+    Append the instrument path to the .templatesyncignore file.
+    """
+    tsync_file: Path = Path(".templatesyncignore").resolve()
+    lines: list[str] = []
+    if tsync_file.exists():
+        lines = tsync_file.read_text(encoding="utf-8").splitlines()
+    if relative_path in lines:
+        return
+    # Append a newline if needed.
+    with tsync_file.open("a", encoding="utf-8") as f:
+        if lines and lines[-1].strip() != "":
+            f.write("\n")
+        f.write(relative_path + "\n")
+
+
+def main() -> None:
+    """
+    Parse args and create the instrument.
+    """
+    parser = argparse.ArgumentParser(
+        description="Create an instrument from a fixed template."
+    )
+    parser.add_argument(
+        "name", type=str, help="New instrument name; must be a valid package name."
+    )
+    parser.add_argument("dest", type=str, help="Destination directory.")
+    args = parser.parse_args()
+
+    if re.fullmatch(r"[a-z][_a-z0-9]*", args.name) is None:
+        print(f"Error: Invalid instrument name '{args.name}'.", file=sys.stderr)
+        sys.exit(1)
+
+    template_path: Path = Path("src/bits/demo_instrument").resolve()
+    destination_parent: Path = Path(args.dest).resolve()
+    new_instrument_dir: Path = destination_parent / args.name
+
+    print(
+        f"Creating instrument '{args.name}' from '{template_path}' into \
+            '{new_instrument_dir}'."
+    )
+
+    if not template_path.exists():
+        print(f"Error: Template '{template_path}' does not exist.", file=sys.stderr)
+        sys.exit(1)
+
+    if new_instrument_dir.exists():
+        print(f"Error: Destination '{new_instrument_dir}' exists.", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        copy_instrument(template_path, new_instrument_dir)
+        print(f"Template copied to '{new_instrument_dir}'.")
+    except Exception as exc:
+        print(f"Error copying instrument: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    pyproject_path: Path = Path("pyproject.toml").resolve()
+    if not pyproject_path.exists():
+        print("Error: pyproject.toml not found.", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        update_pyproject(pyproject_path, args.name, new_instrument_dir)
+        print(f"pyproject.toml updated with '{args.name}'.")
+    except Exception as exc:
+        print(f"Error updating pyproject.toml: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        new_relative_path: str = str(
+            new_instrument_dir.resolve().relative_to(pyproject_path.parent.resolve())
+        )
+        update_templatesyncignore(new_relative_path)
+        print(f".templatesyncignore updated with '{new_relative_path}'.")
+    except Exception as exc:
+        print(f"Error updating .templatesyncignore: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Instrument '{args.name}' created.")
+
+
+if __name__ == "__main__":
+    main()

apsbits/utils/helper_functions.py

@@ -0,0 +1,113 @@
+"""
+Generic utility helper functions
+================================
+
+.. autosummary::
+    ~register_bluesky_magics
+    ~running_in_queueserver
+    ~debug_python
+    ~mpl_setup
+    ~is_notebook
+"""
+
+import logging
+
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+from bluesky.magics import BlueskyMagics
+from bluesky_queueserver import is_re_worker_active
+from IPython import get_ipython
+
+from apsbits.utils.config_loaders import iconfig
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+def register_bluesky_magics() -> None:
+    """
+    Register Bluesky magics if an IPython environment is detected.
+
+    This function registers the BlueskyMagics if get_ipython() returns a valid IPython
+      instance.
+    """
+    ipython = get_ipython()
+    if ipython is not None:
+        ipython.register_magics(BlueskyMagics)
+
+
+def running_in_queueserver() -> bool:
+    """
+    Detect if running in the bluesky queueserver.
+
+    Returns:
+        bool: True if running in the queueserver, False otherwise.
+    """
+    try:
+        active: bool = is_re_worker_active()
+        return active
+    except Exception as cause:
+        print(f"{cause=}")
+        return False
+
+
+def debug_python() -> None:
+    """
+    Enable detailed debugging for Python exceptions in the IPython environment.
+
+    This function adjusts the xmode settings for exception tracebacks based on the
+      configuration.
+    """
+    ipython = get_ipython()
+    if ipython is not None:
+        xmode_level: str = iconfig.get("XMODE_DEBUG_LEVEL", "Minimal")
+        ipython.run_line_magic("xmode", xmode_level)
+        print("\nEnd of IPython settings\n")
+        logger.bsdev("xmode exception level: '%s'", xmode_level)
+
+
+def is_notebook() -> bool:
+    """
+    Detect if the current environment is a Jupyter Notebook.
+
+    Returns:
+        bool: True if running in a notebook (Jupyter notebook or qtconsole),
+        False otherwise.
+    """
+    try:
+        shell: str = get_ipython().__class__.__name__
+        if shell == "ZMQInteractiveShell":
+            return True  # Jupyter notebook or qtconsole
+        elif shell == "TerminalInteractiveShell":
+            return False  # Terminal running IPython
+        else:
+            return False  # Other type
+    except NameError:
+        return False  # Standard Python interpreter
+
+
+def mpl_setup() -> None:
+    """
+    Configure the Matplotlib backend based on the current environment.
+
+    For non-queueserver and non-notebook environments, attempts to use the 'qtAgg'
+      backend.
+    If 'qtAgg' is not available due to missing dependencies, falls back to the 'Agg'
+      backend.
+
+    Returns:
+        None
+    """
+    if not running_in_queueserver():
+        if not is_notebook():
+            try:
+                mpl.use("qtAgg")
+                plt.ion()
+                logger.bsdev("Using qtAgg backend for matplotlib.")
+            except Exception as exc:
+                logger.error(
+                    "qtAgg backend is not available, falling back to Agg backend. \
+                    Error: %s",
+                    exc,
+                )
+                mpl.use("Agg")