pycomap 2.3.1__tar.gz → 2.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pycomap
3
- Version: 2.3.1
3
+ Version: 2.4.0
4
4
  Summary: Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol
5
5
  Author: Igor Panteleyev
6
6
  Author-email: Igor Panteleyev <panteleev.igor69@gmail.com>
@@ -40,8 +40,8 @@ from pycomap.protocol import ComApClient
40
40
 
41
41
  async with Controller(
42
42
  ComApClient(EthernetTransport(IPv4Address("192.168.1.9"))),
43
- access_code="0", # factory default (drives ECDH key derivation)
44
- password=1234, # write-protection password (0-9999); omit for read-only
43
+ access_code="0", # factory default (drives ECDH key derivation)
44
+ password=1234, # write-protection password (0-9999); omit for read-only
45
45
  ) as ctrl:
46
46
  values = await ctrl.read_values()
47
47
  print(values)
@@ -13,8 +13,8 @@ from pycomap.protocol import ComApClient
13
13
 
14
14
  async with Controller(
15
15
  ComApClient(EthernetTransport(IPv4Address("192.168.1.9"))),
16
- access_code="0", # factory default (drives ECDH key derivation)
17
- password=1234, # write-protection password (0-9999); omit for read-only
16
+ access_code="0", # factory default (drives ECDH key derivation)
17
+ password=1234, # write-protection password (0-9999); omit for read-only
18
18
  ) as ctrl:
19
19
  values = await ctrl.read_values()
20
20
  print(values)
@@ -0,0 +1,94 @@
1
+ [project]
2
+ name = "pycomap"
3
+ version = "2.4.0"
4
+ description = "Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ requires-python = ">=3.14"
8
+ dependencies = [
9
+ "cryptography>=42",
10
+ "pytz>=2026.2",
11
+ ]
12
+ classifiers = [
13
+ "Development Status :: 4 - Beta",
14
+ "Intended Audience :: Developers",
15
+ "License :: OSI Approved :: MIT License",
16
+ "Operating System :: OS Independent",
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3.14",
19
+ "Topic :: Home Automation",
20
+ "Topic :: System :: Hardware",
21
+ "Framework :: AsyncIO",
22
+ "Typing :: Typed",
23
+ ]
24
+
25
+ [[project.authors]]
26
+ name = "Igor Panteleyev"
27
+ email = "panteleev.igor69@gmail.com"
28
+
29
+ [project.urls]
30
+ Homepage = "https://github.com/dobters/pycomap"
31
+ Documentation = "https://dobters.github.io/pycomap/"
32
+ Source = "https://github.com/dobters/pycomap"
33
+ Issues = "https://github.com/dobters/pycomap/issues"
34
+ Changelog = "https://github.com/dobters/pycomap/releases"
35
+
36
+ [build-system]
37
+ requires = ["uv_build>=0.9.26,<0.13.0"]
38
+ build-backend = "uv_build"
39
+
40
+ [dependency-groups]
41
+ dev = [
42
+ "configargparse>=1.7.5",
43
+ "ifaddr>=0.2.0",
44
+ "python-dotenv>=1.2.2",
45
+ "zensical>=0.0.50",
46
+ "mkdocstrings-python>=1.0",
47
+ "pre-commit>=4.6.0",
48
+ "pytest>=8",
49
+ "pytest-asyncio>=0.24",
50
+ "pytest-cov>=7.1.0",
51
+ "pytest-env>=1.6.0",
52
+ "pytest-mock>=3.15.1",
53
+ "ruff>=0.15",
54
+ "ty>=0.0.16",
55
+ ]
56
+
57
+ [tool.pytest.ini_options]
58
+ addopts = "-ra"
59
+ asyncio_mode = "auto"
60
+ testpaths = ["tests"]
61
+ markers = ["integration: requires real ComAp hardware reachable on the network (set PYCOMAP_TEST_HOST, see .env.example)"]
62
+
63
+ [tool.pytest_env]
64
+ env_files = [".env"]
65
+
66
+ [tool.coverage.run]
67
+ source = ["src/pycomap"]
68
+ omit = ["tests/*"]
69
+
70
+ [tool.ruff]
71
+ line-length = 100
72
+ target-version = "py314"
73
+
74
+ [tool.ruff.lint]
75
+ select = [
76
+ "E",
77
+ "F",
78
+ "I",
79
+ "UP",
80
+ "B",
81
+ "SIM",
82
+ "C4",
83
+ "RUF",
84
+ ]
85
+
86
+ [tool.ruff.lint.isort]
87
+ known-first-party = ["pycomap"]
88
+
89
+ [tool.ty.environment]
90
+ python-version = "3.14"
91
+
92
+ [tool.uv]
93
+ required-version = ">=0.11.24"
94
+ publish-url = "https://upload.pypi.org/legacy/"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pycomap"
3
- version = "2.3.1"
3
+ version = "2.4.0"
4
4
  description = "Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -33,7 +33,7 @@ Issues = "https://github.com/dobters/pycomap/issues"
