apsbits 1.0.0rc2__py3-none-any.whl

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 .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())

apsbits/utils/make_devices_yaml.py

@@ -0,0 +1,127 @@
+"""
+Make devices from YAML files
+=============================
+
+Construct ophyd-style devices from simple specifications in YAML files.
+
+.. autosummary::
+    :nosignatures:
+
+    ~make_devices
+    ~Instrument
+"""
+
+import logging
+import pathlib
+import sys
+import time
+
+import guarneri
+from apstools.plans import run_blocking_function
+from apstools.utils import dynamic_import
+from bluesky import plan_stubs as bps
+
+from apsbits.utils.aps_functions import host_on_aps_subnet
+from apsbits.utils.config_loaders import load_config_yaml
+from apsbits.utils.context_aware import iconfig
+from apsbits.utils.context_aware import resolve_path
+from apsbits.utils.controls_setup import oregistry  # noqa: F401
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+# Get the main module (same as before)
+main_namespace = sys.modules["__main__"]
+
+# Resolve device files directly using resolve_path
+local_control_devices_file = resolve_path(iconfig["DEVICES_FILE"])
+aps_control_devices_file = resolve_path(iconfig["APS_DEVICES_FILE"])
+
+
+def make_devices(*, pause: float = 1):
+    """
+    (plan stub) Create the ophyd-style controls for this instrument.
+
+    Feel free to modify this plan to suit the needs of your instrument.
+
+    EXAMPLE::
+
+        RE(make_devices())
+
+    PARAMETERS
+
+    pause : float
+        Wait 'pause' seconds (default: 1) for slow objects to connect.
+
+    """
+    logger.debug("(Re)Loading local control objects.")
+    yield from run_blocking_function(_loader, local_control_devices_file, main=True)
+
+    if host_on_aps_subnet():
+        yield from run_blocking_function(_loader, aps_control_devices_file, main=True)
+
+    if pause > 0:
+        logger.debug(
+            "Waiting %s seconds for slow objects to connect.",
+            pause,
+        )
+        yield from bps.sleep(pause)
+
+    # Configure any of the controls here, or in plan stubs
+
+
+def _loader(yaml_device_file, main=True):
+    """
+    Load our ophyd-style controls as described in a YAML file.
+
+    PARAMETERS
+
+    yaml_device_file : str or pathlib.Path
+        YAML file describing ophyd-style controls to be created.
+    main : bool
+        If ``True`` add these devices to the ``__main__`` namespace.
+
+    """
+    logger.debug("Devices file %r.", str(yaml_device_file))
+    t0 = time.time()
+    _instr.load(yaml_device_file)
+    logger.debug("Devices loaded in %.3f s.", time.time() - t0)
+
+    if main:
+        for label in oregistry.device_names:
+            # add to __main__ namespace
+            setattr(main_namespace, label, oregistry[label])
+
+
+class Instrument(guarneri.Instrument):
+    """Custom YAML loader for guarneri."""
+
+    def parse_yaml_file(self, config_file: pathlib.Path | str) -> list[dict]:
+        """Read device configurations from YAML format file."""
+        if isinstance(config_file, str):
+            config_file = pathlib.Path(config_file)
+
+        def parser(creator, specs):
+            if creator not in self.device_classes:
+                self.device_classes[creator] = dynamic_import(creator)
+            entries = [
+                {
+                    "device_class": creator,
+                    "args": (),  # ALL specs are kwargs!
+                    "kwargs": table,
+                }
+                for table in specs
+            ]
+            return entries
+
+        devices = [
+            device
+            # parse the file
+            for k, v in load_config_yaml(config_file).items()
+            # each support type (class, factory, function, ...)
+            for device in parser(k, v)
+        ]
+        return devices
+
+
+_instr = Instrument({}, registry=oregistry)  # singleton

apsbits/utils/metadata.py

