lima2.client 2.2.0__tar.gz → 2.2.1__tar.gz

lima2_client-2.2.1/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: lima2-client
+Version: 2.2.1
+Summary: Python client library for Lima2 detector
+Author: BCU (ESRF)
+License: Copyright (c) 2020-2024 Beamline Control Unit, ESRF
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+        
+Project-URL: Repository, https://gitlab.esrf.fr/limagroup/lima2-client
+Project-URL: Documentation, https://limagroup.gitlab-pages.esrf.fr/lima2-client/
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytango
+Requires-Dist: gevent
+Requires-Dist: jsonschema
+Requires-Dist: jsonschema-default
+Requires-Dist: beartype
+Requires-Dist: numpy
+Requires-Dist: pyyaml
+Requires-Dist: typing-extensions
+Requires-Dist: h5py
+Provides-Extra: dev
+Requires-Dist: black==22.3; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-pyyaml; extra == "dev"
+Requires-Dist: types-jsonschema; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: ipython; extra == "dev"
+Requires-Dist: pytango-db; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-forked; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinxcontrib-mermaid; extra == "docs"
+Requires-Dist: sphinxcontrib-napoleon; extra == "docs"
+Requires-Dist: sphinx-immaterial; extra == "docs"
+Requires-Dist: recommonmark; extra == "docs"
+Dynamic: license-file
+
+# 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==3.10 pytango pytango-db
+pip install .[dev]
+```
+The `dev` extra dependency adds linting, formatting, static analysis and testing tools.
+It also installs `ipython` required to run the `lima2_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-2.2.0 → lima2_client-2.2.1}/README.md

