apsbits 1.0.0__py3-none-any.whl

apsbits/tests/test_config.py

@@ -0,0 +1,113 @@
+"""
+Test the configuration management module.
+"""
+
+import pathlib
+import tempfile
+from typing import TYPE_CHECKING
+
+import pytest
+import tomli_w
+import yaml
+
+from apsbits.utils.config_loaders import load_config
+
+if TYPE_CHECKING:
+    pass
+
+
+@pytest.fixture
+def yml_config_file():
+    """Create a temporary YAML configuration file."""
+    config = {
+        "ICONFIG_VERSION": "2.0.0",
+        "DATABROKER_CATALOG": "temp",
+        "test_key": "test_value",
+    }
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yml", delete=False) as f:
+        yaml.dump(config, f)
+        path = pathlib.Path(f.name)
+
+    yield path
+    path.unlink()
+
+
+@pytest.fixture
+def toml_config_file():
+    """Create a temporary TOML configuration file."""
+    config = {
+        "ICONFIG_VERSION": "2.0.0",
+        "DATABROKER_CATALOG": "temp",
+        "test_key": "test_value",
+    }
+
+    with tempfile.NamedTemporaryFile(mode="wb", suffix=".toml", delete=False) as f:
+        f.write(tomli_w.dumps(config).encode("utf-8"))
+        path = pathlib.Path(f.name)
+
+    yield path
+    path.unlink()
+
+
+def test_load_yaml_config(yml_config_file: pathlib.Path) -> None:
+    """
+    Test loading configuration from a YAML file.
+
+    Args:
+        yml_config_file: Path to the temporary YAML configuration file.
+    """
+    config = load_config(yml_config_file)
+    assert config["ICONFIG_VERSION"] == "2.0.0"
+    assert config["DATABROKER_CATALOG"] == "temp"
+    assert config["test_key"] == "test_value"
+
+
+def test_load_toml_config(toml_config_file: pathlib.Path) -> None:
+    """
+    Test loading configuration from a TOML file.
+
+    Args:
+        toml_config_file: Path to the temporary TOML configuration file.
+    """
+    config = load_config(toml_config_file)
+    assert config["ICONFIG_VERSION"] == "2.0.0"
+    assert config["DATABROKER_CATALOG"] == "temp"
+    assert config["test_key"] == "test_value"
+
+
+def test_load_config_none_path() -> None:
+    """Test loading configuration with None path."""
+    with pytest.raises(ValueError, match="config_path must be provided"):
+        load_config(None)
+
+
+def test_load_config_invalid_file() -> None:
+    """Test loading configuration from a non-existent file."""
+    with pytest.raises(FileNotFoundError):
+        load_config(pathlib.Path("nonexistent.yml"))
+
+
+def test_load_config_invalid_extension() -> None:
+    """Test loading configuration with an unsupported file extension."""
+    with tempfile.NamedTemporaryFile(suffix=".txt", delete=False) as f:
+        path = pathlib.Path(f.name)
+
+    try:
+        with pytest.raises(ValueError, match="Unsupported configuration file format"):
+            load_config(path)
+    finally:
+        path.unlink()
+
+
+def test_load_config_invalid_content() -> None:
+    """Test loading configuration with invalid content."""
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yml", delete=False) as f:
+        f.write("invalid: yaml: content:")
+        path = pathlib.Path(f.name)
+
+    try:
+        with pytest.raises(Exception):  # noqa
+            load_config(path)
+    finally:
+        path.unlink()

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,98 @@
+"""
+Test that instrument can be started.
+
+Here is just enough testing to get a CI workflow started. More are possible.
+"""
+
+import time
+
+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 peaks
+from apsbits.demo_instrument.startup import running_in_queueserver
+from apsbits.demo_instrument.startup import sd
+from apsbits.demo_instrument.startup import specwriter
+from apsbits.utils.config_loaders import get_config
+
+
+def test_startup(runengine_with_devices: object) -> None:
+    """
+    Test that standard startup works and the RunEngine has initialized the devices.
+
+    Parameters
+    ----------
+    runengine_with_devices : object
+        Fixture providing initialized RunEngine with devices.
+    """
+    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 specwriter is not None
+
+    iconfig = get_config()
+    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()
+    # Get the initial number of runs in the catalog
+    n_runs = len(cat)
+    # Use the fixture-provided run engine to run the plan.
+    uids = runengine_with_devices(plan())
+    assert len(uids) == n_uids
+    # Add a small delay to ensure data is saved
+    time.sleep(0.1)
+    # For sim_print_plan, we don't expect any new runs
+    if plan == sim_print_plan:
+        assert len(cat) == n_runs
+    else:
+        assert len(cat) == n_runs + len(uids)
+
+
+def test_iconfig() -> None:
+    """
+    Test the instrument configuration.
+    """
+    iconfig = get_config()
+
+    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,169 @@
+"""
+Configuration management for the instrument.
+
+This module serves as the single source of truth for instrument configuration.
+It loads and validates the configuration from the iconfig.yml file and provides
+access to the configuration throughout the application.
+"""
+
+import logging
+import pathlib
+from pathlib import Path
+from typing import Any
+from typing import Dict
+from typing import Optional
+
+import tomli  # type: ignore
+import yaml
+
+logger = logging.getLogger(__name__)
+logger.bsdev(__file__)
+
+# Global configuration instance
+_iconfig: Dict[str, Any] = {}
+
+
+def load_config(config_path: Optional[Path] = None) -> Dict[str, Any]:
+    """
+    Load configuration from a YAML or TOML file.
+
+    Args:
+        config_path: Path to the configuration file.
+
+    Returns:
+        The loaded configuration dictionary.
+
+    Raises:
+        ValueError: If config_path is None or if the file extension is not supported.
+        FileNotFoundError: If the configuration file does not exist.
+    """
+    global _iconfig
+
+    if config_path is None:
+        raise ValueError("config_path must be provided")
+
+    if not config_path.exists():
+        raise FileNotFoundError(f"Configuration file not found at {config_path}")
+
+    try:
+        with open(config_path, "rb") as f:
+            if config_path.suffix.lower() == ".yml":
+                config = yaml.safe_load(f)
+            elif config_path.suffix.lower() == ".toml":
+                config = tomli.load(f)
+            else:
+                raise ValueError(
+                    f"Unsupported configuration file format: {config_path.suffix}"
+                )
+
+            if config is None:
+                config = {}
+            _iconfig.update(config)
+
+            _iconfig["ICONFIG_PATH"] = str(config_path)
+            _iconfig["INSTRUMENT_PATH"] = str(config_path.parent)
+            _iconfig["INSTRUMENT_FOLDER"] = str(config_path.parent.name)
+
+            return _iconfig
+    except Exception as e:
+        logger.error(f"Error loading configuration: {e}")
+        raise
+
+
+def get_config() -> Dict[str, Any]:
+    """
+    Get the current configuration.
+
+    Returns:
+        The current configuration dictionary.
+    """
+    return _iconfig
+
+
+def update_config(updates: Dict[str, Any]) -> None:
+    """
+    Update the current configuration.
+
+    Args:
+        updates: Dictionary of configuration updates.
+    """
+    _iconfig.update(updates)
+
+
+# def load_config_yaml(config_path: Optional[Path] = None) -> Dict[str, Any]:
+#     """
+#     Load configuration from a YAML file.
+
+#     Args:
+#         config_path: Path to the configuration file.
+
+#     Returns:
+#         The loaded configuration dictionary.
+
+#     Raises:
+#         FileNotFoundError: If the configuration file does not exist.
+#     """
+#     if config_path is None:
+#         raise ValueError("config_path must be provided")
+
+#     if not config_path.exists():
+#         raise FileNotFoundError(f"Configuration file not found at {config_path}")
+
+#     try:
+#         with open(config_path) as f:
+#             config = yaml.safe_load(f)
+#             if config is None:
+#                 config = {}
+#             return config
+#     except Exception as e:
+#         logger.error(f"Error loading configuration: {e}")
+#         raise
+
+
+def load_config_yaml(config_obj) -> dict:
+    """
+    Load configuration from a YAML file.
+
+    Args:
+        config_path: Path to the configuration file.
+
+    Returns:
+        The loaded configuration dictionary.
+
+    Raises:
+        FileNotFoundError: If the configuration file does not exist.
+    """
+
+    if config_obj is None:
+        raise ValueError("config_path must be provided")
+
+    try:
+        # If it's a path, open it first
+        if isinstance(config_obj, (str, pathlib.Path)):
+            with open(config_obj, "r") as f:
+                content = f.read()
+        # Otherwise assume it's a file-like object
+        else:
+            content = config_obj.read()
+
+        iconfig = yaml.load(content, yaml.Loader)
+        return iconfig
+    except Exception as e:
+        logger.error(f"Error loading configuration: {e}")
+        raise
+
+
+# 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}'."
+#     )