sgr-commhandler 0.4.dev20250512__tar.gz

sgr_commhandler-0.4.dev20250512/LICENSE.md

@@ -0,0 +1,14 @@
+Copyright(c) 2022 Verein SmartGridready Switzerland
+
+This Open Source Software is BSD 3 clause licensed:
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in 
+   the documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from 
+   this software without specific prior written permission.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sgr_commhandler-0.4.dev20250512/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.1
+Name: sgr-commhandler
+Version: 0.4.dev20250512
+Summary: SmartGridready CommHandler Library
+Home-page: https://github.com/SmartGridready/SGrPython/commhandler#readme
+Author: Robin Schoch, Matthias Krebs
+Maintainer: Matthias Krebs
+License: BSD-3-Clause
+Project-URL: Homepage, https://www.smartgridready.ch/
+Project-URL: Documentation, https://smartgridready.github.io/SGrPython/docs/commhandler/
+Project-URL: Repository, https://github.com/SmartGridready/SGrPython.git
+Project-URL: Issues, https://github.com/SmartGridready/SGrPython/issues
+Project-URL: Changelog, https://github.com/SmartGridready/SGrPython/blob/master/commhandler/CHANGELOG.md
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: Jinja2<4.0.0,>=3.0.0
+Requires-Dist: jmespath<2.0.0,>=1.0.0
+Requires-Dist: pymodbus<4.0.0,>=3.0.0
+Requires-Dist: setuptools<70.0.0,>=68.0.0
+Requires-Dist: xsdata<23.0.0,>=22.0.0
+Requires-Dist: xmlschema<4.0.0,>=3.0.0
+Requires-Dist: aiohttp<4.0.0,>=3.0.0
+Requires-Dist: certifi
+Requires-Dist: cachetools<6.0.0,>=5.0.0
+Requires-Dist: sgr-specification<3.0.0,>=2.1.0
+
+# SmartGridready CommHandler
+
+The _commhandler_ library provides the interfaces and drivers to access devices.
+
+
+## Contents
+
+- [Directory Structure](#directory-structure)
+- [Build Instructions](#build-instructions)
+
+
+## Directory Structure
+
+- `pyproject.toml` is the main project configuration file.
+- `setup.py` is used to build the library package using _setuptools_.
+- `requirements.txt` contains the dependencies required to use the library.
+- `requirements-dev.txt` contains the dependencies required to run tests.
+- `src/sgr_commhandler` contains the source code of the library, with _sgr_commhandler_ being the root of the namespace.
+- `tests` contains unit and integration tests.
+- `examples` contains basic examples of using the library.
+  See [SGrPythonSamples](https://github.com/SmartGridready/SGrPythonSamples) for more detailed examples.
+
+
+## Build Instructions
+
+### Prerequisites
+
+Check out the [SGrPython](https://github.com/SmartGridready/SGrPython) repository, e.g. in `SGrPython`.
+
+Create and activate virtual environment:
+
+```bash
+cd SGrPython
+python -m venv .venv
+
+# On Linux call this:
+source ./.venv/bin/activate
+
+# On Windows call this:
+.\.venv\Scripts\Activate.ps1
+```
+
+Make sure you have the _specification_ library `sgr-specification` installed in your virtual environment.
+See [specification](../specification/README.md) for instructions.
+
+
+### Run Tests
+
+You can run tests using `pytest` while in virtual environment.
+
+It is not necessary to install the package locally, if you only want to run tests.
+
+```bash
+cd SGrPython/commhandler
+pip install -r requirements-dev.txt
+
+pytest
+```
+
+
+### Build and Use Package
+
+Build package and install in virtual environment:
+
+```bash
+cd SGrPython/commhandler
+pip install -e .
+```
+
+You can use the package `sgr-commhandler` from within the virtual environment now.
+
+**Note:**
+The designated package name `sgr-commhandler` must not be used until the _PyPI_ administrators have
+approved a SmartGridready organization account!
+
+
+### Clean Up
+
+Deactivate the virtual environment after use:
+
+```bash
+cd SGrPython
+deactivate
+```

sgr_commhandler-0.4.dev20250512/README.md

@@ -0,0 +1,84 @@
+# SmartGridready CommHandler
+
+The _commhandler_ library provides the interfaces and drivers to access devices.
+
+
+## Contents
+
+- [Directory Structure](#directory-structure)
+- [Build Instructions](#build-instructions)
+
+
+## Directory Structure
+
+- `pyproject.toml` is the main project configuration file.
+- `setup.py` is used to build the library package using _setuptools_.
+- `requirements.txt` contains the dependencies required to use the library.
+- `requirements-dev.txt` contains the dependencies required to run tests.
+- `src/sgr_commhandler` contains the source code of the library, with _sgr_commhandler_ being the root of the namespace.
+- `tests` contains unit and integration tests.
+- `examples` contains basic examples of using the library.
+  See [SGrPythonSamples](https://github.com/SmartGridready/SGrPythonSamples) for more detailed examples.
+
+
+## Build Instructions
+
+### Prerequisites
+
+Check out the [SGrPython](https://github.com/SmartGridready/SGrPython) repository, e.g. in `SGrPython`.
+
+Create and activate virtual environment:
+
+```bash
+cd SGrPython
+python -m venv .venv
+
+# On Linux call this:
+source ./.venv/bin/activate
+
+# On Windows call this:
+.\.venv\Scripts\Activate.ps1
+```
+
+Make sure you have the _specification_ library `sgr-specification` installed in your virtual environment.
+See [specification](../specification/README.md) for instructions.
+
+
+### Run Tests
+
+You can run tests using `pytest` while in virtual environment.
+
+It is not necessary to install the package locally, if you only want to run tests.
+
+```bash
+cd SGrPython/commhandler
+pip install -r requirements-dev.txt
+
+pytest
+```
+
+
+### Build and Use Package
+
+Build package and install in virtual environment:
+
+```bash
+cd SGrPython/commhandler
+pip install -e .
+```
+
+You can use the package `sgr-commhandler` from within the virtual environment now.
+
+**Note:**
+The designated package name `sgr-commhandler` must not be used until the _PyPI_ administrators have
+approved a SmartGridready organization account!
+
+
+### Clean Up
+
+Deactivate the virtual environment after use:
+
+```bash
+cd SGrPython
+deactivate
+```

sgr_commhandler-0.4.dev20250512/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sgr-commhandler"
+dynamic = ["version"]
+description = "SmartGridready CommHandler Library"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "BSD-3-Clause" }
+authors = [
+    { name = "Robin Schoch" },
+    { name = "Matthias Krebs" }
+]
+maintainers = [
+    { name = "Matthias Krebs" }
+]
+dependencies = [
+    "Jinja2>=3.0.0,<4.0.0",
+    "jmespath>=1.0.0,<2.0.0",
+    "pymodbus>=3.0.0,<4.0.0",
+    "setuptools>=68.0.0,<70.0.0",
+    "xsdata>=22.0.0,<23.0.0",
+    "xmlschema>=3.0.0,<4.0.0",
+    "aiohttp>=3.0.0,<4.0.0",
+    "certifi",
+    "cachetools>=5.0.0,<6.0.0",
+    "sgr-specification>=2.1.0,<3.0.0"
+]
+
+[project.urls]
+Homepage = "https://www.smartgridready.ch/"
+Documentation = "https://smartgridready.github.io/SGrPython/docs/commhandler/"
+Repository = "https://github.com/SmartGridready/SGrPython.git"
+Issues = "https://github.com/SmartGridready/SGrPython/issues"
+Changelog = "https://github.com/SmartGridready/SGrPython/blob/master/commhandler/CHANGELOG.md"
+
+[tool.pyright]
+exclude = ["**/node_modules", "**/__pycache__", "examples"]
+
+[tool.pytest.ini_options]
+pythonpath = [ "src" ]
+asyncio_default_fixture_loop_scope = "session"
+asyncio_mode = "strict"
+log_cli = true
+log_cli_level = "DEBUG"

sgr_commhandler-0.4.dev20250512/setup.cfg

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

sgr_commhandler-0.4.dev20250512/setup.py

@@ -0,0 +1,26 @@
+from setuptools import setup, find_packages
+
+def read_requirements() -> list[str]:
+    with open("./requirements.txt", "r") as file:
+        return file.read().splitlines()
+
+setup(
+    name="sgr-commhandler",
+    version="0.4.dev20250512",
+    packages=find_packages(where="src"),
+    package_dir={"": "src"},
+    install_requires=read_requirements(),
+    url="https://github.com/SmartGridready/SGrPython/commhandler#readme",
+    project_urls={
+        "Issue Tracker": "https://github.com/SmartGridready/SGrPython/issues",
+        "Source": "https://github.com/SmartGridready/SGrPython",
+        "Docs": "https://smartgridready.github.io/SGrPython/docs/commhandler/"
+    },
+    license="BSD-3",
+    license_files=["LICENSE.md"],
+    author="Verein SmartGridready",
+    description="SGr Commhandler",
+    long_description="Communication Handler Library",
+    long_description_content_type="text/plain",
+    python_requires=">=3.9",
+)

sgr_commhandler-0.4.dev20250512/src/sgr_commhandler/api/__init__.py

@@ -0,0 +1,18 @@
+__all__ = [
+    "SGrBaseInterface",
+    "FunctionalProfile",
+    "DataPoint",
+    "DataPointProtocol",
+    "DataPointValidator",
+    "DeviceInformation",
+    "ConfigurationParameter",
+]
+
+from sgr_commhandler.api.configuration_parameter import ConfigurationParameter
+from sgr_commhandler.api.data_point_api import (
+    DataPoint,
+    DataPointProtocol,
+    DataPointValidator,
+)
+from sgr_commhandler.api.device_api import DeviceInformation, SGrBaseInterface
+from sgr_commhandler.api.functional_profile_api import FunctionalProfile

sgr_commhandler-0.4.dev20250512/src/sgr_commhandler/api/configuration_parameter.py

@@ -0,0 +1,71 @@
+from typing import Optional
+
+from sgr_specification.v0.product import (
+    ConfigurationList,
+    ConfigurationListElement,
+)
+
+
+def build_configuration_parameters(params: Optional[ConfigurationList]) -> list['ConfigurationParameter']:
+    """
+    Constructs a configuration parameter list.
+
+    Parameters
+    ----------
+    params : Optional[ConfigurationList]
+        The configuration list of an EID
+    
+    Returns
+    -------
+    list[ConfigurationParameter]
+        a list of configuration parameters
+    """
+    if params is None:
+        return []
+    return [
+        ConfigurationParameter(x) for x in params.configuration_list_element
+    ]
+
+
+class ConfigurationParameter:
+    """
+    Implements an EID configuration parameter.
+    """
+
+    def __init__(self, parameter: ConfigurationListElement):
+        """
+        Constructs a configuration parameter.
+
+        Parameters
+        ----------
+        parameter : ConfigurationListElement
+            A configuration list element of the SGr specification
+        """  
+        translation = parameter.configuration_description
+        self.label = translation[0].label
+        self.name = parameter.name
+        self.type = parameter.data_type
+        self.description = translation[0].text_element
+        self.default_value = parameter.default_value
+
+    def __str__(self) -> str:
+        """
+        Converts to string.
+
+        Returns
+        ----------
+        str
+            A string
+        """
+        return f'{self.label} - {self.name}'
+
+    def __repr__(self):
+        """
+        Gets an object description as string.
+
+        Returns
+        ----------
+        str
+            A string
+        """
+        return f'{self.label} - {self.name}'

sgr_commhandler-0.4.dev20250512/src/sgr_commhandler/api/data_point_api.py

@@ -0,0 +1,316 @@
+from asyncio import run
+from collections.abc import Callable
+from typing import Any, Generic, Protocol, TypeVar
+
+from sgr_specification.v0.generic import DataDirectionProduct, Units
+
+from sgr_commhandler.api.data_types import DataTypes
+
+"""Defines a generic data type."""
+T = TypeVar('T')
+
+
+class DataPointValidator(Protocol):
+    """
+    Defines an interface for data point validators.
+    """
+
+    def validate(self, value: Any) -> bool:
+        """
+        Validates the compatibility of a value.
+
+        Parameters
+        ----------
+        value : Any
+            the value to validate
+
+        Returns
+        -------
+        bool
+            true if value is compatible, false otherwise
+        """
+        ...
+
+    def data_type(self) -> DataTypes:
+        """
+        Gets the validator's data type.
+
+        Returns
+        -------
+        DataTypes
+            the data type enumeration
+        """
+        ...
+
+    def options(self) -> list[Any]:
+        """
+        Gets the validator's options.
+
+        Returns
+        -------
+        list[Any]
+            the options
+        """
+        return []
+
+
+class DataPointProtocol(Protocol):
+    """
+    Defines an interface for data point protocols.
+    """
+
+    async def set_val(self, value: Any):
+        """
+        Writes the data point value.
+
+        Parameters
+        ----------
+        value : Any
+            the data point value to write
+        """
+        ...
+
+    async def get_val(self, skip_cache: bool = False) -> Any:
+        """
+        Reads the data point value.
+
+        Parameters
+        ----------
+        skip_cache : bool
+            does not use cache if true
+        
+        Returns
+        -------
+        Any
+            the data point value
+        """
+        ...
+
+    def name(self) -> tuple[str, str]:
+        """
+        Gets the functional profile and data point names.
+
+        Returns
+        -------
+        tuple[str, str]
+            the functional profile and data point names as tuple
+        """
+        ...
+
+    def direction(self) -> DataDirectionProduct:
+        """
+        Gets the data direction of the data point.
+
+        Returns
+        -------
+        DataDirectionProduct
+            the data point direction
+        """
+        ...
+
+    def unit(self) -> Units:
+        """
+        Gets the unit of measurement of the data point.
+
+        Returns
+        -------
+        Units
+            the unit
+        """
+        ...
+
+    def can_subscribe(self) -> bool:
+        """
+        Defines if subscribe() is allowed.
+
+        Returns
+        -------
+        bool
+            True if allowed, False otherwise
+        """
+        return False
+
+    def subscribe(self, fn: Callable[[Any], None]):
+        """
+        Subscribes to changes of the data point value.
+
+        Parameters
+        ----------
+        fn : Callable[[Any], None]
+            the callback method
+        """
+        raise Exception('Unsupported operation')
+
+    def unsubscribe(self):
+        """
+        Unsubscribes from changes of the data point value.
+        """
+        raise Exception('Unsupported operation')
+
+
+class DataPoint(Generic[T]):
+    """
+    Implements a data point of a generic data type.
+    """
+
+    def __init__(
+        self, protocol: DataPointProtocol, validator: DataPointValidator
+    ):
+        """
+        Constructs a data point.
+
+        Parameters
+        ----------
+        protocol : DataPointProtocol
+            the underlying protocol
+        validator : DataPointValidator
+            the data point's value validator
+        """
+        self._protocol = protocol
+        self._validator = validator
+
+    def name(self) -> tuple[str, str]:
+        """
+        Gets the data point name.
+
+        Returns
+        -------
+        tuple[str, str]
+            the functional profile and data point name
+        """
+        return self._protocol.name()
+
+    async def get_value_async(self) -> T:
+        """
+        Gets the data point value asynchronously.
+
+        Returns
+        -------
+        T
+            the data point value
+        
+        Raises
+        ------
+        Exception
+            when read value is not compatible with data type
+        """
+        value = await self._protocol.get_val()
+        if self._validator.validate(value):
+            return value
+        raise Exception(
+            f'invalid value read from device, {value}, validator: {self._validator.data_type()}'
+        )
+
+    def get_value(self) -> T:
+        """
+        Gets the data point value synchronously.
+
+        Returns
+        -------
+        T
+            the data point value
+        
+        Raises
+        ------
+        Exception
+            when read value is not compatible with data type
+        """
+        return run(self.get_value_async())
+
+    async def set_value_async(self, value: T):
+        """
+        Sets the data point value asynchronously.
+
+        Parameters
+        ----------
+        value: T
+            the data point value
+        """
+        if self._validator.validate(value):
+            return await self._protocol.set_val(value)
+        raise Exception('invalid data to write to device')
+
+    def set_value(self, value: T):
+        """
+        Sets the data point value synchronously.
+
+        Parameters
+        ----------
+        value: T
+            the data point value
+        """
+        return run(self.set_value_async(value))
+
+    def subscribe(self, fn: Callable[[Any], None]):
+        """
+        Subscribes to data point value changes.
+
+        Parameters
+        ----------
+        fn : Callable[[Any], None]
+            the handler method
+        """
+        self._protocol.subscribe(fn)
+
+    def unsubscribe(self):
+        """
+        Unsubscribes from data point value changes.
+        """
+        self._protocol.unsubscribe()
+
+    def direction(self) -> DataDirectionProduct:
+        """
+        Gets the data point direction.
+
+        Returns
+        -------
+        DataDirectionProduct
+            the data point direction
+        """
+        return self._protocol.direction()
+
+    def data_type(self) -> DataTypes:
+        """
+        Gets the data point data type.
+
+        Returns
+        -------
+        DataTypes
+            the data point data type
+        """
+        return self._validator.data_type()
+    
+    def unit(self) -> Units:
+        """
+        Gets the unit of measurement of the data point.
+
+        Returns
+        -------
+        Units
+            the unit
+        """
+        return self._protocol.unit()
+
+    def describe(
+        self,
+    ) -> tuple[tuple[str, str], DataDirectionProduct, DataTypes, Units]:
+        """
+        Describes the data point.
+
+        Returns
+        -------
+        tuple[tuple[str, str], DataDirectionProduct, DataTypes, Units]
+            the data point information
+        """
+        return self.name(), self.direction(), self.data_type(), self.unit()
+
+    def options(self) -> list[Any]:
+        """
+        Describes the data point options.
+
+        Returns
+        -------
+        list[Any]
+            the data point options
+        """
+        return self._validator.options()