dls-dodal 1.68.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

dodal/cli.py

@@ -24,6 +24,40 @@ def main(ctx: click.Context) -> None:
         print("Please invoke subcommand!")
 
 
+@main.command(name="describe")
+@click.argument(
+    "beamline",
+    type=click.Choice(list(all_beamline_names())),
+    required=True,
+)
+@click.option("-n", "--name", "device_manager", default="devices")
+def describe(beamline: str, device_manager: str) -> None:
+    """Initialises a beamline module, gets the docs of all devices and prints them."""
+    os.environ["BEAMLINE"] = beamline
+
+    module_name = module_name_for_beamline(beamline)
+    full_module_path = f"dodal.beamlines.{module_name}"
+
+    print(f"Analysing {beamline} (using {full_module_path})")
+
+    mod = importlib.import_module(full_module_path)
+
+    if (manager := getattr(mod, device_manager, None)) and isinstance(
+        manager, DeviceManager
+    ):
+        factories = manager.get_all_factories()
+    else:
+        print(
+            f"No device manager named '{device_manager}' found in {mod}, convert the beamline to use device manager"
+        )
+        return
+
+    for device_name, factory in sorted(factories.items()):
+        print(f"{device_name}:")
+        print(factory.__doc__)
+        print("*****************************************")
+
+
 @main.command(name="connect")
 @click.argument(
     "beamline",
@@ -48,8 +82,8 @@ def main(ctx: click.Context) -> None:
 @click.option("-n", "--name", "device_manager", default="devices")
 def connect(beamline: str, all: bool, sim_backend: bool, device_manager: str) -> None:
     """Initialises a beamline module, connects to all devices, reports
-    any connection issues."""
-
+    any connection issues.
+    """
     os.environ["BEAMLINE"] = beamline
 
     # We need to make a fake path provider for any detectors that need one,

dodal/common/__init__.py

@@ -1,6 +1,6 @@
 from .coordination import group_uuid, inject
 from .enums import EnabledDisabledUpper, InOutUpper, OnOffUpper
-from .maths import in_micros, step_to_num
+from .maths import Rectangle2D, in_micros, step_to_num
 from .types import MsgGenerator, PlanGenerator
 
 __all__ = [
@@ -13,4 +13,5 @@ __all__ = [
     "MsgGenerator",
     "PlanGenerator",
     "step_to_num",
+    "Rectangle2D",
 ]

dodal/common/beamlines/beamline_parameters.py

@@ -63,7 +63,8 @@ class GDABeamlineParameters:
 
 def get_beamline_parameters(beamline_param_path: str | None = None):
     """Loads the beamline parameters from the specified path, or according to the
-    environment variable if none is given"""
+    environment variable if none is given.
+    """
     if not beamline_param_path:
         beamline_name = get_beamline_name("i03")
         beamline_param_path = BEAMLINE_PARAMETER_PATHS.get(beamline_name)

dodal/common/beamlines/beamline_utils.py

@@ -93,15 +93,17 @@ def device_instantiation(
     define lists of devices in beamline files. Additional keyword arguments are passed
     directly to the device constructor.
 
-    Arguments:
-        device_factory: Callable    the device class
-        name: str                   the name for ophyd
-        prefix: str                 the PV prefix for the most (usually all) components
-        wait: bool                  whether to run .wait_for_connection()
-        fake: bool                  whether to fake with ophyd.sim
-        post_create: Callable       (optional) a function to be run on the device after
-                                    creation
-        bl_prefix: bool             if true, add the beamline prefix when instantiating
+    Args:
+        device_factory (Callable): The device class.
+        name (str): The name for ophyd.
+        prefix (str): The PV prefix for the most (usually all) components.
+        wait (bool): Whether to run .wait_for_connection().
+        fake (bool): Whether to fake with ophyd.sim.
+        post_create (Callable): (optional) a function to be run on the device after
+            creation.
+        bl_prefix (bool): If true, add the beamline prefix when instantiating.
+        **kwargs: Arguments passed on to every device factory.
+
     Returns:
         The instance of the device.
     """

dodal/common/beamlines/commissioning_mode.py

@@ -15,7 +15,8 @@ _commissioning_signal: SignalR | None = None
 def read_commissioning_mode() -> MsgGenerator[bool]:
     """Utility method for reading the commissioning mode state from the context
     of a bluesky plan, where a baton may or may not be present, or
-    commissioning mode is provided by some other mechanism."""
+    commissioning mode is provided by some other mechanism.
+    """
     if _commissioning_signal:
         return (yield from bps.rd(_commissioning_signal))
     else:
@@ -26,8 +27,10 @@ def set_commissioning_signal(signal: SignalR[bool] | None):
     """Commissioning mode is enabled by a PV which when set enables commissioning mode.
     This allows beamline staff to ensure that commissioning mode is disabled prior
     to production use, via their own 'good morning' startup scripts.
+
     Args:
-        signal: The signal which will be read in order to determine whether
-        commissioning mode is enabled."""
+        signal (SignalR): The signal which will be read in order to determine whether
+            commissioning mode is enabled.
+    """
     global _commissioning_signal
     _commissioning_signal = signal

dodal/common/coordination.py

@@ -5,37 +5,35 @@ from dodal.common.types import Group
 
 
 def group_uuid(name: str) -> Group:
-    """
-    Returns a unique but human-readable string, to assist debugging orchestrated groups.
+    """Returns a unique but human-readable string, to assist debugging orchestrated
+    groups.
 
     Args:
-        name (str): A human readable name
+        name (str): A human readable name.
 
     Returns:
-        readable_uid (Group): name appended with a unique string
+        readable_uid (Group): Name appended with a unique string.
     """
     return f"{name}-{str(uuid.uuid4())[:6]}"
 
 
 def inject(name: str = "") -> Any:  # type: ignore
-    """
-    Function to mark a defaulted argument of a plan as a reference to a device stored
+    """Function to mark a defaulted argument of a plan as a reference to a device stored
     in another context and not available to be referenced directly.
+
     Bypasses type checking, returning x as Any and therefore valid as a default
-    argument, leaving handling to the context from which the plan is called.
-    Assumes that device.name is unique.
-    e.g. For a 1-dimensional scan, that is usually performed on a Movable with
-    name "stage_x"
+    argument, leaving handling to the context from which the plan is called. Assumes
+    that device.name is unique. e.g. For a 1-dimensional scan, that is usually performed
+    on a Movable with name "stage_x"::
 
-    def scan(x: Movable = inject("stage_x"), start: float = 0.0 ...)
+        def scan(x: Movable = inject("stage_x"), start: float = 0.0 ...)
 
     Args:
         name (str): Name of a Device to be fetched from an external context. This can be
-        left blank when injecting device composites (the default)
+            left blank when injecting device composites (the default).
 
     Returns:
-        Any: name but without typing checking, valid as any default type
+        Any: Name but without typing checking, valid as any default type.
 
     """
-
     return name

dodal/common/crystal_metadata.py

@@ -6,9 +6,7 @@ from typing import Literal
 
 @dataclass(frozen=True)
 class Material:
-    """
-    Class representing a crystalline material with a specific lattice parameter.
-    """
+    """Class representing a crystalline material with a specific lattice parameter."""
 
     name: str
     lattice_parameter: float  # Lattice parameter in meters
@@ -21,9 +19,8 @@ class MaterialsEnum(Enum):
 
 @dataclass(frozen=True)
 class CrystalMetadata:
-    """
-    Metadata used in the NeXus format,
-    see https://manual.nexusformat.org/classes/base_classes/NXcrystal.html
+    """Metadata used in the NeXus format,
+    see https://manual.nexusformat.org/classes/base_classes/NXcrystal.html.
     """
 
     usage: Literal["Bragg", "Laue"]
@@ -35,8 +32,8 @@ class CrystalMetadata:
     def calculate_default_d_spacing(
         lattice_parameter: float, reflection: tuple[int, int, int]
     ) -> tuple[float, str]:
-        """
-        Calculates the d-spacing value in nanometers based on the given lattice parameter and reflection indices.
+        """Calculates the d-spacing value in nanometers based on the given lattice
+        parameter and reflection indices.
         """
         h_index, k_index, l_index = reflection
         d_spacing_m = lattice_parameter / math.sqrt(

dodal/common/device_utils.py

@@ -19,11 +19,12 @@ async def periodic_reminder(
     """Periodically logs a message according to a schedule with increasing delays.
 
     Args:
-        message: The message the user wants to output through logging.
-        schedule: A tuple list of tuples consisting of (int|float, int|None).
+        message (str): The message the user wants to output through logging.
+        schedule (tuple): A tuple list of tuples consisting of (int|float, int|None).
             A sequence of (delay_seconds, count) pairs defining the logging intervals.
             - delay_seconds is the number of seconds to wait between logs.
-            - count is how many times to log at this interval. If count is None, it logs indefinitely at that delay.
+            - count is how many times to log at this interval. If count is None, it logs
+                indefinitely at that delay.
     """
 
     async def _log_loop():

dodal/common/maths.py

@@ -2,28 +2,24 @@ import numpy as np
 
 
 def step_to_num(start: float, stop: float, step: float) -> tuple[float, float, int]:
-    """
-    Standard handling for converting from start, stop, step to start, stop, num
-    Forces step to be same direction as length
+    """Standard handling for converting from start, stop, step to start, stop, num.
+    Forces step to be same direction as length.
     Includes a final point if it is within 1% of the final step, prevents floating
     point arithmatic errors from giving inconsistent shaped scans between steps of an
     outer axis.
 
     Args:
-        start (float):
-            Start of length, will be returned unchanged
-        stop (float):
-            End of length, if length/step does not divide cleanly will be returned
-            extended up to 1% of step, or else truncated.
-        step (float):
-            Length of a step along the line formed from start to stop.
-            If stop < start, will be coerced to be backwards.
+        start (float): Start of length, will be returned unchanged.
+        stop (float): End of length, if length/step does not divide cleanly will be
+            returned extended up to 1% of step, or else truncated.
+        step (float): Length of a step along the line formed from start to stop. If
+            stop < start, will be coerced to be backwards.
 
     Returns:
         start, adjusted_stop, num = Tuple[float, float, int]
-        start will be returned unchanged
-        adjusted_stop = start + (num - 1) * step
-        num is the maximal number of steps that could fit into the length.
+            - start will be returned unchanged.
+            - adjusted_stop = start + (num - 1) * step.
+            - num is the maximal number of steps that could fit into the length.
 
     """
     # Make step be the right direction
@@ -34,17 +30,89 @@ def step_to_num(start: float, stop: float, step: float) -> tuple[float, float, i
 
 
 def in_micros(t: float) -> int:
-    """
-    Converts between a positive number of seconds and an equivalent
+    """Converts between a positive number of seconds and an equivalent
     number of microseconds.
 
     Args:
-        t (float): A time in seconds
+        t (float): A time in seconds.
+
     Raises:
-        ValueError: if t < 0
+        ValueError: if t < 0.
+
     Returns:
-        t (int): A time in microseconds, rounded up to the nearest whole microsecond,
+        int: A time in microseconds, rounded up to the nearest whole microsecond.
     """
     if t < 0:
         raise ValueError(f"Expected a positive time in seconds, got {t!r}")
     return int(np.ceil(t * 1e6))
+
+
+class Rectangle2D:
+    """A 2D rectangle defined by two opposite corners.
+
+    This class represents a rectangle in 2D space using two points: (x1, y1) and (x2, y2).
+    It provides methods to query rectangle properties and check point containment.
+
+    Attributes:
+        x1 (float): The x-coordinate of the first corner.
+        y1 (float): The y-coordinate of the first corner.
+        x2 (float): The x-coordinate of the second corner.
+        y2 (float): The y-coordinate of the second corner.
+
+    Args:
+        x1 (float): The x-coordinate of the first corner.
+        y1 (float): The y-coordinate of the first corner.
+        x2 (float): The x-coordinate of the second corner.
+        y2 (float): The y-coordinate of the second corner.
+    """
+
+    def __init__(self, x1: float, y1: float, x2: float, y2: float):
+        self.x1, self.y1 = x1, y1
+        self.x2, self.y2 = x2, y2
+
+    def get_max_x(self) -> float:
+        """Get the maximum x-coordinate of the rectangle.
+
+        Returns:
+            float: The larger of the two x-coordinates (x1, x2).
+        """
+        return max(self.x1, self.x2)
+
+    def get_min_x(self) -> float:
+        """Get the minimum x-coordinate of the rectangle.
+
+        Returns:
+            float: The smaller of the two x-coordinates (x1, x2).
+        """
+        return min(self.x1, self.x2)
+
+    def get_max_y(self) -> float:
+        """Get the maximum y-coordinate of the rectangle.
+
+        Returns:
+            float: The larger of the two y-coordinates (y1, y2).
+        """
+        return max(self.y1, self.y2)
+
+    def get_min_y(self) -> float:
+        """Get the minimum y-coordinate of the rectangle.
+
+        Returns:
+            float: The smaller of the two y-coordinates (y1, y2).
+        """
+        return min(self.y1, self.y2)
+
+    def contains(self, x: float, y: float) -> bool:
+        """Check if a point is contained within the rectangle.
+
+        Args:
+            x (float): The x-coordinate of the point.
+            y (float): The y-coordinate of the point.
+
+        Returns:
+            bool: True if the point is within the rectangle bounds, False otherwise.
+        """
+        return (
+            self.get_min_x() <= x <= self.get_max_x()
+            and self.get_min_y() <= y <= self.get_max_y()
+        )

dodal/common/udc_directory_provider.py

@@ -16,7 +16,8 @@ class PandAFilenameProvider(FilenameProvider):
 
 class PandASubpathProvider(UpdatingPathProvider):
     """Directory provider for the HDFPanda. Points to a panda subdirectory within the
-    directory path provided"""
+    directory path provided.
+    """
 
     resource_dir = Path("panda")
 
@@ -34,13 +35,17 @@ class PandASubpathProvider(UpdatingPathProvider):
         return self._filename_provider.suffix or ""
 
     async def update(self, *, directory: Path, suffix: str = "", **kwargs):
-        """Update the root directory into which panda pcap files are written. This will result in the panda
-        subdirectory being created if it does not already exist.
-         Args:
-             directory: Path instance that identifies the root folder. This folder must exist. The panda will
-                attempt to write into the "panda" subdirectory which will be created if not already present.
-             suffix: Optional str that will be appended to the panda device name along with the file
-                type extension to construct the output filename
+        """Update the root directory into which panda pcap files are written. This will
+        result in the panda subdirectory being created if it does not already exist.
+
+        Args:
+            directory (Path): Instance that identifies the root folder. This folder must
+                exist. The panda will attempt to write into the "panda" subdirectory
+                which will be created if not already present.
+            suffix (str, optional): Optional str that will be appended to the panda
+                device name along with the file type extension to construct the output
+                filename.
+            **kwargs: Seemingly unused.
         """
         self._output_directory = directory / self.resource_dir
         self._filename_provider.suffix = suffix

dodal/common/visit.py

@@ -9,32 +9,29 @@ from pydantic import BaseModel, Field
 from dodal.common.types import UpdatingPathProvider
 from dodal.log import LOGGER
 
-"""
-Functionality required for/from the API of a DirectoryService which exposes the specifics of the Diamond filesystem.
-"""
+"""Functionality required for/from the API of a DirectoryService which exposes the
+specifics of the Diamond filesystem."""
 
 
 class DataCollectionIdentifier(BaseModel):
-    """
-    Equivalent to a `Scan Number` or `scan_id`, non-globally unique scan identifier.
-    Should be always incrementing, unique per-visit, co-ordinated with any other scan engines.
+    """Equivalent to a `Scan Number` or `scan_id`, non-globally unique scan identifier.
+    Should be always incrementing, unique per-visit, co-ordinated with any other scan
+    engines.
     """
 
     collection_number: int = Field(alias="collectionNumber")
 
 
 class DirectoryServiceClient(ABC):
-    """
-    Object responsible for I/O in determining collection number
-    """
+    """Object responsible for I/O in determining collection number."""
 
     @abstractmethod
     async def create_new_collection(self) -> DataCollectionIdentifier:
-        """Create new collection"""
+        """Create new collection."""
 
     @abstractmethod
     async def get_current_collection(self) -> DataCollectionIdentifier:
-        """Get current collection"""
+        """Get current collection."""
 
 
 class DiamondFilenameProvider(FilenameProvider):
@@ -50,9 +47,9 @@ class DiamondFilenameProvider(FilenameProvider):
 
 
 class RemoteDirectoryServiceClient(DirectoryServiceClient):
-    """Client for the VisitService REST API
+    """Client for the VisitService REST API.
     Currently exposed by the GDA Server to co-ordinate unique filenames.
-    While VisitService is embedded in GDA, url is likely to be `ixx-control:8088/api`
+    While VisitService is embedded in GDA, url is likely to be `ixx-control:8088/api`.
     """
 
     def __init__(self, url: str) -> None:
@@ -98,13 +95,15 @@ class LocalDirectoryServiceClient(DirectoryServiceClient):
 
 
 class StaticVisitPathProvider(UpdatingPathProvider):
-    """
-    Static (single visit) implementation of PathProvider whilst awaiting auth infrastructure to generate necessary information per-scan.
+    """Static (single visit) implementation of PathProvider whilst awaiting auth
+    infrastructure to generate necessary information per-scan.
     Allows setting a singular visit into which all run files will be saved.
-    update() queries a visit service to get the next DataCollectionIdentifier to increment the suffix of all file writers' next files.
+    update() queries a visit service to get the next DataCollectionIdentifier to
+    increment the suffix of all file writers' next files.
     Requires that all detectors are running with a mutual view on the filesystem.
-    Supports a single Visit which should be passed as a Path relative to the root of the Detector IOC mounting.
-    i.e. to write to visit /dls/ixx/data/YYYY/cm12345-1
+    Supports a single Visit which should be passed as a Path relative to the root of
+    the Detector IOC mounting.
+    i.e. to write to visit `/dls/ixx/data/YYYY/cm12345-1`.
     """
 
     def __init__(
@@ -123,9 +122,7 @@ class StaticVisitPathProvider(UpdatingPathProvider):
         self._session: ClientSession | None
 
     async def update(self, **kwargs) -> None:
-        """
-        Creates a new data collection in the current visit.
-        """
+        """Creates a new data collection in the current visit."""
         # https://github.com/DiamondLightSource/dodal/issues/452
         # TODO: Allow selecting visit as part of a request
         # TODO: DAQ-4827: Pass AuthN information as part of request

dodal/common/watcher_utils.py

@@ -55,22 +55,24 @@ def log_on_percentage_complete(
     message_prefix: str,
     percent_interval: int = 25,
 ):
-    """
-    Add watcher to a WatchableAsyncStatus status which will periodically log a message based on percentage completion
+    """Add watcher to a WatchableAsyncStatus status which will periodically log a
+    message based on percentage completion.
 
     Args:
-        status: A WatchableAsyncStatus. For example, Ophyd-async produces this status from a Motor.set method
-
-        message_prefix: The string at the start of each of the produced logging messages
-
-        percent_interval: How often to produce logging message, in terms of percentage completion
-        of the status.
+        status (WatchableAsyncStatus): For example, Ophyd-async produces this status
+            from a Motor.set method.
+        message_prefix (str): The string at the start of each of the produced logging
+            messages
+        percent_interval (int, optional): How often to produce logging message, in
+            terms of percentage completion of the status.
 
     Note that when using with Bluesky plan stubs you will need to cast the status (as of
-    Bluesky v1.14.2), since a Bluesky status doesn't use generics - see https://github.com/bluesky/bluesky/issues/1948.
+    Bluesky v1.14.2), since a Bluesky status doesn't use generics - see
+    https://github.com/bluesky/bluesky/issues/1948.
 
-    When running Bluesky plans using an interactive terminal, it is better to use the standard bluesky progress
-    bar instead of this function. See https://blueskyproject.io/bluesky/main/progress-bar.html#progress-bar
+    When running Bluesky plans using an interactive terminal, it is better to use the
+    standard bluesky progress bar instead of this function. See
+    https://blueskyproject.io/bluesky/main/progress-bar.html#progress-bar.
 
     Example usage within a Bluesky plan:
     yield from bps.kickoff(my_detector)
@@ -78,6 +80,5 @@ def log_on_percentage_complete(
     status = cast(WatchableAsyncStatus, status)
     log_on_percentage_complete(status, "Data collection triggers received", 10)
     yield from bps.wait("collection complete")
-
     """
     _LogOnPercentageProgressWatcher(status, message_prefix, percent_interval)