33
33
  Changelog = "https://github.com/dobters/pycomap/releases"
34
34
 
35
35
  [build-system]
36
- requires = ["uv_build>=0.9.26,<0.12.0"]
36
+ requires = ["uv_build>=0.9.26,<0.13.0"]
37
37
  build-backend = "uv_build"
38
38
 
39
39
  [dependency-groups]
@@ -109,6 +109,10 @@ class ComApClient[TransportT: Transport]:
109
109
 
110
110
  async def connect(self) -> None:
111
111
  """Open the transport and consume the controller's unsolicited ``VersionIB``."""
112
+ # Start from a clean slate so a client reused after a failed session doesn't carry
113
+ # over the previous session's framing mode or cipher state.
114
+ self._mode = _Mode.NONE
115
+ self._cipher = None
112
116
  await self._transport.connect()
113
117
 
114
118
  message = await self._read_message()
@@ -0,0 +1,190 @@
1
+ """Transport layer abstraction for the ComAp native protocol.
2
+
3
+ ``Transport`` is an ``abc.ABC`` — implementations must subclass it and provide the four
4
+ async methods. ``EthernetTransport`` is the only implementation for now; AirGate (cloud
5
+ relay) and serial transports can be added later without changing ``ComApClient``.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import asyncio
11
+ import contextlib
12
+ import logging
13
+ import socket
14
+ from abc import ABC, abstractmethod
15
+ from ipaddress import IPv4Address
16
+
17
+ from pycomap.exceptions import ComApConnectionError
18
+
19
+ DEFAULT_PORT = 23
20
+ DEFAULT_CONNECT_TIMEOUT = 10.0
21
+ DEFAULT_READ_TIMEOUT = 15.0
22
+ DEFAULT_WRITE_TIMEOUT = 10.0
23
+
24
+ # TCP keepalive: probe after 30 s idle, every 10 s, drop after 3 misses (~60 s to detect a
25
+ # dead peer instead of the OS default of hours).
26
+ _KEEPALIVE_IDLE = 30
27
+ _KEEPALIVE_INTERVAL = 10
28
+ _KEEPALIVE_COUNT = 3
29
+
30
+ _log = logging.getLogger(__name__)
31
+
32
+
33
+ class Transport(ABC):
34
+ """Byte-stream transport used by ``ComApClient``."""
35
+
36
+ @abstractmethod
37
+ async def connect(self) -> None:
38
+ """Open the underlying connection."""
39
+
40
+ @abstractmethod
41
+ async def close(self) -> None:
42
+ """Close the underlying connection, suppressing already-closed errors."""
43
+
44
+ @abstractmethod
45
+ async def read_exactly(self, n: int) -> bytes:
46
+ """Read exactly ``n`` bytes, raising ``ComApConnectionError`` if the stream ends."""
47
+
48
+ @abstractmethod
49
+ async def write(self, data: bytes) -> None:
50
+ """Write ``data`` and flush."""
51
+
52
+
53
+ class EthernetTransport(Transport):
54
+ """TCP transport for the ComAp native protocol (port 23).
55
+
56
+ Connects to ``host:port`` via plain TCP; the ``ComApClient`` layer adds the
57
+ ECDH/AES framing on top.
58
+ """
59
+
60
+ def __init__(
61
+ self,
62
+ host: IPv4Address,
63
+ port: int = DEFAULT_PORT,
64
+ *,
65
+ connect_timeout: float | None = DEFAULT_CONNECT_TIMEOUT,
66
+ read_timeout: float | None = DEFAULT_READ_TIMEOUT,
67
+ write_timeout: float | None = DEFAULT_WRITE_TIMEOUT,
68
+ ) -> None:
69
+ """
70
+ Args:
71
+ host: Controller IP address. Exposed back via
72
+ [host][pycomap.protocol.EthernetTransport.host] for e.g. probing reachability
73
+ via [discover_host][pycomap.discovery.discover_host].
74
+ port: TCP port; defaults to ``23`` (ComAp native protocol port).
75
+ connect_timeout: Seconds to wait for the TCP connection to open (``None`` = no limit).
76
+ read_timeout: Seconds to wait for each ``read_exactly`` call to complete, i.e. for
77
+ the controller to send the requested bytes (``None`` = no limit).
78
+ write_timeout: Seconds to wait for each ``write`` to flush (``None`` = no limit).
79
+
80
+ A timeout, like any socket error, raises
81
+ [ComApConnectionError][pycomap.ComApConnectionError] and closes the transport: after a
82
+ timeout the stream may be out of sync with the controller, so it must be reopened with
83
+ ``connect()`` before further use.
84
+ """
85
+ self._host = host
86
+ self._port = port
87
+ self._connect_timeout = connect_timeout
88
+ self._read_timeout = read_timeout
89
+ self._write_timeout = write_timeout
90
+ self._reader: asyncio.StreamReader | None = None
91
+ self._writer: asyncio.StreamWriter | None = None
92
+
93
+ @property
94
+ def host(self) -> IPv4Address:
95
+ """The controller's configured IP address."""
96
+ return self._host
97
+
98
+ @property
99
+ def port(self) -> int:
100
+ """The controller's configured TCP port."""
101
+ return self._port
102
+
103
+ async def connect(self) -> None:
104
+ _log.debug("connecting to %s:%d", self._host, self._port)
105
+ # Drop any previous (possibly half-dead) connection before opening a new one.
106
+ self._abort()
107
+ try:
108
+ self._reader, self._writer = await asyncio.wait_for(
109
+ asyncio.open_connection(str(self._host), self._port),
110
+ self._connect_timeout,
111
+ )
112
+ except TimeoutError as exc:
113
+ raise ComApConnectionError(
114
+ f"timed out connecting to {self._host}:{self._port}"
115
+ ) from exc
116
+ except OSError as exc:
117
+ raise ComApConnectionError(f"failed to connect to {self._host}:{self._port}") from exc
118
+ self._enable_keepalive()
119
+ _log.info("connected to %s:%d", self._host, self._port)
120
+
121
+ async def close(self) -> None:
122
+ if self._writer is not None:
123
+ self._writer.close()
124
+ with contextlib.suppress(OSError, TimeoutError):
125
+ await asyncio.wait_for(self._writer.wait_closed(), self._write_timeout)
126
+ _log.info("disconnected from %s:%d", self._host, self._port)
127
+ self._reader = None
128
+ self._writer = None
129
+
130
+ async def read_exactly(self, n: int) -> bytes:
131
+ if self._reader is None:
132
+ raise ComApConnectionError("not connected — call connect() first")
133
+ try:
134
+ return await asyncio.wait_for(self._reader.readexactly(n), self._read_timeout)
135
+ except asyncio.IncompleteReadError as exc:
136
+ self._abort()
137
+ raise ComApConnectionError("connection closed while reading a message") from exc
138
+ except TimeoutError as exc:
139
+ self._abort()
140
+ raise ComApConnectionError(
141
+ f"timed out after {self._read_timeout}s waiting for data from the controller"
142
+ ) from exc
143
+ except OSError as exc:
144
+ self._abort()
145
+ raise ComApConnectionError(f"connection error while reading: {exc}") from exc
146
+
147
+ async def write(self, data: bytes) -> None:
148
+ if self._writer is None:
149
+ raise ComApConnectionError("not connected — call connect() first")
150
+ try:
151
+ self._writer.write(data)
152
+ await asyncio.wait_for(self._writer.drain(), self._write_timeout)
153
+ except TimeoutError as exc:
154
+ self._abort()
155
+ raise ComApConnectionError(
156
+ f"timed out after {self._write_timeout}s writing to the controller"
157
+ ) from exc
158
+ except OSError as exc:
159
+ self._abort()
160
+ raise ComApConnectionError(f"connection error while writing: {exc}") from exc
161
+
162
+ def _abort(self) -> None:
163
+ """Drop the connection immediately (no graceful close) and forget the streams."""
164
+ if self._writer is not None:
165
+ with contextlib.suppress(OSError):
166
+ self._writer.transport.abort()
167
+ self._reader = None
168
+ self._writer = None
169
+
170
+ def _enable_keepalive(self) -> None:
171
+ """Turn on TCP keepalive so a silently dead peer is detected in about a minute."""
172
+ if self._writer is None:
173
+ return
174
+ sock = self._writer.get_extra_info("socket")
175
+ if sock is None:
176
+ return
177
+ try:
178
+ sock.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
179
+ # Idle option name differs per platform: TCP_KEEPIDLE (Linux/Windows),
180
+ # TCP_KEEPALIVE (macOS). Interval/count are best-effort.
181
+ idle_opt = getattr(socket, "TCP_KEEPIDLE", getattr(socket, "TCP_KEEPALIVE", None))
182
+ for opt, value in (
183
+ (idle_opt, _KEEPALIVE_IDLE),
184
+ (getattr(socket, "TCP_KEEPINTVL", None), _KEEPALIVE_INTERVAL),
185
+ (getattr(socket, "TCP_KEEPCNT", None), _KEEPALIVE_COUNT),
186
+ ):
187
+ if opt is not None:
188
+ sock.setsockopt(socket.IPPROTO_TCP, opt, value)
189
+ except OSError:
190
+ _log.debug("could not configure TCP keepalive", exc_info=True)
@@ -1,102 +0,0 @@
1
- """Transport layer abstraction for the ComAp native protocol.
2
-
3
- ``Transport`` is an ``abc.ABC`` — implementations must subclass it and provide the four
4
- async methods. ``EthernetTransport`` is the only implementation for now; AirGate (cloud
5
- relay) and serial transports can be added later without changing ``ComApClient``.
6
- """
7
-
8
- from __future__ import annotations
9
-
10
- import asyncio
11
- import contextlib
12
- import logging
13
- from abc import ABC, abstractmethod
14
- from ipaddress import IPv4Address
15
-
16
- from pycomap.exceptions import ComApConnectionError
17
-
18
- DEFAULT_PORT = 23
19
-
20
- _log = logging.getLogger(__name__)
21
-
22
-
23
- class Transport(ABC):
24
- """Byte-stream transport used by ``ComApClient``."""
25
-
26
- @abstractmethod
27
- async def connect(self) -> None:
28
- """Open the underlying connection."""
29
-
30
- @abstractmethod
31
- async def close(self) -> None:
32
- """Close the underlying connection, suppressing already-closed errors."""
33
-
34
- @abstractmethod
35
- async def read_exactly(self, n: int) -> bytes:
36
- """Read exactly ``n`` bytes, raising ``ComApConnectionError`` if the stream ends."""
37
-
38
- @abstractmethod
39
- async def write(self, data: bytes) -> None:
40
- """Write ``data`` and flush."""
41
-
42
-
43
- class EthernetTransport(Transport):
44
- """TCP transport for the ComAp native protocol (port 23).
45
-
46
- Connects to ``host:port`` via plain TCP; the ``ComApClient`` layer adds the
47
- ECDH/AES framing on top.
48
- """
49
-
50
- def __init__(self, host: IPv4Address, port: int = DEFAULT_PORT) -> None:
51
- """
52
- Args:
53
- host: Controller IP address. Exposed back via
54
- [host][pycomap.protocol.EthernetTransport.host] for e.g. probing reachability
55
- via [discover_host][pycomap.discovery.discover_host].
56
- port: TCP port; defaults to ``23`` (ComAp native protocol port).
57
- """
58
- self._host = host
59
- self._port = port
60
- self._reader: asyncio.StreamReader | None = None
61
- self._writer: asyncio.StreamWriter | None = None
62
-
63
- @property
64
- def host(self) -> IPv4Address:
65
- """The controller's configured IP address."""
66
- return self._host
67
-
68
- @property
69
- def port(self) -> int:
70
- """The controller's configured TCP port."""
71
- return self._port
72
-
73
- async def connect(self) -> None:
74
- _log.debug("connecting to %s:%d", self._host, self._port)
75
- try:
76
- self._reader, self._writer = await asyncio.open_connection(str(self._host), self._port)
77
- except OSError as exc:
78
- raise ComApConnectionError(f"failed to connect to {self._host}:{self._port}") from exc
79
- _log.info("connected to %s:%d", self._host, self._port)
80
-
81
- async def close(self) -> None:
82
- if self._writer is not None:
83
- self._writer.close()
84
- with contextlib.suppress(OSError):
85
- await self._writer.wait_closed()
86
- _log.info("disconnected from %s:%d", self._host, self._port)
87
- self._reader = None
88
- self._writer = None
89
-
90
- async def read_exactly(self, n: int) -> bytes:
91
- if self._reader is None:
92
- raise ComApConnectionError("not connected — call connect() first")
93
- try:
94
- return await self._reader.readexactly(n)
95
- except asyncio.IncompleteReadError as exc:
96
- raise ComApConnectionError("connection closed while reading a message") from exc
97
-
98
- async def write(self, data: bytes) -> None:
99
- if self._writer is None:
100
- raise ComApConnectionError("not connected — call connect() first")
101
- self._writer.write(data)
102
- await self._writer.drain()
File without changes
File without changes
File without changes
File without changes