@@ -0,0 +1,101 @@
+"""
+RunEngine Metadata
+==================
+
+.. autosummary::
+    ~MD_PATH
+    ~get_md_path
+    ~re_metadata
+"""
+
+import getpass
+import logging
+import os
+import pathlib
+import socket
+import sys
+
+import apstools
+import bluesky
+import databroker
+import epics
+import h5py
+import intake
+import matplotlib
+import numpy
+import ophyd
+import pyRestTable
+import pysumreg
+import spec2nexus
+
+import apsbits
+from apsbits.utils.config_loaders import iconfig
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+re_config = iconfig.get("RUN_ENGINE", {})
+
+DEFAULT_MD_PATH = pathlib.Path.home() / ".config" / "Bluesky_RunEngine_md"
+HOSTNAME = socket.gethostname() or "localhost"
+USERNAME = getpass.getuser() or "Bluesky user"
+VERSIONS = dict(
+    apstools=apstools.__version__,
+    bluesky=bluesky.__version__,
+    databroker=databroker.__version__,
+    epics=epics.__version__,
+    h5py=h5py.__version__,
+    intake=intake.__version__,
+    matplotlib=matplotlib.__version__,
+    numpy=numpy.__version__,
+    ophyd=ophyd.__version__,
+    pyRestTable=pyRestTable.__version__,
+    python=sys.version.split(" ")[0],
+    pysumreg=pysumreg.__version__,
+    spec2nexus=spec2nexus.__version__,
+    apsbits=apsbits.__version__,
+)
+RE_CONFIG = iconfig.get("RUN_ENGINE", {})
+
+
+def get_md_path():
+    """
+    Get path for RE metadata.
+
+    ==============  ==============================================
+    support         path
+    ==============  ==============================================
+    PersistentDict  Directory where dictionary keys are stored in separate files.
+    StoredDict      File where dictionary is stored as YAML.
+    ==============  ==============================================
+
+    In either case, the 'path' can be relative or absolute.  Relative
+    paths are with respect to the present working directory when the
+    bluesky session is started.
+    """
+    md_path_name = RE_CONFIG.get("MD_PATH", DEFAULT_MD_PATH)
+    path = pathlib.Path(md_path_name)
+    logger.info("RunEngine metadata saved in directory: %s", str(path))
+    return str(path)
+
+
+def re_metadata(cat=None):
+    """Programmatic metadata for the RunEngine."""
+    md = {
+        "login_id": f"{USERNAME}@{HOSTNAME}",
+        "versions": VERSIONS,
+        "pid": os.getpid(),
+        "iconfig": iconfig,
+    }
+    if cat is not None:
+        md["databroker_catalog"] = cat.name
+    md.update(RE_CONFIG.get("DEFAULT_METADATA", {}))
+
+    conda_prefix = os.environ.get("CONDA_PREFIX")
+    if conda_prefix is not None:
+        md["conda_prefix"] = conda_prefix
+    return md
+
+
+MD_PATH = get_md_path()
+"""Storage path to save RE metadata between sessions."""

apsbits/utils/sim_creator.py

