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

{hutch_python-1.21.0 → hutch_python-1.23.0}/.github/workflows/standard.yml

@@ -18,10 +18,10 @@ jobs:
       # Extras that will be installed for both conda/pip:
       testing-extras: ""
       # Extras to be installed only for conda-based testing:
-      conda-testing-extras: "ipython=8.4.0"
+      conda-testing-extras: ""
       # Extras to be installed only for pip-based testing:
       # Set numpy<2 for now, remove when xraylib updates
-      pip-testing-extras: "ipython==8.4.0 numpy<2"
+      pip-testing-extras: ""
       # System packages to be installed only for conda-based testing:
       conda-system-packages: ""
       # System packages to be installed only for pip-based testing:

{hutch_python-1.21.0 → hutch_python-1.23.0}/.pre-commit-config.yaml

@@ -7,7 +7,7 @@ exclude: |
 
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v5.0.0
     hooks:
     -   id: no-commit-to-branch
     -   id: trailing-whitespace
@@ -27,11 +27,11 @@ repos:
     -   id: debug-statements
 
 -   repo: https://github.com/pycqa/flake8.git
-    rev: 6.0.0
+    rev: 7.2.0
     hooks:
     -   id: flake8
 
 -   repo: https://github.com/timothycrosley/isort
-    rev: 5.12.0
+    rev: 6.0.1
     hooks:
     -   id: isort

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: hutch-python
-Version: 1.21.0
+Version: 1.23.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
@@ -55,14 +55,14 @@ Requires-Dist: bluesky>=1.8.0
 Requires-Dist: coloredlogs>=15.0.0
 Requires-Dist: cookiecutter>=1.7.0
 Requires-Dist: happi>=1.9.0
-Requires-Dist: ipython>=7.26.0
+Requires-Dist: ipython<9.0.0
 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: pcdsdevices>8.7.0
 Requires-Dist: pcdsutils>=0.5.0
 Requires-Dist: psdaq-control-minimal
 Requires-Dist: pyfiglet>=0.8.0
@@ -83,7 +83,7 @@ Requires-Dist: sphinx; extra == "doc"
 Requires-Dist: sphinx_rtd_theme; extra == "doc"
 Requires-Dist: sphinxcontrib-jquery; extra == "doc"
 Requires-Dist: pypandoc; extra == "doc"
-Requires-Dist: numpy<2; extra == "doc"
+Dynamic: license-file
 
 ============
 Hutch Python

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

@@ -27,14 +27,14 @@ requirements:
   - cookiecutter >=1.7.0
   - elog >=1.1.0
   - happi >=1.9.0
-  - ipython >=7.26.0
+  - ipython <9.0.0
   - jinja2 >=2.11.0
   - 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
+  - pcdsdevices >8.7.0
   - pcdsutils >=0.6.0
   - psdaq-control-minimal >=3.3.19
   - psdm_qs_cli >=0.3.1

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

@@ -2,6 +2,69 @@ Release History
 ###############
 
 
+v1.23.0 (2025-04-07)
+====================
+
+Features
+--------
+- Added ability to load additional devices not on the current beamline or hutch/area using happi search.
+
+Bugfixes
+--------
+- update functions anticipating py3.12 and IPython > 8.26
+
+Maintenance
+-----------
+- Enable the deferral of preset loading to avoid a pre-mature performance hit
+
+Contributors
+------------
+- janeliu-slac
+- tangkong
+
+
+
+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.23.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,58 @@ 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 string
+that starts with a "-" symbol on each line. The string is the name of a device
+that should not be loaded.
+
+This feature reduces the amount of unnecessary information shown in the console
+at load time. The list uses the following format:
+
+.. code-block:: YAML
+
+   exclude_devices:
+      - crix_cryo_y
+      - at2k2_calc
+      - tmo_lamp_sqr1
+
+
+additional_devices
+------------
+The ``additional_devices`` key is optional. This key allows hutch-python to
+load additional devices that are on a different beamline or in a different
+hutch/area. The first entry below ``additional_devices`` is a search name,
+such as 'tmo_sqr1_search'. Search names are arbitrarily determined by the user
+but should start with a letter or number. Each search name is followed by a
+happi search key, such as "beamline" and a value. For example, "beamline: TMO".
+This tells hutch-python to gather all devices on the TMO beamline and load
+them. A second search criterion can be added below "beamline: TMO" to constrain
+the search further, so that only those devices that fit both search criteria
+will be loaded. For example, adding "device_class: pcdsdevices.sqr1.SQR1" below
+"beamline: TMO" tells hutch-python to load devices from the TMO beamline whose
+"device_class" key has a value of "pcdsdevices.sqr1.SQR1". More lines can be
+added to obtain even more specific search results.
+
+A search value can contain a wildcard symbol (*). For example, "name: tmo_*".
+
+In the example below hutch-python will load all devices from "tmo_sqr1_search",
+"las_search", and "crix_search".
+
+.. code-block:: YAML
+
+   additional_devices:
+      tmo_sqr1_search:
+         beamline: TMO
+         device_class: pcdsdevices.sqr1.SQR1
+         z: -1, 1
+      las_search:
+        name: LAS
+      crix_search:
+         name: crix_*
+
+
 Full File Example
 -----------------
 

