sgr-commhandler 0.4.dev20250512__py3-none-any.whl

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/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/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()

sgr_commhandler/api/data_types.py

@@ -0,0 +1,14 @@
+from enum import Enum
+
+
+class DataTypes(Enum):
+    """Defines the data point data types supported by the SGr specification."""
+
+    INT = "INT"
+    FLOAT = "FLOAT"
+    STRING = "STRING"
+    ENUM = "ENUM"
+    BOOLEAN = "BOOLEAN"
+    BITMAP = "BITMAP"
+    DATE_TIME = "DATE_TIME"
+    JSON = "JSON"

sgr_commhandler/api/device_api.py

@@ -0,0 +1,226 @@
+from asyncio import run
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from sgr_specification.v0.generic import DataDirectionProduct, DeviceCategory
+from sgr_specification.v0.product.product import DeviceFrame
+
+from sgr_commhandler.api import DataPoint
+from sgr_commhandler.api.configuration_parameter import (
+    ConfigurationParameter,
+    build_configuration_parameters,
+)
+from sgr_commhandler.api.data_types import DataTypes
+from sgr_commhandler.api.functional_profile_api import FunctionalProfile
+
+
+@dataclass
+class DeviceInformation:
+    """
+    Implements a device information container.
+
+    Attributes
+    ----------
+    name : str
+        Defines the device name
+    manufacturer : str
+        Defines the manufacturer's name
+    software_revision : str
+        Defines the device software version
+    hardware_revision : str
+        Defines the device hardware version
+    device_category : DeviceCategory
+        Defines the device category
+    is_local : bool
+        Defines if the device is controlled locally or via cloud
+    """
+    name: str
+    manufacturer: str
+    software_revision: str
+    hardware_revision: str
+    device_category: DeviceCategory
+    is_local: bool
+
+
+class SGrBaseInterface(Protocol):
+    """
+    Defines an abstract base class for all SGr device interfaces.
+
+    Attributes
+    ----------
+    device_frame : DeviceFrame
+        the device specification
+    configuration_parameters : list[ConfigurationParameter]
+        the configuration parameters with default values
+    device_information : DeviceInformation
+        the device information
+    functional_profiles : Mapping[str, FunctionalProfile]
+        the configured functional profiles
+    """
+    device_frame: DeviceFrame
+    configuration_parameters: list[ConfigurationParameter]
+    device_information: DeviceInformation
+    functional_profiles: Mapping[str, FunctionalProfile]
+
+    def _inititalize_device(
+        self, frame: DeviceFrame
+    ):
+        self.device_frame = frame
+        self.configuration_parameters = build_configuration_parameters(
+            frame.configuration_list
+        )
+        self.device_information = DeviceInformation(
+            name=frame.device_name if frame.device_name else '',
+            manufacturer=frame.manufacturer_name
+            if frame.manufacturer_name
+            else '',
+            software_revision=frame.device_information.software_revision
+            if frame.device_information
+            and frame.device_information.software_revision
+            else '',
+            hardware_revision=frame.device_information.hardware_revision
+            if frame.device_information
+            and frame.device_information.hardware_revision
+            else '',
+            device_category=frame.device_information.device_category
+            if frame.device_information
+            and frame.device_information.device_category
+            else DeviceCategory.DEVICE_INFORMATION,
+            is_local=frame.device_information.is_local_control
+            if frame.device_information
+            and frame.device_information.is_local_control
+            else False,
+        )
+
+    def connect(self):
+        """
+        Connects the device synchronously.
+        """
+        run(self.connect_async())
+
+    async def connect_async(self):
+        """
+        Connects the device asynchronously.
+        """
+        ...
+
+    def disconnect(self):
+        """
+        Disconnects the device synchronously.
+        """
+        run(self.disconnect_async())
+
+    async def disconnect_async(self):
+        """
+        Disconnects the device asynchronously.
+        """
+        ...
+
+    def is_connected(self) -> bool:
+        """
+        Gets the connection state.
+
+        Returns
+        -------
+        bool
+            the connection state
+        """
+        ...
+
+    def get_functional_profile(
+        self, functional_profile_name: str
+    ) -> FunctionalProfile:
+        """
+        Gets a functional profile.
+
+        Parameters
+        ----------
+        functional_profile_name : str
+            the functional profile name
+
+        Returns
+        -------
+        FunctionalProfile
+            a functional profile
+        """
+        return self.functional_profiles[functional_profile_name]
+
+    def get_data_point(self, dp: tuple[str, str]) -> DataPoint:
+        """
+        Gets a data point.
+
+        Parameters
+        ----------
+        dp : tuple[str, str]
+            the functional profile and data point name
+
+        Returns
+        -------
+        DataPoint
+            a data point
+        """
+        return self.get_functional_profile(dp[0]).get_data_point(dp[1])
+
+    def get_data_points(self) -> dict[tuple[str, str], DataPoint]:
+        """
+        Gets all data points.
+
+        Returns
+        -------
+        dict[tuple[str, str], DataPoint]
+            all data points
+        """
+        data_points = {}
+        for fp in self.functional_profiles.values():
+            data_points.update(fp.get_data_points())
+        return data_points
+
+    def get_values(self) -> dict[tuple[str, str], Any]:
+        """
+        Gets all data point values synchronously.
+
+        Returns
+        -------
+        dict[tuple[str, str], Any]
+            all data point values
+        """
+        return run(self.get_values_async())
+
+    async def get_values_async(self) -> dict[tuple[str, str], Any]:
+        """
+        Gets all data point values asynchronously.
+
+        Returns
+        -------
+        dict[tuple[str, str], Any]
+            all data point values
+        """
+        data = {}
+        for fp in self.functional_profiles.values():
+            data.update(
+                {
+                    (fp.name(), key): value
+                    for key, value in (await fp.get_value_async()).items()
+                }
+            )
+        return data
+
+    def describe(
+        self,
+    ) -> tuple[
+        str, dict[str, dict[str, tuple[DataDirectionProduct, DataTypes]]]
+    ]:
+        """
+        Gets the device description and all data.
+
+        Returns
+        -------
+        tuple[str, dict[str, dict[str, tuple[DataDirectionProduct, DataTypes]]]]
+            a tuple of device name and all data point values
+        """
+        data = {}
+        for fp in self.functional_profiles.values():
+            key, dps = fp.describe()
+            data[key] = dps
+        return self.device_information.name, data