hutch-python 1.21.0__tar.gz → 1.22.0__tar.gz

{hutch_python-1.21.0 → hutch_python-1.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hutch-python
-Version: 1.21.0
+Version: 1.22.0
 Summary: Launcher and Config Reader for LCLS Interactive IPython Sessions
 Author: SLAC National Accelerator Laboratory
 License: Copyright (c) 2023, The Board of Trustees of the Leland Stanford Junior
@@ -60,7 +60,7 @@ Requires-Dist: jinja2>=2.11.0
 Requires-Dist: lightpath>=1.0.1
 Requires-Dist: matplotlib>=3.4.0
 Requires-Dist: nabs>=1.5.0
-Requires-Dist: pcdscalc>=0.3.0
+Requires-Dist: pcdscalc>=0.6.0
 Requires-Dist: pcdsdaq>=2.3.0
 Requires-Dist: pcdsdevices>=7.0.0
 Requires-Dist: pcdsutils>=0.5.0

{hutch_python-1.21.0 → hutch_python-1.22.0}/conda-recipe/meta.yaml

@@ -32,7 +32,7 @@ requirements:
   - lightpath >=1.0.1
   - matplotlib-base >=3.4.0
   - nabs >=1.5.0
-  - pcdscalc >=0.3.0
+  - pcdscalc >=0.6.0
   - pcdsdaq >=2.3.0
   - pcdsdevices >=7.0.0
   - pcdsutils >=0.6.0

{hutch_python-1.21.0 → hutch_python-1.22.0}/docs/source/releases.rst

@@ -2,6 +2,47 @@ Release History
 ###############
 
 
+v1.22.0 (2024-12-19)
+====================
+
+Features
+--------
+- Add ``pcdscalc.xray`` to the calc namespace.
+- Add top-level shortcuts to some of the most used calcs,
+  ``E2lam``, ``lam2E``, ``bragg_angle``, ``darwin_width``,
+  and ``transmission``.
+  ``E2lam`` is an alias for ``energy_to_wavelength`` and
+  ``lam2E`` is an alias for ``wavelength_to_energy``
+  to match scientist expectations.
+- Added ability to ignore specific upstream devices when loading hutch-python.
+
+  - ``UPSTREAM``: The hutch's devices, and devices upstream from the requested hutch.
+    If there are multiple paths to the requested hutch, all paths devices are loaded.
+  - ``STANDARD``: Devices gathered via ``UPSTREAM``, plus devices that share the
+    "beamline" field in happi with the ``UPSTREAM`` devices.  (The current standard)
+  - ``ALL``: All devices in the happi database.  Use this option at your own risk.
+
+
+Bugfixes
+--------
+- Make test_create_arg agnostic to where pytest was invoked from
+- Fix an issue where the user could clobber their own ``elog``
+  object in a way that would allow the ``ElogPoster`` utility to
+  load and then fail at scan time.
+
+Maintenance
+-----------
+- Updates documentation formatting for device load_level, and adds an ascii beamline map to the test suite
+
+Contributors
+------------
+- janeliu-slac
+- tangkong
+- vespos
+- zllentz
+
+
+
 v1.21.0 (2024-08-20)
 ====================
 

{hutch_python-1.21.0 → hutch_python-1.22.0}/docs/source/yaml_files.rst

@@ -4,7 +4,7 @@ Yaml Files
 ``hutch-python`` uses a ``conf.yml`` file for basic configuration. This is a
 standard yaml file with the following valid keys:
 ``hutch``, ``db``, ``load``, ``load_level``, ``experiment``, ``obj_config``,
-``daq_type``, ``daq_host``, and ``daq_platform``.
+``daq_type``, ``daq_host``, and ``daq_platform``, ``exclude_devices``.
 
 
 hutch
@@ -75,9 +75,11 @@ The ``load_level`` key expects one of the following strings, corresponding to th
 amount of ophyd devices to load:
 
 - ``UPSTREAM``: The hutch's devices, and devices upstream from the requested hutch.
-If there are multiple paths to the requested hutch, all paths' devices are loaded.
+  If there are multiple paths to the requested hutch, all paths' devices are loaded.
+
 - ``STANDARD``: Devices gathered via ``UPSTREAM``, plus devices that share the
-"beamline" field in happi with the ``UPSTREAM`` devices.  (The current standard)
+  "beamline" field in happi with the ``UPSTREAM`` devices.  (The current standard)
+
 - ``ALL``: All devices in the happi database.  Use this option at your own risk.
 
 .. code-block:: YAML
@@ -104,6 +106,7 @@ particular experiment.
 
 .. _obj_conf_yaml:
 
+
 obj_conf
 --------
 
@@ -135,6 +138,7 @@ This key expects a string with one of four valid values:
 LCLS1-style daq, a simulated LCLS1-style daq, an LCLS2-style daq,
 or no daq respectively.
 
+
 daq_host
 --------
 
@@ -142,6 +146,7 @@ The daq collection host as a string. This is a required key
 when using the lcls2 daq_type, and is ignored with any other daq_type.
 It will be used in the creation of the lcls2 daq object.
 
+
 daq_platform
 ------------
 
@@ -155,6 +160,26 @@ experiment. Additional keys are interpreted as hostnames to use
 alternate platforms for. Alternate platforms will post to the
 secondary elog.
 
+
+exclude_devices
+------------
+The ``exclude_devices`` key is optional. ``exclude_devices`` expects a list
+of strings containing names of upstream devices that should not be loaded.
+It reduces the amount of unnecessary information shown in the console at
+load time. The list can be created as a multi-line array of strings or all
+on one line using the following formats:
+
+.. code-block:: YAML
+
+   exclude_devices:
+      - crix_cryo_y
+      - at2k2_calc
+
+.. code-block:: YAML
+
+   exclude_devices: ['crix_cryo_y', 'at2k2_calc']
+
+
 Full File Example
 -----------------
 

{hutch_python-1.21.0 → hutch_python-1.22.0}/hutch_python/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.21.0'
-__version_tuple__ = version_tuple = (1, 21, 0)
+__version__ = version = '1.22.0'
+__version_tuple__ = version_tuple = (1, 22, 0)

{hutch_python-1.21.0 → hutch_python-1.22.0}/hutch_python/calc_defaults.py

@@ -1,5 +1,9 @@
 from importlib import import_module
 
+from pcdscalc.common import energy_to_wavelength, wavelength_to_energy
+from pcdscalc.diffraction import bragg_angle, darwin_width
+from pcdscalc.xray import transmission
+
 from .utils import HelpfulNamespace
 
 
@@ -33,7 +37,13 @@ def collect_functions(modules):
 
 
 calc_namespace = HelpfulNamespace(
+    E2lam=energy_to_wavelength,
+    lam2E=wavelength_to_energy,
+    bragg_angle=bragg_angle,
+    darwin_width=darwin_width,
+    transmission=transmission,
     be_lens=collect_functions(['pcdscalc.be_lens_calcs']),
     common=collect_functions(['pcdscalc.common']),
     diffraction=collect_functions(['pcdscalc.diffraction']),
+    xray=collect_functions(['pcdscalc.xray']),
 )

{hutch_python-1.21.0 → hutch_python-1.22.0}/hutch_python/constants.py

@@ -39,6 +39,7 @@ VALID_KEYS = (
     'daq_host',
     'obj_config',
     'session_timer',
+    'exclude_devices'
 )
 NO_LOG_EXCEPTIONS = (KeyboardInterrupt, SystemExit)
 LOG_DOMAINS = {".pcdsn", ".slac.stanford.edu"}

{hutch_python-1.21.0 → hutch_python-1.22.0}/hutch_python/happi.py

@@ -29,7 +29,8 @@ def get_happi_objs(
     db: str,
     light_ctrl: LightController,
     endstation: str,
-    load_level: DeviceLoadLevel = DeviceLoadLevel.STANDARD
+    load_level: DeviceLoadLevel = DeviceLoadLevel.STANDARD,
+    exclude_devices: list[str] = None
 ) -> dict[str, ophyd.Device]:
     """
     Get the relevant items for ``endstation`` from the happi database ``db``.
@@ -57,6 +58,11 @@ def get_happi_objs(
     objs: ``dict``
         A mapping from item name to item
     """
+
+    # Explicitly set exclude_devices to empty list to avoid mutable default arguments issue.
+    if not exclude_devices:
+        exclude_devices = []
+
     # Load the happi Client
     if None not in (light_ctrl, lightpath):
         client = light_ctrl.client
@@ -67,47 +73,51 @@ def get_happi_objs(
     if load_level == DeviceLoadLevel.ALL:
         results = client.search(active=True)
         containers.extend(res.item for res in results)
-        return _load_devices(*containers)
 
-    if light_ctrl is None or (endstation.upper() not in light_ctrl.beamlines):
+    elif light_ctrl is None or (endstation.upper() not in light_ctrl.beamlines):
         # lightpath was unavailable, search by beamline name
         reqs = dict(beamline=endstation.upper(), active=True)
         results = client.search(**reqs)
         containers.extend(res.item for res in results)
-        return _load_devices(*containers)
-
-    # if lightpath exists, we can grab upstream devices
-    dev_names = set()
-    paths = light_ctrl.beamlines[endstation.upper()]
-    for path in paths:
-        dev_names.update(path)
-
-    # gather happi items for each of these
-    for name in dev_names:
-        results = client.search(name=name)
-        containers.extend(res.item for res in results)
 
-    if load_level >= DeviceLoadLevel.STANDARD:
-        # also any device with the same beamline name
-        # since lightpath only grabs lightpath-active devices
-        beamlines = {it.beamline for it in containers}
-        beamlines.add(endstation.upper())
-
-        for line in beamlines:
-            # Assume we want hutch items that are active
-            # items can be lightpath-inactive
-            reqs = dict(beamline=line, active=True)
-            results = client.search(**reqs)
-            blc = [res.item for res in results
-                   if res.item.name not in dev_names]
-            # Add the beamline containers to the complete list
-            if blc:
-                containers.extend(blc)
+    else:
+        # if lightpath exists, we can grab upstream devices
+        dev_names = set()
+        paths = light_ctrl.beamlines[endstation.upper()]
+        for path in paths:
+            dev_names.update(path)
+
+        # gather happi items for each of these
+        for name in dev_names:
+            results = client.search(name=name)
+            containers.extend(res.item for res in results)
+
+        if load_level >= DeviceLoadLevel.STANDARD:
+            # also any device with the same beamline name
+            # since lightpath only grabs lightpath-active devices
+            beamlines = {it.beamline for it in containers}
+            beamlines.add(endstation.upper())
+
+            for line in beamlines:
+                # Assume we want hutch items that are active
+                # items can be lightpath-inactive
+                reqs = dict(beamline=line, active=True)
+                results = client.search(**reqs)
+                blc = [res.item for res in results
+                       if res.item.name not in dev_names]
+                # Add the beamline containers to the complete list
+                if blc:
+                    containers.extend(blc)
 
     if len(containers) < 1:
         logger.warning(f'{len(containers)} active devices found for '
                        'this beampath')
 
+    # Do not load excluded devices
+    for device in containers.copy():
+        if device.name in exclude_devices:
+            containers.remove(device)
+
     return _load_devices(*containers)
 
 
@@ -132,7 +142,7 @@ def _load_devices(*containers: happi.HappiItem):
     return dev_namespace.__dict__
 
 
-def get_lightpath(db, hutch) -> LightController:
+def get_lightpath(db: str, hutch: str) -> LightController:
     """
     Create a ``lightpath.LightController`` from relevant ``happi`` objects.
 
@@ -155,10 +165,14 @@ def get_lightpath(db, hutch) -> LightController:
     if None in (lightpath, beamlines):
         logger.warning('Lightpath module is not available.')
         return None
+
     # Load the happi Client
     client = happi.Client(path=db)
+
     # Allow the lightpath module to create a path
     lc = lightpath.LightController(client, endstations=[hutch.upper()])
+
     # Return paths (names only) seen by the LightController
     # avoid loding the devices so hutch-python can keep track of it
+
     return lc

{hutch_python-1.21.0 → hutch_python-1.22.0}/hutch_python/load_conf.py

@@ -297,6 +297,20 @@ def load_conf(conf, hutch_dir=None, args=None):
         daq_platform = 0
         logger.info('Selected default hutch-python daq platform: 0')
 
+    try:
+        # This is a list of all devices that should not be loaded
+        exclude_devices = conf['exclude_devices']
+        if not isinstance(exclude_devices, list):
+            logger.error(
+                'Invalid exclude_devices conf, must be a list.')
+            exclude_devices = []
+        else:
+            exclude_devices = [device_name.strip() for device_name in exclude_devices]
+    except KeyError:
+        exclude_devices = []
+        logger.info(
+            'Missing exclude_devices in conf. Will load all devices.')
+
     # Set the session timeout duration
     try:
         hutch_python.ipython_session_timer.configure_timeout(
@@ -460,7 +474,8 @@ def load_conf(conf, hutch_dir=None, args=None):
             lc = get_lightpath(db, hutch)
 
             # Gather relevant objects given the BeamPath
-            happi_objs = get_happi_objs(db, lc, hutch, load_level=load_level)
+            happi_objs = get_happi_objs(
+                db, lc, hutch, load_level=load_level, exclude_devices=exclude_devices)
             cache(**happi_objs)
 
             # create and store beampath

hutch_python-1.22.0/hutch_python/startup_script.py

@@ -0,0 +1,49 @@
+"""
+Initialize the ELogPoster callback and subscribe it to the RunEngine
+
+Startup script files to be run after ipython is initialized via:
+``c.InteractiveTerminalApp.exec_files``
+
+Code here will take executed after both IPython has been loaded and
+the namespace has been populated with hutch objects.
+
+These will be run as standalone python files, and should not be
+imported from.
+"""
+
+
+def _configure_elog_poster():
+    import IPython
+    from nabs.callbacks import ELogPoster
+
+    from hutch_python.utils import safe_load
+
+    with safe_load('ELogPoster'):
+        try:
+            from bluesky.run_engine import RunEngine
+            from elog import HutchELog
+        except ImportError:
+            raise RuntimeError("A required module is missing, skip ElogPoster")
+
+        # RE, elog will already exist by now, if not we fail and skip.
+        # Some effort to give better error message for the logs.
+        try:
+            elog = globals()['elog']
+        except KeyError:
+            raise RuntimeError("elog not loaded, skip ElogPoster")
+        try:
+            RE = globals()['RE']
+        except KeyError:
+            raise RuntimeError("RE not loaded, skip ElogPoster")
+        # Even if they exist, things can go wrong if the user accidentally clobbers the name
+        if not isinstance(elog, HutchELog):
+            raise RuntimeError("elog replaced, skip ELogPoster")
+        if not isinstance(RE, RunEngine):
+            raise RuntimeError("RE replaced, skip ELogPoster")
+
+        elogc = ELogPoster(elog, IPython.get_ipython())
+        RE.subscribe(elogc)
+
+
+if __name__ == '__main__':
+    _configure_elog_poster()

hutch_python-1.22.0/hutch_python/tests/conf.yaml

@@ -0,0 +1,15 @@
+hutch: tst
+
+# Our test happi database has the following configuration:
+# tst_device_3 (inactive)
+
+# z +-> (0.8)               (1.0)           (2.0)
+# X0 -- tst_device_5 ------ tst_device_1 -- test_device_2 -- "TST"
+#                  \
+# Z0                -- tst_device_4 -- tst_device_6
+# z +->                (0.85)          (1.85)
+db: happi_db.json
+
+load: tst.beamline
+
+experiment: tstx010

{hutch_python-1.21.0 → hutch_python-1.22.0}/hutch_python/tests/test_cli.py

@@ -69,7 +69,9 @@ def test_sim_arg(no_ipython_launch):
 def test_create_arg():
     logger.debug('test_create_arg_dev')
     hutch = 'temp_create'
-    test_dir = CFG_PATH.parent.parent.parent / hutch
+    # CLI invocation will create the hutch folder in the folder pytest was
+    # called from.  We should check and clean that folder.
+    test_dir = Path.cwd() / hutch
     if test_dir.exists():
         shutil.rmtree(test_dir)
 

{hutch_python-1.21.0 → hutch_python-1.22.0}/hutch_python/tests/test_happi.py

@@ -17,9 +17,6 @@ def test_happi_objs():
     logger.debug("test_happi_objs")
     db = os.path.join(os.path.abspath(os.path.dirname(__file__)),
                       'happi_db.json')
-    # patch lightpath configs to include test db beamline
-    conftest.beamlines['TST'] = ['X0']
-    conftest.sources.append('X0')
     # Only select active objects
     lc = get_lightpath(db, 'tst')
     objs = get_happi_objs(db, lc, 'tst')
@@ -44,9 +41,6 @@ def test_load_level(load_level: DeviceLoadLevel, num_devices: int):
     logger.debug("test_load_level")
     db = os.path.join(os.path.abspath(os.path.dirname(__file__)),
                       'happi_db.json')
-    # patch lightpath configs to include test db beamline
-    conftest.beamlines['TST'] = ['X0']
-    conftest.sources.append('X0')
     # Only select active objects
     lc = get_lightpath(db, 'tst')
     objs = get_happi_objs(db, lc, 'tst', load_level=load_level)
@@ -63,3 +57,30 @@ def test_get_lightpath():
     # Check that we created a valid BeamPath with no inactive objects
     assert obj.name == 'TST'
     assert len(obj.devices) == 3
+
+
+# run test_happi_objs() with exclude_devices
+@conftest.requires_lightpath
+def test_happi_objs_with_exclude_devices():
+    # This test checks whether devices from exclude_devices have been removed from the
+    # output of get_happi_objs(). For comparison, get_happi_objs() is first called without
+    # exclude_devices and then called again with exclude_devices.
+    exclude_devices = ['tst_device_5', 'tst_device_1']
+
+    logger.debug("test_happi_objs")
+    db = os.path.join(os.path.abspath(os.path.dirname(__file__)),
+                      'happi_db.json')
+    # Only select active objects
+    lc = get_lightpath(db, 'tst')
+
+    # Call get_happi_objs() without exclude_devices
+    objs = get_happi_objs(db, lc, 'tst', DeviceLoadLevel.STANDARD)
+    assert len(objs) == 4
+
+    # Call get_happi_objs() with exclude_devices
+    objs_exclude_devices = get_happi_objs(db, lc, 'tst', DeviceLoadLevel.STANDARD, exclude_devices)
+    assert len(objs_exclude_devices) == 2
+
+    # Check that none of the loaded devices are in the exclude_devices list
+    for obj in objs_exclude_devices:
+        assert obj not in exclude_devices

{hutch_python-1.21.0 → hutch_python-1.22.0}/hutch_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hutch-python
-Version: 1.21.0
+Version: 1.22.0
 Summary: Launcher and Config Reader for LCLS Interactive IPython Sessions
 Author: SLAC National Accelerator Laboratory
 License: Copyright (c) 2023, The Board of Trustees of the Leland Stanford Junior
@@ -60,7 +60,7 @@ Requires-Dist: jinja2>=2.11.0
 Requires-Dist: lightpath>=1.0.1
 Requires-Dist: matplotlib>=3.4.0
 Requires-Dist: nabs>=1.5.0
-Requires-Dist: pcdscalc>=0.3.0
+Requires-Dist: pcdscalc>=0.6.0
 Requires-Dist: pcdsdaq>=2.3.0
 Requires-Dist: pcdsdevices>=7.0.0
 Requires-Dist: pcdsutils>=0.5.0

{hutch_python-1.21.0 → hutch_python-1.22.0}/hutch_python.egg-info/requires.txt

@@ -8,7 +8,7 @@ jinja2>=2.11.0
 lightpath>=1.0.1
 matplotlib>=3.4.0
 nabs>=1.5.0
-pcdscalc>=0.3.0
+pcdscalc>=0.6.0
 pcdsdaq>=2.3.0
 pcdsdevices>=7.0.0
 pcdsutils>=0.5.0

{hutch_python-1.21.0 → hutch_python-1.22.0}/requirements.txt

@@ -8,7 +8,7 @@ jinja2>=2.11.0
 lightpath>=1.0.1
 matplotlib>=3.4.0
 nabs>=1.5.0
-pcdscalc>=0.3.0
+pcdscalc>=0.6.0
 pcdsdaq>=2.3.0
 pcdsdevices>=7.0.0
 pcdsutils>=0.5.0

hutch_python-1.21.0/hutch_python/startup_script.py

@@ -1,32 +0,0 @@
-"""
-Initialize the ELogPoster callback and subscribe it to the RunEngine
-
-Startup script files to be run after ipython is initialized via:
-``c.InteractiveTerminalApp.exec_files``
-
-Code here will take executed after both IPython has been loaded and
-the namespace has been populated with hutch objects.
-
-These will be run as standalone python files, and should not be
-imported from.
-"""
-
-
-def _configure_elog_poster():
-    import IPython
-    from nabs.callbacks import ELogPoster
-
-    from hutch_python.utils import safe_load
-
-    with safe_load('ELogPoster'):
-        # RE, ELog will already exist by now
-        elog = globals().get('elog', None)
-        RE = globals().get('RE', None)
-        assert elog is not None
-
-        elogc = ELogPoster(elog, IPython.get_ipython())
-        RE.subscribe(elogc)
-
-
-if __name__ == '__main__':
-    _configure_elog_poster()

hutch_python-1.21.0/hutch_python/tests/conf.yaml

@@ -1,7 +0,0 @@
-hutch: tst
-
-db: happi_db.json
-
-load: tst.beamline
-
-experiment: tstx010