plesty-sdk 0.0.2.dev2__py3-none-any.whl

plesty_sdk-0.0.2.dev2.dist-info/licenses/COPYING.LESSER

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

plesty_sdk-0.0.2.dev2.dist-info/licenses/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

plestysdk/__init__.py

@@ -0,0 +1 @@
+"""Init."""

plestysdk/assets/docs-build-gitlab-ci.yml

@@ -0,0 +1,11 @@
+stages: [deploy]
+
+pages:
+  stage: deploy
+  rules:
+    - exists:
+      - "html/latest/"
+  script:
+    - echo "Serving documentation on GitLab pages..."
+  pages:
+    publish: html/latest

plestysdk/assets/ruff.toml

@@ -0,0 +1,11 @@
+line-length = 99
+src = ["src"]
+
+[lint]
+# errors, pyflake, warnings, docstring (pydocstyle)
+select = ["E", "F", "W", "D"]
+# as before in the script
+ignore = ["E203", "D401", "D205"]
+
+[lint.pydocstyle]
+convention = "google"

plestysdk/cache.py

@@ -0,0 +1,106 @@
+"""Cache management."""
+
+# Copyright (C) 2025, 2026 Christopher Borchers, fvrehlinger, Maximilian
+# Heller, Michael Zopf (names in alphabetic order wrt. surnames)
+#
+# This file is part of plesty-sdk which is part of the Plesty library.
+#
+# plesty-sdk is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option) any
+# later version.
+#
+# plesty-sdk is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License along
+# with plesty-sdk. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+import os
+import shutil
+from collections.abc import Callable
+from importlib import metadata
+from typing import ClassVar
+
+
+class CachedFile:
+    """Function decorator for defining cached (text) files with content generated at runtime.
+    This class also serves as a registry of files to be cached.
+    """
+
+    registry: ClassVar[list[CachedFile]] = []
+    """Registry of instanciated CachedFile objects."""
+    filename: str
+    """The path to the file to be cached, relative to the '.plesty' cache directory."""
+    content: Callable[[], str]
+    """The decorated function that generates the content of the cached file."""
+
+    def __init__(self, filename: str) -> None:
+        """Add the File object to the registry.
+
+        Args:
+            filename: The path to the file to be cached, relative to the '.plesty'
+                cache directory.
+        """
+        self.filename = filename
+        CachedFile.registry.append(self)
+
+    def __call__(self, content: Callable[[], str]) -> None:
+        """Apply the decorator to a function."""
+        self.content = content
+
+    def generate(self) -> None:
+        """Write the content of the cached file to disk."""
+        complete_file_path = os.path.join(os.getcwd(), '.plesty', self.filename)
+        os.makedirs(os.path.dirname(complete_file_path), exist_ok=True)
+        with open(complete_file_path, 'xt') as file:
+            file.write(self.content())
+
+    def is_correct(self) -> bool:
+        """Check whether the cached file is up-to-date by comparing the generated content
+        with the content of the existing file on disk.
+
+        Returns:
+            False, if the file does not exist on disk or its content is not up-to-date.
+            True otherwise.
+        """
+        complete_file_path = os.path.join(os.getcwd(), '.plesty', self.filename)
+        if not os.path.exists(complete_file_path):
+            return False
+        with open(complete_file_path, 'rt') as file:
+            existing_content = file.read()
+        if not existing_content == self.content():
+            return False
+        return True
+
+
+def ensure_cache() -> None:
+    """Ensure that the cache directory '.plesty' exists and that all files are
+    up-to-date. If not, (re)create the cache.
+    """
+    for file in CachedFile.registry:
+        if not file.is_correct():
+            break
+    else:
+        return
+
+    cache_dir_path = os.path.join(os.getcwd(), '.plesty')
+    if os.path.exists(cache_dir_path):
+        shutil.rmtree(cache_dir_path)
+    os.makedirs(cache_dir_path)
+    for file in CachedFile.registry:
+        file.generate()
+
+
+@CachedFile('.gitignore')
+def gitignore() -> str:
+    """This file causes the entire '.plesty' cache directory to be ignored by version control."""
+    return '*'
+
+
+@CachedFile('.sdk-version')
+def sdk_version() -> str:
+    """This file specifies the version number of the Plesty SDK used when creating the cache."""
+    return metadata.version('plesty-sdk')

plestysdk/cli.py

@@ -0,0 +1,32 @@
+"""CLI tool."""
+
+# Copyright (C) 2025, 2026 Christopher Borchers, fvrehlinger, Maximilian
+# Heller, Michael Zopf (names in alphabetic order wrt. surnames)
+#
+# This file is part of plesty-sdk which is part of the Plesty library.
+#
+# plesty-sdk is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option) any
+# later version.
+#
+# plesty-sdk is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License along
+# with plesty-sdk. If not, see <https://www.gnu.org/licenses/>.
+
+import click
+
+from plesty_sdk.commands.check import check_command
+from plesty_sdk.commands.docs import docs_command
+
+
+@click.group("plesty")
+def app():
+    """The Plesty CLI tool."""
+
+
+app.add_command(check_command)
+app.add_command(docs_command)

plestysdk/commands/check.py

