unitelabs-cdk 0.2.4__tar.gz

unitelabs_cdk-0.2.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 UniteLabs
+
+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.

unitelabs_cdk-0.2.4/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.1
+Name: unitelabs-cdk
+Version: 0.2.4
+Summary: A framework to develop UniteLabs connectors based on the SiLA 2 standard specification.
+Home-page: https://unitelabs.io
+License: MIT
+Keywords: UniteLabs,SiLA 2,laboratory,automation,connectivity
+Author: UniteLabs
+Author-email: developers+cdk@unitelabs.io
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: click (==8.1.7)
+Requires-Dist: pydantic_settings (==2.1.0)
+Requires-Dist: unitelabs-sila (==0.1.5)
+Project-URL: Bug Tracker, https://gitlab.com/unitelabs/dev-tools/python-cdk/-/issues
+Project-URL: Documentation, https://gitlab.com/unitelabs/dev-tools/python-cdk/-/tree/main/docs/
+Project-URL: Repository, https://gitlab.com/unitelabs/dev-tools/python-cdk
+Description-Content-Type: text/markdown
+
+# UniteLabs Connector Framework
+
+The UniteLabs Connector Framework is a free and open-source framework that enables you to build connectors for
+laboratory hard- and software systems with interfaces that are based on industry standards like
+[SiLA 2](https://sila-standard.com). If you plan on implementing an interface natively for your device or as wrapper
+around an existing proprietary interface, you can use this framework to get it built quickly without deep-diving into
+the standard specifications with our intuitive, code-first approach. It provides configurable modules you can use to
+quickly integrate the hardware or software you want to connect.
+
+## Installation
+
+[<img src="https://img.shields.io/badge/python-≥3.9.2-0052FF.svg?logo=LOGO&amp;labelColor=090422">](LINK)
+[<img src="https://img.shields.io/badge/poetry-≥1.3.1-0052FF.svg?logo=LOGO&amp;labelColor=090422">](LINK)
+
+The UniteLabs Connector Framework requires Python 3.9 or later. To get started quickly, we recommend to clone one of the
+starter projects with:
+
+```
+$ git clone --depth 1 https://gitlab.com/unitelabs/connector-starter.git <my-connector-name>
+$ cd <my-connector-name>
+$ poetry install
+$ poetry run connector start
+```
+
+You can also manually create a new project from scratch and [install the framework](docs/1.get-started/2.installation.md)
+with pip. In this case, of course, you'll be responsible for creating the project boilerplate files yourself.
+
+```
+$ pip install unitelabs-connector-framework
+```
+
+## Documentation
+
+Explor the UniteLabs [Connector Development Kit documentation](https://docs-unitelabs-web-815d69b03b66df4c3a4817af38d7e7b09a17f7c4b50b.gitlab.io/connectivity/overview) 
+on our docs page. From there you can find your way to the tutorials and guides.
+
+## Contribute
+
+There are many ways to contribute to this project and our vision of freely and readily available interfaces for laboratory systems.
+
+- Check out our [contribution guidelines](docs/6.community/1.contributing.md) to help us improve this project
+- Join the over 400 developers in the [SiLA Slack community](https://sila-standard.org/slack)
+- Give back to the community and add your connectors to the [UniteHub](https://hub.unitelabs.io) by sending us an
+  [email](mailto:connectors@unitelabs.io)!
+- Get in touch with our developers regarding feedback and feature requests at [developers@unitelabs.io](mailto:developers@unitelabs.io)
+- Give us a ⭐️ on [GitLab](https://gitlab.com/unitelabs/dev-tools/python-cdk)
+
+## License
+
+We, UniteLabs, provide and maintain this free and open-source framework with the aim to enable the community to overcome
+any barriers in digitalizing their laboratory environment. We highly appreciate, if the users of this framework value
+the same principles. Therefore, if you want to make your connectors available for others, we encourage you to share them
+on our sharing platform, the [UniteHub](https://hub.unitelabs.io). As we do not want to enforce disclosure of your work,
+we distribute this framework under the [MIT license](LICENSE).
+

unitelabs_cdk-0.2.4/README.md

@@ -0,0 +1,54 @@
+# UniteLabs Connector Framework
+
+The UniteLabs Connector Framework is a free and open-source framework that enables you to build connectors for
+laboratory hard- and software systems with interfaces that are based on industry standards like
+[SiLA 2](https://sila-standard.com). If you plan on implementing an interface natively for your device or as wrapper
+around an existing proprietary interface, you can use this framework to get it built quickly without deep-diving into
+the standard specifications with our intuitive, code-first approach. It provides configurable modules you can use to
+quickly integrate the hardware or software you want to connect.
+
+## Installation
+
+[<img src="https://img.shields.io/badge/python-≥3.9.2-0052FF.svg?logo=LOGO&amp;labelColor=090422">](LINK)
+[<img src="https://img.shields.io/badge/poetry-≥1.3.1-0052FF.svg?logo=LOGO&amp;labelColor=090422">](LINK)
+
+The UniteLabs Connector Framework requires Python 3.9 or later. To get started quickly, we recommend to clone one of the
+starter projects with:
+
+```
+$ git clone --depth 1 https://gitlab.com/unitelabs/connector-starter.git <my-connector-name>
+$ cd <my-connector-name>
+$ poetry install
+$ poetry run connector start
+```
+
+You can also manually create a new project from scratch and [install the framework](docs/1.get-started/2.installation.md)
+with pip. In this case, of course, you'll be responsible for creating the project boilerplate files yourself.
+
+```
+$ pip install unitelabs-connector-framework
+```
+
+## Documentation
+
+Explor the UniteLabs [Connector Development Kit documentation](https://docs-unitelabs-web-815d69b03b66df4c3a4817af38d7e7b09a17f7c4b50b.gitlab.io/connectivity/overview) 
+on our docs page. From there you can find your way to the tutorials and guides.
+
+## Contribute
+
+There are many ways to contribute to this project and our vision of freely and readily available interfaces for laboratory systems.
+
+- Check out our [contribution guidelines](docs/6.community/1.contributing.md) to help us improve this project
+- Join the over 400 developers in the [SiLA Slack community](https://sila-standard.org/slack)
+- Give back to the community and add your connectors to the [UniteHub](https://hub.unitelabs.io) by sending us an
+  [email](mailto:connectors@unitelabs.io)!
+- Get in touch with our developers regarding feedback and feature requests at [developers@unitelabs.io](mailto:developers@unitelabs.io)
+- Give us a ⭐️ on [GitLab](https://gitlab.com/unitelabs/dev-tools/python-cdk)
+
+## License
+
+We, UniteLabs, provide and maintain this free and open-source framework with the aim to enable the community to overcome
+any barriers in digitalizing their laboratory environment. We highly appreciate, if the users of this framework value
+the same principles. Therefore, if you want to make your connectors available for others, we encourage you to share them
+on our sharing platform, the [UniteHub](https://hub.unitelabs.io). As we do not want to enforce disclosure of your work,
+we distribute this framework under the [MIT license](LICENSE).

unitelabs_cdk-0.2.4/pyproject.toml

@@ -0,0 +1,78 @@
+[tool.poetry]
+name = "unitelabs-cdk"
+version = "0.2.4"
+description = "A framework to develop UniteLabs connectors based on the SiLA 2 standard specification."
+license = "MIT"
+authors = ["UniteLabs <developers+cdk@unitelabs.io>"]
+readme = "README.md"
+homepage = "https://unitelabs.io"
+repository = "https://gitlab.com/unitelabs/dev-tools/python-cdk"
+documentation = "https://gitlab.com/unitelabs/dev-tools/python-cdk/-/tree/main/docs/"
+keywords = ["UniteLabs", "SiLA 2", "laboratory", "automation", "connectivity"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Healthcare Industry",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+packages = [{ include = "unitelabs", from = "src" }]
+
+[tool.poetry.urls]
+"Bug Tracker" = "https://gitlab.com/unitelabs/dev-tools/python-cdk/-/issues"
+
+[tool.poetry.scripts]
+certificate = 'unitelabs.cdk.cli:certificate'
+connector = 'unitelabs.cdk.cli:connector'
+
+[tool.poetry.dependencies]
+python = "^3.9"
+click = "8.1.7"
+pydantic_settings = "2.1.0"
+unitelabs-sila = {version = "0.1.5", source = "unitelabs"}
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.5.1"
+pytest = "7.4.4"
+pytest-asyncio = "0.23.3"
+pytest-cov = "4.1.0"
+unitelabs-jsondocs = { version="0.1.1", source="unitelabs" }
+
+
+[[tool.poetry.source]]
+name = "unitelabs"
+url = "https://gitlab.com/api/v4/groups/1009252/-/packages/pypi/simple"
+priority = "supplemental"
+
+[tool.ruff]
+src = ["src", "tests"]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["test"]
+asyncio_mode = "auto"
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "@typing.overload",
+]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

unitelabs_cdk-0.2.4/src/unitelabs/cdk/__init__.py

@@ -0,0 +1,9 @@
+from importlib.metadata import version
+
+from .compose_app import AppFactory, compose_app
+from .config import Config
+from .connector import Connector
+from .logging import create_logger
+
+__version__ = version("unitelabs_cdk")
+__all__ = ["__version__", "Connector", "Config", "create_logger", "compose_app", "AppFactory"]

unitelabs_cdk-0.2.4/src/unitelabs/cdk/cli/__init__.py

@@ -0,0 +1,4 @@
+from .certificate import certificate
+from .connector import connector
+
+__all__ = ["certificate", "connector"]

unitelabs_cdk-0.2.4/src/unitelabs/cdk/cli/certificate.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import pathlib
+
+import click
+from sila import server
+
+from unitelabs.cdk import Config
+
+config = Config()
+
+
+@click.group()
+def certificate() -> None:
+    """Utility tool to handle certificates for TLS encryption."""
+
+
+@certificate.command()
+@click.option(
+    "--uuid",
+    type=str,
+    default=config.sila_server.get("uuid", None),
+    required=True,
+    help="The SiLA server's uuid.",
+)
+@click.option(
+    "--host",
+    type=str,
+    default=lambda: config.sila_server.get("host", "0.0.0.0"),
+    help="The SiLA server's host address.",
+)
+@click.option(
+    "--target",
+    "-t",
+    type=str,
+    default=".",
+    help="The output directory in which to store the certificate files.",
+)
+def generate(uuid: str, host: str, target: str):
+    """Generates a new self-signed certificate according to the SiLA 2 specification."""
+    key, cert = server.generate_certificate(uuid, host)
+
+    directory = pathlib.Path(target)
+    directory.mkdir(parents=True, exist_ok=True)
+    (directory / "cert.pem").write_bytes(cert)
+    (directory / "key.pem").write_bytes(key)
+
+
+if __name__ == "__main__":
+    certificate()

unitelabs_cdk-0.2.4/src/unitelabs/cdk/cli/connector.py

@@ -0,0 +1,59 @@
+import importlib
+import importlib.machinery
+import importlib.metadata
+import importlib.util
+import logging
+
+import click
+
+from unitelabs.cdk import AppFactory, compose_app, utils
+
+
+@click.group()
+def connector() -> None:
+    """Base cli"""
+
+
+@connector.command()
+@click.option(
+    "--app",
+    type=str,
+    metavar="IMPORT",
+    default=utils.find_factory,
+    help="The application factory function to load, in the form 'module:name'.",
+)
+@click.option(
+    "-v",
+    "--verbose",
+    count=True,
+    help="Increase the verbosity of to debug.",
+)
+@utils.coroutine
+async def start(app, verbose: int):
+    """Application Entrypoint"""
+    log_level = logging.DEBUG if verbose > 0 else logging.INFO
+
+    create_app = await load_create_app(app)
+    app = await compose_app(create_app, log_level=log_level)
+
+    await app.start()
+
+
+async def load_create_app(location: str) -> AppFactory:
+    """
+    Dynamically import the application factory from the given location.
+
+    Args:
+      location: Where to find the app factory formatted as "module:name".
+    """
+
+    module_name, _, factory_name = location.partition(":")
+
+    module = importlib.import_module(module_name)
+    create_app = getattr(module, factory_name)
+
+    return create_app
+
+
+if __name__ == "__main__":
+    connector()

unitelabs_cdk-0.2.4/src/unitelabs/cdk/compose_app.py

@@ -0,0 +1,147 @@
+import collections.abc
+import functools
+import inspect
+import logging
+import signal
+import sys
+import types
+import typing
+
+from .connector import Connector
+from .logging import create_logger
+
+T = typing.TypeVar("T")
+
+
+Generator = typing.Union[
+    collections.abc.Generator[T, None, None],
+    collections.abc.AsyncGenerator[T, None],
+]
+
+
+AppFactory = collections.abc.Callable[
+    ...,
+    typing.Union[
+        Connector,
+        collections.abc.Awaitable[Connector],
+        Generator,
+    ],
+]
+
+
+async def compose_app(create_app: AppFactory, log_level: int = logging.INFO) -> Connector:
+    """
+    Creates and configures a ready to use Connector.
+
+    Args:
+      create_app: The factory method used to create the Connector instance.
+
+    Returns:
+      The newly created Connector.
+
+    Raises:
+      ValueError: If create_app does not follow the required interface.
+    """
+
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+
+    create_logger("sila", log_level)
+    create_logger("unitelabs", log_level)
+
+    app = await init_app(app_factory=create_app)
+
+    return app
+
+
+# pylint: disable-next=unused-argument
+def signal_handler(signum: int, frame: typing.Optional[types.FrameType]) -> None:
+    """
+    Gracefully handle received signals.
+
+    Args:
+      signum: The signal number.
+      frame: The current stack frame.
+    """
+
+    sys.exit(signum)
+
+
+async def init_app(app_factory: AppFactory) -> Connector:
+    """
+    Uses the provided factory method to init a new Connector.
+
+    Args:
+      app_factory: The factory method to call.
+
+    Returns:
+      The initialized Connector.
+
+    Raises:
+      ValueError: If app_factory does not follow the required interface.
+    """
+
+    if inspect.isasyncgenfunction(app_factory) or inspect.isgeneratorfunction(app_factory):
+        generator: Generator[Connector] = app_factory()
+        generator = _sync_to_async_gen(generator)
+
+        try:
+            app = await generator.__anext__()
+        except (StopAsyncIteration, StopIteration):
+            raise ValueError("Unable to create app: `create_app` did not yield a value.") from None
+
+        shutdown_handler = functools.partial(_shutdown_yield, generator)
+        app.on_shutdown(handler=shutdown_handler)
+
+        return app
+
+    if inspect.iscoroutinefunction(app_factory):
+        return await app_factory()
+
+    if inspect.isfunction(app_factory):
+        return app_factory()
+
+    raise ValueError(f"Invalid `create_app`: '{app_factory}'. Provide a callable function that returns a Connector.")
+
+
+async def _shutdown_yield(generator: collections.abc.AsyncGenerator[T, None]) -> None:
+    """
+    Execute the shutdown of a factory function by advancing the iterator
+    after the yield and ensure the iteration ends (if not it means there is
+    more than one yield in the function).
+
+    Args:
+      generator: The factory function to create the app.
+    """
+
+    try:
+        await generator.__anext__()
+    except (StopAsyncIteration, StopIteration):
+        pass
+    else:
+        await _shutdown_yield(generator)
+
+
+async def _sync_to_async_gen(generator: Generator[T]) -> collections.abc.AsyncGenerator[T, None]:
+    """
+    Wraps any generator into an async generator.
+
+    Args:
+      generator: The generator to wrap as async.
+
+    Returns:
+      The async generator.
+    """
+
+    if inspect.isasyncgen(generator):
+        async for item in generator:
+            yield item
+
+        return
+
+    if inspect.isgenerator(generator):
+        while True:
+            try:
+                yield next(generator)
+            except StopIteration:
+                return

unitelabs_cdk-0.2.4/src/unitelabs/cdk/config.py

@@ -0,0 +1,12 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from sila import cloud_connector, server
+
+
+class Config(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env", env_file_encoding="utf-8", env_nested_delimiter="__", extra="ignore"
+    )
+
+    environment: str = "development"
+    sila_server: server.ServerConfig = server.ServerConfig()
+    cloud_server_endpoint: cloud_connector.CloudServerEndpointConfig = cloud_connector.CloudServerEndpointConfig()

unitelabs_cdk-0.2.4/src/unitelabs/cdk/connector.py

@@ -0,0 +1,126 @@
+import asyncio
+import contextlib
+import logging
+import typing
+
+from sila import cloud_connector, discovery, server
+from unitelabs.cdk.features.core.sila_service import SiLAService
+
+from .config import Config
+
+Handler = typing.Callable[..., typing.Union[typing.Any, typing.Awaitable[typing.Any]]]
+
+
+class Connector:
+    """Main app"""
+
+    def __init__(self, config: typing.Optional[dict] = None):
+        self.__config = Config.parse_obj(config or {})
+
+        self._shutdown_handlers: list[Handler] = []
+
+        self._sila_server = server.Server(config=self.config.sila_server)
+        self.logger.debug(self._sila_server)
+        self._broadcaster = discovery.Broadcaster(self._sila_server)
+
+        self.config.cloud_server_endpoint["options"] = {
+            # The period (in milliseconds) after which a keepalive ping is sent on the transport.
+            "grpc.keepalive_time_ms": 60 * 1000,
+            # The amount of time (in milliseconds) the sender of the keepalive ping waits for an
+            # acknowledgement. If it does not receive an acknowledgment within this time, it will
+            # close the connection.
+            "grpc.keepalive_timeout_ms": 3 * 60 * 1000,
+            # If set to 1 (0 : false; 1 : true), allows keepalive pings to be sent even if there
+            # are no calls in flight.
+            "grpc.keepalive_permit_without_calls": 0,
+            # How many pings can the client send before needing to send a data/header frame.
+            "grpc.http2.max_pings_without_data": 0,
+        } | self.config.cloud_server_endpoint.get("options", {})
+
+        self._cloud_server_endpoint = cloud_connector.CloudServerEndpoint(
+            self._sila_server, self.config.cloud_server_endpoint
+        )
+
+        self.register(SiLAService())
+
+    def register(self, feature: server.Feature):
+        """Register a new feature to this driver"""
+        self.logger.debug("Added feature: %s", feature)
+        self._sila_server.add_feature(feature)
+
+    async def start(self):
+        """
+        Start the connector and all related services.
+        """
+
+        try:
+            await asyncio.gather(
+                asyncio.create_task(self._sila_server.start()),
+                asyncio.create_task(self._broadcaster.start()),
+                asyncio.create_task(self._cloud_server_endpoint.start()),
+            )
+        except asyncio.CancelledError:
+            pass
+        finally:
+            await self.close()
+
+    async def close(self):
+        """
+        Close the connector and all related services.
+        """
+
+        for shutdown_handler in self._shutdown_handlers:
+            with contextlib.suppress(Exception):
+                if asyncio.iscoroutinefunction(shutdown_handler):
+                    await shutdown_handler()
+                else:
+                    shutdown_handler()
+
+    @property
+    def config(self) -> Config:
+        return self.__config
+
+    @property
+    def sila_server(self) -> server.Server:
+        return self._sila_server
+
+    @property
+    def logger(self) -> logging.Logger:
+        """A standard Python :class:`~logging.Logger` for the app."""
+        return logging.getLogger(__package__)
+
+    @property
+    def debug(self) -> bool:
+        """Whether debug mode is enabled."""
+        return True
+
+    def on_shutdown(self, handler: Handler) -> None:
+        """
+        Add a shutdown hook to be called in the terminating phase (in response
+        to an explicit call to `app.close()` or upon receipt of system signals
+        such as SIGINT or SIGTERM).
+
+        Args:
+          handler: The method to be called on shutdown.
+
+        Raises:
+          TypeError: If the `handler` argument is not callable.
+        """
+
+        if not callable(handler):
+            raise TypeError("The `handler` argument must be callable.")
+
+        self._shutdown_handlers.append(handler)
+
+    def off_shutdown(self, handler: Handler) -> None:
+        """
+        Remove a previously added shutdown hook.
+
+        Args:
+          handler: The handler to be removed from the shutdown hooks.
+        """
+
+        try:
+            self._shutdown_handlers.remove(handler)
+        except ValueError:
+            pass