dls-dodal 1.54.0__tar.gz → 1.55.1__tar.gz

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/.github/workflows/_test.yml

@@ -62,6 +62,7 @@ jobs:
         with:
           repository: epics-containers/example-services
           path: example-services
+          ref: '2025.8.1'
 
       - name: Run docker compose
         uses: hoverkraft-tech/compose-action@v2.3.0

dls_dodal-1.55.1/.talismanrc

@@ -0,0 +1,10 @@
+fileignoreconfig:
+# Allow CI workflows to pin to the SHA hash
+- filename: ".github/**/*.yml"
+  allowed_patterns:
+   - "uses: .*"
+# Allow use of pass_energy signal name
+- filename: "*.py"
+  allowed_patterns:
+    - pass_energy
+ 

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dls-dodal
-Version: 1.54.0
+Version: 1.55.1
 Summary: Ophyd devices and other utils that could be used across DLS beamlines
 Author-email: Dominic Oram <dominic.oram@diamond.ac.uk>, Joseph Ware <joseph.ware@diamond.ac.uk>, Oliver Silvester <Oliver.Silvester@diamond.ac.uk>, Noemi Frisina <noemi.frisina@diamond.ac.uk>
 License:                                  Apache License
@@ -215,7 +215,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click
 Requires-Dist: ophyd
-Requires-Dist: ophyd-async[ca,pva]>=0.12.3
+Requires-Dist: ophyd-async[ca,pva]>=0.13.0
 Requires-Dist: bluesky
 Requires-Dist: pyepics
 Requires-Dist: dataclasses-json

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/docs/how-to/create-beamline.rst

@@ -63,14 +63,14 @@ The following example creates a fictitious beamline ``w41``, with a simulated tw
     """
 
     """
