apsbits 1.0.0rc2__py3-none-any.whl

apsbits/demo_instrument/plans/sim_plans.py

@@ -0,0 +1,69 @@
+"""
+Simulators from ophyd
+=====================
+
+For development and testing only, provides plans.
+
+.. autosummary::
+    ~sim_count_plan
+    ~sim_print_plan
+    ~sim_rel_scan_plan
+"""
+
+import logging
+
+from bluesky import plan_stubs as bps
+from bluesky import plans as bp
+
+from apsbits.utils.controls_setup import oregistry
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+DEFAULT_MD = {"title": "test run with simulator(s)"}
+
+
+def sim_count_plan(num: int = 1, imax: float = 10_000, md: dict = DEFAULT_MD):
+    """Demonstrate the ``count()`` plan."""
+    logger.debug("sim_count_plan()")
+    sim_det = oregistry["sim_det"]
+    yield from bps.mv(sim_det.Imax, imax)
+    yield from bp.count([sim_det], num=num, md=md)
+
+
+def sim_print_plan():
+    """Demonstrate a ``print()`` plan stub (no data streams)."""
+    logger.debug("sim_print_plan()")
+    yield from bps.null()
+    sim_det = oregistry["sim_det"]
+    sim_motor = oregistry["sim_motor"]
+    print("sim_print_plan(): This is a test.")
+    print(f"sim_print_plan():  {sim_motor.position=}  {sim_det.read()=}.")
+
+
+def sim_rel_scan_plan(
+    span: float = 5,
+    num: int = 11,
+    imax: float = 10_000,
+    center: float = 0,
+    sigma: float = 1,
+    noise: str = "uniform",  # none poisson uniform
+    md: dict = DEFAULT_MD,
+):
+    """Demonstrate the ``rel_scan()`` plan."""
+    logger.debug("sim_rel_scan_plan()")
+    sim_det = oregistry["sim_det"]
+    sim_motor = oregistry["sim_motor"]
+    # fmt: off
+    yield from bps.mv(
+        sim_det.Imax, imax,
+        sim_det.center, center,
+        sim_det.sigma, sigma,
+        sim_det.noise, noise,
+    )
+    # fmt: on
+    print(f"sim_rel_scan_plan(): {sim_motor.position=}.")
+    print(f"sim_rel_scan_plan(): {sim_det.read()=}.")
+    print(f"sim_rel_scan_plan(): {sim_det.read_configuration()=}.")
+    print(f"sim_rel_scan_plan(): {sim_det.noise._enum_strs=}.")
+    yield from bp.rel_scan([sim_det], sim_motor, -span / 2, span / 2, num=num, md=md)

apsbits/demo_instrument/startup.py

@@ -0,0 +1,63 @@
+"""
+Start Bluesky Data Acquisition sessions of all kinds.
+
+Includes:
+
+* Python script
+* IPython console
+* Jupyter notebook
+* Bluesky queueserver
+"""
+
+import logging
+
+from apsbits.core.best_effort_init import bec  # noqa: F401
+from apsbits.core.best_effort_init import peaks  # noqa: F401
+from apsbits.core.catalog_init import cat  # noqa: F401
+from apsbits.core.run_engine_init import RE  # noqa: F401
+from apsbits.core.run_engine_init import sd  # noqa: F401
+from apsbits.utils.aps_functions import aps_dm_setup
+from apsbits.utils.config_loaders import iconfig
+
+# Bluesky data acquisition setup
+# from apsbits.utils.config_loaders import iconfig
+from apsbits.utils.helper_functions import register_bluesky_magics
+from apsbits.utils.helper_functions import running_in_queueserver
+from apsbits.utils.make_devices_yaml import make_devices  # noqa: F401
+
+# User specific imports
+from .plans import *  # noqa: F403
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+aps_dm_setup(iconfig.get("DM_SETUP_FILE"))
+
+if iconfig.get("USE_BLUESKY_MAGICS", False):
+    register_bluesky_magics()
+
+# Configure the session with callbacks, devices, and plans.
+if iconfig.get("NEXUS_DATA_FILES", {}).get("ENABLE", False):
+    from .callbacks.nexus_data_file_writer import nxwriter  # noqa: F401
+
+if iconfig.get("SPEC_DATA_FILES", {}).get("ENABLE", False):
+    from .callbacks.spec_data_file_writer import newSpecFile  # noqa: F401
+    from .callbacks.spec_data_file_writer import spec_comment  # noqa: F401
+    from .callbacks.spec_data_file_writer import specwriter  # noqa: F401
+
+# These imports must come after the above setup.
+if running_in_queueserver():
+    ### To make all the standard plans available in QS, import by '*', otherwise import
+    ### plan by plan.
+    from apstools.plans import lineup2  # noqa: F401
+    from bluesky.plans import *  # noqa: F403
+
+else:
+    # Import bluesky plans and stubs with prefixes set by common conventions.
+    # The apstools plans and utils are imported by '*'.
+    from apstools.plans import *  # noqa: F403
+    from apstools.utils import *  # noqa: F403
+    from bluesky import plan_stubs as bps  # noqa: F401
+    from bluesky import plans as bp  # noqa: F401
+
+    from apsbits.utils.controls_setup import oregistry  # noqa: F401

