lima2.client 1.0.9__tar.gz → 2.0rc2__tar.gz

{lima2_client-1.0.9/src/lima2.client.egg-info → lima2_client-2.0rc2}/PKG-INFO

@@ -1,21 +1,26 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: lima2.client
-Version: 1.0.9
+Version: 2.0rc2
 Summary: Python client library for Lima2 detector
-Home-page: https://gitlab.esrf.fr/limagroup/Lima2-client
+Home-page: https://gitlab.esrf.fr/limagroup/lima2-client
 Author: BCU (ESRF)
-License: LGPLv3
+License: MIT
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Description-Content-Type: text/markdown
-License-File: LICENCE
+License-File: LICENSE
 Requires-Dist: pytango
 Requires-Dist: gevent
 Requires-Dist: jsonschema
 Requires-Dist: jsonschema-default
 Requires-Dist: finite-state-machine
 Requires-Dist: beartype
+Requires-Dist: numpy
+Requires-Dist: pyyaml
+Requires-Dist: typing-extensions
+Provides-Extra: shell
+Requires-Dist: ipython; extra == "shell"
 
 # LImA 2 Client library
 
@@ -23,6 +28,31 @@ This project provides a Python interface to the LImA 2 distributed system.
 
 Checkout the [documentation here](https://limagroup.gitlab-pages.esrf.fr/lima2-client/).
 
+### Development setup
+
+In order to install lima2-client in a new conda environment:
+```sh
+conda create -n l2c -c esrf-bcu python pytango finite-state-machine
+pip install .
+```
+and, if you need the lima2-client shell:
+```sh
+pip install .[shell]
+```
+
+### Quickstart with blissdemo
+
+With `bliss-demo-servers` running, you can run an interactive Lima2 client shell to manipulate the
+Lima2 simulator devices and test the client API:
+
+```sh
+export TANGO_HOST="localhost:10000"  # Assuming you are running bliss-demo-servers locally
+lima2_shell
+```
+
+The `lima2_shell` utility instantiates a `Client` object using config from `l2c_config.yaml`,
+creates a set of default control, acquisition and processing parameters, and starts an ipython session.
+
 ### Bootstrapping the documentation
 
 The source for the documentation is in the `docs` folder. Here are the instructions to built and read it locally. The documentation is built with [Doxygen](http://www.doxygen.org/) and [Sphinx](http://www.sphinx-doc.org). The sphinx template is from [Sphinx Material](https://bashtage.github.io/sphinx-material/).
@@ -30,7 +60,7 @@ The source for the documentation is in the `docs` folder. Here are the instructi
 ```
     conda create -n doc --file docs/requirements.txt -c conda-forge
     conda activate doc
-    cd docs  
+    cd docs
     make html
 ```
 

lima2_client-2.0rc2/README.md

@@ -0,0 +1,43 @@
+# LImA 2 Client library
+
+This project provides a Python interface to the LImA 2 distributed system.
+
+Checkout the [documentation here](https://limagroup.gitlab-pages.esrf.fr/lima2-client/).
+
+### Development setup
+
+In order to install lima2-client in a new conda environment:
+```sh
+conda create -n l2c -c esrf-bcu python pytango finite-state-machine
+pip install .
+```
+and, if you need the lima2-client shell:
+```sh
+pip install .[shell]
+```
+
+### Quickstart with blissdemo
+
+With `bliss-demo-servers` running, you can run an interactive Lima2 client shell to manipulate the
+Lima2 simulator devices and test the client API:
+
+```sh
+export TANGO_HOST="localhost:10000"  # Assuming you are running bliss-demo-servers locally
+lima2_shell
+```
+
+The `lima2_shell` utility instantiates a `Client` object using config from `l2c_config.yaml`,
+creates a set of default control, acquisition and processing parameters, and starts an ipython session.
+
+### Bootstrapping the documentation
+
+The source for the documentation is in the `docs` folder. Here are the instructions to built and read it locally. The documentation is built with [Doxygen](http://www.doxygen.org/) and [Sphinx](http://www.sphinx-doc.org). The sphinx template is from [Sphinx Material](https://bashtage.github.io/sphinx-material/).
+
+```
+    conda create -n doc --file docs/requirements.txt -c conda-forge
+    conda activate doc
+    cd docs
+    make html
+```
+
+The html documentation is generated in `docs/.build/html`.

{lima2_client-1.0.9 → lima2_client-2.0rc2}/setup.cfg

@@ -4,11 +4,11 @@ author = BCU (ESRF)
 description = Python client library for Lima2 detector
 long_description = file: README.md
 long_description_content_type = text/markdown
-license = LGPLv3
-url = https://gitlab.esrf.fr/limagroup/Lima2-client
+license = MIT
+url = https://gitlab.esrf.fr/limagroup/lima2-client
 classifiers = 
 	Intended Audience :: Science/Research
-	License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+	License :: OSI Approved :: MIT License
 	Programming Language :: Python :: 3
 
 [options]
@@ -19,16 +19,33 @@ install_requires =
 	jsonschema-default
 	finite-state-machine
 	beartype
+	numpy
+	pyyaml
+	typing-extensions
 
 [options.entry_points]
 console_scripts = 
-	lima2_cli = lima2.client.cli:main
+	lima2_shell = lima2.client.shell:main [shell]
+
+[options.extras_require]
+shell = 
+	ipython
 
 [flake8]
 ignore = E501,W503,E203,W504,E251,E262,E265,E266,W291,W293
+per-file-ignores = 
+	src/lima2/client/shell.py:E402
 
 [tool:pytest]
+required_plugins = 
+	pytest-cov>=6.0.0
+	pytest-forked>=1.6.0
 addopts = -v --forked
+pythonpath = src
+
+[coverage:run]
+omit = 
+	src/lima2/client/shell.py
 
 [egg_info]
 tag_build = 

{lima2_client-1.0.9 → lima2_client-2.0rc2}/src/lima2/client/__init__.py

@@ -3,7 +3,7 @@
 # This file is part of the Lima2 project
 #
 # Copyright (c) 2020-2024 Beamline Control Unit, ESRF
-# Distributed under the MIT licence. See LICENSE for more info.
+# Distributed under the MIT license. See LICENSE for more info.
 
 """Lima2.Client package
 
@@ -13,6 +13,9 @@
     state_machine.State
 """
 
-from lima2.client.detector import Detector, CommError
+from lima2.client.client import Client
+from lima2.client.detector import CommError
 from lima2.client.state_machine import State
-from lima2.client.processing import Processing
+from lima2.client.pipeline import Pipeline
+
+__all__ = ["Client", "CommError", "State", "Pipeline"]

{lima2_client-1.0.9 → lima2_client-2.0rc2}/src/lima2/client/channel.py

@@ -3,7 +3,7 @@
 # This file is part of the Lima2 project
 #
 # Copyright (c) 2020-2024 Beamline Control Unit, ESRF
-# Distributed under the MIT licence. See LICENSE for more info.
+# Distributed under the MIT license. See LICENSE for more info.
 
 import numpy as np
 from abc import ABC, abstractmethod

lima2_client-2.0rc2/src/lima2/client/client.py

@@ -0,0 +1,276 @@
+# -*- coding: utf-8 -*-
+#
+# This file is part of the Lima2 project
+#
+# Copyright (c) 2020-2024 Beamline Control Unit, ESRF
+# Distributed under the MIT license. See LICENSE for more info.
+
+"""User-facing interface exposing Lima2's control and acquisition API.
+
+The role of the client is to connect the user to the Lima2 devices via Tango.
+
+The Client object instantiates a `Detector` object, allowing the user to control the acquisition
+via the standard prepare/start/stop sequence.
+
+The client hides away the topology by providing aggregated stats and counters in the form of
+`ProgressCounter` objects. If needed, these can be explored to trace the information back to
+individual receivers, for instance if one of them is stuck on a frame while the rest are still
+processing data.
+"""
+
+import os
+from uuid import UUID
+
+import tango as tg
+import yaml
+from beartype import beartype
+from typing_extensions import Any, Optional
+
+from lima2.client import pipelines, progress_counter, state_machine, topology
+from lima2.client.detector import Detector
+from lima2.client.pipeline import Pipeline
+from lima2.client.progress_counter import ProgressCounter, SingleCounter
+from lima2.client.topology import TopologyKind
+from lima2.client.utils import docstring_from
+
+
+@beartype
+class Client:
+    """Lima2 user-facing client."""
+
+    def __init__(
+        self,
+        ctl_dev: tg.DeviceProxy,
+        rcv_devs: list[tg.DeviceProxy],
+    ):
+        """Construct a Client given tango device proxies.
+
+        The Client can also be built from a yaml config file (see `from_yaml`).
+        The topology is queried from the control device properties.
+        """
+
+        self._detector = Detector(ctl_dev, *rcv_devs)
+
+        try:
+            # Get the topology property from control
+            topology_prop = ctl_dev.get_property("receiver_topology")
+            topology_name = topology_prop["receiver_topology"][0]
+            self.topology_kind = TopologyKind(topology_name)
+        except IndexError:
+            # Property does not exist
+            raise RuntimeError(
+                "Could not find 'receiver_topology' property in control device"
+            ) from None
+        except ValueError as e:
+            # Invalid topology (no matching name in Topology enum)
+            raise ValueError(
+                f"No matching topology type for {repr(topology_name)}"
+            ) from e
+
+        self.recv_devs = rcv_devs
+
+        # Cache of processing pipelines by uuid (see method `pipeline`)
+        self.__pipelines: dict[UUID, Pipeline] = {}
+
+        self.tango_db = tg.Database()
+
+    @classmethod
+    def from_yaml(
+        cls,
+        config_filename: str = "l2c_config.yaml",
+    ) -> "Client":
+        with open(os.path.abspath(config_filename)) as config_f:
+            # Raises on io/parsing error
+            config = yaml.safe_load(config_f)
+
+        ctl_url = config["ctl_url"]
+        rcv_urls = config["rcv_urls"]
+
+        ctl_dev = tg.DeviceProxy(ctl_url)
+        rcv_devs = [tg.DeviceProxy(url) for url in rcv_urls]
+
+        return Client(ctl_dev=ctl_dev, rcv_devs=rcv_devs)
+
+    @property
+    def detector(self) -> Detector:
+        return self._detector
+
+    ####################################################################################
+    # Detector properties
+    ####################################################################################
+
+    @property
+    @docstring_from(Detector.det_info)
+    def det_info(self) -> dict[str, Any]:
+        return self.detector.det_info
+
+    @property
+    @docstring_from(Detector.det_status)
+    def det_status(self) -> dict[str, Any]:
+        return self.detector.det_status
+
+    @property
+    @docstring_from(Detector.det_capabilities)
+    def det_capabilities(self) -> dict[str, Any]:
+        return self.detector.det_capabilities
+
+    @property
+    @docstring_from(Detector.state)
+    def state(self) -> state_machine.State:
+        return self.detector.state
+
+    @property
+    @docstring_from(Detector.params_default)
+    def params_default(self) -> dict[str, Any]:
+        return self.detector.params_default
+
+    ####################################################################################
+    # Control
+    ####################################################################################
+
+    def prepare_acq(
+        self, uuid: UUID, ctrl_params: dict, acq_params: dict, proc_params: dict
+    ) -> None:
+        """Prepare acquisition with a given uuid and set of params."""
+
+        # Adjust params for distributed acquisition
+        ctl, acq, proc = topology.distribute_acq(
+            ctl_params=ctrl_params,
+            acq_params=acq_params,
+            proc_params=proc_params,
+            num_receivers=len(self.recv_devs),
+        )
+
+        self.detector.prepare_acq(uuid, ctl, acq, proc)
+
+    @docstring_from(Detector.start_acq)
+    def start_acq(self) -> None:
+        self.detector.start_acq()
+
+    @docstring_from(Detector.trigger)
+    def trigger(self) -> None:
+        self.detector.trigger()
+
+    @docstring_from(Detector.stop_acq)
+    def stop_acq(self) -> None:
+        self.detector.stop_acq()
+
+    @docstring_from(Detector.reset_acq)
+    def reset_acq(self) -> None:
+        self.detector.reset_acq()
+
+    ####################################################################################
+    # Progress counters
+    ####################################################################################
+
+    @property
+    def nb_frames_acquired(self) -> ProgressCounter:
+        """Number of frames acquired"""
+        return ProgressCounter.from_single(
+            SingleCounter(
+                name="nb_frames_acquired",
+                value=self.detector.nb_frames_acquired,
+                source=self.detector.ctrl.name(),
+            )
+        )
+
+    @property
+    def nb_frames_xferred(self) -> ProgressCounter:
+        """Aggregated number of frames transferred"""
+        return progress_counter.aggregate(
+            [
+                SingleCounter(
+                    name="nb_frames_xferred",
+                    value=recv.nb_frames_xferred,
+                    source=recv.name(),
+                )
+                for recv in self.detector.recvs
+            ]
+        )
+
+    ####################################################################################
+    # Pipelines
+    ####################################################################################
+
+    @property
+    def pipelines(self) -> list[UUID]:
+        """Get list of available pipelines UUID"""
+        uuids = [recv.pipelines for recv in self.recv_devs]
+        if all(uuid is None for uuid in uuids):
+            return []
+        return [UUID(u) for u in {y for x in uuids for y in x}]
+
+    def pipeline(self, uuid: Optional[UUID] = None) -> Pipeline:
+        """Get a specific pipeline by uuid. Return the current one by default (uuid=None)"""
+        if uuid is None:
+            return self.current_pipeline
+
+        if uuid in self.__pipelines:
+            return self.__pipelines[uuid]
+
+        # uuid isn't in the local cache of pipelines: get it from Tango
+        instances = self.tango_db.get_device_exported(f"*/limaprocessing/{uuid}*")
+        if not instances:
+            raise ValueError(f"Pipeline not found in tango database: {uuid=}")
+
+        class_names = [
+            self.tango_db.get_device_info(instance).class_name for instance in instances
+        ]
+
+        # Select the pipeline according to the Tango class (Homogeneous processing for now)
+        pipeline_class = pipelines.get_class(tango_class_name=class_names[0])
+
+        # Note: sort list of pipeline instances by name such that pipelines are ordered
+        # by receiver index. This is necessary e.g. in a strict round-robin topology to
+        # be able to find a frame by index.
+        proc_devs = [tg.DeviceProxy(url) for url in sorted(list(instances))]
+
+        # Instantiate pipeline
+        self.__pipelines[uuid] = pipeline_class(uuid, proc_devs, self.topology_kind)
+
+        return self.__pipelines[uuid]
+
+    @property
+    def current_pipeline(self) -> Pipeline:
+        """Return the current pipeline as a Pipeline object.
+
+        Raises if no pipeline has been created, or if receivers disagree on the
+        current pipeline's uuid.
+        """
+        uuids: list[str] = [recv.current_pipeline for recv in self.recv_devs]
+
+        if all([uuid == "" for uuid in uuids]):
+            raise ValueError("No pipeline present in the tango database")
+
+        uuids: list[UUID] = [UUID(uuid) for uuid in uuids]
+
+        if not all([uuid == uuids[0] for uuid in uuids]):
+            raise ValueError(f"Inconsistent pipeline uuids on all receivers: {uuids=}")
+
+        return self.pipeline(uuids[0])
+
+    def erase_pipeline(self, uuid: UUID) -> None:
+        """Erase a pipeline instance"""
+        self.__pipelines.pop(uuid, None)
+        for recv in self.recv_devs:
+            recv.erasePipeline(str(uuid))
+
+    ####################################################################################
+    # Utility
+    ####################################################################################
+
+    def __repr__(self) -> str:
+        return "\n".join(
+            [
+                "Lima2 client",
+                f"State: {self.detector.state}",
+                "Controller:",
+                f" {self.detector.ctrl}",
+                f"Receivers ({self.topology_kind}):",
+                *[f" - {recv}" for recv in self.detector.recvs],
+                "Progress counters:",
+                f" - {self.nb_frames_acquired}",
+                f" - {self.nb_frames_xferred}",
+                str(self.current_pipeline) if self.__pipelines else "",
+            ]
+        )

{lima2_client-1.0.9 → lima2_client-2.0rc2}/src/lima2/client/convert.py

@@ -3,7 +3,7 @@
 # This file is part of the Lima2 project
 #
 # Copyright (c) 2020-2024 Beamline Control Unit, ESRF
-# Distributed under the MIT licence. See LICENSE for more info.
+# Distributed under the MIT license. See LICENSE for more info.
 
 """Convertion routines.