-    A valid factory function which:
-    - may be instantiated automatically, selectively on live beamline
-        - caches and re-uses the result for subsequent calls
-    - automatically names the device
-    - may be skipped when make_all_devices is called on this module
-    - must be explicitly connected (may be automated by tools)
-        - when connected may connect to a simulated backend
-        - may be connected concurrently (when automated by tools)
+    This decorator gives extra desirable behaviour to this factory function:
+    - it may be instantiated automatically, selectively on live beamline
+        - caching and re-using the result for subsequent calls
+    - it automatically names the device if no name is explicitly set
+    - it may be skipped when make_all_devices is called on this module
+    - it must be explicitly connected (which may be automated by tools)
+        - when connected it may connect to a simulated backend
+        - it may be connected concurrently (when automated by tools)
     """"
     @device_factory(skip = BL == "s41")
     def synchrotron() -> Synchrotron:
@@ -85,9 +85,3 @@ The following example creates a fictitious beamline ``w41``, with a simulated tw
             drv_suffix=CAM_SUFFIX,
             fileio_suffix=HDF5_SUFFIX,
         )
-
-
-``w41`` should also be added to the list of ``ALL_BEAMLINES`` in ``tests/beamlines/test_device_instantiation``.
-This test checks that the function returns a type that conforms to Bluesky protocols, 
-that it always returns the same instance of the device and that the arguments passed 
-into the Device class constructor are valid.

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/docs/how-to/create-device.md

@@ -1,7 +1,7 @@
 Creating a new device
 ---------------------
 
-Devices are written using the ophyd-async framework, the hardware abstraction library at Diamond. 
+Devices are written using the ophyd-async framework, the hardware abstraction library at Diamond. Before creating your device, you should [consider where the new code should live](../reference/device-standards.rst#where_to_put_devices).
 
 Reusing an existing class
 =========================

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/docs/reference/device-standards.rst

@@ -7,6 +7,9 @@ Some devices have been written in ``ophyd`` for historic reasons. However, all n
 ``ophyd-async`` and any old ``ophyd`` devices undergoing a large re-write should be considered for 
 conversion to ``ophyd-async``. 
 
+
+.. _where_to_put_devices:
+
 Where to put devices
 --------------------
 
@@ -19,7 +22,11 @@ should think about where to place them in the following order:
    complex device (e.g. multiple files) it should have a folder of its own e.g. ``oav``
 #. A device that is very specific to a particular beamline should go in the ``devices/ixx`` folder
 
-This is in an effort to avoid duplication across facilities/beamlines. 
+This is in an effort to avoid duplication across facilities/beamlines. You should also consider whether it is best for a piece of logic is better suited to the control system or a bluesky plan - see `ophyd-async's guide <https://blueskyproject.io/ophyd-async/main/explanations/where-device-logic.html>`_ on that.
+
+Determining where in dodal a device should live can be summarised below:
+
+.. image:: ../assets/where-to-put-dodal-logic.png
 
 Device Best Practices
 ----------------------------
@@ -27,10 +34,33 @@ Device Best Practices
 Ophyd-async directory contains a flowchart_ for a simplified decision tree about what interfaces
 should a given device implement. In addition to this the following guidelines are strongly recommended:
 
+#. Device should have their name as an optional str parameter with a default of ""- this allows ophyd-async to automatically name the device
 #. Devices should contain only the PV suffixes that are generic for any instance of the device. See `PV Suffixes`_
 #. Anything in a device that is expected to be set externally should be a signal. See `Use of signals`_
 #. Devices should not hold state, when they are read they should read the hardware. See `Holding State`_
 
+Defaulting Names
+----------------
+
+Device should provide the ability to override their name while maintaining a default name of ""-
+this allows the device to be named on connection from the name of its factory function when using
+the device_factory decorator.
+
+When a device is named in this way, all of its child devices are named appropriately.
+
+.. code-block:: python
+    class MyDevice(Device):
+        def __init__(self, prefix: str, name: str = "")
+            x = Motor(prefix + "X")
+            super().__init__(name)
+
+    @device_factory()
+    def foo() -> MyDevice:
+        return MyDevice("FOO:")
+
+    f = foo()
+    f.name == "foo"
+    f.x.name == "foo-x"
 
 PV Suffixes
 -----------
@@ -40,23 +70,22 @@ In general devices should contain only the PV suffixes that are generic for any
 .. code-block:: python
 
     class MyDevice(Device):
-        def __init__(self, name: str, prefix: str)
+        def __init__(self, prefix: str, name: str = "")
             self.bragg = Motor(prefix + "BRAGG")
-            super().__init__(name)        
-    
-    device_instantiation(MyDevice, "dcm", "-MO-DCM-01:")
+            super().__init__(name)  
 
+    MyDevice("BLXXI-MO-DCM-01:")      
 
 is preferred over
 
 .. code-block:: python
 
     class MyDevice(Device):
-        def __init__(self, name: str, prefix: str)
+        def __init__(self, prefix: str, name: str = "")
             self.bragg = Motor(prefix + "-MO-DCM-01:BRAGG")
             super().__init__(name)        
 
-    device_instantiation(MyDevice, "dcm", "")
+    MyDevice("BLXXI")
 
 This is so that a new device on say ``-MO-DCM-02`` can be easily created.
 

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/pyproject.toml

@@ -14,7 +14,7 @@ description = "Ophyd devices and other utils that could be used across DLS beaml
 dependencies = [
     "click",
     "ophyd",
-    "ophyd-async[ca,pva]>=0.12.3",
+    "ophyd-async[ca,pva]>=0.13.0",
     "bluesky",
     "pyepics",
     "dataclasses-json",

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/src/dls_dodal.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dls-dodal
-Version: 1.54.0
+Version: 1.55.1
 Summary: Ophyd devices and other utils that could be used across DLS beamlines
 Author-email: Dominic Oram <dominic.oram@diamond.ac.uk>, Joseph Ware <joseph.ware@diamond.ac.uk>, Oliver Silvester <Oliver.Silvester@diamond.ac.uk>, Noemi Frisina <noemi.frisina@diamond.ac.uk>
 License:                                  Apache License
@@ -215,7 +215,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click
 Requires-Dist: ophyd
-Requires-Dist: ophyd-async[ca,pva]>=0.12.3
+Requires-Dist: ophyd-async[ca,pva]>=0.13.0
 Requires-Dist: bluesky
 Requires-Dist: pyepics
 Requires-Dist: dataclasses-json

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/src/dls_dodal.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 .copier-answers.yml
 .gitignore
 .pre-commit-config.yaml
+.talismanrc
 Dockerfile
 LICENSE
 README.md
@@ -39,6 +40,7 @@ docs/tutorials.md
 docs/_templates/custom-module-template.rst
 docs/_templates/autosummary/class.rst
 docs/_templates/autosummary/module.rst
+docs/assets/where-to-put-dodal-logic.png
 docs/assets/zocalo.png
 docs/explanations/decisions.md
 docs/explanations/reviews.md
@@ -90,6 +92,7 @@ src/dodal/log.py
 src/dodal/utils.py
 src/dodal/beamline_specific_utils/__init__.py
 src/dodal/beamline_specific_utils/i03.py
+src/dodal/beamline_specific_utils/i05_shared.py
 src/dodal/beamlines/README.md
 src/dodal/beamlines/__init__.py
 src/dodal/beamlines/adsim.py
@@ -177,6 +180,7 @@ src/dodal/devices/undulator.py
 src/dodal/devices/watsonmarlow323_pump.py
 src/dodal/devices/webcam.py
 src/dodal/devices/xbpm_feedback.py
+src/dodal/devices/aithre_lasershaping/__init__.py
 src/dodal/devices/aithre_lasershaping/goniometer.py
 src/dodal/devices/aithre_lasershaping/laser_robot.py
 src/dodal/devices/areadetector/plugins/CAM.py
@@ -352,7 +356,6 @@ tests/common/test_visit.py
 tests/common/beamlines/__init__.py
 tests/common/beamlines/test_beamline_parameters.py
 tests/common/beamlines/test_beamline_utils.py
-tests/common/beamlines/test_device_helpers.py
 tests/common/beamlines/test_device_instantiation.py
 tests/devices/__init__.py
 tests/devices/test_common_dcm.py

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/src/dls_dodal.egg-info/requires.txt

@@ -1,6 +1,6 @@
 click
 ophyd
-ophyd-async[ca,pva]>=0.12.3
+ophyd-async[ca,pva]>=0.13.0
 bluesky
 pyepics
 dataclasses-json

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/src/dodal/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.54.0'
-__version_tuple__ = version_tuple = (1, 54, 0)
+__version__ = version = '1.55.1'
+__version_tuple__ = version_tuple = (1, 55, 1)

dls_dodal-1.55.1/src/dodal/beamline_specific_utils/i05_shared.py

@@ -0,0 +1,11 @@
+from dodal.common.beamlines.beamline_utils import device_factory
+from dodal.devices.i05.enums import Grating
+from dodal.devices.pgm import PGM
+from dodal.utils import BeamlinePrefix
+
+PREFIX = BeamlinePrefix("i05", "I")
+
+
+@device_factory()
+def pgm() -> PGM:
+    return PGM(prefix=f"{PREFIX.beamline_prefix}-OP-PGM-01:", grating=Grating)

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/src/dodal/beamlines/aithre.py

@@ -12,12 +12,12 @@ PREFIX = "LA18L"
 
 @device_factory()
 def goniometer() -> Goniometer:
-    return Goniometer(f"{PREFIX}-MO-LSR-01:", "goniometer")
+    return Goniometer(f"{PREFIX}-MO-LSR-01:")
 
 
 @device_factory()
 def robot() -> LaserRobot:
-    return LaserRobot("robot", f"{PREFIX}-MO-ROBOT-01:")
+    return LaserRobot(f"{PREFIX}-MO-ROBOT-01:")
 
 
 @device_factory()
@@ -25,6 +25,5 @@ def oav(params: OAVConfigBeamCentre | None = None) -> OAVBeamCentreFile:
     return OAVBeamCentreFile(
         prefix=f"{PREFIX}-DI-OAV-01:",
         config=params or OAVConfigBeamCentre(ZOOM_PARAMS_FILE, DISPLAY_CONFIG),
-        name="oav",
         zoom_controller=NullZoomController(),
     )

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/src/dodal/beamlines/b01_1.py

@@ -1,16 +1,12 @@
-from pathlib import Path
-
 from ophyd_async.epics.adaravis import AravisDetector
 from ophyd_async.fastcs.panda import HDFPanda
 
 from dodal.common.beamlines.beamline_utils import (
     device_factory,
     get_path_provider,
-    set_path_provider,
 )
 from dodal.common.beamlines.beamline_utils import set_beamline as set_utils_beamline
 from dodal.common.beamlines.device_helpers import CAM_SUFFIX, HDF5_SUFFIX
-from dodal.common.visit import LocalDirectoryServiceClient, StaticVisitPathProvider
 from dodal.devices.motors import XYZStage
 from dodal.devices.synchrotron import Synchrotron
 from dodal.log import set_beamline as set_log_beamline
@@ -21,14 +17,6 @@ PREFIX = BeamlinePrefix(BL)
 set_log_beamline(BL)
 set_utils_beamline(BL)
 
-set_path_provider(
-    StaticVisitPathProvider(
-        BL,
-        Path("/dls/b01-1/data/2025/cm40661-1/"),
-        client=LocalDirectoryServiceClient(),
-    )
-)
-
 """
 NOTE: Due to ArgoCD and the k8s cluster configuration those PVs are not available remotely.
 You need to be on the beamline-local network to access them.

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/src/dodal/beamlines/b16.py