apsbits/tests/__init__.py

@@ -0,0 +1 @@
+"""Test code for minimal instrument package."""

apsbits/tests/conftest.py

@@ -0,0 +1,32 @@
+"""
+Pytest fixtures for instrument tests.
+
+This module provides fixtures for initializing the RunEngine with devices,
+allowing tests to operate with device-dependent configurations without relying
+on the production startup logic.
+
+Fixtures:
+    runengine_with_devices: A RunEngine object in a session with devices configured.
+"""
+
+from typing import Any
+
+import pytest
+
+from apsbits.demo_instrument.startup import RE
+from apsbits.demo_instrument.startup import make_devices
+
+
+@pytest.fixture(scope="session")
+def runengine_with_devices() -> Any:
+    """
+    Initialize the RunEngine with devices for testing.
+
+    This fixture calls RE with the `make_devices()` plan stub to mimic
+    the behavior previously performed in the startup module.
+
+    Returns:
+        Any: An instance of the RunEngine with devices configured.
+    """
+    RE(make_devices())
+    return RE

apsbits/tests/test_device_factories.py

@@ -0,0 +1,44 @@
+"""Test the device factories."""
+
+import pytest
+
+from apsbits.utils.sim_creator import motors
+from apsbits.utils.sim_creator import predefined_device
+
+
+@pytest.mark.parametrize(
+    "creator, name, klass",
+    [
+        ["ophyd.sim.motor", None, "SynAxis"],
+        ["ophyd.sim.motor", "sim_motor", "SynAxis"],
+        ["ophyd.sim.noisy_det", None, "SynGauss"],
+        ["ophyd.sim.noisy_det", "sim_det", "SynGauss"],
+    ],
+)
+def test_predefined(creator, name, klass):
+    """import predefined devices"""
+    for device in predefined_device(creator=creator, name=name):
+        assert device is not None
+        assert device.__class__.__name__ == klass
+        if name is not None:
+            assert device.name == name
+
+
+@pytest.mark.parametrize(
+    "kwargs",
+    [
+        {"prefix": "ioc:m", "first": 1, "last": 4, "labels": ["motor"]},
+        {"prefix": "ioc:m", "names": "m", "first": 7, "last": 22, "labels": ["motor"]},
+    ],
+)
+def test_motors(kwargs):
+    """create a block of motors"""
+    count = 0
+    for device in motors(**kwargs):
+        count += 1
+        assert device is not None
+        assert device.__class__.__name__ == "EpicsMotor"
+        if kwargs.get("names") is None:
+            assert device.name.startswith("m")
+            assert isinstance(int(device.name[1:]), int)
+    assert count == (1 + kwargs["last"] - kwargs["first"])

apsbits/tests/test_general.py