{hutch_python-1.21.0 → hutch_python-1.23.0}/docs-requirements.txt

@@ -4,5 +4,3 @@ sphinx
 sphinx_rtd_theme
 sphinxcontrib-jquery
 pypandoc
-# Temporary pin, xraylib 4.1.3 (pcdscalc) incompatible
-numpy <2

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

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,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.23.0'
+__version_tuple__ = version_tuple = (1, 23, 0)

{hutch_python-1.21.0 → hutch_python-1.23.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.23.0}/hutch_python/constants.py

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

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

@@ -1,9 +1,11 @@
 import enum
 import inspect
 import logging
+from typing import Dict, List, Optional
 
 import happi
 import ophyd
+from happi.cli import search_parser
 from happi.loader import load_devices
 
 try:
@@ -29,7 +31,9 @@ def get_happi_objs(
     db: str,
     light_ctrl: LightController,
     endstation: str,
-    load_level: DeviceLoadLevel = DeviceLoadLevel.STANDARD
+    load_level: DeviceLoadLevel = DeviceLoadLevel.STANDARD,
+    exclude_devices: Optional[List[str]] = None,
+    additional_devices: Optional[Dict[str, Dict[str, str]]] = None
 ) -> dict[str, ophyd.Device]:
     """
     Get the relevant items for ``endstation`` from the happi database ``db``.
@@ -52,11 +56,30 @@ def get_happi_objs(
     endstation: ``str``
         Name of hutch
 
+    load_level: ``DeviceLoadLevel``
+        load all or standard devices
+
+    exclude_devices: ``Optional[List[str]]``
+        an optional list of devices that should be excluded when loading
+
+    additional_devices: ``Optional[Dict[str, Dict[str, str]]]``
+        an optional dictionary of dictionaries with happi search terms
+        whose results are loaded
+
     Returns
     -------
     objs: ``dict``
         A mapping from item name to item
     """
+
+    # Explicitly set exclude_devices and additional_devices to empty
+    # containers to avoid mutable default arguments issue.
+    if not exclude_devices:
+        exclude_devices = []
+
+    if not additional_devices:
+        additional_devices = {}
+
     # Load the happi Client
     if None not in (light_ctrl, lightpath):
         client = light_ctrl.client
@@ -67,47 +90,73 @@ 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')
 
+    # Load additional devices
+    for search_val in additional_devices.values():
+
+        search_list = []
+        final_results = []
+
+        for entry_key, entry_val in search_val.items():
+            search_string = entry_key + '=' + entry_val
+            search_list.append(search_string)
+
+        search_results = search_parser(
+            client=client,
+            use_glob=True,
+            search_criteria=search_list
+        )
+        search_results = list(search_results)
+        final_results += search_results
+        final_results = list(set(final_results))
+
+        containers.extend(
+            res.item for res in final_results if res.item not in containers)
+
+    # 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 +181,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 +204,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.23.0}/hutch_python/ipython_session_timer.py

@@ -58,11 +58,11 @@ class IPythonSessionTimer:
         ipython.events.register('pre_run_cell', self._set_user_active)
         ipython.events.register('post_run_cell', self._set_user_inactive)
 
-    def _set_user_active(self):
+    def _set_user_active(self, *args, **kwargs):
         self.user_active = True
         self.last_active_time = time.monotonic()
 
-    def _set_user_inactive(self):
+    def _set_user_inactive(self, *args, **kwargs):
         self.user_active = False
         self.last_active_time = time.monotonic()
 

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

@@ -297,6 +297,33 @@ 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(
+            'Exclude_devices has not been set in conf. Will load all devices.')
+
+    try:
+        # These are the additional devices to load
+        additional_devices = conf['additional_devices']
+        for search_val in additional_devices.values():
+            if not isinstance(search_val, dict):
+                logger.error(
+                    'Invalid additional_devices conf, must be a dictionary of dictionaries.')
+    except KeyError:
+        additional_devices = {}
+        logger.info(
+            'Additional_devices has not been set in conf. No additional devices will be loaded.')
+
     # Set the session timeout duration
     try:
         hutch_python.ipython_session_timer.configure_timeout(
@@ -304,7 +331,7 @@ def load_conf(conf, hutch_dir=None, args=None):
     except KeyError:
         hutch_python.ipython_session_timer.configure_timeout(172800)
         logger.info(
-            'Missing session_timer value from conf. Set default value to 172800 seconds (48 hours).')
+            'Missing session_timer value from conf. Session will time out in 48 hours.')
 
     # Make cache namespace
     cache = LoadCache((hutch or 'hutch') + '.db', hutch_dir=hutch_dir)
@@ -460,7 +487,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, additional_devices=additional_devices)
             cache(**happi_objs)
 
             # create and store beampath
@@ -568,10 +596,12 @@ def load_conf(conf, hutch_dir=None, args=None):
                     path.mkdir()
                     path.chmod(0o777)
             if experiment is None:
-                setup_preset_paths(hutch=beamline_presets)
+                setup_preset_paths(hutch=beamline_presets,
+                                   defer_loading=True)
             else:
                 setup_preset_paths(hutch=beamline_presets,
-                                   exp=experiment_presets)
+                                   exp=experiment_presets,
+                                   defer_loading=True)
 
     # configure objects
     if obj_config is not None:

hutch_python-1.23.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.23.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