pyg90alarm 2.4.1__tar.gz → 2.5.0__tar.gz

{pyg90alarm-2.4.1 → pyg90alarm-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyg90alarm
-Version: 2.4.1
+Version: 2.5.0
 Summary: G90 Alarm system protocol
 Home-page: https://github.com/hostcc/pyg90alarm
 Author: Ilia Sotnikov

{pyg90alarm-2.4.1 → pyg90alarm-2.5.0}/src/pyg90alarm/__init__.py

@@ -52,6 +52,10 @@ from .local.host_config import (
 from .local.alarm_phones import G90AlarmPhones
 from .local.net_config import G90NetConfig, G90APNAuth
 from .local.history import G90History
+
+from .dataclass.validation import (
+    get_field_validation_constraints,
+)
 from .const import (
     G90MessageTypes,
     G90NotificationTypes,
@@ -95,4 +99,6 @@ __all__ = [
     'G90AlarmPhones',
     # History
     'G90History',
+    # Dataclass validation
+    'get_field_validation_constraints',
 ]

{pyg90alarm-2.4.1 → pyg90alarm-2.5.0}/src/pyg90alarm/const.py

@@ -39,6 +39,8 @@ ROOM_ID = 0
 
 CMD_PAGE_SIZE = 10
 
+BUG_REPORT_URL = 'https://github.com/hostcc/pyg90alarm/issues'
+
 
 class G90Commands(IntEnum):
     """

pyg90alarm-2.4.1/src/pyg90alarm/local/dataclass_load_save.py → pyg90alarm-2.5.0/src/pyg90alarm/dataclass/load_save.py

@@ -22,16 +22,106 @@
 Base class for loading/saving dataclasses to a device.
 """
 from __future__ import annotations
-from typing import TYPE_CHECKING, Type, TypeVar, Optional, ClassVar, Any, Dict
+from typing import (
+    TYPE_CHECKING, Type, TypeVar, Optional, ClassVar, Any, Dict, List, cast
+)
 import logging
-from dataclasses import dataclass, astuple, asdict
+from dataclasses import dataclass, asdict, field, fields
+from .validation import ValidatorBase
 from ..const import G90Commands
 if TYPE_CHECKING:
     from ..alarm import G90Alarm
 
 
 _LOGGER = logging.getLogger(__name__)
-S = TypeVar('S', bound='DataclassLoadSave')
+DataclassLoadSaveT = TypeVar('DataclassLoadSaveT', bound='DataclassLoadSave')
+T = TypeVar('T')
+
+
+class Metadata:
+    """
+    Metadata keys for DataclassLoadSave fields.
+    """
+    # pylint: disable=too-few-public-methods
+    NO_SERIALIZE = 'no_serialize'
+    SKIP_NONE = 'skip_none'
+
+
+class ReadOnlyIfNotProvided(ValidatorBase[T]):
+    """
+    Descriptor for dataclass fields to be read-only if not provided during
+    initialization.
+
+    The field can be read, but attempts to modify it will raise a
+    ValueError if the field was not provided during initialization. In
+    other words, the only way to set the value is during object creation.
+
+    Example usage:
+
+        @dataclass
+        class Example:
+            read_only_field: Optional[int] = field_readonly_if_not_provided(
+                default=None
+            )
+
+        # Works ok
+        ex = Example(read_only_field=42)
+        print(ex.read_only_field)  # Outputs: 42
+        ex.read_only_field = 100  # Works ok
+
+        # Raises ValueError
+        ex2 = Example()
+        print(ex2.read_only_field)  # Outputs: None
+        ex2.read_only_field = 100  # Raises ValueError
+
+    :param default: Default value to return upon read if not provided during
+     initialization.
+    """
+    # pylint: disable=too-few-public-methods
+
+    def __validate__(self, obj: Any, value: T) -> bool:
+        """
+        Validation method.
+        """
+        # Prevent setting the value if it was not provided during
+        # initialization. The condition is determined by checking if the
+        # current value is `self` - i.e. the descriptor instance hasn't been
+        # replaced with an actual value
+        if getattr(obj, self.__field_name__, self._default) is self:
+            raise ValueError(
+                f'Field {self.__unmangled_name__} is read-only because'
+                ' it was not provided during initialization'
+            )
+        return True
+
+
+def field_readonly_if_not_provided(
+    *args: Any, default: Optional[T] = None, **kwargs: Any
+) -> T:
+    """
+    Helper function to create a dataclass field with ReadOnlyIfNotProvided
+    descriptor.
+
+    :param args: Positional arguments to pass to `dataclasses.field()`.
+    :param default: Default value to return upon read if not provided during
+     initialization.
+    :param kwargs: Keyword arguments to pass to `dataclasses.field()`.
+    :return: A dataclass field with ReadOnlyIfNotProvided descriptor attached.
+    """
+    # Also set SKIP_NONE metadata if default is None, so that the field is
+    # skipped during serialization when its value is None
+    if default is None:
+        if 'metadata' not in kwargs:
+            kwargs['metadata'] = {}
+        kwargs['metadata'][Metadata.SKIP_NONE] = True
+
+    # Instantiate the field with ReadOnlyIfNotProvided descriptor and rest of
+    # the provided arguments
+    # pylint: disable=invalid-field-call
+    return cast(T, field(
+        *args, **kwargs,
+        default=ReadOnlyIfNotProvided[T](default)
+    ))
 
 
 @dataclass
@@ -79,6 +169,34 @@ class DataclassLoadSave:
         # declared here to avoid being part of dataclass fields
         self._parent: Optional[G90Alarm] = None
 
+    def serialize(self) -> List[Any]:
+        """
+        Returns the dataclass fields as a list.
+
+        Handles specific metadata for the fields.
+        :seealso:`Metadata`.
+
+        :return: Dataclass serialized as list.
+        """
+        result = []
+
+        for f in fields(self):
+            # Skip fields marked with NO_SERIALIZE metadata
+            if f.metadata.get(Metadata.NO_SERIALIZE, False):
+                continue
+
+            # Skip fields with None value if SKIP_NONE metadata is set
+            if (
+                f.metadata.get(Metadata.SKIP_NONE, False)
+                and getattr(self, f.name) is None
+            ):
+                continue
+
+            # Append field value to the result list
+            result.append(getattr(self, f.name))
+
+        return result
+
     async def save(self) -> None:
         """
         Save the current data to the device.
@@ -89,11 +207,13 @@ class DataclassLoadSave:
         _LOGGER.debug('Setting data to the device: %s', str(self))
         await self._parent.command(
             self.SAVE_COMMAND,
-            list(astuple(self))
+            self.serialize()
         )
 
     @classmethod
-    async def load(cls: Type[S], parent: G90Alarm) -> S:
+    async def load(
+        cls: Type[DataclassLoadSaveT], parent: G90Alarm
+    ) -> DataclassLoadSaveT:
         """
         Create an instance with values loaded from the device.