unitelabs-cdk 0.2.7__tar.gz

unitelabs_cdk-0.2.7/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.7/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.1
+Name: unitelabs-cdk
+Version: 0.2.7
+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.13
+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: python-dotenv (==1.0.1)
+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.7/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.7/pyproject.toml

@@ -0,0 +1,79 @@
+[tool.poetry]
+name = "unitelabs-cdk"
+version = "0.2.7"
+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"
+python-dotenv = "1.0.1"
+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.7/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.7/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.7/src/unitelabs/cdk/cli/certificate.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import pathlib
+
+import click
+import dotenv
+
+from sila import server
+from unitelabs.cdk import Config
+
+config = Config()
+
+
+@click.group()
+def certificate() -> None:
+    """Utility tool to handle certificates for TLS encryption."""
+
+    dotenv.load_dotenv()
+
+
+@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.7/src/unitelabs/cdk/cli/connector.py

@@ -0,0 +1,113 @@
+import importlib
+import importlib.machinery
+import importlib.metadata
+import importlib.util
+import logging
+import os
+import pathlib
+
+import click
+import dotenv
+
+from unitelabs.cdk import AppFactory, compose_app, utils
+
+
+class TLSConfigurationError(Exception):
+    pass
+
+
+@click.group()
+def connector() -> None:
+    """Base cli"""
+
+    dotenv.load_dotenv()
+
+
+@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(
+    "--tls/--no-tls",
+    required=False,
+    default=None,
+    envvar="SILA_SERVER__TLS",
+    help="Use TLS encryption. Alone, this will assume cert and key exist in `certificate.generate` default location.",
+)
+@click.option(
+    "-C",
+    "--cert",
+    required=False,
+    envvar="SILA_SERVER__CERT",
+    default=None,
+    help="The path to the certificate chain file, overriding .env setting of `SILA_SERVER__CERT`, default: ./cert.pem",
+)
+@click.option(
+    "-K",
+    "--key",
+    required=False,
+    envvar="SILA_SERVER__KEY",
+    default=None,
+    help="The path to the private key file, overriding .env setting of `SILA_SERVER__KEY`, default: ./key.pem",
+)
+@click.option(
+    "-v",
+    "--verbose",
+    count=True,
+    help="Increase the verbosity of to debug.",
+)
+@utils.coroutine
+async def start(app, tls, cert, key, verbose: int):
+    """Application Entrypoint."""
+    if tls is not None:
+        os.environ["SILA_SERVER__TLS"] = str(tls)
+
+    if tls:
+        cert = pathlib.Path(cert) if cert else pathlib.Path("./cert.pem")
+        key = pathlib.Path(key) if key else pathlib.Path("./key.pem")
+        cert = cert.resolve()
+        key = key.resolve()
+
+        msg = ""
+        if not cert.exists():
+            msg += f"Certificate file at {cert} does not exist. Specify path with --cert. "
+
+        if not key.exists():
+            msg += f"Private key file at {key} does not exist. Specify path with --key."
+
+        if msg:
+            raise TLSConfigurationError(msg)
+
+        os.environb[b"SILA_SERVER__CERT"] = cert.read_bytes()
+        os.environb[b"SILA_SERVER__KEY"] = key.read_bytes()
+
+    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.7/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.7/src/unitelabs/cdk/config.py

@@ -0,0 +1,13 @@
+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()