pycomap 2.0.0__tar.gz → 2.1.0__tar.gz

{pycomap-2.0.0 → pycomap-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycomap
-Version: 2.0.0
+Version: 2.1.0
 Summary: Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol
 Author: Igor Panteleyev
 Author-email: Igor Panteleyev <panteleev.igor69@gmail.com>

{pycomap-2.0.0 → pycomap-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pycomap"
-version = "2.0.0"
+version = "2.1.0"
 description = "Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol"
 readme = "README.md"
 license = "MIT"
@@ -33,7 +33,7 @@ Issues = "https://github.com/igor-panteleev/pycomap/issues"
 Changelog = "https://github.com/igor-panteleev/pycomap/releases"
 
 [build-system]
-requires = ["uv_build>=0.9.26,<0.10.0"]
+requires = ["uv_build>=0.9.26,<0.12.0"]
 build-backend = "uv_build"
 
 [dependency-groups]
@@ -90,4 +90,5 @@ known-first-party = ["pycomap"]
 python-version = "3.14"
 
 [tool.uv]
+required-version = ">=0.11.24"
 publish-url = "https://upload.pypi.org/legacy/"

{pycomap-2.0.0 → pycomap-2.1.0}/src/pycomap/controller.py

@@ -31,6 +31,7 @@ import logging
 import re
 from collections.abc import Mapping
 from types import MappingProxyType, TracebackType
+from typing import Self
 
 from pycomap.alarms import AlarmRecord, parse_alarm_list
 from pycomap.configuration import (
@@ -61,6 +62,7 @@ from pycomap.history import HistoryRecord, parse_history_record
 from pycomap.protocol.client import ComApClient
 from pycomap.protocol.commands import ControllerCommand
 from pycomap.protocol.objects import CommunicationObject
+from pycomap.protocol.transport import Transport
 
 _log = logging.getLogger(__name__)
 
@@ -133,7 +135,7 @@ def _encode_setpoint_value(
     return encode_raw_value(data_type, value, decimal_places)
 
 
-class Controller:
+class Controller[TransportT: Transport]:
     """High-level async client for a ComAp controller.
 
     Fetches and caches the ``ConfigurationTable`` on [connect][pycomap.Controller.connect],
@@ -172,7 +174,7 @@ class Controller:
 
     def __init__(
         self,
-        client: ComApClient,
+        client: ComApClient[TransportT],
         access_code: str,
         password: int | None = None,
         include_invisible: bool = False,
@@ -207,7 +209,7 @@ class Controller:
         """Close the underlying transport."""
         await self._client.close()
 
-    async def __aenter__(self) -> Controller:
+    async def __aenter__(self) -> Self:
         await self.connect()
         return self
 
@@ -222,7 +224,7 @@ class Controller:
     # -- properties ----------------------------------------------------------
 
     @property
-    def client(self) -> ComApClient:
+    def client(self) -> ComApClient[TransportT]:
         """The underlying low-level client (escape hatch for direct comm object access)."""
         return self._client
 

{pycomap-2.0.0 → pycomap-2.1.0}/src/pycomap/discovery.py

@@ -119,7 +119,10 @@ def _parse_device(data: bytes) -> DiscoveryDevice:
     is_units_list_complete = bool(data[offset])
     offset += 1
 
-    assert offset == header_size
+    if offset != header_size:
+        raise ComApProtocolError(
+            f"discovery device header parse offset mismatch: got {offset}, expected {header_size}"
+        )
     units = [
         DiscoveryUnit(
             type=data[i],

{pycomap-2.0.0 → pycomap-2.1.0}/src/pycomap/protocol/client.py

@@ -23,6 +23,7 @@ import hashlib
 import logging
 import struct
 from types import TracebackType
+from typing import Self
 
 from pycomap.datatypes import decode_fdate, decode_ftime, encode_fdate, encode_ftime
 from pycomap.exceptions import (
@@ -63,9 +64,14 @@ _AUTH_FALLBACK_CODES = {
 _log = logging.getLogger(__name__)
 
 
-class ComApClient:
+class ComApClient[TransportT: Transport]:
     """Speaks the ECDH/AES-encrypted ``EthernetMessage`` protocol over any ``Transport``.
 
+    Generic over the concrete ``Transport`` type, so
+    [transport][pycomap.protocol.ComApClient.transport] gives back the type you passed in
+    (e.g. ``ComApClient[EthernetTransport]`` exposes ``.transport.host``) instead of the
+    narrower structural ``Transport`` protocol.
+
     Pass any ``Transport`` implementation — typically ``EthernetTransport``::
 
         from ipaddress import IPv4Address
@@ -76,7 +82,7 @@ class ComApClient:
             await client.authenticate("0")
     """
 
-    def __init__(self, transport: Transport) -> None:
+    def __init__(self, transport: TransportT) -> None:
         """
         Args:
             transport: Byte-stream transport to use (typically ``EthernetTransport``).
@@ -87,7 +93,7 @@ class ComApClient:
         self._cipher: ChainedAesCbc | None = None
 
     @property
-    def transport(self) -> Transport:
+    def transport(self) -> TransportT:
         """The underlying byte-stream transport."""
         return self._transport
 
@@ -195,7 +201,7 @@ class ComApClient:
         self._mode = _Mode.NONE
         self._cipher = None
 
-    async def __aenter__(self) -> ComApClient:
+    async def __aenter__(self) -> Self:
         await self.connect()
         return self
 
@@ -353,7 +359,8 @@ class ComApClient:
 
         if self._mode is _Mode.ALIGNED:
             return block_payload
-        assert self._cipher is not None
+        if self._cipher is None:
+            raise ComApProtocolError("AES mode active but cipher not initialized")
         return self._cipher.decrypt(block_payload)
 
     async def _write_inner(self, inner: bytes) -> None:
@@ -363,5 +370,6 @@ class ComApClient:
         elif self._mode is _Mode.ALIGNED:
             await self._transport.write(wrap_outer(padded))
         else:
-            assert self._cipher is not None
+            if self._cipher is None:
+                raise ComApProtocolError("AES mode active but cipher not initialized")
             await self._transport.write(wrap_outer(self._cipher.encrypt(padded)))

{pycomap-2.0.0 → pycomap-2.1.0}/src/pycomap/protocol/transport.py

@@ -1,9 +1,8 @@
 """Transport layer abstraction for the ComAp native protocol.
 
-``Transport`` is a structural ``typing.Protocol`` — any object with the four async
-methods qualifies, no subclassing required. ``EthernetTransport`` is the only
-implementation for now; AirGate (cloud relay) and serial transports can be added later
-without changing ``ComApClient``.
+``Transport`` is an ``abc.ABC`` — implementations must subclass it and provide the four
+async methods. ``EthernetTransport`` is the only implementation for now; AirGate (cloud
+relay) and serial transports can be added later without changing ``ComApClient``.
 """
 
 from __future__ import annotations
@@ -11,8 +10,8 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import logging
+from abc import ABC, abstractmethod
 from ipaddress import IPv4Address
-from typing import Protocol, runtime_checkable
 
 from pycomap.exceptions import ComApConnectionError
 
@@ -21,28 +20,27 @@ DEFAULT_PORT = 23
 _log = logging.getLogger(__name__)
 
 
-@runtime_checkable
-class Transport(Protocol):
+class Transport(ABC):
     """Byte-stream transport used by ``ComApClient``."""
 
+    @abstractmethod
     async def connect(self) -> None:
         """Open the underlying connection."""
-        ...
 
+    @abstractmethod
     async def close(self) -> None:
         """Close the underlying connection, suppressing already-closed errors."""
-        ...
 
+    @abstractmethod
     async def read_exactly(self, n: int) -> bytes:
         """Read exactly ``n`` bytes, raising ``ComApConnectionError`` if the stream ends."""
-        ...
 
+    @abstractmethod
     async def write(self, data: bytes) -> None:
         """Write ``data`` and flush."""
-        ...
 
 
-class EthernetTransport:
+class EthernetTransport(Transport):
     """TCP transport for the ComAp native protocol (port 23).
 
     Connects to ``host:port`` via plain TCP; the ``ComApClient`` layer adds the
@@ -67,6 +65,11 @@ class EthernetTransport:
         """The controller's configured IP address."""
         return self._host
 
+    @property
+    def port(self) -> int:
+        """The controller's configured TCP port."""
+        return self._port
+
     async def connect(self) -> None:
         _log.debug("connecting to %s:%d", self._host, self._port)
         try:
@@ -85,13 +88,15 @@ class EthernetTransport:
         self._writer = None
 
     async def read_exactly(self, n: int) -> bytes:
-        assert self._reader is not None
+        if self._reader is None:
+            raise ComApConnectionError("not connected — call connect() first")
         try:
             return await self._reader.readexactly(n)
         except asyncio.IncompleteReadError as exc:
             raise ComApConnectionError("connection closed while reading a message") from exc
 
     async def write(self, data: bytes) -> None:
-        assert self._writer is not None
+        if self._writer is None:
+            raise ComApConnectionError("not connected — call connect() first")
         self._writer.write(data)
         await self._writer.drain()