pyg90alarm 2.4.2__py3-none-any.whl → 2.5.1__py3-none-any.whl

pyg90alarm/__init__.py

@@ -52,6 +52,11 @@ 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.load_save import DataclassLoadSave
+from .dataclass.validation import (
+    get_field_validation_constraints,
+)
 from .const import (
     G90MessageTypes,
     G90NotificationTypes,
@@ -95,4 +100,8 @@ __all__ = [
     'G90AlarmPhones',
     # History
     'G90History',
+    # Dataclass validation
+    'get_field_validation_constraints',
+    # Dataclass load/save
+    'DataclassLoadSave',
 ]

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/{local/dataclass_load_save.py → 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.
 

pyg90alarm/dataclass/validation.py

@@ -0,0 +1,572 @@
+# Copyright (c) 2026 Ilia Sotnikov
+#
+# 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.
+"""
+Validation descriptors for dataclass fields.
+
+This module provides descriptor-based validation for dataclass fields,
+supporting integer range validation and string length validation.
+
+Example usage:
+
+    from dataclasses import dataclass
+    from pyg90alarm.dataclass.validation import (
+        validated_int_field,
+        validated_string_field,
+    )
+
+    @dataclass
+    class Config:
+        # Integer field with range validation
+        count: int = validated_int_field(min_value=0, max_value=100)
+
+        # String field with length validation
+        name: str = validated_string_field(min_length=1, max_length=50)
+"""
+from __future__ import annotations
+from typing import (
+    Optional, Any, cast, TYPE_CHECKING, overload, TypeVar, Generic
+)
+import logging
+from dataclasses import dataclass, field, fields, is_dataclass
+
+from ..const import BUG_REPORT_URL
+if TYPE_CHECKING:
+    from _typeshed import DataclassInstance
+
+_LOGGER = logging.getLogger(__name__)
+
+
+# pylint: disable=too-few-public-methods
+class ValidationConstraintsAbsent:
+    """
+    Sentinel/marker type indicating that no validation constraints are defined.
+
+    This is used in type annotations and metadata to distinguish the absence
+    of constraints from an explicit constraints container.
+    """
+
+
+@dataclass
+class IntValidationConstraints:
+    """
+    Container for integer validation constraints.
+    """
+    min_value: Optional[int] = None
+    max_value: Optional[int] = None
+
+
+@dataclass
+class StrValidationConstraints:
+    """
+    Container for string validation constraints.
+    """
+    min_length: Optional[int] = None
+    max_length: Optional[int] = None
+
+
+METADATA_KEY = 'validation_constraints'
+T = TypeVar('T')
+
+
+class ValidatorBase(Generic[T]):
+    """
+    Base dataclass descriptor for validating field values.
+
+    :param default: Default value to return upon read if not provided during
+     initialization.
+    :param trust_initial_value: If True, skips validation during dataclass
+     initialization assuming init value is valid.
+    """
+    def __init__(
+        self,
+        default: Optional[T] = None,
+        trust_initial_value: bool = False
+    ) -> None:
+        self._name: Optional[str] = None
+        self._default = default
+        self._trust_initial_value = trust_initial_value
+
+    def __validate__(self, obj: Any, value: T) -> bool:
+        """
+        Validates the value before setting.
+
+        This method should be overridden by subclasses to implement specific
+        validation logic.
+
+        :param obj: The dataclass instance.
+        :param value: The value to validate.
+        :raises ValueError: Exception to raise if the value is invalid.
+        :return: True if the value is valid, False otherwise. Only returned if
+         no exception is raised.
+        """
+        raise NotImplementedError(
+            'Subclasses must implement __validate__() method'
+        )
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        """
+        Stores the name of the attribute this descriptor is assigned to.
+
+        Note that the name is prepended with an underscore to avoid recursion
+        between __get__() and __set__(), since those aren't called for such an
+        attribute
+
+        :param owner: The owner class.
+        :param name: The name of the attribute.
+        """
+        self._name = "_" + name
+
+    @property
+    def __unmangled_name__(self) -> str:
+        """
+        Returns the unmangled field name.
+
+        :return: Unmangled field name.
+        """
+        return self.__field_name__[1:]
+
+    @property
+    def __field_name__(self) -> str:
+        """
+        Returns the field name the descriptor is assigned to.
+
+        Note that the name is mangled, see :py:meth:`__set_name__`.
+
+        :return: Field name.
+        """
+        assert self._name is not None, 'Descriptor not initialized properly'
+        return self._name
+
+    def __get__(
+        self, obj: Any, objtype: Optional[type] = None
+    ) -> Optional[T]:
+        """
+        Retrieves the field value, returning default if not set.
+
+        :param obj: The dataclass instance.
+        :param objtype: The dataclass type.
+        :return: The field value or default if not set.
+        """
+        # Dataclass requests the default value for the field
+        if obj is None:
+            return self._default
+
+        # Return stored value if it exists, otherwise return default if the
+        # value is the descriptor itself, i.e. not set
+        value = getattr(obj, self.__field_name__, self._default)
+        if value is self:
+            _LOGGER.debug(
+                "%s: Getting default value '%s'",
+                self.__unmangled_name__, self._default
+            )
+            value = self._default
+        return value
+
+    def __set__(self, obj: Any, value: T) -> None:
+        """
+        Sets the field value after validating it
+
+        The validation is skipped if `trust_initial_value` is True and this is
+        the first time setting the value during dataclass initialization.
+
+        :param obj: The dataclass instance.
+        :param value: The value to set.
+        """
+        # Default value assignment, e.g. when field not provided during
+        # initialization thus being assigned the descriptor instance itself
+        if value is self and self._default is not None:
+            _LOGGER.debug(
+                "%s: Assigning default value '%s'",
+                self.__unmangled_name__, self._default
+            )
+            value = self._default
+
+        # First time setting the value during dataclass initialization and its
+        # value should be trusted if `trust_initial_value` is True
+        trusted_init_value = (
+            not hasattr(obj, self.__field_name__)
+            and self._trust_initial_value
+        )
+
+        # Validate the value before setting
+        _LOGGER.debug(
+            "%s: Validating value '%s'", self.__unmangled_name__, value
+        )
+
+        try:
+            if not self.__validate__(obj, value):
+                # For unification, raise ValueError if validation fails if the
+                # validation method just returned False
+                raise ValueError(
+                    f"Invalid value '{value}' for field"
+                    f' {self.__unmangled_name__}'
+                )
+        except ValueError as exc:
+            # Validation failed for the value not being trusted during initial
+            # assignment, re-raise the exception
+            if not trusted_init_value:
+                _LOGGER.debug(
+                    "%s: Validation failed for value '%s'",
+                    self.__unmangled_name__, value
+                )
+                raise
+
+            # Log a warning about the validation failure during trusted init,
+            # so that constraints can be revised. The value will still be set,
+            # since it is trusted.
+            _LOGGER.warning(
+                "%s: Validation failed during initialization for trusted value"
+                " '%s' (%s). Please create bug report at %s if you see this"
+                " warning.",
+                self.__unmangled_name__, value, exc, BUG_REPORT_URL
+            )
+
+        # Set the validated value
+        _LOGGER.debug(
+            "%s: Setting value to '%s'", self.__unmangled_name__, value
+        )
+        setattr(obj, self.__field_name__, value)
+
+
+class IntRangeValidator(ValidatorBase[int]):
+    """
+    Descriptor for validating integer field values against min/max constraints.
+
+    The field value is validated when set. A ValueError is raised if the value
+    is outside the specified range.
+
+    Example usage:
+
+        @dataclass
+        class Example:
+            value: int = validated_int_field(min_value=0, max_value=100)
+
+        ex = Example(value=50)  # OK
+        ex.value = 100  # OK
+        ex.value = 101  # Raises ValueError
+
+    :param min_value: Minimum allowed value (inclusive), or None for no
+     minimum.
+    :param max_value: Maximum allowed value (inclusive), or None for no
+     maximum.
+    :param *: Rest of the params are passed to base class.
+    """
+    def __init__(
+        self, *,
+        min_value: Optional[int] = None,
+        max_value: Optional[int] = None,
+        **kwargs: Any
+    ) -> None:
+        super().__init__(**kwargs)
+        self._min_value = min_value
+        self._max_value = max_value
+
+    def __validate__(self, obj: Any, value: int) -> bool:
+        # Validate the value before setting
+        if value is None:
+            msg = (
+                f'{self.__unmangled_name__}: None value is not allowed'
+            )
+            _LOGGER.debug(msg)
+            raise ValueError(msg)
+
+        if self._min_value is not None and value < self._min_value:
+            msg = (
+                f'{self.__unmangled_name__}: Value {value} is below minimum'
+                f' allowed value {self._min_value}'
+            )
+            _LOGGER.debug(msg)
+            raise ValueError(msg)
+
+        if self._max_value is not None and value > self._max_value:
+            msg = (
+                f'{self.__unmangled_name__}: Value {value} is above maximum'
+                f' allowed value {self._max_value}'
+            )
+            _LOGGER.debug(msg)
+            raise ValueError(msg)
+
+        return True
+
+
+class StringLengthValidator(ValidatorBase[str]):
+    """
+    Descriptor for validating string field values against length constraints.
+
+    The field value is validated when set. A ValueError is raised if the string
+    length is outside the specified range.
+
+    Example usage:
+
+        @dataclass
+        class Example:
+            name: str = validated_string_field(min_length=1, max_length=50)
+
+        ex = Example(name="hello")  # OK
+        ex.name = "a"  # OK
+        ex.name = ""  # Raises ValueError
+
+    :param min_length: Minimum string length (inclusive), or None for no
+     minimum.
+    :param max_length: Maximum string length (inclusive), or None for no
+     maximum.
+    :param *: Rest of the params are passed to base class.
+    """
+    def __init__(
+        self,
+        *,
+        min_length: Optional[int] = None,
+        max_length: Optional[int] = None,
+        **kwargs: Any
+    ) -> None:
+        super().__init__(**kwargs)
+        self._min_length = min_length
+        self._max_length = max_length
+
+    def __validate__(self, obj: Any, value: str) -> bool:
+        if value is None:
+            msg = (
+                f'{self.__unmangled_name__}: None value is not allowed'
+            )
+            _LOGGER.debug(msg)
+            raise ValueError(msg)
+
+        length = len(value)
+
+        # Validate the length before setting
+        if self._min_length is not None and length < self._min_length:
+            msg = (
+                f'{self.__unmangled_name__}: String length {length} is below'
+                f' minimum allowed length {self._min_length}'
+            )
+            _LOGGER.debug(msg)
+            raise ValueError(msg)
+
+        if self._max_length is not None and length > self._max_length:
+            msg = (
+                f'{self.__unmangled_name__}: String length {length} is above'
+                f' maximum allowed length {self._max_length}'
+            )
+            _LOGGER.debug(msg)
+            raise ValueError(msg)
+
+        return True
+
+
+def validated_int_field(
+    *,
+    min_value: Optional[int] = None,
+    max_value: Optional[int] = None,
+    default: Optional[int] = None,
+    trust_initial_value: bool = False,
+    **kwargs: Any
+) -> int:
+    """
+    Create a dataclass field with integer range validation.
+
+    The field value will be validated when set, raising ValueError if outside
+    the specified range. Validation constraints are stored in field metadata
+    for later retrieval.
+
+    :param min_value: Minimum allowed value (inclusive), or None for no
+     minimum.
+    :param max_value: Maximum allowed value (inclusive), or None for no
+     maximum.
+    :param default: Default value for the field, or None for no default.
+    :param trust_initial_value: If True, skips validation during dataclass
+     initialization assuming init value is valid.
+    :param kwargs: Additional keyword arguments to pass to dataclasses.field().
+    :return: A dataclass field with IntRangeValidator descriptor and metadata.
+
+    Example:
+
+        @dataclass
+        class Config:
+            count: int = validated_int_field(
+                min_value=0, max_value=100, default=50
+            )
+    """
+    # Store validation constraints in metadata
+    if 'metadata' not in kwargs:
+        kwargs['metadata'] = {}
+    else:
+        # Avoid modifying caller's dict
+        kwargs['metadata'] = dict(kwargs['metadata'])
+
+    metadata = IntValidationConstraints(min_value, max_value)
+    kwargs['metadata'][METADATA_KEY] = metadata
+
+    # Create the field with the descriptor as default, passing along default
+    # value
+    # pylint: disable=invalid-field-call
+    return cast(int, field(
+        **kwargs,
+        default=IntRangeValidator(
+            min_value=min_value, max_value=max_value, default=default,
+            trust_initial_value=trust_initial_value
+        )
+    ))
+
+
+def validated_string_field(
+    *,
+    min_length: Optional[int] = None,
+    max_length: Optional[int] = None,
+    default: Optional[str] = None,
+    trust_initial_value: bool = False,
+    **kwargs: Any
+) -> str:
+    """
+    Create a dataclass field with string length validation.
+
+    The field value will be validated when set, raising ValueError if the
+    string length is outside the specified range. Validation constraints are
+    stored in field metadata for later retrieval.
+
+    :param min_length: Minimum string length (inclusive), or None for no
+     minimum.
+    :param max_length: Maximum string length (inclusive), or None for no
+     maximum.
+    :param default: Default value for the field, or None for no default.
+    :param trust_initial_value: If True, skips validation during dataclass
+     initialization assuming init value is valid.
+    :param kwargs: Additional keyword arguments to pass to dataclasses.field().
+    :return: A dataclass field with StringLengthValidator descriptor and
+     metadata.
+
+    Example:
+
+        @dataclass
+        class Config:
+            name: str = validated_string_field(
+                min_length=1, max_length=50, default="default"
+            )
+    """
+    # Store validation constraints in metadata
+    if 'metadata' not in kwargs:
+        kwargs['metadata'] = {}
+    else:
+        # Avoid modifying caller's dict
+        kwargs['metadata'] = dict(kwargs['metadata'])
+
+    metadata = StrValidationConstraints(min_length, max_length)
+    kwargs['metadata'][METADATA_KEY] = metadata
+
+    # Create the field with the descriptor as default, passing along default
+    # value
+    # pylint: disable=invalid-field-call
+    return cast(str, field(
+        **kwargs,
+        default=StringLengthValidator(
+            min_length=min_length, max_length=max_length, default=default,
+            trust_initial_value=trust_initial_value
+        )
+    ))
+
+
+# `get_field_validation_constraints` overload for `int` type
+@overload
+def get_field_validation_constraints(
+    dataclass_type: DataclassInstance | type[DataclassInstance],
+    field_name: str, expected_type: type[int]
+) -> IntValidationConstraints:
+    ...
+
+
+# `get_field_validation_constraints` overload for `str` type
+@overload
+def get_field_validation_constraints(
+    dataclass_type: DataclassInstance | type[DataclassInstance],
+    field_name: str, expected_type: type[str]
+) -> StrValidationConstraints:
+    ...
+
+
+# `get_field_validation_constraints` overload when no expected type is given
+@overload
+def get_field_validation_constraints(
+    dataclass_type: DataclassInstance | type[DataclassInstance],
+    field_name: str, expected_type: None = None
+) -> ValidationConstraintsAbsent:
+    ...
+
+
+# `get_field_validation_constraints` overload when non-dataclass is given
+@overload
+def get_field_validation_constraints(
+    dataclass_type: Any,
+    field_name: str, expected_type: None = None
+) -> ValidationConstraintsAbsent:
+    ...
+
+
+def get_field_validation_constraints(
+    dataclass_type: DataclassInstance | type[DataclassInstance],
+    field_name: str, expected_type: Optional[type] = None
+) -> Any:
+    """
+    Retrieve validation constraints for a specific dataclass field.
+
+    :param dataclass_type: The dataclass type or instance to inspect.
+    :param field_name: The name of the field to get constraints for.
+    :param expected_type: Expected type of the field to
+     determine which constraints to retrieve.
+    :return: Validation constraints container, or ValidationConstraintsAbsent
+     if none found. The latter is to avoid returning None and free callers from
+     having to check for it.
+
+    Example:
+
+        constraints = get_field_validation_constraints(Config, 'count', int)
+        # Returns: object with `constraints.min_value`, `constraints.max_value`
+    """
+    if not is_dataclass(dataclass_type):
+        # Not a dataclass, return absent indicator
+        return ValidationConstraintsAbsent()
+
+    fields_list = fields(dataclass_type)
+    for f in fields_list:
+        # Find the field by name
+        if f.name != field_name:
+            continue
+
+        # Retrieve validation constraints from metadata per expected type
+        for typ, klass in (
+            # Constraints for `int` field
+            (int, IntValidationConstraints),
+            # Constraints for `str` field
+            (str, StrValidationConstraints),
+        ):
+            if expected_type is not typ:
+                continue
+
+            constraints = (
+                getattr(f, 'metadata', {}).get(METADATA_KEY, None)
+            )
+
+            # Return stored constraints if available
+            if isinstance(constraints, klass):
+                return constraints
+
+            # Otherwise return empty constraints
+            return klass()
+
+    # No validation constraints found, return absent indicator
+    return ValidationConstraintsAbsent()

pyg90alarm/entities/base_list.py

@@ -68,6 +68,7 @@ class G90BaseList(Generic[T], ABC):
 
         :return: Async generator of entities
         """
+        # Placeholder to satisfy the abstractmethod
         yield cast(T, None)  # pragma: no cover
 
     @property
@@ -118,7 +119,11 @@ class G90BaseList(Generic[T], ABC):
                         )
 
                         existing_entity.update(entity)
-                        non_existing_entities.remove(existing_entity)
+                        # The entity might have already been removed if there
+                        # are duplicate entities from the `_fetch` method,
+                        # protect against that
+                        if existing_entity in non_existing_entities:
+                            non_existing_entities.remove(existing_entity)
 
                         # Invoke the list change callback for the existing
                         # entity to notify about the update

pyg90alarm/exceptions.py

@@ -32,7 +32,7 @@ class G90Error(Exception):
     """
 
 
-class G90TimeoutError(asyncio.TimeoutError):  # pylint:disable=R0903
+class G90TimeoutError(asyncio.TimeoutError, G90Error):
     """
     Raised when particular package class to report an operation (typically
     device command) has timed out.

pyg90alarm/local/alarm_phones.py

@@ -24,7 +24,8 @@ from __future__ import annotations
 from typing import Dict, Any
 from dataclasses import dataclass
 from ..const import G90Commands
-from .dataclass_load_save import DataclassLoadSave
+from ..dataclass.load_save import DataclassLoadSave
+from ..dataclass.validation import validated_string_field
 
 
 @dataclass
@@ -36,28 +37,54 @@ class G90AlarmPhones(DataclassLoadSave):
     LOAD_COMMAND = G90Commands.GETALMPHONE
     SAVE_COMMAND = G90Commands.SETALMPHONE
 
+    # The field constraints below have been determined experimentally by
+    # entering various values into panel configuration manually. All values
+    # received from the panel remotely are trusted (i.e. bypass validation)
+
     # Password to operate the panel via SMS or incoming call.
-    panel_password: str
+    panel_password: str = validated_string_field(
+        min_length=4, max_length=4, trust_initial_value=True
+    )
     # Phone number of the alarm panel's SIM card.
-    panel_phone_number: str
+    # Might be empty, the panel will then presumably refuse handling SMS/calls
+    # with remote commands.
+    panel_phone_number: str = validated_string_field(
+        max_length=14, trust_initial_value=True
+    )
     # Alarm phone number to be called on alarm.
-    # Should be in country code + number format.
-    phone_number_1: str
+    # Should be in country code + number format, or empty to disable.
+    phone_number_1: str = validated_string_field(
+        max_length=14, trust_initial_value=True
+    )
     # Same, but for second alarm phone number.
-    phone_number_2: str
+    phone_number_2: str = validated_string_field(
+        max_length=14, trust_initial_value=True
+    )
     # Same, but for third alarm phone number.
-    phone_number_3: str
+    phone_number_3: str = validated_string_field(
+        max_length=14, trust_initial_value=True
+    )
     # Same, but for fourth alarm phone number.
-    phone_number_4: str
+    phone_number_4: str = validated_string_field(
+        max_length=14, trust_initial_value=True
+    )
     # Same, but for fifth alarm phone number.
-    phone_number_5: str
+    phone_number_5: str = validated_string_field(
+        max_length=14, trust_initial_value=True
+    )
     # Same, but for sixth alarm phone number.
-    phone_number_6: str
+    phone_number_6: str = validated_string_field(
+        max_length=14, trust_initial_value=True
+    )
     # Phone number to send SMS notifications on alarm.
     # Should be in country code + number format.
-    sms_push_number_1: str
+    sms_push_number_1: str = validated_string_field(
+        max_length=14, trust_initial_value=True
+    )
     # Same, but for second SMS notification phone number.
-    sms_push_number_2: str
+    sms_push_number_2: str = validated_string_field(
+        max_length=14, trust_initial_value=True
+    )
 
     def _asdict(self) -> Dict[str, Any]:
         """

pyg90alarm/local/host_config.py

@@ -21,10 +21,13 @@
 Protocol entity for G90 alarm panel config.
 """
 from __future__ import annotations
-from typing import Dict, Any
+from typing import Dict, Any, Optional
 from dataclasses import dataclass
 from enum import IntEnum
-from .dataclass_load_save import DataclassLoadSave
+from ..dataclass.load_save import (
+    DataclassLoadSave, field_readonly_if_not_provided,
+)
+from ..dataclass.validation import validated_int_field
 from ..const import G90Commands
 
 
@@ -70,28 +73,60 @@ class G90HostConfig(DataclassLoadSave):
     LOAD_COMMAND = G90Commands.GETHOSTCONFIG
     SAVE_COMMAND = G90Commands.SETHOSTCONFIG
 
+    # The field constraints below have been determined experimentally by
+    # entering various values into panel configuration manually. All values
+    # received from the panel remotely are trusted (i.e. bypass validation)
+
     # Duration of the alarm siren when triggered, in seconds
-    alarm_siren_duration: int
+    alarm_siren_duration: int = validated_int_field(
+        min_value=0, max_value=999, trust_initial_value=True
+    )
     # Delay before arming the panel, in seconds
-    arm_delay: int
+    arm_delay: int = validated_int_field(
+        min_value=0, max_value=255, trust_initial_value=True
+    )
     # Delay before the alarm is triggered, in seconds
-    alarm_delay: int
+    alarm_delay: int = validated_int_field(
+        min_value=0, max_value=255, trust_initial_value=True
+    )
     # Duration of the backlight, in seconds
-    backlight_duration: int
+    backlight_duration: int = validated_int_field(
+        min_value=0, max_value=255, trust_initial_value=True
+    )
     # Alarm volume level, applies to panel's built-in speaker
-    _alarm_volume_level: int
+    _alarm_volume_level: int = validated_int_field(
+        min_value=min(G90VolumeLevel), max_value=max(G90VolumeLevel),
+        trust_initial_value=True
+    )
     # Speech volume level
-    _speech_volume_level: int
+    _speech_volume_level: int = validated_int_field(
+        min_value=min(G90VolumeLevel), max_value=max(G90VolumeLevel),
+        trust_initial_value=True
+    )
     # Duration of the ring for the incoming call, in seconds
-    ring_duration: int
+    ring_duration: int = validated_int_field(
+        min_value=0, max_value=255, trust_initial_value=True
+    )
     # Speech language
-    _speech_language: int
+    _speech_language: int = validated_int_field(
+        min_value=min(G90SpeechLanguage), max_value=max(G90SpeechLanguage),
+        trust_initial_value=True
+    )
     # Key tone volume level
-    _key_tone_volume_level: int
+    _key_tone_volume_level: int = validated_int_field(
+        min_value=min(G90VolumeLevel), max_value=max(G90VolumeLevel),
+        trust_initial_value=True
+    )
     # Timezone offset, in minutes
-    timezone_offset_m: int
-    # Ring volume level for incoming calls
-    _ring_volume_level: int
+    timezone_offset_m: int = validated_int_field(
+        min_value=-720, max_value=720, trust_initial_value=True
+    )
+    # Ring volume level for incoming calls, could only be modified if the
+    # device has sent a value for it when loading the data (i.e. has a cellular
+    # module) otherwise it is read-only and None
+    _ring_volume_level: Optional[int] = field_readonly_if_not_provided(
+        default=None
+    )
 
     @property
     def speech_language(self) -> G90SpeechLanguage:
@@ -138,10 +173,16 @@ class G90HostConfig(DataclassLoadSave):
         self._key_tone_volume_level = value.value
 
     @property
-    def ring_volume_level(self) -> G90VolumeLevel:
+    def ring_volume_level(self) -> Optional[G90VolumeLevel]:
         """
         Returns the ring volume level as an enum.
+
+        :return: Ring volume level, or `None` if the device does not have
+         cellular module.
         """
+        if self._ring_volume_level is None:
+            return None
+
         return G90VolumeLevel(self._ring_volume_level)
 
     @ring_volume_level.setter
@@ -163,5 +204,6 @@ class G90HostConfig(DataclassLoadSave):
             'speech_language': self.speech_language.name,
             'key_tone_volume_level': self.key_tone_volume_level.name,
             'timezone_offset_m': self.timezone_offset_m,
-            'ring_volume_level': self.ring_volume_level.name,
+            # The field is optional
+            'ring_volume_level': getattr(self.ring_volume_level, 'name', None)
         }

pyg90alarm/local/net_config.py

@@ -22,10 +22,11 @@ Interprets network configuration data fields of GETAPINFO/SETAPINFO commands.
 """
 from __future__ import annotations
 from enum import IntEnum
-from dataclasses import dataclass
-from typing import Any, Dict
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
 from ..const import G90Commands
-from .dataclass_load_save import DataclassLoadSave
+from ..dataclass.load_save import DataclassLoadSave, Metadata
+from ..dataclass.validation import validated_int_field, validated_string_field
 
 
 class G90APNAuth(IntEnum):
@@ -47,27 +48,52 @@ class G90NetConfig(DataclassLoadSave):
     LOAD_COMMAND = G90Commands.GETAPINFO
     SAVE_COMMAND = G90Commands.SETAPINFO
 
+    # The field constraints below have been determined experimentally by
+    # entering various values into panel configuration manually. All values
+    # received from the panel remotely are trusted (i.e. bypass validation)
+
     # Whether the access point is enabled, so that the device can be accessed
     # via WiFi
-    _ap_enabled: int
+    _ap_enabled: int = validated_int_field(
+        min_value=0, max_value=1, trust_initial_value=True
+    )
     # Access point password
-    ap_password: str
+    ap_password: str = validated_string_field(
+        min_length=9, max_length=64, trust_initial_value=True
+    )
     # Whether WiFi is enabled, so that the device can connect to WiFi network
-    _wifi_enabled: int
+    _wifi_enabled: int = validated_int_field(
+        min_value=0, max_value=1, trust_initial_value=True
+    )
     # Whether GPRS is enabled, so that the device can connect via cellular
     # network
-    _gprs_enabled: int
+    _gprs_enabled: int = validated_int_field(
+        min_value=0, max_value=1, trust_initial_value=True
+    )
     # Access Point Name (APN) for GPRS connection, as provided by the cellular
     # operator
-    apn_name: str
+    apn_name: str = validated_string_field(
+        min_length=1, max_length=100, trust_initial_value=True
+    )
     # User name for APN authentication, as provided by the cellular operator
-    apn_user: str
+    apn_user: str = validated_string_field(
+        min_length=0, max_length=64, trust_initial_value=True
+    )
     # Password for APN authentication, as provided by the cellular operator
-    apn_password: str
+    apn_password: str = validated_string_field(
+        min_length=0, max_length=64, trust_initial_value=True
+    )
     # APN authentication method, as provided by the cellular operator
-    _apn_auth: int
-    # GSM operator code
-    gsm_operator: str
+    _apn_auth: int = validated_int_field(
+        min_value=min(G90APNAuth), max_value=max(G90APNAuth),
+        trust_initial_value=True
+    )
+    # GSM operator code, optional for devices lacking cellular module.
+    # The field is always skipped when saving to device.
+    gsm_operator: Optional[str] = field(
+        metadata={Metadata.NO_SERIALIZE: True},
+        default=None
+    )
 
     @property
     def ap_enabled(self) -> bool:

{pyg90alarm-2.4.2.dist-info → pyg90alarm-2.5.1.dist-info}/METADATA

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

{pyg90alarm-2.4.2.dist-info → pyg90alarm-2.5.1.dist-info}/RECORD

@@ -1,38 +1,40 @@
-pyg90alarm/__init__.py,sha256=hZXvjpbWNO0ae88_B2qR4XDG6JXjPx5EZK8T2qxMcMM,3473
+pyg90alarm/__init__.py,sha256=ehUcPV8O2jBszU3hPAfI91nXjj2UXIfYjoREvL4QE2c,3719
 pyg90alarm/alarm.py,sha256=BDBVQ8qRa2Bx2-786uytShTw8znlFEWakxweCGvgxME,50130
 pyg90alarm/callback.py,sha256=9PVtjRs2MLn80AgiM-UJNL8ZJF4_PxcopJIpxMmB3vc,4707
-pyg90alarm/const.py,sha256=XBmtojOV0OrjqwL7x_wixqnt4Vcs9xOGlz-wHY4uO_Q,7948
+pyg90alarm/const.py,sha256=cpaMlb8rqE1EfvmUEh3Yd_29dNO0usIo_Y-esPBh8B0,8012
 pyg90alarm/event_mapping.py,sha256=hSmRWkkuA5hlauGvYakdOrw8QFt0TMNfUuDQ4J3vHpQ,3438
-pyg90alarm/exceptions.py,sha256=9LleQC2SkJXjv80FlWMeaHs9ZjXxCvZx9UtYdrvejyY,1951
+pyg90alarm/exceptions.py,sha256=9rSd5zIKALHtRHBBLD-R5zxW-5OBkHK04uVupCnAK8s,1937
 pyg90alarm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pyg90alarm/cloud/__init__.py,sha256=u7ZzrIwCsdgmBmgtpCe6c_Kipdo8nG8PEOEcaAHXCxI,1407
 pyg90alarm/cloud/const.py,sha256=FYUxkj0DSI7nnXZHsJMfv8RNQiXKV3TYKGHSdfHdMjg,2113
 pyg90alarm/cloud/messages.py,sha256=L3cpP3IbDRdw3W6FeQxTPXoDlpUv7Fm4t-RkH9Uj4dg,18032
 pyg90alarm/cloud/notifications.py,sha256=0RxCBVcvDuwE0I1m3SLDXDQqCJimDcN4f45gr-Hvt1A,15669
 pyg90alarm/cloud/protocol.py,sha256=82l2IXSM12tv_iWkTrAQZ-aw5UR4tmWFQJKVcgBfIww,16159
+pyg90alarm/dataclass/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyg90alarm/dataclass/load_save.py,sha256=I2WDeW4GingN8AEiwZm9Epf1gVL_Ynkise2h781Dn3I,8604
+pyg90alarm/dataclass/validation.py,sha256=yd3Q86S0L5NekzoiVFW5SwpefbIhWpwvsS-S15X4Sf8,19107
 pyg90alarm/definitions/__init__.py,sha256=s0NZnkW_gMH718DJbgez28z9WA231CyszUf1O_ojUiI,68
 pyg90alarm/definitions/base.py,sha256=Q2DQXfFks9u-ke65_5xVTqCUXJmJGxBxFTeWnite1bw,6757
 pyg90alarm/definitions/devices.py,sha256=K0DQnyE-1hlhIGwRfZojKJYMSmlJzmyWcZ_98urixsc,12042
 pyg90alarm/definitions/sensors.py,sha256=bDecBGyUo7wFVNuD5Fu1JNZQHcMDv-234BuNKioaQQs,27426
 pyg90alarm/entities/__init__.py,sha256=hHb6AOiC4Tz--rOWiiICMdLaZDs1Tf_xpWk_HeS_gO4,66
 pyg90alarm/entities/base_entity.py,sha256=hNhhuuwNuir54uVMZzPbjE0N6WL8wKvoW_KZa4R8L8U,2680
-pyg90alarm/entities/base_list.py,sha256=vNP0T8qg7lgrES0IBs4zOggQM6Uxyfarfds46bbAnH0,9482
+pyg90alarm/entities/base_list.py,sha256=oyhCszJZuVUeIoDCmMi_1XkQ87HK297_bnbRJBpYLv0,9807
 pyg90alarm/entities/device.py,sha256=eWE_N83hiDs5I-TT5F_W0Vb8sVugLldrDc9Lj9sgVLo,3700
 pyg90alarm/entities/device_list.py,sha256=PKnHEazeT3iUEaz70bW1OaWh0wq-7WOY-7dpV4FVCTc,5984
 pyg90alarm/entities/sensor.py,sha256=pq4tARSKQC_AJlT_ZaBcqTDtaXKuyo5nz6BqmHohSQk,27649
 pyg90alarm/entities/sensor_list.py,sha256=0S88bhTn91O45WgbIIMQ0iXaNjlUWmMBOOFwj2Hg73U,6993
 pyg90alarm/local/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pyg90alarm/local/alarm_phones.py,sha256=OKH7t8jBziHOSJth1bnYKYVKFiX1o83JzA-6ijCYBDc,3149
+pyg90alarm/local/alarm_phones.py,sha256=bGg4aEJwtl7oMlLdOGpW2Vv4q4zS9wzkpW4q3Qy2JCU,4375
 pyg90alarm/local/alert_config.py,sha256=n2dycEf6TH0MKefQXMcRsCFJyYvUMV55LRsy4FARtDI,6027
 pyg90alarm/local/base_cmd.py,sha256=f0PozHJjErIg08vn0sAacHbigJSFor8q5jdxfXiM27c,10491
 pyg90alarm/local/config.py,sha256=QYetAc6QLrAN8T-37D4Esifvao52w_uJ01nHciLbGME,1390
-pyg90alarm/local/dataclass_load_save.py,sha256=wmHT5834_rOlgPMe0ryZW0SbdFNTLC6-4NjJlSt6mhY,4738
 pyg90alarm/local/discovery.py,sha256=8YVIXuNe57lhas0VSRf7QXZH83pEDGNj9oehNY4Kh2U,3576
 pyg90alarm/local/history.py,sha256=sL6_Z1BNYkuUwAZUi78d4p5hhcCfsXKw29i4Qu1O60M,10811
-pyg90alarm/local/host_config.py,sha256=ycGx8WdSQ_azuBWpK366gvldZcxfVGnYBa_frbI9-TM,5502
+pyg90alarm/local/host_config.py,sha256=KMtrkM7IPm2b38f_kCIVGxYvPOd9ZDoA3nIoT-2SBKg,7376
 pyg90alarm/local/host_info.py,sha256=4lFIaFEpYd3EvgNrDJmKijTrzX9i29nFISLLlXGnkmE,2759
 pyg90alarm/local/host_status.py,sha256=WHGtw-A0wHILqVWP4DnZhXj8DPRGyS26AV0bL1isTz4,1863
-pyg90alarm/local/net_config.py,sha256=wjJMzL6tcHAfYF-OtregRpCoNEviOlkHHr5SpDaTmNs,4157
+pyg90alarm/local/net_config.py,sha256=x-hrisOktdy1ChacCoVBjaOq75KiDJ36nT1JsPGS42g,5453
 pyg90alarm/local/notifications.py,sha256=Vs6NQJciYqDALV-WwzH6wIcTGdX_UD4XBuHWjSOpCDY,4591
 pyg90alarm/local/paginated_cmd.py,sha256=5pPVP8f4ydjgu8Yq6MwqINJAUt52fFlD17wO4AI88Pc,4467
 pyg90alarm/local/paginated_result.py,sha256=p_e8QAVznp1Q5Xi9ifjb9Bx-S3ZiAkVlPKrY6r0bYLs,5483
@@ -41,8 +43,8 @@ pyg90alarm/local/user_data_crc.py,sha256=JQBOPY3RlOgVtvR55R-rM8OuKjYW-BPXQ0W4pi6
 pyg90alarm/notifications/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pyg90alarm/notifications/base.py,sha256=d3N_zNPa_jcTX4QpA78jdgMHDhmrgwqyM3HdvuO14Jk,16682
 pyg90alarm/notifications/protocol.py,sha256=TlZQ3P8-N-E2X5bzkGefz432x4lBYyIBF9VriwYn9ds,4790
-pyg90alarm-2.4.2.dist-info/licenses/LICENSE,sha256=f884inRbeNv-O-hbwz62Ro_1J8xiHRTnJ2cCx6A0WvU,1070
-pyg90alarm-2.4.2.dist-info/METADATA,sha256=vS1FIyQ1EwK8fbEBs2EsamOz93YLtwJUwmxoslRD5Ak,12568
-pyg90alarm-2.4.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pyg90alarm-2.4.2.dist-info/top_level.txt,sha256=czHiGxYMyTk5QEDTDb0EpPiKqUMRa8zI4zx58Ii409M,11
-pyg90alarm-2.4.2.dist-info/RECORD,,
+pyg90alarm-2.5.1.dist-info/licenses/LICENSE,sha256=f884inRbeNv-O-hbwz62Ro_1J8xiHRTnJ2cCx6A0WvU,1070
+pyg90alarm-2.5.1.dist-info/METADATA,sha256=C-0PG6RSQTPeWYdMNOE-fzZ65N8B0qoemx39bYOIDw8,12568
+pyg90alarm-2.5.1.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+pyg90alarm-2.5.1.dist-info/top_level.txt,sha256=czHiGxYMyTk5QEDTDb0EpPiKqUMRa8zI4zx58Ii409M,11
+pyg90alarm-2.5.1.dist-info/RECORD,,

{pyg90alarm-2.4.2.dist-info → pyg90alarm-2.5.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any