@@ -0,0 +1,83 @@
+"""
+Test that instrument can be started.
+
+Here is just enough testing to get a CI workflow started. More are possible.
+"""
+
+import pytest
+
+from apsbits.demo_instrument.plans.sim_plans import sim_count_plan
+from apsbits.demo_instrument.plans.sim_plans import sim_print_plan
+from apsbits.demo_instrument.plans.sim_plans import sim_rel_scan_plan
+from apsbits.demo_instrument.startup import bec
+from apsbits.demo_instrument.startup import cat
+from apsbits.demo_instrument.startup import iconfig
+from apsbits.demo_instrument.startup import peaks
+from apsbits.demo_instrument.startup import running_in_queueserver
+from apsbits.demo_instrument.startup import sd
+from apsbits.demo_instrument.startup import specwriter
+
+
+def test_startup(runengine_with_devices: object) -> None:
+    """
+    Test that standard startup works and the RunEngine has initialized the devices.
+    """
+    # The fixture ensures that runengine_with_devices is initialized.
+    assert runengine_with_devices is not None
+    assert cat is not None
+    assert bec is not None
+    assert peaks is not None
+    assert sd is not None
+    assert iconfig is not None
+    assert specwriter is not None
+
+    if iconfig.get("DATABROKER_CATALOG", "temp") == "temp":
+        assert len(cat) == 0
+    assert not running_in_queueserver()
+
+
+@pytest.mark.parametrize(
+    "plan, n_uids",
+    [
+        [sim_print_plan, 0],
+        [sim_count_plan, 1],
+        [sim_rel_scan_plan, 1],
+    ],
+)
+def test_sim_plans(runengine_with_devices: object, plan: object, n_uids: int) -> None:
+    """
+    Test supplied simulator plans using the RunEngine with devices.
+    """
+    bec.disable_plots()
+    n_runs = len(cat)
+    # Use the fixture-provided run engine to run the plan.
+    uids = runengine_with_devices(plan())
+    assert len(uids) == n_uids
+    assert len(cat) == n_runs + len(uids)
+
+
+def test_iconfig() -> None:
+    """
+    Test the instrument configuration.
+    """
+    version: str = iconfig.get(
+        "ICONFIG_VERSION", "0.0.0"
+    )  # TODO: Will anyone ever have a wrong catalog version?
+    assert version >= "2.0.0"
+
+    cat_name: str = iconfig.get("DATABROKER_CATALOG")
+    assert cat_name is not None
+    assert cat_name == cat.name
+
+    assert "RUN_ENGINE" in iconfig
+    assert "DEFAULT_METADATA" in iconfig["RUN_ENGINE"]
+
+    default_md = iconfig["RUN_ENGINE"]["DEFAULT_METADATA"]
+    assert "beamline_id" in default_md
+    assert "instrument_name" in default_md
+    assert "proposal_id" in default_md
+    assert "databroker_catalog" in default_md
+    assert default_md["databroker_catalog"] == cat.name
+
+    xmode = iconfig.get("XMODE_DEBUG_LEVEL")
+    assert xmode is not None

apsbits/tests/test_stored_dict.py

