pycomap 2.0.0__tar.gz → 2.1.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycomap
-Version: 2.0.0
+Version: 2.1.1
 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>
@@ -50,7 +50,7 @@ async with Controller(
     await ctrl.set_setpoint("Summer Time Mode", "Winter")  # STRING_LIST by label
 ```
 
-See the [API docs](https://igor-panteleev.github.io/pycomap/) for full reference. `just docs-serve` to browse locally.
+See the [API docs](https://igor-panteleev.github.io/pycomap/) for full reference, built with [Zensical](https://zensical.org/). `just docs-serve` to browse locally.
 
 ## Development
 

{pycomap-2.0.0 → pycomap-2.1.1}/README.md

@@ -23,7 +23,7 @@ async with Controller(
     await ctrl.set_setpoint("Summer Time Mode", "Winter")  # STRING_LIST by label
 ```
 
-See the [API docs](https://igor-panteleev.github.io/pycomap/) for full reference. `just docs-serve` to browse locally.
+See the [API docs](https://igor-panteleev.github.io/pycomap/) for full reference, built with [Zensical](https://zensical.org/). `just docs-serve` to browse locally.
 
 ## Development
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "pycomap"
-version = "2.0.0"
+version = "2.1.1"
 description = "Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol"
 readme = "README.md"
 license = "MIT"
@@ -33,15 +33,16 @@ 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]
 dev = [
+    "configargparse>=1.7.5",
     "ifaddr>=0.2.0",
-    "mkdocs>=1.6,<2",
-    "mkdocs-material>=9.5",
-    "mkdocstrings[python]>=0.25",
+    "python-dotenv>=1.2.2",
+    "zensical>=0.0.50",
+    "mkdocstrings-python>=1.0",
     "pre-commit>=4.6.0",
     "pytest>=8",
     "pytest-asyncio>=0.24",
@@ -90,4 +91,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.1}/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
 
@@ -317,6 +319,51 @@ class Controller:
         except KeyError:
             raise KeyError(f"no setpoint named {name_or_number!r}") from None
 
+    def _string_list_options(
+        self, desc: ValueDescription | SetpointDescription
+    ) -> list[tuple[int, str]]:
+        """Shared ``STRING_LIST`` option lookup for
+        [value_options][pycomap.Controller.value_options] and
+        [setpoint_options][pycomap.Controller.setpoint_options].
+
+        Options are stored in ``CommonNames`` at indices ``[low_limit .. high_limit]``.
+        """
+        if desc.data_type is not DataType.STRING_LIST:
+            raise ComApProtocolError(
+                f"{desc.name!r} is DataType.{desc.data_type.name}, not STRING_LIST"
+            )
+        return [
+            (wire_value, self._common_names[desc.low_limit + wire_value])
+            for wire_value in range(desc.high_limit - desc.low_limit + 1)
+            if desc.low_limit + wire_value < len(self._common_names)
+        ]
+
+    def value_options(self, name_or_number: str | int) -> list[tuple[int, str]]:
+        """Return the available options for a ``STRING_LIST`` value.
+
+        Options are stored in ``CommonNames`` at indices ``[low_limit .. high_limit]``.
+        The wire value (0-based) is what the controller sends on the wire and what
+        [value_label][pycomap.Controller.value_label] expects; the label is the string
+        shown on the front panel and in InteliConfig. Note that
+        [read_values][pycomap.Controller.read_values] resolves ``STRING_LIST`` values to
+        their label automatically — this method is for enumerating all possible options
+        up front (e.g. to build a legend or validate against known states).
+
+        Args:
+            name_or_number: Value name or comm object number.
+
+        Returns:
+            ``[(wire_value, label), ...]`` ordered by wire value.
+
+        Raises:
+            ComApProtocolError: If the value is not ``STRING_LIST`` type.
+
+        Examples:
+            >>> ctrl.value_options("Engine State")
+            [(0, 'Ready'), (1, 'Prestart'), (2, 'Cranking'), ...]
+        """
+        return self._string_list_options(self.value_info(name_or_number))
+
     def setpoint_options(self, name_or_number: str | int) -> list[tuple[int, str]]:
         """Return the available options for a ``STRING_LIST`` setpoint.
 
@@ -338,16 +385,7 @@ class Controller:
             >>> ctrl.setpoint_options("Summer Time Mode")
             [(0, 'Disabled'), (1, 'Winter'), (2, 'Summer'), (3, 'Winter-S'), (4, 'Summer-S')]
         """
-        desc = self.setpoint_info(name_or_number)
-        if desc.data_type is not DataType.STRING_LIST:
-            raise ComApProtocolError(
-                f"setpoint {desc.name!r} is DataType.{desc.data_type.name}, not STRING_LIST"
-            )
-        return [
-            (wire_value, self._common_names[desc.low_limit + wire_value])
-            for wire_value in range(desc.high_limit - desc.low_limit + 1)
-            if desc.low_limit + wire_value < len(self._common_names)
-        ]
+        return self._string_list_options(self.setpoint_info(name_or_number))
 
     def value_label(self, name_or_number: str | int, wire_value: int) -> str:
         """Return the display label for a ``STRING_LIST`` value's wire integer.

{pycomap-2.0.0 → pycomap-2.1.1}/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.1}/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.1}/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()