@@ -62,7 +62,6 @@ def fds2() -> AreaDetector:
 def sim_stage() -> XYZStage:
     return XYZStage(
         f"{PREFIX.beamline_prefix}-MO-SIM-01:",
-        "sim_stage",
         x_infix="M1",
         y_infix="M2",
         z_infix="M3",

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/src/dodal/beamlines/b21.py

@@ -116,8 +116,6 @@ def slits_7() -> Slits:
         prefix=f"{PREFIX.beamline_prefix}-AL-SLITS-07:",
         x_gap="X:GAP",
         y_gap="Y:GAP",
-        x_centre="X:CENTRE",
-        y_centre="Y:CENTRE",
     )
 
 

{dls_dodal-1.54.0 → dls_dodal-1.55.1}/src/dodal/beamlines/i03.py

@@ -1,5 +1,6 @@
 from ophyd_async.fastcs.eiger import EigerDetector as FastEiger
 from ophyd_async.fastcs.panda import HDFPanda
+from yarl import URL
 
 from dodal.common.beamlines.beamline_parameters import get_beamline_parameters
 from dodal.common.beamlines.beamline_utils import (
@@ -49,7 +50,7 @@ from dodal.devices.zebra.zebra_constants_mapping import (
     ZebraTTLOutputs,
 )
 from dodal.devices.zebra.zebra_controlled_shutter import ZebraShutter
-from dodal.devices.zocalo import ZocaloResults
+from dodal.devices.zocalo import ZocaloResults, ZocaloSource
 from dodal.log import set_beamline as set_log_beamline
 from dodal.utils import BeamlinePrefix, get_beamline_name
 
@@ -105,7 +106,6 @@ def beamstop() -> Beamstop:
     """
     return Beamstop(
         prefix=f"{PREFIX.beamline_prefix}-MO-BS-01:",
-        name="beamstop",
         beamline_parameters=get_beamline_parameters(),
     )
 
@@ -117,7 +117,6 @@ def dcm() -> DCM:
     """
     return DCM(
         prefix=f"{PREFIX.beamline_prefix}-MO-DCM-01:",
-        name="dcm",
     )
 
 
@@ -125,7 +124,6 @@ def dcm() -> DCM:
 def vfm() -> FocusingMirrorWithStripes:
     return FocusingMirrorWithStripes(
         prefix=f"{PREFIX.beamline_prefix}-OP-VFM-01:",
-        name="vfm",
         bragg_to_lat_lut_path=DAQ_CONFIGURATION_PATH
         + "/lookup/BeamLineEnergy_DCM_VFM_x_converter.txt",
         x_suffix="LAT",
@@ -136,7 +134,6 @@ def vfm() -> FocusingMirrorWithStripes:
 @device_factory()
 def mirror_voltages() -> MirrorVoltages:
     return MirrorVoltages(
-        name="mirror_voltages",
         prefix=f"{PREFIX.beamline_prefix}-MO-PSU-01:",
         daq_configuration_path=DAQ_CONFIGURATION_PATH,
     )
@@ -147,7 +144,7 @@ def backlight() -> Backlight:
     """Get the i03 backlight device, instantiate it if it hasn't already been.
     If this is called when already instantiated in i03, it will return the existing object.
     """
-    return Backlight(prefix=PREFIX.beamline_prefix, name="backlight")
+    return Backlight(prefix=PREFIX.beamline_prefix)
 
 
 @device_factory()
@@ -157,7 +154,6 @@ def detector_motion() -> DetectorMotion:
     """
     return DetectorMotion(
         prefix=PREFIX.beamline_prefix,
-        name="detector_motion",
     )
 
 
@@ -197,7 +193,6 @@ def zebra_fast_grid_scan() -> ZebraFastGridScan:
     """
     return ZebraFastGridScan(
         prefix=f"{PREFIX.beamline_prefix}-MO-SGON-01:",
-        name="zebra_fast_grid_scan",
     )
 
 
@@ -209,7 +204,6 @@ def panda_fast_grid_scan() -> PandAFastGridScan:
     """
     return PandAFastGridScan(
         prefix=f"{PREFIX.beamline_prefix}-MO-SGON-01:",
-        name="panda_fast_grid_scan",
     )
 
 
@@ -222,7 +216,6 @@ def oav(
     """
     return OAVBeamCentreFile(
         prefix=f"{PREFIX.beamline_prefix}-DI-OAV-01:",
-        name="oav",
         config=params or OAVConfigBeamCentre(ZOOM_PARAMS_FILE, DISPLAY_CONFIG),
     )
 
@@ -234,7 +227,6 @@ def pin_tip_detection() -> PinTipDetection:
     """
     return PinTipDetection(
         f"{PREFIX.beamline_prefix}-DI-OAV-01:",
-        "pin_tip_detection",
     )
 
 
@@ -243,7 +235,7 @@ def smargon() -> Smargon:
     """Get the i03 Smargon device, instantiate it if it hasn't already been.
     If this is called when already instantiated in i03, it will return the existing object.
     """
-    return Smargon(f"{PREFIX.beamline_prefix}-MO-SGON-01:", "smargon")
+    return Smargon(f"{PREFIX.beamline_prefix}-MO-SGON-01:")
 
 
 @device_factory()
@@ -253,7 +245,6 @@ def s4_slit_gaps() -> S4SlitGaps:
     """
     return S4SlitGaps(
         f"{PREFIX.beamline_prefix}-AL-SLITS-04:",
-        "s4_slit_gaps",
     )
 
 
@@ -262,7 +253,7 @@ def synchrotron() -> Synchrotron:
     """Get the i03 synchrotron device, instantiate it if it hasn't already been.
     If this is called when already instantiated in i03, it will return the existing object.
     """
-    return Synchrotron("", "synchrotron")
+    return Synchrotron()
 
 
 @device_factory()
@@ -272,7 +263,6 @@ def undulator(daq_configuration_path: str | None = None) -> Undulator:
     """
     return Undulator(
         f"{BeamlinePrefix(BL).insertion_prefix}-MO-SERVC-01:",
-        name="undulator",
         # evaluate here not as parameter default to enable post-import mocking
         id_gap_lookup_table_path=f"{daq_configuration_path or DAQ_CONFIGURATION_PATH}/lookup/BeamLine_Undulator_toGap.txt",
     )
@@ -290,7 +280,6 @@ def undulator_dcm(daq_configuration_path: str | None = None) -> UndulatorDCM:
         else undulator()
     )
     return UndulatorDCM(
-        name="undulator_dcm",
         prefix=PREFIX.beamline_prefix,
         undulator=undulator_singleton,
         dcm=dcm(),
@@ -304,7 +293,6 @@ def zebra() -> Zebra:
     If this is called when already instantiated in i03, it will return the existing object.
     """
     return Zebra(
-        name="zebra",
         prefix=f"{PREFIX.beamline_prefix}-EA-ZEBRA-01:",
         mapping=I03_ZEBRA_MAPPING,
     )
@@ -317,7 +305,6 @@ def xspress3mini() -> Xspress3:
     """
     return Xspress3(
         f"{PREFIX.beamline_prefix}-EA-XSP3-01:",
-        "xspress3mini",
     )
 
 
@@ -329,7 +316,6 @@ def panda() -> HDFPanda:
     return HDFPanda(
         f"{PREFIX.beamline_prefix}-EA-PANDA-01:",
         path_provider=get_path_provider(),
-        name="panda",
     )
 
 
@@ -340,7 +326,6 @@ def sample_shutter() -> ZebraShutter:
     """
     return ZebraShutter(
         f"{PREFIX.beamline_prefix}-EA-SHTR-01:",
-        "sample_shutter",
     )
 
 
@@ -351,7 +336,6 @@ def flux() -> Flux:
     """
     return Flux(
         f"{PREFIX.beamline_prefix}-MO-FLUX-01:",
-        "flux",
     )
 
 
@@ -362,7 +346,6 @@ def xbpm_feedback() -> XBPMFeedback:
     """
     return XBPMFeedback(
         PREFIX.beamline_prefix,
-        "xbpm_feedback",
     )
 
 
@@ -371,7 +354,10 @@ def zocalo() -> ZocaloResults:
     """Get the i03 ZocaloResults device, instantiate it if it hasn't already been.
     If this is called when already instantiated in i03, it will return the existing object.
     """
-    return ZocaloResults(name="zocalo", prefix=PREFIX.beamline_prefix, use_gpu=True)
+    return ZocaloResults(
+        prefix=PREFIX.beamline_prefix,
+        results_source=ZocaloSource.GPU,
+    )
 
 
 @device_factory()
@@ -380,7 +366,6 @@ def robot() -> BartRobot:
     If this is called when already instantiated in i03, it will return the existing object.
     """
     return BartRobot(
-        "robot",
         f"{PREFIX.beamline_prefix}-MO-ROBOT-01:",
     )
 
@@ -391,9 +376,7 @@ def webcam() -> Webcam:
     If this is called when already instantiated in i03, it will return the existing object.
     """
     return Webcam(
-        "webcam",
-        PREFIX.beamline_prefix,
-        url="http://i03-webcam1/axis-cgi/jpg/image.cgi",
+        url=URL("http://i03-webcam1/axis-cgi/jpg/image.cgi"),
     )
 
 
@@ -404,7 +387,6 @@ def thawer() -> Thawer:
     """
     return Thawer(
         f"{PREFIX.beamline_prefix}-EA-THAW-01",
-        "thawer",
     )
 
 
@@ -415,7 +397,6 @@ def lower_gonio() -> XYZStage:
     """
     return XYZStage(
         f"{PREFIX.beamline_prefix}-MO-GONP-01:",
-        "lower_gonio",
     )
 
 
@@ -426,7 +407,6 @@ def cryo_stream() -> CryoStream:
     """
     return CryoStream(
         PREFIX.beamline_prefix,
-        "cryo_stream",
     )
 
 
@@ -447,7 +427,6 @@ def qbpm() -> QBPM:
     """
     return QBPM(
         f"{PREFIX.beamline_prefix}-DI-QBPM-01:",
-        "qbpm",
     )