@@ -0,0 +1,139 @@
+"""
+Test the utils.stored_dict module.
+"""
+
+import pathlib
+import tempfile
+import time
+from contextlib import nullcontext as does_not_raise
+
+import pytest
+
+from apsbits.utils.config_loaders import load_config_yaml
+from apsbits.utils.stored_dict import StoredDict
+
+
+def luftpause(delay=0.05):
+    """A brief wait for content to flush to storage."""
+    time.sleep(max(0, delay))
+
+
+@pytest.fixture
+def md_file():
+    """Provide a temporary file (deleted on close)."""
+    tfile = tempfile.NamedTemporaryFile(
+        prefix="re_md_",
+        suffix=".yml",
+        delete=False,
+    )
+    path = pathlib.Path(tfile.name)
+    yield pathlib.Path(tfile.name)
+
+    if path.exists():
+        path.unlink()  # delete the file
+
+
+def test_StoredDict(md_file):
+    """Test the StoredDict class."""
+    assert md_file.exists()
+    assert len(open(md_file).read().splitlines()) == 0  # empty
+
+    sdict = StoredDict(md_file, delay=0.2, title="unit testing")
+    assert sdict is not None
+    assert len(sdict) == 0
+    assert sdict._delay == 0.2
+    assert sdict._title == "unit testing"
+    assert len(open(md_file).read().splitlines()) == 0  # still empty
+    assert sdict._sync_key == f"sync_agent_{id(sdict):x}"
+    assert not sdict.sync_in_progress
+
+    # Write an empty dictionary.
+    sdict.flush()
+    luftpause()
+    buf = open(md_file).read().splitlines()
+    assert len(buf) == 4, f"{buf=}"
+    assert buf[-1] == "{}"  # The empty dict.
+    assert buf[0].startswith("# ")
+    assert buf[1].startswith("# ")
+    assert "unit testing" in buf[0]
+
+    # Add a new {key: value} pair.
+    assert not sdict.sync_in_progress
+    sdict["a"] = 1
+    assert sdict.sync_in_progress
+    sdict.flush()
+    assert time.time() > sdict._sync_deadline
+    luftpause()
+    assert not sdict.sync_in_progress
+    assert len(open(md_file).read().splitlines()) == 4
+
+    # Change the only value.
+    sdict["a"] = 2
+    sdict.flush()
+    luftpause()
+    assert len(open(md_file).read().splitlines()) == 4  # Still.
+
+    # Add another key.
+    sdict["bee"] = "bumble"
+    sdict.flush()
+    print(f"\n\nthis is the md_file: {md_file}\n\n")
+    luftpause()
+    assert len(open(md_file).read().splitlines()) == 5
+
+    # Test _delayed_sync_to_storage.
+    sdict["bee"] = "queen"
+    md = load_config_yaml(md_file)
+    assert len(md) == 2  # a & bee
+    assert "a" in md
+    assert md["bee"] == "bumble"  # The old value.
+
+    time.sleep(sdict._delay / 2)
+    # Still not written ...
+    assert load_config_yaml(md_file)["bee"] == "bumble"
+
+    time.sleep(sdict._delay)
+    # Should be written by now.
+    assert load_config_yaml(md_file)["bee"] == "queen"
+
+    del sdict["bee"]  # __delitem__
+    assert "bee" not in sdict  # __getitem__
+
+
+@pytest.mark.parametrize(
+    "md, xcept, text",
+    [
+        [{"a": 1}, None, str(None)],  # int value is ok
+        [{"a": 2.2}, None, str(None)],  # float value is ok
+        [{"a": "3"}, None, str(None)],  # str value is ok
+        [{"a": [4, 5, 6]}, None, str(None)],  # list value is ok
+        [{"a": {"bb": [4, 5, 6]}}, None, str(None)],  # nested value is ok
+        [{1: 1}, None, str(None)],  # int key is ok
+        [{"a": object()}, TypeError, "not JSON serializable"],
+        [{object(): 1}, TypeError, "keys must be str, int, float, "],
+        [{"a": [4, object(), 6]}, TypeError, "not JSON serializable"],
+        [{"a": {object(): [4, 5, 6]}}, TypeError, "keys must be str, int, "],
+    ],
+)
+def test_set_exceptions(md, xcept, text, md_file):
+    """Cases that might raise an exception."""
+    sdict = StoredDict(md_file, delay=0.2, title="unit testing")
+    context = does_not_raise() if xcept is None else pytest.raises(xcept)
+    with context as reason:
+        sdict.update(md)
+    assert text in str(reason), f"{reason=}"
+
+
+def test_popitem(md_file):
+    """Can't popitem from empty dict."""
+    sdict = StoredDict(md_file, delay=0.2, title="unit testing")
+    with pytest.raises(KeyError) as reason:
+        sdict.popitem()
+    assert "dictionary is empty" in str(reason), f"{reason=}"
+
+
+def test_repr(md_file):
+    """__repr__"""
+    sdict = StoredDict(md_file, delay=0.1, title="unit testing")
+    sdict["a"] = 1
+    assert repr(sdict) == "<StoredDict {'a': 1}>"
+    assert str(sdict) == "<StoredDict {'a': 1}>"

apsbits/utils/__init__.py

@@ -0,0 +1 @@
+"""Local utilties and miscellaneous code."""

apsbits/utils/aps_functions.py

