Version 0.0.1

.flake8

@@ -1,5 +1,5 @@
 [flake8]
-select = B,B9,C,D,DAR,E,F,N,RST,S,W
+select = B,B9,C,DAR,E,F,N,RST,S,W
 ignore = E203,E501,RST201,RST203,RST301,W503
 max-line-length = 80
 max-complexity = 10

.github/workflows/tests.yml

@@ -28,7 +28,7 @@ jobs:
           - { python: "3.10", os: "macos-latest", session: "tests" }
           - { python: "3.10", os: "ubuntu-latest", session: "typeguard" }
           - { python: "3.10", os: "ubuntu-latest", session: "xdoctest" }
-          - { python: "3.10", os: "ubuntu-latest", session: "docs-build" }
+          - { python: "3.6", os: "ubuntu-latest", session: "docs-build" }
 
     env:
       NOXSESSION: ${{ matrix.session }}

.gitignore

@@ -8,3 +8,4 @@
 /docs/_build/
 /src/*.egg-info/
 __pycache__/
+*ignore*

Makefile

@@ -0,0 +1,42 @@
+# Heps setup basic env development
+
+# poetry is required on your system
+# suggested installation method
+# or refer to official docs
+# https://python-poetry.org/docs/
+.PHONY: install-poetry
+install-poetry:
+	curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
+
+# install deve dependecis as sugested by coockicutter
+# https://cookiecutter-hypermodern-python.readthedocs.io/en/2021.11.26/quickstart.html
+.PHONY: install-dev
+install-dev:
+	pip install nox nox-poetry
+
+.PHONY: tests
+tests:	# run tests on lowest python interpreter
+	nox -r -s tests -p 3.6
+
+.PHONY: nox-36
+nox-36:	# runs nox with python 3.6
+	nox -p 3.6
+
+.PHONY: tests-dev
+tests-dev:
+	pytest -vv -s --exitfirst --failed-first --pdb tests/
+
+.PHONY: docs
+docs:	# runs and displays docs
+	#runs with py3.6 change the noxfile.py to use different interpreter version
+	nox -r -s docs
+
+
+.PHONY: codestyle
+codestyle:	# runs codestyle enforcement
+	isort .
+	black .
+
+.PHONY: mypy
+mypy: # runs mypy
+	nox -p 3.6 -r -s mypy

README.rst

@@ -42,12 +42,6 @@ Features
 * TODO
 
 
-Requirements
-------------
-
-* TODO
-
-
 Installation
 ------------
 
@@ -61,7 +55,7 @@ You can install *Osparc Control* via pip_ from PyPI_:
 Usage
 -----
 
-Please see the `Command-line Reference <Usage_>`_ for details.
+Please have a look at the examples folder.
 
 
 Contributing

codecov.yml

@@ -3,7 +3,7 @@ coverage:
   status:
     project:
       default:
-        target: "100"
+        target: "99"
     patch:
       default:
-        target: "100"
+        target: "99"

docs/conf.py

@@ -1,7 +1,6 @@
 """Sphinx configuration."""
 from datetime import datetime
 
-
 project = "Osparc Control"
 author = "Andrei Neagu"
 copyright = f"{datetime.now().year}, {author}"

docs/reference.rst

@@ -5,5 +5,18 @@ Reference
 osparc_control
 --------------
 
-.. automodule:: osparc_control
+.. autoclass:: osparc_control.ControlInterface
    :members:
+   :undoc-members:
+
+.. autoclass:: osparc_control.CommandManifest
+   :members:
+   :undoc-members:
+
+.. autoclass:: osparc_control.CommandParameter
+   :members:
+   :undoc-members:
+
+.. autoclass:: osparc_control.CommnadType
+   :members:
+   :undoc-members:

docs/usage.rst

@@ -1,6 +1,20 @@
 Usage
 =====
 
-.. click:: osparc_control.__main__:main
-   :prog: osparc-control
-   :nested: full
+Please have a look at the examples folder.
+
+
+Minimual examples
+=================
+
+In one terminal run ``python examples/basic/requester.py``:
+
+.. literalinclude:: ../examples/basic/requester.py
+   :language: python
+
+
+
+In a second terminal run ``python examples/basic/replyer.py``:
+
+.. literalinclude:: ../examples/basic/replyer.py
+   :language: python

examples/base_time_add/README.md

@@ -0,0 +1,8 @@
+# About
+
+This example consists of a `time_solver`. Which can add, the current time by a provided value.
+
+# Usage
+
+In one terminal run `sidecar_controller.py`.
+In a second terminal run `time_solver.py`. It will load data from the `sidecar_solver.py` to use when communicating with the `sidecar_controller.py`

examples/base_time_add/sidecar_controller.py

@@ -0,0 +1,37 @@
+from osparc_control import ControlInterface
+
+
+control_interface = ControlInterface(
+    remote_host="localhost", exposed_interface=[], remote_port=1234, listen_port=1235
+)
+control_interface.start_background_sync()
+
+# add_internal_time
+
+add_params = {"a": 10}
+print("Will add ", add_params)
+request_id = control_interface.request_with_delayed_reply(
+    "add_internal_time", params=add_params
+)
+
+has_result = False
+result = None
+while not has_result:
+    has_result, result = control_interface.check_for_reply(request_id=request_id)
+
+print("result of addition", result)
+
+# get_time
+
+print("getting solver time")
+solver_time = control_interface.request_with_immediate_reply("get_time", timeout=1.0)
+random_int = control_interface.request_with_immediate_reply(
+    "random_in_range", timeout=1.0, params={"a": 1, "b": 3}
+)
+print("solver time", solver_time)
+
+print("sending command to print internal status")
+control_interface.request_without_reply("print_status")
+
+
+control_interface.stop_background_sync()

examples/base_time_add/sidecar_solver.py

@@ -0,0 +1,36 @@
+from osparc_control import CommandManifest
+from osparc_control import CommandParameter
+from osparc_control import CommnadType
+from osparc_control import ControlInterface
+
+
+command_add = CommandManifest(
+    action="add_internal_time",
+    description="adds internal time to a provided paramter",
+    params=[
+        CommandParameter(name="a", description="param to add to internal time"),
+    ],
+    command_type=CommnadType.WITH_DELAYED_REPLY,
+)
+
+command_get_time = CommandManifest(
+    action="get_time",
+    description="gets the time",
+    params=[],
+    command_type=CommnadType.WITH_IMMEDIATE_REPLY,
+)
+
+command_print_solver_status = CommandManifest(
+    action="print_status",
+    description="prints the status of the solver",
+    params=[],
+    command_type=CommnadType.WITHOUT_REPLY,
+)
+
+
+control_interface = ControlInterface(
+    remote_host="localhost",
+    exposed_interface=[command_add, command_get_time, command_print_solver_status],
+    remote_port=1235,
+    listen_port=1234,
+)

examples/base_time_add/time_solver.py

@@ -0,0 +1,75 @@
+from time import sleep
+
+from sidecar_solver import command_add
+from sidecar_solver import command_get_time
+from sidecar_solver import command_print_solver_status
+from sidecar_solver import control_interface
+
+from osparc_control.core import ControlInterface
+from osparc_control.models import CommandRequest
+
+
+def handle_inputs(time_solver: "TimeSolver", request: CommandRequest) -> None:
+    if request.action == command_add.action:
+        sum_result = time_solver._add(**request.params)
+        time_solver.control_interface.reply_to_command(
+            request_id=request.request_id, payload=sum_result
+        )
+        return
+
+    if request.action == command_get_time.action:
+        time_solver.control_interface.reply_to_command(
+            request_id=request.request_id, payload=time_solver.time
+        )
+        return
+
+    if request.action == command_print_solver_status.action:
+        print("Solver internal status", time_solver)
+        # finally exit
+        time_solver.can_continue = False
+        return
+
+
+class TimeSolver:
+    def __init__(
+        self, initial_time: float, control_interface: ControlInterface
+    ) -> None:
+        self.time = initial_time
+        self.control_interface = control_interface
+
+        # internal time tick
+        self.sleep_internal: float = 0.1
+        self.can_continue: bool = True
+
+    def __repr__(self) -> str:
+        return (
+            f"<{self.__class__.__name__} time={self.time}, "
+            f"sleep_interval={self.sleep_internal}>"
+        )
+
+    def _add(self, a: float) -> float:
+        return self.time + a
+
+    def run(self) -> None:
+        """main loop of the solver"""
+        while self.can_continue:
+            # process incoming requests from remote
+            for request in self.control_interface.get_incoming_requests():
+                handle_inputs(time_solver=self, request=request)
+
+            # process internal stuff
+            self.time += 1
+            sleep(self.sleep_internal)
+
+
+def main() -> None:
+    control_interface.start_background_sync()
+
+    solver = TimeSolver(initial_time=0, control_interface=control_interface)
+    solver.run()
+
+    control_interface.stop_background_sync()
+
+
+if __name__ == "__main__":
+    main()

examples/basic/replyer.py

@@ -0,0 +1,42 @@
+import random
+import time
+
+from osparc_control import CommandManifest
+from osparc_control import CommandParameter
+from osparc_control import CommnadType
+from osparc_control import ControlInterface
+
+random_in_range_manifest = CommandManifest(
+    action="random_in_range",
+    description="gets the time",
+    params=[
+        CommandParameter(name="a", description="lower bound for random numbers"),
+        CommandParameter(name="b", description="upper bound for random numbers"),
+    ],
+    command_type=CommnadType.WITH_IMMEDIATE_REPLY,
+)
+
+control_interface = ControlInterface(
+    remote_host="localhost",
+    exposed_interface=[random_in_range_manifest],
+    remote_port=2346,
+    listen_port=2345,
+)
+control_interface.start_background_sync()
+
+wait_for_requests = True
+while wait_for_requests:
+    for command in control_interface.get_incoming_requests():
+        if command.action == random_in_range_manifest.action:
+            random_int = random.randint(  # noqa: S311
+                command.params["a"], command.params["b"]
+            )
+            control_interface.reply_to_command(
+                request_id=command.request_id, payload=random_int
+            )
+            wait_for_requests = False
+
+# allow for message to be delivered
+time.sleep(0.01)
+
+control_interface.stop_background_sync()

examples/basic/requester.py

@@ -0,0 +1,15 @@
+from osparc_control import ControlInterface
+
+control_interface = ControlInterface(
+    remote_host="localhost", exposed_interface=[], remote_port=2345, listen_port=2346
+)
+
+control_interface.start_background_sync()
+
+random_int = control_interface.request_with_immediate_reply(
+    "random_in_range", timeout=10.0, params={"a": 1, "b": 10}
+)
+print(random_int)
+assert 1 <= random_int <= 10  # noqa: S101
+
+control_interface.stop_background_sync()