aioads 0.1.0.dev2__tar.gz → 0.1.0.dev4__tar.gz

aioads-0.1.0.dev4/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  # Keep the SHA-pinned GitHub Actions current (Dependabot updates both the
+  # pinned SHA and the trailing version comment).
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+
+  # Python dev/runtime dependencies tracked in pdm.lock / pyproject.toml.
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]

aioads-0.1.0.dev4/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up PDM
+        uses: pdm-project/setup-pdm@973541a5febeafcfdadf8a51211435be6ecfd90f  # v4.5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: true
+
+      - name: Install dependencies
+        run: pdm install
+
+      - name: Lint
+        run: pdm run lint
+
+      - name: Run tests with coverage
+        run: pdm run coverage
+
+      - name: Upload coverage artifact
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: ignore

aioads-0.1.0.dev4/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Avoid two releases racing to publish the same version.
+concurrency:
+  group: publish-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up PDM
+        uses: pdm-project/setup-pdm@973541a5febeafcfdadf8a51211435be6ecfd90f  # v4.5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: pdm build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Only publish for real releases, not manual test runs.
+    if: github.event_name == 'release'
+    environment:
+      name: pypi
+      url: https://pypi.org/project/aioads/
+    permissions:
+      # IMPORTANT: required for OIDC trusted publishing.
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+        with:
+          # Sign the published distributions with PEP 740 build provenance.
+          attestations: true

{aioads-0.1.0.dev2 → aioads-0.1.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aioads
-Version: 0.1.0.dev2
+Version: 0.1.0.dev4
 Summary: An asynchronous Python library for communicating with Beckhoff TwinCAT PLCs
 Author-email: MkKiefer <102972583+MkKiefer@users.noreply.github.com>
 License: MIT

{aioads-0.1.0.dev2 → aioads-0.1.0.dev4}/aioads/ads_client.py

@@ -266,36 +266,59 @@ class AdsClient:
     ) -> dict[str, SymbolReadResult]:
         """
         Read multiple symbols by their names from the ADS device.
+
+        The returned dict is keyed by the symbol names exactly as requested,
+        preserving their original casing.
         """
         symbol_infos = await self._cache.read_symbol_infos_by_names(symbol_names)
         if raise_errors:
             self._raise_if_error(symbol_infos)
 
-        read_commands = [
-            AdsReadCommand(
-                transport=self.transport,
-                ams_address=self.dst_address,
-                idx_group=symbol_info.idx_group,
-                idx_offset=symbol_info.idx_offset,
-                length=symbol_info.idx_length,
-            )
-            for _, symbol_info in symbol_infos.values()
-        ]
+        output: dict[str, SymbolReadResult] = {}
+
+        # Only symbols whose info resolved successfully can be read. Symbols
+        # with a lookup error are reported as-is; building a read command from
+        # their (invalid) index group/offset would misalign the bulk response.
+        readable: list[tuple[str, SymbolInfo]] = []
+        for requested_name, (error_code, symbol_info) in symbol_infos.items():
+            if not error_code.ok:
+                output[requested_name] = SymbolReadResult(error_code, None)
+            else:
+                readable.append((requested_name, symbol_info))
+
+        if not readable:
+            return output
+
         function = AdsSumRead(
             transport=self.transport,
             ams_address=self.dst_address,
-            commands=read_commands,
+            commands=[
+                AdsReadCommand(
+                    transport=self.transport,
+                    ams_address=self.dst_address,
+                    idx_group=symbol_info.idx_group,
+                    idx_offset=symbol_info.idx_offset,
+                    length=symbol_info.idx_length,
+                )
+                for _, symbol_info in readable
+            ],
         )
-
         response = await function.execute()
-        output: dict[str, SymbolReadResult] = {}
 
+        loop = asyncio.get_running_loop()
+        parse_names: list[str] = []
         tasks = []