@@ -7,14 +7,13 @@ Checkout the [documentation here](https://limagroup.gitlab-pages.esrf.fr/lima2-c
 ### 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]
+conda create -n l2c -c esrf-bcu python==3.10 pytango pytango-db
+pip install .[dev]
 ```
+The `dev` extra dependency adds linting, formatting, static analysis and testing tools.
+It also installs `ipython` required to run the `lima2_shell`.
 
 ### Quickstart with blissdemo
 

lima2_client-2.2.1/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=45", "setuptools_scm[toml]>=6.2"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+version_scheme = "guess-next-dev"
+
+[project]
+name = "lima2-client"
+requires-python = ">= 3.9"
+dynamic = ["version"]
+authors = [{ name = "BCU (ESRF)" }]
+description = "Python client library for Lima2 detector"
+readme = "README.md"
+license = { file = "LICENSE" }
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "pytango",
+    "gevent",
+    "jsonschema",
+    "jsonschema-default",
+    "beartype",
+    "numpy",
+    "pyyaml",
+    "typing-extensions",
+    "h5py",
+]
+
+[project.urls]
+Repository = "https://gitlab.esrf.fr/limagroup/lima2-client"
+Documentation = "https://limagroup.gitlab-pages.esrf.fr/lima2-client/"
+
+[project.scripts]
+lima2_shell = "lima2.client.shell:main [dev]"
+
+[project.optional-dependencies]
+dev = [
+    "black==22.3",
+    "mypy",
+    "types-pyyaml",
+    "types-jsonschema",
+    "flake8",
+    "ipython",
+    "pytango-db",
+    "pytest",
+    "pytest-forked",
+    "pytest-asyncio",
+    "pytest-cov",
+]
+docs = [
+    "sphinx",
+    "sphinxcontrib-mermaid",
+    "sphinxcontrib-napoleon",
+    "sphinx-immaterial",
+    "recommonmark",
+]
+
+[tool.pytest.ini_options]
+addopts = "-v"
+testpaths = "tests"
+required_plugins = [
+    "pytest-cov>=6.0.0",
+    "pytest-forked>=1.6.0",
+    "pytest-asyncio>=0.25.3",
+]
+
+[tool.coverage.run]
+omit = ["src/lima2/client/shell.py"]

lima2_client-2.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lima2_client-2.2.1/src/finite_state_machine/__init__.py

@@ -0,0 +1,6 @@
+"""Lightweight, decorator-based implementation of a Finite State Machine"""
+
+__version__ = "0.5.0"
+
+
+from .state_machine import StateMachine, transition  # noqa

lima2_client-2.2.1/src/finite_state_machine/draw_state_diagram.py

@@ -0,0 +1,109 @@
+import argparse
+import importlib
+import inspect
+import os
+import sys
+from typing import List
+
+from finite_state_machine.state_machine import TransitionDetails
+
+
+def import_state_machine_class(path):  # pragma: no cover
+    """Load State Machine workflow class
+
+    Copied from https://packaging.python.org/specifications/entry-points/#data-model
+    """
+    modname, qualname_separator, qualname = path.partition(":")
+    obj = importlib.import_module(modname)
+    if qualname_separator:
+        for attr in qualname.split("."):
+            obj = getattr(obj, attr)
+    return obj
+
+
+def generate_state_diagram_markdown(cls, initial_state):
+    """Create State Diagram in Mermaid Markdown
+
+    https://mermaid-js.github.io/mermaid/diagrams-and-syntax-and-examples/stateDiagram.html
+    """
+
+    class_fns = inspect.getmembers(cls, predicate=inspect.isfunction)
+    state_transitions: List[TransitionDetails] = [
+        func._fsm for name, func in class_fns if hasattr(func, "_fsm")
+    ]
+
+    transition_template = "    {source} --> {target} : {name}\n"
+
+    all_state_transitions = []
+    for state_transition in state_transitions:
+        if isinstance(state_transition.source, list):
+            for src in state_transition.source:
+                t = transition_template.format(
+                    source=src,
+                    target=state_transition.target,
+                    name=state_transition.name,
+                )
+                all_state_transitions.append(t)
+
+                if state_transition.on_error:
+                    t = transition_template.format(
+                        source=src, target=state_transition.on_error, name="on_error"
+                    )
+                    all_state_transitions.append(t)
+        else:
+            t = transition_template.format(
+                source=state_transition.source,
+                target=state_transition.target,
+                name=state_transition.name,
+            )
+            all_state_transitions.append(t)
+
+            if state_transition.on_error:
+                t = transition_template.format(
+                    source=state_transition.source,
+                    target=state_transition.on_error,
+                    name="on_error",
+                )
+                all_state_transitions.append(t)
+
+        mermaid_markdown = "stateDiagram-v2\n"
+        if initial_state:
+            mermaid_markdown += f"    [*] --> {initial_state}\n"
+        for t in all_state_transitions:
+            mermaid_markdown += t
+
+    return mermaid_markdown
+
+
+def parse_args():  # pragma: no cover
+    description = "Create State Diagram for a State Machine"
+    parser = argparse.ArgumentParser(description=description)
+    parser.add_argument(
+        "--class",
+        type=str,
+        help="Path to State Machine class, e.g. importable.module:class",
+        required=True,
+    )
+    parser.add_argument(
+        "--initial_state",
+        type=str,
+        help="Initial state of State Machine",
+        required=False,
+    )
+    return vars(parser.parse_args())
+
+
+def main():  # pragma: no cover
+    args = parse_args()
+    class_path = args["class"]
+    initial_state = args["initial_state"]
+
+    sys.path.append(os.getcwd())
+    class_obj = import_state_machine_class(class_path)
+
+    markdown = generate_state_diagram_markdown(class_obj, initial_state)
+    print(markdown)
+
+
+if __name__ == "__main__":
+    main()

lima2_client-2.2.1/src/finite_state_machine/examples/async_github_pull_request.py

@@ -0,0 +1,46 @@
+from finite_state_machine import StateMachine, transition
+
+
+async def async_is_approved_or_is_admin(machine, user):
+    return machine.num_approvals >= 1 or user.is_admin
+
+
+def sync_is_approved_or_is_admin(machine, user):
+    return machine.num_approvals >= 1 or user.is_admin
+
+
+class GitHubPullRequest(StateMachine):
+    """State Machine to represent a GitHub Pull Request workflow"""
+
+    def __init__(self):
+        self.state = "opened"
+        self.num_approvals = 0
+        self.changes_request = False
+
+    @transition(source="opened", target="opened")
+    async def approve(self):
+        self.num_approvals += 1
+
+    @transition(source="opened", target="opened")
+    async def request_changes(self):
+        self.changes_request = True
+
+    @transition(source="opened", target="closed")
+    async def close_pull_request(self):
+        pass
+
+    @transition(
+        source="opened",
+        target="merged",
+        conditions=[async_is_approved_or_is_admin],
+    )
+    async def fully_async_merge_pull_request(self, user):
+        pass
+
+    @transition(
+        source="opened",
+        target="merged",
+        conditions=[sync_is_approved_or_is_admin],
+    )
+    async def async_merge_pull_request_with_sync_condition(self, user):
+        pass

lima2_client-2.2.1/src/finite_state_machine/examples/async_turnstile.py

@@ -0,0 +1,21 @@
+from finite_state_machine import StateMachine, transition
+
+
+class Turnstile(StateMachine):
+    initial_state = "close"
+
+    def __init__(self):
+        self.state = self.initial_state
+        super().__init__()
+
+    @transition(source=["close", "open"], target="open", on_error="error_state")
+    async def insert_coin(self):
+        return "inserted coin"
+
+    @transition(source="open", target="close")
+    async def pass_thru(self):
+        return "passed thru"
+
+    @transition(source="close", target="close", on_error="error_state")
+    async def error_function(self):
+        raise ValueError

lima2_client-2.2.1/src/finite_state_machine/examples/boolean_field.py

@@ -0,0 +1,22 @@
+from finite_state_machine import StateMachine, transition
+
+
+def account_in_good_standing(self):
+    return len(self.account.bills_outstanding) == 0
+
+
+class EnableFeatureStateMachine(StateMachine):
+    """Example state machine around a feature flag field"""
+
+    def __init__(self, account):
+        self.account = account
+        self.state = account.feature["enabled"]
+        super().__init__()
+
+    @transition(source=False, target=True, conditions=[account_in_good_standing])
+    def enable_feature(self):
+        pass
+
+    @transition(source=True, target=False)
+    def disable_feature(self):
+        pass

lima2_client-2.2.1/src/finite_state_machine/examples/github_pull_request.py

@@ -0,0 +1,30 @@
+from finite_state_machine import StateMachine, transition
+
+
+def is_approved_or_is_admin(machine, user):
+    return machine.num_approvals >= 1 or user.is_admin
+
+
+class GitHubPullRequest(StateMachine):
+    """State Machine to represent a GitHub Pull Request workflow"""
+
+    def __init__(self):
+        self.state = "opened"
+        self.num_approvals = 0
+        self.changes_request = False
+
+    @transition(source="opened", target="opened")
+    def approve(self):
+        self.num_approvals += 1
+
+    @transition(source="opened", target="opened")
+    def request_changes(self):
+        self.changes_request = True
+
+    @transition(source="opened", target="closed")
+    def close_pull_request(self):
+        pass
+
+    @transition(source="opened", target="merged", conditions=[is_approved_or_is_admin])
+    def merge_pull_request(self, user):
+        pass

lima2_client-2.2.1/src/finite_state_machine/examples/turnstile.py

@@ -0,0 +1,17 @@
+from finite_state_machine import StateMachine, transition
+
+
+class Turnstile(StateMachine):
+    initial_state = "close"
+
+    def __init__(self):
+        self.state = self.initial_state
+        super().__init__()
+
+    @transition(source=["close", "open"], target="open")
+    def insert_coin(self):
+        pass
+
+    @transition(source="open", target="close")
+    def pass_thru(self):
+        pass

lima2_client-2.2.1/src/finite_state_machine/exceptions.py

@@ -0,0 +1,13 @@
+class TransitionNotAllowed(Exception):
+    pass
+
+
+class InvalidStartState(TransitionNotAllowed):
+    pass
+
+
+class ConditionsNotMet(TransitionNotAllowed):
+    def __init__(self, conditions):
+        conditions_not_met = ", ".join(condition.__name__ for condition in conditions)
+        message = f"Following conditions did not return True: {conditions_not_met}"
+        super().__init__(message)

lima2_client-2.2.1/src/finite_state_machine/state_machine.py

@@ -0,0 +1,151 @@
+import asyncio
+from enum import Enum
+import functools
+import types
+from typing import NamedTuple, Union
+
+from .exceptions import ConditionsNotMet, InvalidStartState
+
+
+class StateMachine:
+    def __init__(self):
+        try:
+            self.state
+        except AttributeError:
+            raise ValueError("Need to set a state instance variable")
+
+
+class TransitionDetails(NamedTuple):
+    name: str
+    source: Union[list, bool, int, str]
+    target: Union[bool, int, str]
+    conditions: list
+    on_error: Union[bool, int, str]
+
+
+class transition:
+    def __init__(self, source, target, conditions=None, on_error=None, reraise=False):
+        allowed_types = (str, bool, int, Enum)
+
+        if isinstance(source, allowed_types):
+            source = [source]
+        if not isinstance(source, list):
+            raise ValueError("Source can be a bool, int, string, Enum, or list")
+        for item in source:
+            if not isinstance(item, allowed_types):
+                raise ValueError("Source can be a bool, int, string, Enum, or list")
+        self.source = source
+
+        if not isinstance(target, allowed_types):
+            raise ValueError("Target needs to be a bool, int or string")
+        self.target = target
+
+        if not conditions:
+            conditions = []
+        if not isinstance(conditions, list):
+            raise ValueError("conditions must be a list")
+        for condition in conditions:
+            if not isinstance(condition, types.FunctionType):
+                raise ValueError("conditions list must contain functions")
+        self.conditions = conditions
+
+        if on_error:
+            if not isinstance(on_error, allowed_types):
+                raise ValueError("on_error needs to be a bool, int or string")
+        self.on_error = on_error
+
+        self.reraise = reraise
+
+    def __call__(self, func):
+        func._fsm = TransitionDetails(
+            func.__name__,
+            self.source,
+            self.target,
+            self.conditions,
+            self.on_error,
+        )
+
+        @functools.wraps(func)
+        def sync_callable(*args, **kwargs):
+            try:
+                state_machine, rest = args
+            except ValueError:
+                state_machine = args[0]
+
+            if state_machine.state not in self.source:
+                exception_message = (
+                    f"Current state is {state_machine.state}. "
+                    f"{func.__name__} allows transitions from {self.source}."
+                )
+                raise InvalidStartState(exception_message)
+
+            conditions_not_met = []
+            for condition in self.conditions:
+                if condition(*args, **kwargs) is not True:
+                    conditions_not_met.append(condition)
+            if conditions_not_met:
+                raise ConditionsNotMet(conditions_not_met)
+
+            if not self.on_error:
+                result = func(*args, **kwargs)
+                state_machine.state = self.target
+                return result
+
+            try:
+                result = func(*args, **kwargs)
+                state_machine.state = self.target
+                return result
+            except Exception:
+                # TODO should we log this somewhere?
+                # logger.error? maybe have an optional parameter to set this up
+                # how to libraries log?
+                state_machine.state = self.on_error
+                return
+
+        @functools.wraps(func)
+        async def async_callable(*args, **kwargs):
+            try:
+                state_machine, rest = args
+            except ValueError:
+                state_machine = args[0]
+
+            if state_machine.state not in self.source:
+                exception_message = (
+                    f"Current state is {state_machine.state}. "
+                    f"{func.__name__} allows transitions from {self.source}."
+                )
+                raise InvalidStartState(exception_message)
+
+            conditions_not_met = []
+            for condition in self.conditions:
+                if asyncio.iscoroutinefunction(condition):
+                    condition_result = await condition(*args, **kwargs)
+                else:
+                    condition_result = condition(*args, **kwargs)
+                if condition_result is not True:
+                    conditions_not_met.append(condition)
+            if conditions_not_met:
+                raise ConditionsNotMet(conditions_not_met)
+
+            if not self.on_error:
+                result = await func(*args, **kwargs)
+                state_machine.state = self.target
+                return result
+
+            try:
+                result = await func(*args, **kwargs)
+                state_machine.state = self.target
+                return result
+            except Exception as e:
+                # TODO should we log this somewhere?
+                # logger.error? maybe have an optional parameter to set this up
+                # how to libraries log?
+                state_machine.state = self.on_error
+                if self.reraise:
+                    raise e
+                return
+
+        if asyncio.iscoroutinefunction(func):
+            return async_callable
+        else:
+            return sync_callable

{lima2_client-2.2.0 → lima2_client-2.2.1}/src/lima2/client/__init__.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-#
 # This file is part of the Lima2 project
 #
 # Copyright (c) 2020-2024 Beamline Control Unit, ESRF

{lima2_client-2.2.0 → lima2_client-2.2.1}/src/lima2/client/client.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-#
 # This file is part of the Lima2 project
 #
 # Copyright (c) 2020-2024 Beamline Control Unit, ESRF
@@ -241,10 +239,15 @@ class Client:
         # 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
+        # Note: sort list of pipeline instances by id in 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))]
+        def rcv_idx(name):
+            return int(name.split("@")[1])
+
+        proc_devs = [
+            tg.DeviceProxy(url) for url in sorted(list(instances), key=rcv_idx)
+        ]
 
         # Instantiate pipeline
         self.__pipelines[uuid] = pipeline_class(

{lima2_client-2.2.0 → lima2_client-2.2.1}/src/lima2/client/convert.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-#
 # This file is part of the Lima2 project
 #
 # Copyright (c) 2020-2024 Beamline Control Unit, ESRF

{lima2_client-2.2.0 → lima2_client-2.2.1}/src/lima2/client/detector.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-#
 # This file is part of the Lima2 project
 #
 # Copyright (c) 2020-2024 Beamline Control Unit, ESRF

{lima2_client-2.2.0 → lima2_client-2.2.1}/src/lima2/client/devencoded/__init__.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-#
 # This file is part of the Lima2 project
 #
 # Copyright (c) 2020-2024 Beamline Control Unit, ESRF