@@ -0,0 +1,199 @@
+"""
+Device factories
+================
+
+Device factories are used to:
+
+* *Create* several similar ophyd-style devices (such as ``ophyd.Device``
+  or ``ophyd.Signal``) that fit a pattern.
+
+* *Import* a device which is pre-defined in a module, such as the
+  ophyd simulators in ``ophyd.sim``.
+
+.. autosummary::
+
+    ~factory_base
+    ~motors
+    ~predefined_device
+"""
+
+import logging
+
+from apstools.utils import dynamic_import
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+def predefined_device(*, name="", creator=""):
+    """
+    Provide a predefined device such as from the 'ophyd.sim' module.
+
+    PARAMETERS
+
+    creator : str
+        Name of the predefined device to be used
+    name : str
+        Simulator will be assigned this name.  (default: use existing name)
+
+    Example entry in `devices.yml` file:
+
+    .. code-block:: yaml
+        :linenos:
+
+        instrument.devices.factories.predefined_device:
+          - {creator: ophyd.sim.motor, name: sim_motor}
+          - {creator: ophyd.sim.noisy_det, name: sim_det}
+    """
+    if creator == "":
+        raise ValueError("Must provide a value for 'creator'.")
+    device = dynamic_import(creator)
+    if name != "":
+        device.name = name
+    logger.debug(device)
+    yield device
+
+
+def factory_base(
+    *,
+    prefix=None,
+    names="object{}",
+    first=0,
+    last=0,
+    creator="ophyd.Signal",
+    **kwargs,
+):
+    """
+    Make one or more objects using  'creator'.
+
+    PARAMETERS
+
+    prefix : str
+        Prefix *pattern* for the EPICS PVs (default: ``None``).
+
+    names : str
+        Name *pattern* for the objects.  The default pattern is ``"object{}"`` which
+        produces devices named ``object1, object2, ..., ```.  If a formatting
+        specification (``{}``) is not provided, it is appended.  Each object
+        will be named using this code: ``names.format(number)``, such as::
+
+            In [23]: "object{}".format(22)
+            Out[23]: 'object22'
+
+    first : int
+        The first object number in the continuous series from 'first' through
+        'last' (inclusive).
+
+    last : int
+        The first object number in the continuous series from 'first' through
+        'last' (inclusive).
+
+    creator : str
+        Name of the *creator* code that will be used to construct each device.
+        (default: ``"ophyd.Signal"``)
+
+    kwargs : dict
+        Dictionary of additional keyword arguments.  This is included
+        when creating each object.
+    """
+    if "{" not in names:
+        names += "{}"
+    if prefix is not None and "{" not in prefix:
+        prefix += "{}"
+
+    klass = dynamic_import(creator)
+
+    first, last = sorted([first, last])
+    for i in range(first, 1 + last):
+        keywords = {"name": names.format(i)}
+        if prefix is not None:
+            keywords["prefix"] = prefix.format(i)
+        keywords.update(kwargs)
+        device = klass(**keywords)
+        logger.debug(device)
+        yield device
+
+
+def motors(
+    *,
+    prefix=None,
+    names="m{}",
+    first=0,
+    last=0,
+    **kwargs,
+):
+    """
+    Make one or more '``ophyd.EpicsMotor``' objects.
+
+    Example entry in `devices.yml` file:
+
+    .. code-block:: yaml
+        :linenos:
+
+        instrument.devices.factories.motors:
+          - {prefix: "ioc:m", first: 1, last: 4, labels: ["motor"]}
+          # skip m5 & m6
+          - {prefix: "ioc:m", first: 7, last: 22, labels: ["motor"]}
+
+    Uses this pattern:
+
+    .. code-block:: py
+        :linenos:
+
+        ophyd.EpicsMotor(
+                prefix=prefix.format(i),
+                name=names.format(i),
+                **kwargs,
+            )
+
+    where ``i`` iterates from 'first' through 'last' (inclusive).
+
+    PARAMETERS
+
+    prefix : str
+        Name *pattern* for the EPICS PVs.  There is no default pattern. If a
+        formatting specification (``{}``) is not  provided, it is appended (as
+        with other ophyd devices).  Each motor will be configured with this
+        prefix: ``prefix.format(number)``, such as::
+
+            In [23]: "ioc:m{}".format(22)
+            Out[23]: 'ioc:m22'
+
+    names : str
+        Name *pattern* for the motors.  The default pattern is ``"m{}"`` which
+        produces motors named ``m1, m2, ..., m22, m23, ...```.  If a formatting
+        specification (``{}``) is not provided, it is appended.  Each motor
+        will be named using this code: ``names.format(number)``, such as::
+
+            In [23]: "m{}".format(22)
+            Out[23]: 'm22'
+
+    first : int
+        The first motor number in the continuous series from 'first' through
+        'last' (inclusive).
+
+    last : int
+        The first motor number in the continuous series from 'first' through
+        'last' (inclusive).
+
+    kwargs : dict
+        Dictionary of additional keyword arguments.  This is included
+        with each EpicsMotor object.
+    """
+    if prefix is None:
+        raise ValueError("Must define a string value for 'prefix'.")
+
+    kwargs["names"] = names or "m{}"
+    kwargs["prefix"] = prefix
+    kwargs.update(
+        {
+            "prefix": prefix,
+            "names": names or "m{}",
+            "first": first,
+            "last": last,
+            "creator": "ophyd.EpicsMotor",
+        }
+    )
+
+    for motor in factory_base(**kwargs):
+        yield motor