-        for (_, resp_payload), (error_code, symbol_info) in zip(
-            response, symbol_infos.values()
+        for (requested_name, symbol_info), (read_response, resp_payload) in zip(
+            readable, response
         ):
+            # A failed read yields no usable payload, so skip parsing it.
+            if read_response.error_code != 0:
+                output[requested_name] = SymbolReadResult(
+                    read_response.error_code, None)
+                continue
+            parse_names.append(requested_name)
             tasks.append(
-                asyncio.get_running_loop().run_in_executor(
+                loop.run_in_executor(
                     self.parser_pool,
                     self.parser.parse,
                     symbol_info.data_type,
@@ -303,11 +326,11 @@ class AdsClient:
                     resp_payload,
                 )
             )
-        parsed = await asyncio.gather(*tasks)
 
-        for symbol_data, (error_code, symbol_info) in zip(parsed, symbol_infos.values()):
-            output[symbol_info.symbol_name] = SymbolReadResult(
-                error_code, symbol_data)
+        parsed = await asyncio.gather(*tasks)
+        for requested_name, symbol_data in zip(parse_names, parsed):
+            output[requested_name] = SymbolReadResult(
+                AdsErrorCode(0), symbol_data)
 
         return output
 

{aioads-0.1.0.dev2 → aioads-0.1.0.dev4}/aioads/ads_symbol_parser.py

@@ -67,6 +67,8 @@ class PrimitiveTypeParser(ISymbolParser):
 
     def parse(self, data_type: AdsSymbolDataType, type_name: str,  raw_data: AdsStream) -> Any:
         """Parse a primitive data type."""
+        if data_type == AdsSymbolDataType.VOID:
+            return None
         if data_type == AdsSymbolDataType.STRING:
             return self._parse_string(type_name, raw_data)
         if data_type == AdsSymbolDataType.WSTRING:

{aioads-0.1.0.dev2 → aioads-0.1.0.dev4}/aioads/commands/ads_add_notification.py

@@ -77,7 +77,7 @@ class AdsAddNotificationCommand(ICommand[AdsAddNotificationResponse]):
     Ads command to create a ads notification (subscription to a remote resource)
     """
 
-    SERIALIZE_STRUCT_DEF: Final[Struct] = Struct("<IIIIIII16s")
+    SERIALIZE_STRUCT_DEF: Final[Struct] = Struct("<IIIIII16s")
 
     def __init__(
         self,

{aioads-0.1.0.dev2 → aioads-0.1.0.dev4}/aioads/commands/errors.py

@@ -27,4 +27,7 @@ class AdsCommandError(Exception):
 
     def __repr__(self) -> str:
         """Returns a detailed representation of the error for debugging."""
-        return f"AdsCommandError(error_code={self.error_code!r}, error_message:{self.error_code.description} args={self.args!r})"
+        return (
+            f"AdsCommandError(error_code={self.error_code!r}, "
+            f"error_message:{self.error_code.description} args={self.args!r})"
+        )

{aioads-0.1.0.dev2 → aioads-0.1.0.dev4}/aioads/transport.py

@@ -3,7 +3,9 @@ TCP transport implementation for ADS protocol.
 """
 import asyncio
 import contextlib
+import enum
 import logging
+import random
 import re
 from abc import ABC
 from dataclasses import dataclass
@@ -64,6 +66,23 @@ class ITransport(ABC):
         raise NotImplementedError
 
 
+class ConnectionState(enum.Enum):
+    """
+    Lifecycle state of a transport connection.
+    """
+
+    DISCONNECTED = enum.auto()
+    """Never connected, or the initial connect failed."""
+    CONNECTING = enum.auto()
+    """Initial connect attempt in progress."""
+    CONNECTED = enum.auto()
+    """Connected; requests are allowed."""
+    RECONNECTING = enum.auto()
+    """Connection dropped; the supervisor is re-establishing it. Requests fail fast."""
+    CLOSED = enum.auto()
+    """Intentionally closed via disconnect(); the supervisor must not reconnect."""
+
+
 class BaseTransport:
     """
     Common base class for all transport implementations, providing common functionality for:
@@ -189,6 +208,8 @@ class AdsTcpTransport(BaseTransport, ITransport):
 
     REQUEST_TIMEOUT = 120.0
     CONNECT_TIMEOUT = 30.0
+    RECONNECT_INITIAL_BACKOFF = 1.0
+    RECONNECT_MAX_BACKOFF = 30.0
 
     def __init__(
         self,
@@ -210,7 +231,8 @@ class AdsTcpTransport(BaseTransport, ITransport):
         self._stream: None | tuple[asyncio.StreamReader,
                                    asyncio.StreamWriter] = None
         self._stream_lock = asyncio.Lock()
-        self._reader_task: None | asyncio.Task[None] = None
+        self._supervisor_task: None | asyncio.Task[None] = None
+        self._state = ConnectionState.DISCONNECTED
 
     def set_notification_callback(
         self, callback: Callable[[AmsHeader, AdsStream], Coroutine[None, None, None]]
@@ -220,29 +242,63 @@ class AdsTcpTransport(BaseTransport, ITransport):
     async def connect(self):
         """
         Connect to the remote PLC via TCP.
+
+        Performs the initial connection synchronously and raises on failure.
+        On success a background supervisor task takes over the read loop and
+        transparently reconnects (with backoff) if the connection drops.
         """
-        if self._stream is not None:
+        if self._supervisor_task is not None and not self._supervisor_task.done():
             return
 
-        self._stream = await asyncio.wait_for(
-            asyncio.open_connection(self.ip, self.port), self.CONNECT_TIMEOUT
-        )
-        self._reader_task = asyncio.create_task(self._reader())
+        self._state = ConnectionState.CONNECTING
+        try:
+            await self._open()
+        except Exception:
+            self._state = ConnectionState.DISCONNECTED
+            raise
+        self._supervisor_task = asyncio.create_task(self._supervise())
 
     async def disconnect(self):
         """
-        Disconnect from the remote PLC.
+        Disconnect from the remote PLC and stop the supervisor.
+
+        Sets CLOSED first so the supervisor does not attempt to reconnect, then
+        tears down the stream (which unblocks the read loop) and awaits the
+        supervisor task.
         """
-        if self._stream is None:
-            return
+        self._state = ConnectionState.CLOSED
+        await self._teardown_stream(ConnectionError("Transport disconnected"))
+        await self.cancel_task(self._supervisor_task)
+        self._supervisor_task = None
 
-        await self.cancel_task(self._reader_task)
-        _, writer = self._stream
-        writer.close()
-        await writer.wait_closed()
+    async def _open(self):
+        """
+        Open the TCP connection and publish it as the active stream.
+        Raises on failure; callers own the surrounding state transitions.
+        """
+        reader, writer = await asyncio.wait_for(
+            asyncio.open_connection(self.ip, self.port), self.CONNECT_TIMEOUT
+        )
+        async with self._stream_lock:
+            self._stream = (reader, writer)
+        self._state = ConnectionState.CONNECTED
 
-        self._stream = None
-        self._reader_task = None
+    async def _teardown_stream(self, ex: BaseException):
+        """
+        Fail all in-flight requests and close the current stream (if any).
+
+        In-flight requests are intentionally *not* replayed: a write may already
+        have been applied on the PLC, so resending could double-apply it.
+        """
+        self.cancel_pending_requests(ex)
+        async with self._stream_lock:
+            stream = self._stream
+            self._stream = None
+        if stream is not None:
+            _, writer = stream
+            writer.close()
+            with contextlib.suppress(Exception):
+                await writer.wait_closed()
 
     async def request(
         self, command_payload: bytes, command_id: AdsCommandId, ams_address: AmsAddress
@@ -253,8 +309,10 @@ class AdsTcpTransport(BaseTransport, ITransport):
 
         :return: A tuple containing the AmsHeader and the payload bytes
         """
-        if self._stream is None:
-            raise ConnectionError("Not connected to the remote PLC")
+        if self._state is not ConnectionState.CONNECTED:
+            raise ConnectionError(
+                f"Not connected to the remote (state: {self._state.name})"
+            )
 
         invoke_id = self.get_next_invoke_id()
 
@@ -276,7 +334,14 @@ class AdsTcpTransport(BaseTransport, ITransport):
 
         async with self.subscribe_request(invoke_id) as response_future:
             async with self._stream_lock:
-                _, writer = self._stream
+                stream = self._stream
+                if stream is None:
+                    # A teardown raced this send; surface the failure it already
+                    # set on the future rather than a fresh, unretrieved one.
+                    if response_future.done():
+                        return await response_future
+                    raise ConnectionError("Not connected to the remote")
+                _, writer = stream
                 # Send request
                 writer.write(tcp_header_bytes +
                              ams_header_bytes + command_payload)
@@ -285,36 +350,86 @@ class AdsTcpTransport(BaseTransport, ITransport):
                 response_future, timeout=self.REQUEST_TIMEOUT
             )
 
-    async def _reader(self):
-        """
-        Reader task that continuously reads from the TCP stream.
-        """
-        try:
-            if not self._stream:
-                raise ConnectionError("Not connected to the remote PLC")
+    async def _supervise(self):
+        """
+        Own the connection lifecycle: run the read loop, and when the connection
+        drops, fail in-flight requests and reconnect with exponential backoff.
+
+        This is the only place that reconnects, so concurrent senders never
+        trigger competing reconnect attempts. Senders fail fast instead (see
+        :meth:`request`), which also respects the Beckhoff single-connection
+        backoff/lockout behavior.
+        """
+        backoff = self.RECONNECT_INITIAL_BACKOFF
+        while self._state is not ConnectionState.CLOSED:
+            try:
+                await self._read_loop()
+            except asyncio.CancelledError: #pylint: disable=try-except-raise
+                # Except everything... except a cancellation event
+                raise
+            except Exception as e:
+                self.logger.info("Connection lost: %s", e)
+
+            if self._state is ConnectionState.CLOSED:
+                break
+
+            self._state = ConnectionState.RECONNECTING
+            await self._teardown_stream(ConnectionError("Connection lost"))
+
+            while self._state is not ConnectionState.CLOSED:
+                try:
+                    await self._open()
+                    self.logger.info("Reconnected to the remote")
+                    backoff = self.RECONNECT_INITIAL_BACKOFF
+                    break
+                except asyncio.CancelledError: #pylint: disable=try-except-raise
+                    raise
+                except Exception as e:  # pylint: disable=broad-exception-caught
+                    self.logger.info(
+                        "Reconnect failed: %s, retrying in %.1fs", e, backoff
+                    )
+                    await asyncio.sleep(backoff + random.uniform(0, backoff))
+                    backoff = min(backoff * 2, self.RECONNECT_MAX_BACKOFF)
+
+    async def _read_loop(self):
+        """
+        Continuously read and dispatch messages from the active stream.
+        Returns/raises when the connection drops; the supervisor handles recovery.
+        """
+        stream = self._stream
+        if stream is None:
+            raise ConnectionError("Not connected to the remote PLC")
 
-            reader, _ = self._stream
-            while True:
+        reader, _ = stream
+        while True:
+            try:
                 # Read AmsTcpHeader
                 tcp_header_bytes = await reader.readexactly(AmsTcpHeader.FIXED_SIZE)
                 tcp_header = AmsTcpHeader.deserialize(tcp_header_bytes)
                 payload_bytes = await reader.readexactly(tcp_header.length)
+            except asyncio.IncompleteReadError as e:
+                # readexactly hit EOF: the peer's recv() returned 0 bytes,
+                # i.e. the remote closed the connection. An empty partial is an
+                # orderly close on a message boundary; a non-empty partial means
+                # we were cut off mid-message. Either way the stream is dead, so
+                # raise a clear ConnectionError for the supervisor to reconnect.
+                if e.partial:
+                    raise ConnectionError(
+                        f"Connection closed mid-message: received "
+                        f"{len(e.partial)} of {e.expected} expected bytes"
+                    ) from e
+                raise ConnectionError("Connection closed by remote") from e
+
+            ams_message_stream = AdsStream(memoryview(payload_bytes))
+            ams_header = AmsHeader.deserialize(ams_message_stream)
+            ams_command = ams_message_stream.sub_stream(
+                ams_header.command_length)
 
-                ams_message_stream = AdsStream(memoryview(payload_bytes))
-                ams_header = AmsHeader.deserialize(ams_message_stream)
-                ams_command = ams_message_stream.sub_stream(
-                    ams_header.command_length)
-
-                if AdsCommandState.ADS_RESPONSE in ams_header.command_flags:
-                    await self._handle_response(ams_header, ams_command)
+            if AdsCommandState.ADS_RESPONSE in ams_header.command_flags:
+                await self._handle_response(ams_header, ams_command)
 
-                elif AdsCommandState.ADS_REQUEST in ams_header.command_flags:
-                    await self._handle_request(ams_header, ams_command)
-        except asyncio.CancelledError:
-            pass
-        except Exception as e:  # pylint: disable=broad-exception-caught
-            self.logger.error("Reader task encountered an error", exc_info=e)
-            self.cancel_pending_requests(e)
+            elif AdsCommandState.ADS_REQUEST in ams_header.command_flags:
+                await self._handle_request(ams_header, ams_command)
 
 
 @dataclass
@@ -358,6 +473,7 @@ class AdsOverMqttTopics:
 
 
 class MqttBaseTransport(BaseTransport):
+    """Base transport that tunnels AMS/ADS frames over an MQTT broker."""
 
     REQUEST_TIMEOUT = 120.0
 
@@ -670,7 +786,7 @@ class AdsGMqttTransport(MqttBaseTransport, ITransport):
                 response_future, timeout=self.REQUEST_TIMEOUT
             )
 
-    async def _on_response(self, _client: gmqtt.Client, topic: str, payload: bytes, qos: int, properties: dict):
+    async def _on_response(self, _client: gmqtt.Client, topic: str, payload: bytes, _qos: int, _properties: dict):
         if self.topics.matches(self.topics.sub_response, topic):
             ams_message_stream = AdsStream(memoryview(payload))
             ams_header = AmsHeader.deserialize(ams_message_stream)