@@ -0,0 +1,146 @@
+"""Check a module for plesty standard."""
+
+# Copyright (C) 2025, 2026 Christopher Borchers, fvrehlinger, Maximilian
+# Heller, Michael Zopf (names in alphabetic order wrt. surnames)
+#
+# This file is part of plesty-sdk which is part of the Plesty library.
+#
+# plesty-sdk is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option) any
+# later version.
+#
+# plesty-sdk is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License along
+# with plesty-sdk. If not, see <https://www.gnu.org/licenses/>.
+
+import asyncio
+import importlib
+import subprocess
+from importlib import resources
+from pathlib import Path
+from typing import Any, Literal
+
+import click
+from bluesky.protocols import Readable
+try:
+    from PySide6.QtWidgets import QWidget
+    PYSIDE6_IS_INSTALLED = True
+except ImportError:
+    PYSIDE6_IS_INSTALLED = False
+
+from plesty_sdk.context import ApplicationContext, pass_context
+
+
+@click.command(name="check", short_help="Check compliance with the Plesty standard.")
+@click.option(
+    "--standard",
+    help="...",
+    default="pixel",
+    type=click.Choice(["pixel", "nebula", "quantum"]),
+    show_choices=True,
+    show_default=True,
+)
+@click.option("--device", help="...", is_flag=True)
+@pass_context
+def check_command(
+    context: ApplicationContext, standard: Literal["pixel", "nebula", "quantum"], device: bool
+):
+    """..."""
+    # ruff
+    run_linter()
+
+    check_gui(standard, context.pyproject_toml)
+
+    if device:
+        check_device(standard, context.pyproject_toml)
+
+
+def check_gui(standard: Literal["pixel", "nebula", "quantum"], pyproject_toml: dict[str, Any]):
+    """Checks whether the module's GUI class, if present, is compatible with the standard."""
+    click.echo("Checking GUI requirements...")
+    project_name: str = pyproject_toml["project"]["name"]
+    module = importlib.import_module(project_name.replace("-", "_"))
+    try:
+        gui_class = getattr(module, "GUI")
+    except AttributeError:
+        click.echo("Module does not implement a GUI.")
+        return
+    match standard:
+        case "pixel":
+            click.echo("Check passed, no GUI specific requirements in standard pixel.")
+        case "nebula" | "quantum":
+            if not PYSIDE6_IS_INSTALLED:
+                raise click.ClickException(
+                    "PySide6 is not installed in the environment, but the GUI "
+                    "class is required to inherit from PySide6.QtWidgets.QtWidget "
+                    f"to be compatible with plesty standard {standard}."
+                )
+            if not issubclass(gui_class, QWidget):
+                raise click.ClickException(
+                    "GUI class does not inherit from PySide6.QtWidgets.QtWidget "
+                    f"required by plesty standard {standard}."
+                )
+            try:
+                if not callable(getattr(gui_class, "connect")):
+                    raise AttributeError
+            except AttributeError:
+                raise click.ClickException(
+                    "GUI class does not implement a connect method "
+                    f"required by plesty standard {standard}."
+                )
+            click.echo(f"Check passed for standard {standard}.")
+
+
+def check_device(standard: Literal["pixel", "nebula", "quantum"], pyproject_toml: dict[str, Any]):
+    """Checks whether the device has a Bluesky compatible interface."""
+    click.echo("Checking device specific requirements...")
+    match standard:
+        case "pixel":
+            click.echo("Check passed, no device specific requirements in standard pixel.")
+        case "nebula" | "quantum":
+            device_class = pyproject_toml["tool"]["plesty"]["device-class"]
+            project_name = pyproject_toml["project"]["name"]
+            module = importlib.import_module(project_name.replace("-", "_"))
+            device_instance = getattr(module, device_class)()
+            # check for compatibility with bluesky Readable
+            if not isinstance(device_instance, Readable):
+                raise click.ClickException(
+                    "Device class does not implement the 'Readable' protocol from Bluesky required"
+                    f"by standard {standard}."
+                )
+            # check for async connect method
+            if not asyncio.iscoroutinefunction(getattr(device_instance, "connect")):
+                raise click.ClickException(
+                    "Device class does not implement an asyncronous 'connect' functions requried"
+                    f"by plesty standard {standard}."
+                )
+            click.echo(f"Check passed for standard {standard}.")
+
+
+def run_linter():
+    """Run ruff linter.
+
+    Prints errors if checks are not fulfilled and exits.
+    Checks pyflakes, pycodestyle errors & warnings and pydocstyle.
+    Independent of standard level, as it needs to be fulfilled for every level.
+    """
+    pkg_root = resources.files("plesty_sdk")
+    config = pkg_root.joinpath("assets/ruff.toml")
+
+    repo_root = str(Path.cwd())
+    with resources.as_file(config) as config_path:
+        commands = [
+            ["ruff", "check", "--config", str(config_path), repo_root],
+            ["ruff", "format", "--check", "--config", str(config_path), repo_root],
+        ]
+
+        for cmd in commands:
+            p = subprocess.run(cmd, text=True, capture_output=True)
+            print(p.stdout)
+            print(p.stderr)
+            if p.returncode != 0:
+                raise SystemExit(p.returncode)