pywmswebcontrolpro 0.1.0__tar.gz → 0.1.2__tar.gz

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/.github/workflows/validate.yaml

@@ -16,6 +16,7 @@ jobs:
       - run: python -m pip install -r requirements_lint.txt
       - run: ruff check .
       - run: ruff format --check .
+      - run: mypy
   test:
     runs-on: ubuntu-24.04
     steps:

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pywmswebcontrolpro
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python library for the Warema WMS WebControl pro API
 Author-email: Marc Hoersken <info@marc-hoersken.de>
 License-Expression: Apache-2.0
@@ -14,7 +14,7 @@ Description-Content-Type: text/markdown
 # pywmswebcontrolpro
 
 Python library for the Warema WMS WebControl pro API. It is the companion library of the
-Home Assistant integration `ha_wms_webcontrol_pro`.
+Home Assistant integration [`wms_webcontrol_pro`](https://github.com/zomtec/ha_wms_webcontrol_pro).
 
 Reference: https://media.warema.com/dokumente/anleitungen-handbuecher/966664/warema_2064534_alhb_de_v0.pdf
 

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/README.md

@@ -1,7 +1,7 @@
 # pywmswebcontrolpro
 
 Python library for the Warema WMS WebControl pro API. It is the companion library of the
-Home Assistant integration `ha_wms_webcontrol_pro`.
+Home Assistant integration [`wms_webcontrol_pro`](https://github.com/zomtec/ha_wms_webcontrol_pro).
 
 Reference: https://media.warema.com/dokumente/anleitungen-handbuecher/966664/warema_2064534_alhb_de_v0.pdf
 

pywmswebcontrolpro-0.1.2/mypy.ini

@@ -0,0 +1,6 @@
+[mypy]
+python_version = 3.14
+files = pywmswebcontrolpro
+
+[mypy-aiohttp.*,aiofiles.*]
+ignore_missing_imports = True

pywmswebcontrolpro-0.1.2/pywmswebcontrolpro/__init__.py

@@ -0,0 +1 @@
+"""Python client for the Warema WMS WebControl pro gateway."""

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/pywmswebcontrolpro/action.py

@@ -1,6 +1,8 @@
+"""An action of a destination with its stored settings and movement model."""
+
 import math
 from dataclasses import asdict, replace
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from .const import (
     WMS_WebControl_pro_API_actionDescription,
@@ -10,17 +12,28 @@ from .const import (
 from .store import STORE_VERSION, ActionSettings, JsonStore, TravelDirection
 from .travel import CoverModel, Measurement
 
+if TYPE_CHECKING:
+    from .destination import Destination
+    from .webcontrol import WebControlPro
+
 _STORED_KEYS = frozenset({"version", "overwrites", "settings", "state"})
 
 
 class ActionList(list):
-    def __init__(self, control) -> None:
+    """Actions that are sent to the gateway with one request."""
+
+    def __init__(self, control: WebControlPro) -> None:
+        """Create an empty list for the given client."""
         super().__init__()
         self._control = control
 
     async def __call__(
-        self, responseType=WMS_WebControl_pro_API_responseType.Instant
+        self,
+        responseType: WMS_WebControl_pro_API_responseType = (
+            WMS_WebControl_pro_API_responseType.Instant
+        ),
     ) -> Any:
+        """Send all actions and return the answer of the gateway."""
         if len(self) == 0:
             raise ValueError("ActionList is empty")
         return await self._control._action(
@@ -30,9 +43,17 @@ class ActionList(list):
 
 
 class Action:
+    """One function of a destination, for example moving an awning."""
+
     def __init__(
-        self, dest, id: int, actionType: int, actionDescription: int, **kwargs
+        self,
+        dest: Destination,
+        id: int,
+        actionType: int,
+        actionDescription: int,
+        **kwargs: Any,
     ) -> None:
+        """Create the action from the configuration of the gateway."""
         self._dest = dest
         self._id = id
         self._persist = (dest._persist / f"{id}.json") if dest._persist else None
@@ -42,8 +63,8 @@ class Action:
             actionDescription
         )
         self._attrs = kwargs
-        self._params = {}
-        self._overwrites = {}
+        self._params: dict[str, Any] = {}
+        self._overwrites: dict[str, Any] = {}
         self._needs_load = True
         self._needs_save = False
         self._extra: dict[str, Any] = {}
@@ -57,8 +78,8 @@ class Action:
     def __repr__(self) -> str:
         return f"<Action {self.id}: {self} ({self.actionType.name})>"
 
-    def __eq__(self, other) -> bool:
-        return self.id == other.id
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Action) and self.id == other.id
 
     def __hash__(self) -> int:
         return hash(self.id)
@@ -67,18 +88,22 @@ class Action:
 
     @property
     def host(self) -> str:
+        """Return the host of the gateway."""
         return self._dest.host
 
     @property
     def id(self) -> int:
+        """Return the id of the action."""
         return self._id
 
     @property
     def actionType(self) -> WMS_WebControl_pro_API_actionType:
+        """Return the kind of value or command of the action."""
         return self._actionType
 
     @property
     def actionDescription(self) -> WMS_WebControl_pro_API_actionDescription:
+        """Return the function of the action."""
         return self._actionDescription
 
     # --- Private methods ---
@@ -191,7 +216,8 @@ class Action:
             del self._overwrites[name]
             self._needs_save = True
 
-    def prep(self, **kwargs) -> ActionList:
+    def prep(self, **kwargs: Any) -> ActionList:
+        """Return an action list with this action and the given parameters."""
         actionList = ActionList(self._dest._control)
         actionList.append(
             {
@@ -203,14 +229,20 @@ class Action:
         return actionList
 
     async def __call__(
-        self, responseType=WMS_WebControl_pro_API_responseType.Instant, **kwargs
+        self,
+        responseType: WMS_WebControl_pro_API_responseType = (
+            WMS_WebControl_pro_API_responseType.Instant
+        ),
+        **kwargs: Any,
     ) -> Any:
+        """Send the action with the given parameters to the gateway."""
         return await self._dest._control._action(
             actions=self.prep(**kwargs),
             responseType=responseType,
         )
 
     def diag(self) -> dict:
+        """Return the action for the diagnostics."""
         return {
             "id": self.id,
             "actionType": self.actionType.name,

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/pywmswebcontrolpro/const.py

@@ -1,3 +1,5 @@
+"""Constants and enumerations of the WMS WebControl pro API."""
+
 from enum import IntEnum
 
 WMS_WebControl_pro_API_protocolVersion = "1.0"
@@ -11,6 +13,8 @@ WMS_WebControl_pro_API_command_sceneActions = "sceneActions"
 
 
 class WMS_WebControl_pro_API_animationType(IntEnum):
+    """Kind of device that a destination controls."""
+
     VenetianBlind = 0
     Awning = 1
     RollerShutterBlind = 2
@@ -22,6 +26,8 @@ class WMS_WebControl_pro_API_animationType(IntEnum):
 
 
 class WMS_WebControl_pro_API_actionType(IntEnum):
+    """Kind of value or command of an action."""
+
     Percentage = 0
     PercentageDelta = 1
     Rotation = 2
@@ -36,6 +42,8 @@ class WMS_WebControl_pro_API_actionType(IntEnum):
 
 
 class WMS_WebControl_pro_API_actionDescription(IntEnum):
+    """Function of an action, for example awning drive or light switch."""
+
     AwningDrive = 0
     ValanceDrive = 1
     SlatDrive = 2
@@ -54,16 +62,22 @@ class WMS_WebControl_pro_API_actionDescription(IntEnum):
 
 
 class WMS_WebControl_pro_API_responseType(IntEnum):
+    """How much the gateway answers to a command."""
+
     Instant = 0
     Detailed = 1
 
 
 class WMS_WebControl_pro_API_sceneActionType(IntEnum):
+    """Command for a scene."""
+
     Relearn = 0
     Execute = 1
 
 
 class WMS_WebControl_pro_API_drivingCause(IntEnum):
+    """Reason why a drive moved last."""
+
     _None = 0  # No driving cause
     Sun = 1
     DuskDawn = 2

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/pywmswebcontrolpro/destination.py

@@ -1,9 +1,11 @@
+"""A destination of the gateway, for example a drive, a light or a load."""
+
 import asyncio
 import logging
 import time
 from collections.abc import Mapping
 from types import MappingProxyType
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import aiohttp
 
@@ -23,14 +25,24 @@ from .refresh import (
 )
 from .room import Room
 
+if TYPE_CHECKING:
+    from .webcontrol import WebControlPro
+
 DEFAULT_REFRESH_RETRIES = 2
 
 _LOGGER = logging.getLogger(__name__)
 
 
 class Destination:
+    """A component of the gateway with its actions and the last known status."""
+
     def __init__(
-        self, control, id: int, names: list, actions: list, animationType: int
+        self,
+        control: WebControlPro,
+        id: int,
+        names: list[str],
+        actions: list[dict[str, Any]],
+        animationType: int,
     ) -> None:
         self._control = control
         self._id = id
@@ -39,10 +51,10 @@ class Destination:
         self._actions = {action["id"]: Action(self, **action) for action in actions}
         self._animationType = WMS_WebControl_pro_API_animationType(animationType)
         self._drivingCause = WMS_WebControl_pro_API_drivingCause.Unknown
-        self._unknownProducts = {}
+        self._unknownProducts: dict[int, Any] = {}
         self._heartbeatError = None
         self._blocking = None
-        self._status = {}
+        self._status: dict[str, Any] = {}
         self._stats = RefreshStats()
 
     def __str__(self) -> str:
@@ -51,8 +63,8 @@ class Destination:
     def __repr__(self) -> str:
         return f"<Destination {self.id}: {self}>"
 
-    def __eq__(self, other) -> bool:
-        return self.id == other.id
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Destination) and self.id == other.id
 
     def __hash__(self) -> int:
         return hash(self.id)
@@ -61,30 +73,37 @@ class Destination:
 
     @property
     def host(self) -> str:
+        """Return the host of the gateway."""
         return self._control.host
 
     @property
     def id(self) -> int:
+        """Return the id of the destination."""
         return self._id
 
     @property
     def name(self) -> str:
+        """Return the name of the destination."""
         return self._names[0]
 
     @property
     def actions(self) -> dict:
+        """Return the actions of the destination by id."""
         return self._actions
 
     @property
     def animationType(self) -> WMS_WebControl_pro_API_animationType:
+        """Return the kind of device that the destination controls."""
         return self._animationType
 
     @property
     def drivingCause(self) -> WMS_WebControl_pro_API_drivingCause:
+        """Return why the drive moved last."""
         return self._drivingCause
 
     @property
     def room(self) -> Room | None:
+        """Return the room of the destination, if it belongs to one."""
         for room in self._control.rooms.values():
             if self._id in room._destination_ids:
                 return room
@@ -92,10 +111,12 @@ class Destination:
 
     @property
     def available(self) -> bool:
+        """Return False while the gateway reports an error or a blocked drive."""
         return not (self._heartbeatError or self._blocking)
 
     @property
     def status(self) -> Mapping:
+        """Return the last status that the gateway answered."""
         return MappingProxyType(self._status)
 
     @property
@@ -209,6 +230,7 @@ class Destination:
         actionDescription: WMS_WebControl_pro_API_actionDescription,
         actionType: WMS_WebControl_pro_API_actionType | None = None,
     ) -> bool:
+        """Return True if the destination has a matching action."""
         for action in self._actions.values():
             if action.actionDescription == actionDescription and (
                 actionType is None or actionType == action.actionType
@@ -221,6 +243,7 @@ class Destination:
         actionDescription: WMS_WebControl_pro_API_actionDescription,
         actionType: WMS_WebControl_pro_API_actionType | None = None,
     ) -> Action:
+        """Return the matching action or raise NotImplementedError."""
         for action in self._actions.values():
             if action.actionDescription == actionDescription and (
                 actionType is None or actionType == action.actionType
@@ -234,6 +257,7 @@ class Destination:
         )
 
     def diag(self) -> dict:
+        """Return the destination for the diagnostics."""
         return {
             "id": self.id,
             "name": self.name,

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/pywmswebcontrolpro/room.py

@@ -1,5 +1,22 @@
+"""A room of the gateway with its destinations and scenes."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .webcontrol import WebControlPro
+
+
 class Room:
-    def __init__(self, control, id: int, name: str, destinations: list, scenes: list):
+    """A room that groups destinations and scenes."""
+
+    def __init__(
+        self,
+        control: WebControlPro,
+        id: int,
+        name: str,
+        destinations: list[int],
+        scenes: list[int],
+    ) -> None:
         self._control = control
         self._id = id
         self._name = name
@@ -12,8 +29,8 @@ class Room:
     def __repr__(self) -> str:
         return f"<Room {self.id}: {self}>"
 
-    def __eq__(self, other) -> bool:
-        return self.id == other.id
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Room) and self.id == other.id
 
     def __hash__(self) -> int:
         return hash(self.id)
@@ -22,24 +39,29 @@ class Room:
 
     @property
     def host(self) -> str:
+        """Return the host of the gateway."""
         return self._control.host
 
     @property
     def id(self) -> int:
+        """Return the id of the room."""
         return self._id
 
     @property
     def name(self) -> str:
+        """Return the name of the room."""
         return self._name
 
     @property
     def destinations(self) -> dict:
+        """Return the destinations of the room by id."""
         return {
             dest_id: self._control.dests[dest_id] for dest_id in self._destination_ids
         }
 
     @property
     def scenes(self) -> dict:
+        """Return the scenes of the room by id."""
         return {
             scene_id: self._control.scenes[scene_id] for scene_id in self._scene_ids
         }
@@ -47,6 +69,7 @@ class Room:
     # --- Public methods ---
 
     def diag(self) -> dict:
+        """Return the room for the diagnostics."""
         return {
             "id": self.id,
             "name": self.name,

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/pywmswebcontrolpro/scene.py

@@ -1,10 +1,17 @@
-from typing import Any
+"""A scene of the gateway."""
+
+from typing import TYPE_CHECKING, Any
 
 from .room import Room
 
+if TYPE_CHECKING:
+    from .webcontrol import WebControlPro
+
 
 class Scene:
-    def __init__(self, control, id: int, names: list):
+    """A scene that the gateway can execute."""
+
+    def __init__(self, control: WebControlPro, id: int, names: list[str]) -> None:
         self._control = control
         self._id = id
         self._names = names
@@ -15,8 +22,8 @@ class Scene:
     def __repr__(self) -> str:
         return f"<Scene {self.id}: {self}>"
 
-    def __eq__(self, other) -> bool:
-        return self.id == other.id
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Scene) and self.id == other.id
 
     def __hash__(self) -> int:
         return hash(self.id)
@@ -25,18 +32,22 @@ class Scene:
 
     @property
     def host(self) -> str:
+        """Return the host of the gateway."""
         return self._control.host
 
     @property
     def id(self) -> int:
+        """Return the id of the scene."""
         return self._id
 
     @property
     def name(self) -> str:
+        """Return the name of the scene."""
         return self._names[0]
 
     @property
     def room(self) -> Room | None:
+        """Return the room of the scene, if it belongs to one."""
         for room in self._control.rooms.values():
             if self._id in room._scene_ids:
                 return room
@@ -44,10 +55,12 @@ class Scene:
 
     # --- Public methods ---
 
-    async def __call__(self, **kwargs) -> Any:
+    async def __call__(self, **kwargs: Any) -> Any:
+        """Execute the scene and return the answer of the gateway."""
         return await self._control._sceneActions(self._id, **kwargs)
 
     def diag(self) -> dict:
+        """Return the scene for the diagnostics."""
         return {
             "id": self.id,
             "name": self.name,

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/pywmswebcontrolpro/travel.py

@@ -81,12 +81,20 @@ class CoverModel:
     @property
     def is_opening(self) -> bool:
         """Return True while an interpolated drive moves towards open."""
-        return self.is_travelling and self._target > self._start
+        return (
+            self._target is not None
+            and self._start is not None
+            and self._target > self._start
+        )
 
     @property
     def is_closing(self) -> bool:
         """Return True while an interpolated drive moves towards closed."""
-        return self.is_travelling and self._target < self._start
+        return (
+            self._target is not None
+            and self._start is not None
+            and self._target < self._start
+        )
 
     @property
     def position_int(self) -> int | None:
@@ -109,7 +117,12 @@ class CoverModel:
 
         Returns True if a drive reached its target with this call.
         """
-        if not self.is_travelling:
+        if (
+            self._target is None
+            or self._start is None
+            or self._started_at is None
+            or self._duration is None
+        ):
             return False
         elapsed = max(0.0, now - self._started_at)
         if elapsed >= self._duration:
@@ -235,7 +248,7 @@ class CoverModel:
             "position": self.position_int,
             "tilt": self.tilt,
             "target_position": (
-                int(self._target + 0.5) if self.is_travelling else None
+                int(self._target + 0.5) if self._target is not None else None
             ),
             "target_tilt": self._pending_tilt if self.is_travelling else None,
         }

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/pywmswebcontrolpro/webcontrol.py

@@ -1,13 +1,16 @@
+"""Client of the local API of the WMS WebControl pro gateway."""
+
 import asyncio
 import pprint
 import time
 from collections.abc import Mapping
+from dataclasses import dataclass
 from datetime import timedelta
 from pathlib import Path
 from types import MappingProxyType
 from typing import Any
 
-from aiohttp import ClientSession
+from aiohttp import ClientSession, ClientTimeout
 
 from .const import (
     WMS_WebControl_pro_API_actionDescription,
@@ -31,7 +34,17 @@ DEFAULT_RETRY_DELAY = 1.0
 DEFAULT_REQUEST_SPACING = 0.5
 
 
+@dataclass(frozen=True)
+class ConfigChanges:
+    """Destinations that appeared or disappeared with a configuration refresh."""
+
+    added: frozenset[int] = frozenset()
+    removed: frozenset[int] = frozenset()
+
+
 class WebControlPro:
+    """Client of one WMS WebControl pro gateway."""
+
     def __init__(
         self,
         host: str,
@@ -42,7 +55,9 @@ class WebControlPro:
         retry_delay: float = DEFAULT_RETRY_DELAY,
         request_spacing: float = DEFAULT_REQUEST_SPACING,
     ) -> None:
-        """Create a client; stale_warning_after sets how long a destination may
+        """Create a client.
+
+        stale_warning_after sets how long a destination may
         stay silent before a warning is logged, retry_delay the pause in
         seconds between retries after a radio busy answer and request_spacing
         the minimum pause in seconds between two status requests.
@@ -57,14 +72,14 @@ class WebControlPro:
         self._control = f"http://{host}/commonCommand"
         self._session = session
         self._persist = Path(persist) if persist else None
-        self._config = {}
-        self._dests = {}
-        self._rooms = {}
-        self._scenes = {}
+        self._config: dict[str, Any] = {}
+        self._dests: dict[int, Destination] = {}
+        self._rooms: dict[int, Room] = {}
+        self._scenes: dict[int, Scene] = {}
 
     # --- Private methods ---
 
-    async def _commonCommand(self, command: str, **kwargs) -> Any:
+    async def _commonCommand(self, command: str, **kwargs: Any) -> Any:
         data = {
             "protocolVersion": WMS_WebControl_pro_API_protocolVersion,
             "command": command,
@@ -73,7 +88,9 @@ class WebControlPro:
         data.update(kwargs)
         async with (
             self._common_lock,
-            self._session.post(url=self._control, json=data, timeout=5) as response,
+            self._session.post(
+                url=self._control, json=data, timeout=ClientTimeout(total=5)
+            ) as response,
         ):
             return await response.json()
 
@@ -99,7 +116,11 @@ class WebControlPro:
                 self._status_last = time.monotonic()
 
     async def _action(
-        self, actions: list, responseType=WMS_WebControl_pro_API_responseType.Instant
+        self,
+        actions: list,
+        responseType: WMS_WebControl_pro_API_responseType = (
+            WMS_WebControl_pro_API_responseType.Instant
+        ),
     ) -> Any:
         return await self._commonCommand(
             WMS_WebControl_pro_API_command_action,
@@ -110,8 +131,12 @@ class WebControlPro:
     async def _sceneActions(
         self,
         sceneId: int,
-        sceneActionType=WMS_WebControl_pro_API_sceneActionType.Execute,
-        responseType=WMS_WebControl_pro_API_responseType.Instant,
+        sceneActionType: WMS_WebControl_pro_API_sceneActionType = (
+            WMS_WebControl_pro_API_sceneActionType.Execute
+        ),
+        responseType: WMS_WebControl_pro_API_responseType = (
+            WMS_WebControl_pro_API_responseType.Instant
+        ),
     ) -> Any:
         return await self._commonCommand(
             WMS_WebControl_pro_API_command_sceneActions,
@@ -123,25 +148,41 @@ class WebControlPro:
     # --- Public methods ---
 
     async def ping(self) -> bool:
+        """Return True if the gateway answers the ping."""
         ping = await self._ping()
         return ping["status"] == 0
 
-    async def refresh(self) -> None:
+    async def refresh(self) -> ConfigChanges:
+        """Read the configuration and create destinations, rooms and scenes.
+
+        A destination that is already known stays the same object, so its
+        actions keep their movement model and stored state. Only new
+        destinations are created, and the result names the destinations that
+        appeared and disappeared. Rooms and scenes are created again.
+        """
         config = await self._getConfiguration()
         self._config = config
+        known = self._dests
         self._dests = {
-            dest["id"]: Destination(self, **dest) for dest in config["destinations"]
+            dest["id"]: known.get(dest["id"]) or Destination(self, **dest)
+            for dest in config["destinations"]
         }
         self._rooms = {room["id"]: Room(self, **room) for room in config["rooms"]}
         self._scenes = {scene["id"]: Scene(self, **scene) for scene in config["scenes"]}
+        return ConfigChanges(
+            added=frozenset(self._dests) - frozenset(known),
+            removed=frozenset(known) - frozenset(self._dests),
+        )
 
     def dest(self, name: str) -> Destination:
+        """Return the destination with the given name or raise KeyError."""
         for dest in self._dests.values():
             if dest.name == name:
                 return dest
         raise KeyError(f"Destination with name '{name}' not found")
 
     def diag(self) -> dict:
+        """Return the client for the diagnostics."""
         return {
             "host": self._host,
             "config": self._config,
@@ -154,26 +195,32 @@ class WebControlPro:
 
     @property
     def host(self) -> str:
+        """Return the host of the gateway."""
         return self._host
 
     @property
     def config(self) -> Mapping:
+        """Return the configuration of the gateway."""
         return MappingProxyType(self._config)
 
     @property
     def dests(self) -> Mapping:
+        """Return the destinations by id."""
         return MappingProxyType(self._dests)
 
     @property
     def rooms(self) -> Mapping:
+        """Return the rooms by id."""
         return MappingProxyType(self._rooms)
 
     @property
     def scenes(self) -> Mapping:
+        """Return the scenes by id."""
         return MappingProxyType(self._scenes)
 
 
-async def async_main_test():
+async def async_main_test() -> None:
+    """Run the example against a gateway named webcontrol."""
     async with ClientSession() as session:
         control = WebControlPro("webcontrol", session)
         pprint.pprint(await control.ping())

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/requirements_lint.txt

@@ -1 +1,2 @@
 ruff==0.17.3
+mypy==2.4.1

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/ruff.toml

@@ -3,6 +3,8 @@ line-length = 88
 
 [lint]
 select = [
+    "ANN",  # type annotations
+    "D",  # docstrings
     "ASYNC",  # blocking calls in async code
     "B",  # bugbear
     "C4",  # comprehensions
@@ -21,11 +23,17 @@ select = [
     "W",  # pycodestyle warnings
 ]
 ignore = [
+    "ANN401",  # the answers of the gateway are untyped JSON
+    "D105",  # magic methods are self-explanatory
+    "D107",  # the class docstring describes the constructor
+    "D203",  # incompatible with D211
+    "D213",  # incompatible with D212
     "E501",  # line length is enforced by the formatter
 ]
 
 [lint.per-file-ignores]
-"simulator/**" = ["T20"]
+"tests/**" = ["D", "ANN"]
+"simulator/**" = ["D", "ANN", "T20"]
 "pywmswebcontrolpro/webcontrol.py" = ["T20"]  # example main prints
 
 [lint.isort]

{pywmswebcontrolpro-0.1.0 → pywmswebcontrolpro-0.1.2}/tests/conftest.py

@@ -106,12 +106,13 @@ class FakeGateway:
     def __init__(self) -> None:
         self.status_answers: list[dict[str, Any] | Exception] = []
         self.requests: list[dict[str, Any]] = []
+        self.config = CONFIG
 
     def post(self, url: str, json: dict[str, Any], timeout: int) -> FakeRequest:
         """Answer one request of the library."""
         self.requests.append(json)
         if json["command"] == "getConfiguration":
-            return FakeRequest(CONFIG)
+            return FakeRequest(self.config)
         return FakeRequest(self.status_answers.pop(0))
 
     @property

pywmswebcontrolpro-0.1.2/tests/test_configuration.py

@@ -0,0 +1,59 @@
+"""Tests for reading the configuration of the gateway again."""
+
+from collections.abc import Callable
+from copy import deepcopy
+from typing import Any
+
+from pywmswebcontrolpro.webcontrol import ConfigChanges, WebControlPro
+
+from .conftest import CONFIG, DEST_ID, FakeGateway
+
+NEW_DEST_ID = 8
+
+
+def _config_with(*dest_ids: int) -> dict[str, Any]:
+    """Return a configuration with copies of the test destination."""
+    config = deepcopy(CONFIG)
+    template = config["destinations"][0]
+    config["destinations"] = [{**template, "id": dest_id} for dest_id in dest_ids]
+    return config
+
+
+async def test_first_refresh_reports_all_destinations_as_added(
+    make_control: Callable[..., WebControlPro],
+) -> None:
+    """The first read of the configuration finds the destinations."""
+    changes = await make_control().refresh()
+
+    assert changes == ConfigChanges(added=frozenset({DEST_ID}))
+
+
+async def test_refresh_reports_added_and_removed_destinations(
+    make_control: Callable[..., WebControlPro], gateway: FakeGateway
+) -> None:
+    """A destination that appears or disappears is named in the result."""
+    control = make_control()
+    await control.refresh()
+    gateway.config = _config_with(NEW_DEST_ID)
+
+    changes = await control.refresh()
+
+    assert changes == ConfigChanges(
+        added=frozenset({NEW_DEST_ID}), removed=frozenset({DEST_ID})
+    )
+    assert set(control.dests) == {NEW_DEST_ID}
+
+
+async def test_refresh_keeps_the_known_destinations(
+    make_control: Callable[..., WebControlPro], gateway: FakeGateway
+) -> None:
+    """A known destination stays the same object with its state."""
+    control = make_control()
+    await control.refresh()
+    known = control.dests[DEST_ID]
+    gateway.config = _config_with(DEST_ID, NEW_DEST_ID)
+
+    changes = await control.refresh()
+
+    assert changes == ConfigChanges(added=frozenset({NEW_DEST_ID}))
+    assert control.dests[DEST_ID] is known