apsbits 1.0.0__py3-none-any.whl

apsbits/utils/controls_setup.py

@@ -0,0 +1,107 @@
+"""
+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
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+DEFAULT_CONTROL_LAYER = "PyEpics"
+DEFAULT_TIMEOUT = 60  # default used next...
+
+
+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, scan_id_pv: str = None):
+    """
+    Define a PV to use for the RunEngine's `scan_id`.
+    """
+    from ophyd import EpicsSignal
+
+    pv = pv or 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.
+    """
+
+    ophyd.set_cl(control_layer.lower())
+
+    logger.info("using ophyd control layer: %r", ophyd.cl.name)
+
+
+def set_timeouts(timeouts):
+    """Set default timeout for all EpicsSignal connections & communications."""
+    if not EpicsSignalBase._EpicsSignalBase__any_instantiated:
+        # Only BEFORE any EpicsSignalBase (or subclass) are created!
+        EpicsSignalBase.set_defaults(
+            auto_monitor=True,
+            timeout=timeouts.get("PV_READ", DEFAULT_TIMEOUT),
+            write_timeout=timeouts.get("PV_WRITE", DEFAULT_TIMEOUT),
+            connection_timeout=timeouts.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,129 @@
+#!/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 os
+import re
+import shutil
+import sys
+from pathlib import Path
+
+
+def copy_instrument(destination_dir: Path) -> None:
+    """
+    Copy template directory to the destination.
+
+    :param template_dir: Path to the template directory.
+    :param destination_dir: Path to the new instrument directory.
+    :return: None
+    """
+
+    demo_template_path: Path = (
+        Path(__file__).resolve().parent.parent / "demo_instrument"
+    ).resolve()
+
+    shutil.copytree(str(demo_template_path), str(destination_dir))
+
+
+def create_qserver(qserver_dir: Path, name: str) -> None:
+    """
+    Create a qserver config file in the destination directory.
+    """
+
+    demo_qserver_path: Path = (
+        Path(__file__).resolve().parent.parent / "demo_qserver"
+    ).resolve()
+
+    os.makedirs(qserver_dir, exist_ok=True)
+    # Copy all yml files from demo_qserver to destination qserver dir
+    for yml_file in demo_qserver_path.glob("*"):
+        shutil.copy2(yml_file, qserver_dir)
+
+    # Update startup module in qs-config.yml
+    qs_config_path = qserver_dir / "qs-config.yml"
+
+    with open(qs_config_path, "r") as f:
+        config_contents = f.read()
+    # Replace demo_instrument with new name in startup module path
+    updated_contents = config_contents.replace(
+        "startup_module: demo_instrument.startup", f"startup_module: {name}.startup"
+    )
+
+    with open(qs_config_path, "w") as f:
+        f.write(updated_contents)
+
+    new_script_path = qserver_dir / "qs_host.sh"
+
+    # Read script contents
+    with open(new_script_path, "r") as src:
+        script_contents = src.read()
+
+    # Replace demo package name with new instrument name
+    updated_contents = script_contents.replace("demo_instrument", name)
+
+    # Write updated script
+    with open(new_script_path, "w") as dest:
+        dest.write(updated_contents)
+
+    # Make script executable
+    os.chmod(new_script_path, new_script_path.stat().st_mode | 0o755)
+
+
+def main() -> None:
+    """
+    Parse arguments and create the instrument.
+
+    :return: None
+    """
+    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."
+    )
+    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)
+
+    main_path: Path = Path(os.getcwd()).resolve()
+
+    new_instrument_dir: Path = main_path / "src" / args.name
+
+    new_qserver_dir: Path = main_path / "src" / f"{args.name}_qserver"
+
+    print(
+        f"Creating instrument '{args.name}' from demo_instrument into \
+        '{new_instrument_dir}'."
+    )
+
+    if new_instrument_dir.exists():
+        print(f"Error: Destination '{new_instrument_dir}' exists.", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        copy_instrument(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)
+
+    try:
+        create_qserver(new_qserver_dir, args.name)
+        print(f"Qserver config created in '{new_qserver_dir}'.")
+    except Exception as exc:
+        print(f"Error creating qserver config: {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,123 @@
+"""
+Generic utility helper functions
+================================
+
+.. autosummary::
+    ~register_bluesky_magics
+    ~running_in_queueserver
+    ~debug_python
+    ~mpl_setup
+    ~is_notebook
+"""
+
+import logging
+import os
+
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+from bluesky.magics import BlueskyMagics
+from IPython import get_ipython
+
+from apsbits.utils.config_loaders import get_config
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+def register_bluesky_magics() -> None:
+    """Register Bluesky IPython magics."""
+    try:
+        ip = get_ipython()
+        if ip is not None:
+            ip.register_magics(BlueskyMagics)
+            logger.info("Registered Bluesky IPython magics")
+    except Exception as e:
+        logger.warning("Could not register Bluesky IPython magics: %s", e)
+
+
+def running_in_queueserver() -> bool:
+    """
+    Check if we are running in a Bluesky queueserver.
+
+    Returns:
+        True if running in a queueserver, False otherwise.
+    """
+    return os.environ.get("QSERVER_URI") is not None
+
+
+def get_xmode_level() -> str:
+    """
+    Get the current XMode debug level.
+
+    Returns:
+        The current XMode debug level.
+    """
+    iconfig = get_config()
+    xmode_level: str = iconfig.get("XMODE_DEBUG_LEVEL", "Plain")
+    return xmode_level
+
+
+def debug_python(xmode_level: str = "Plain") -> None:
+    """
+    Enable detailed debugging for Python exceptions in the IPython environment.
+
+    This function adjusts the xmode settings for exception tracebacks based on
+    the provided xmode_level argument.
+
+    Args:
+        xmode_level (str): The level of detail for exception tracebacks.
+                           Defaults to "Minimal".
+    """
+    ipython = get_ipython()
+    if ipython is not None:
+        xmode_level: str = get_xmode_level()
+        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")

apsbits/utils/logging_setup.py

@@ -0,0 +1,211 @@
+"""
+Configure logging for this session.
+
+.. rubric:: Public
+.. autosummary::
+    ~configure_logging
+
+.. rubric:: Internal
+.. autosummary::
+    ~_setup_console_logger
+    ~_setup_file_logger
+    ~_setup_ipython_logger
+    ~_setup_module_logging
+
+.. seealso:: https://blueskyproject.io/bluesky/main/debugging.html
+"""
+
+import logging
+import logging.handlers
+import os
+import pathlib
+
+BYTE = 1
+kB = 1024 * BYTE
+MB = 1024 * kB
+
+BRIEF_DATE = "%a-%H:%M:%S"
+BRIEF_FORMAT = "%(levelname)-.1s %(asctime)s.%(msecs)03d: %(message)s"
+DEFAULT_CONFIG_FILE = (
+    pathlib.Path(__file__).parent.parent / "demo_instrument" / "configs" / "logging.yml"
+)
+
+
+# Add your custom logging level at the top-level, before configure_logging()
+def addLoggingLevel(levelName, levelNum, methodName=None):
+    """
+    Comprehensively adds a new logging level to the `logging` module and the
+    currently configured logging class.
+
+    `levelName` becomes an attribute of the `logging` module with the value
+    `levelNum`. `methodName` becomes a convenience method for both `logging`
+    itself and the class returned by `logging.getLoggerClass()` (usually just
+    `logging.Logger`). If `methodName` is not specified, `levelName.lower()` is
+    used.
+
+    To avoid accidental clobberings of existing attributes, this method will
+    raise an `AttributeError` if the level name is already an attribute of the
+    `logging` module or if the method name is already present
+
+    Example
+    -------
+    >>> addLoggingLevel('TRACE', logging.INFO - 5)
+    >>> logging.getLogger(__name__).setLevel("TEST")
+    >>> logging.getLogger(__name__).test('that worked')
+    >>> logging.test('so did this')
+    >>> logging.TEST
+    5
+
+    """
+    if not methodName:
+        methodName = levelName.lower()
+
+    if hasattr(logging, levelName):
+        raise AttributeError("{} already defined in logging module".format(levelName))
+    if hasattr(logging, methodName):
+        raise AttributeError("{} already defined in logging module".format(methodName))
+    if hasattr(logging.getLoggerClass(), methodName):
+        raise AttributeError("{} already defined in logger class".format(methodName))
+
+    # This method was inspired by the answers to Stack Overflow post
+    # http://stackoverflow.com/q/2183233/2988730, especially
+    # http://stackoverflow.com/a/13638084/2988730
+    def logForLevel(self, message, *args, **kwargs):
+        if self.isEnabledFor(levelNum):
+            self._log(levelNum, message, args, **kwargs)
+
+    def logToRoot(message, *args, **kwargs):
+        logging.log(levelNum, message, *args, **kwargs)
+
+    logging.addLevelName(levelNum, levelName)
+    setattr(logging, levelName, levelNum)
+    setattr(logging.getLoggerClass(), methodName, logForLevel)
+    setattr(logging, methodName, logToRoot)
+
+
+addLoggingLevel("BSDEV", logging.INFO - 5)
+
+
+def configure_logging():
+    """Configure logging as described in file."""
+    from apsbits.utils.config_loaders import load_config_yaml
+
+    # (Re)configure the root logger.
+    logger = logging.getLogger(__name__).root
+    logger.debug("logger=%r", logger)
+
+    config_file = os.environ.get("BLUESKY_INSTRUMENT_CONFIG_FILE")
+    if config_file is None:
+        config_file = DEFAULT_CONFIG_FILE
+    else:
+        config_file = pathlib.Path(config_file)
+
+    logging_configuration = load_config_yaml(config_file)
+    for part, cfg in logging_configuration.items():
+        logging.debug("%r - %s", part, cfg)
+
+        if part == "console_logs":
+            _setup_console_logger(logger, cfg)
+
+        elif part == "file_logs":
+            _setup_file_logger(logger, cfg)
+
+        elif part == "ipython_logs":
+            _setup_ipython_logger(logger, cfg)
+
+        elif part == "modules":
+            _setup_module_logging(cfg)
+
+
+def _setup_console_logger(logger, cfg):
+    """
+    Reconfigure the root logger as configured by the user.
+
+    We can't apply user configurations in ``configure_logging()`` above
+    because the code to read the config file triggers initialization of
+    the logging system.
+
+    .. seealso:: https://docs.python.org/3/library/logging.html#logging.basicConfig
+    """
+    logging.basicConfig(
+        encoding="utf-8",
+        level=cfg["root_level"].upper(),
+        format=cfg["log_format"],
+        datefmt=cfg["date_format"],
+        force=True,  # replace any previous setup
+    )
+    h = logger.handlers[0]
+    h.setLevel(cfg["level"].upper())
+
+
+def _setup_file_logger(logger, cfg):
+    """Record log messages in file(s)."""
+    formatter = logging.Formatter(
+        fmt=cfg["log_format"],
+        datefmt=cfg["date_format"],
+        style="%",
+        validate=True,
+    )
+    formatter.default_msec_format = "%s.%03d"
+
+    backupCount = cfg.get("backupCount", 9)
+    maxBytes = cfg.get("maxBytes", 1 * MB)
+    log_path = pathlib.Path(cfg.get("log_directory", ".logs")).resolve()
+    if not log_path.exists():
+        os.makedirs(str(log_path))
+
+    file_name = log_path / cfg.get("log_filename_base", "logging.log")
+    if maxBytes > 0 or backupCount > 0:
+        backupCount = max(backupCount, 1)  # impose minimum standards
+        maxBytes = max(maxBytes, 100 * kB)
+        handler = logging.handlers.RotatingFileHandler(
+            file_name,
+            maxBytes=maxBytes,
+            backupCount=backupCount,
+        )
+    else:
+        handler = logging.FileHandler(file_name)
+    handler.setFormatter(formatter)
+    if cfg.get("rotate_on_startup", False):
+        handler.doRollover()
+    logger.addHandler(handler)
+    logger.info("%s Bluesky Startup Initialized", "*" * 40)
+    logger.bsdev(__file__)
+    logger.bsdev("Log file: %s", file_name)
+
+
+def _setup_ipython_logger(logger, cfg):
+    """
+    Internal: Log IPython console session In and Out to a file.
+
+    See ``logrotate?`` int he IPython console for more information.
+    """
+    log_path = pathlib.Path(cfg.get("log_directory", ".logs")).resolve()
+    try:
+        from IPython import get_ipython
+
+        # start logging console to file
+        # https://ipython.org/ipython-doc/3/interactive/magics.html#magic-logstart
+        _ipython = get_ipython()
+        log_file = log_path / cfg.get("log_filename_base", "ipython_log.py")
+        log_mode = cfg.get("log_mode", "rotate")
+        options = cfg.get("options", "-o -t")
+        if _ipython is not None:
+            print(
+                "\nBelow are the IPython logging settings for your session."
+                "\nThese settings have no impact on your experiment.\n"
+            )
+            _ipython.run_line_magic("logstart", f"{options} {log_file} {log_mode}")
+            if logger is not None:
+                logger.bsdev("Console logging: %s", log_file)
+    except Exception as exc:
+        if logger is None:
+            print(f"Could not setup console logging: {exc}")
+        else:
+            logger.exception("Could not setup console logging.")
+
+
+def _setup_module_logging(cfg):
+    """Internal: Set logging level for each named module."""
+    for module, level in cfg.items():
+        logging.getLogger(module).setLevel(level.upper())