@@ -0,0 +1,67 @@
+"""
+APS utility helper functions
+============================
+
+.. autosummary::
+    ~host_on_aps_subnet
+    ~aps_dm_setup
+"""
+
+import logging
+import os
+import pathlib
+import socket
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+
+def aps_dm_setup(dm_setup_file_path):
+    """
+    APS Data Management setup
+    =========================
+
+    Read the bash shell script file used by DM to setup the environment. Parse any
+    ``export`` lines and add their environment variables to this session.  This is
+    done by brute force here since the APS DM environment setup requires different
+    Python code than bluesky and the two often clash.
+
+    This setup must be done before any of the DM package libraries are called.
+
+    """
+    if dm_setup_file_path is not None:
+        bash_script = pathlib.Path(dm_setup_file_path)
+        if bash_script.exists():
+            logger.info("APS DM environment file: %s", str(bash_script))
+            # parse environment variables from bash script
+            environment = {}
+            for line in open(bash_script).readlines():
+                if not line.startswith("export "):
+                    continue
+                k, v = line.strip().split()[-1].split("=")
+                environment[k] = v
+            os.environ.update(environment)
+
+            workflow_owner = os.environ["DM_STATION_NAME"].lower()
+            logger.info("APS DM workflow owner: %s", workflow_owner)
+        else:
+            logger.warning("APS DM setup file does not exist: '%s'", bash_script)
+
+
+def host_on_aps_subnet():
+    """Detect if this host is on an APS subnet."""
+    LOOPBACK_IP4 = "127.0.0.1"
+    PUBLIC_IP4_PREFIX = "164.54."
+    PRIVATE_IP4_PREFIX = "10.54."
+    TEST_IP = "10.254.254.254"  # does not have to be reachable
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+        sock.settimeout(0)
+        try:
+            sock.connect((TEST_IP, 1))
+            ip4 = sock.getsockname()[0]
+        except Exception:
+            ip4 = LOOPBACK_IP4
+    return True in [
+        ip4.startswith(PUBLIC_IP4_PREFIX),
+        ip4.startswith(PRIVATE_IP4_PREFIX),
+    ]

apsbits/utils/config_loaders.py

@@ -0,0 +1,61 @@
+"""
+Load configuration files
+========================
+
+Load supported configuration files, such as ``iconfig.yml``.
+
+.. autosummary::
+    ~load_config_yaml
+    ~IConfigFileVersionError
+"""
+
+import logging
+import pathlib
+
+import yaml
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+instrument_path = pathlib.Path(__file__).parent.parent
+DEFAULT_ICONFIG_YML_FILE = (
+    instrument_path / "demo_instrument" / "configs" / "iconfig.yml"
+)
+ICONFIG_MINIMUM_VERSION = "2.0.0"
+
+
+def load_config_yaml(iconfig_yml=None) -> dict:
+    """
+    Load iconfig.yml (and other YAML) configuration files.
+
+    Parameters
+    ----------
+    iconfig_yml: str
+        Name of the YAML file to be loaded.  The name can be
+        absolute or relative to the current working directory.
+        Default: ``INSTRUMENT/demo_instrument/configs/iconfig.yml``
+    """
+
+    if iconfig_yml is None:
+        path = DEFAULT_ICONFIG_YML_FILE
+    else:
+        path = pathlib.Path(iconfig_yml)
+    if not path.exists():
+        raise FileExistsError(f"Configuration file '{path}' does not exist.")
+    config = yaml.load(open(path, "r").read(), yaml.Loader)
+    return config
+
+
+# class IConfigFileVersionError(ValueError):
+#     """Configuration file version too old."""
+
+
+# # Validate the iconfig file has the minimum version.
+# _version = iconfig.get("ICONFIG_VERSION")
+# print(f"\n\n\niconfig version: {_version}\n\n\n")
+# if _version is None or _version < ICONFIG_MINIMUM_VERSION:
+#     raise IConfigFileVersionError(
+#         "Configuration file version too old."
+#         f" Found {_version!r}."
+#         f" Expected minimum {ICONFIG_MINIMUM_VERSION!r}."
+#         f" Configuration file '{DEFAULT_ICONFIG_YML_FILE}'."
+#     )