aioads 0.1.0.dev9__tar.gz → 0.1.0.dev10__tar.gz

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aioads
-Version: 0.1.0.dev9
+Version: 0.1.0.dev10
 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.dev9 → aioads-0.1.0.dev10}/aioads/ads_client.py

@@ -50,17 +50,24 @@ class AdsClient:
         parser: ISymbolParser,
         cache: AdsSymbolCache,
         notification: NotificationManager,
+        sum_batch_size: int,
     ) -> None:
         self.logger = logging.getLogger(f"{__name__}.'{dst_address.net_id}'")
         self.transport = transport
         self.dst_address = dst_address
         self.parser = parser
+        self.sum_batch_size = sum_batch_size
         self._cache = cache
         self._notification = notification
 
     @classmethod
     def create_tcp(
-        cls, src: AmsAddress, dst: AmsAddress, ip: str, port: int = 48898
+        cls,
+        src: AmsAddress,
+        dst: AmsAddress,
+        ip: str,
+        port: int = 48898,
+        sum_batch_size: int = 500,
     ) -> "AdsClient":
         """
         Create a new ADS client with TCP transport.
@@ -68,11 +75,14 @@ class AdsClient:
         :param dst: The destination AMS address
         :param ip: The target IP address
         :param port: The target port
+        :param sum_batch_size: Maximum commands per ADS sum command (1..500)
         :return: An instance of AdsClient
         """
         parser = AdsSymbolParser([])
         transport = AdsTcpTransport(src_address=src, ip=ip, port=port)
-        cache = AdsSymbolCache(transport=transport, dst_address=dst)
+        cache = AdsSymbolCache(
+            transport=transport, dst_address=dst, batch_size=sum_batch_size
+        )
         notification_manager = NotificationManager(
             transport=transport,
             dst_address=dst,
@@ -85,21 +95,28 @@ class AdsClient:
             dst_address=dst,
             cache=cache,
             notification=notification_manager,
+            sum_batch_size=sum_batch_size,
         )
 
     @classmethod
     def create_from_transport(
-        cls, dst: AmsAddress, transport: ITransport
+        cls,
+        dst: AmsAddress,
+        transport: ITransport,
+        sum_batch_size: int = 500,
     ) -> "AdsClient":
         """
         Create a new ADS client with an existing transport instance.
         :param src: The source AMS address
         :param dst: The destination AMS address
         :param transport: The existing transport instance
+        :param sum_batch_size: Maximum commands per ADS sum command (1..500)
         :return: An instance of AdsClient
         """
         parser = AdsSymbolParser([])
-        cache = AdsSymbolCache(transport=transport, dst_address=dst)
+        cache = AdsSymbolCache(
+            transport=transport, dst_address=dst, batch_size=sum_batch_size
+        )
         notification_manager = NotificationManager(
             transport=transport,
             dst_address=dst,
@@ -112,6 +129,7 @@ class AdsClient:
             dst_address=dst,
             cache=cache,
             notification=notification_manager,
+            sum_batch_size=sum_batch_size,
         )
 
     async def connect(self) -> None:
@@ -255,7 +273,8 @@ class AdsClient:
             exceptions.append(AdsCommandError(error_code, symbol_path))
 
         if exceptions:
-            raise ExceptionGroup("One or more symbol read errors occurred", exceptions)
+            raise ExceptionGroup(
+                "One or more symbol read errors occurred", exceptions)
 
     async def read_symbols_by_names(
         self, symbol_names: set[str], raise_errors: bool = True
@@ -299,6 +318,7 @@ class AdsClient:
                 )
                 for _, info in readable
             ],
+            batch_size=self.sum_batch_size,
         )
         response = await sum_read.execute()
 

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/aioads/ads_symbol_cache.py

@@ -29,12 +29,14 @@ class AdsSymbolCache:
         self,
         transport: ITransport,
         dst_address: AmsAddress,
+        batch_size: int,
         ttl_seconds: int = 21600,
     ) -> None:
         self._logger = logging.getLogger(f"{__name__}.'{dst_address.net_id}'")
         self._transport = transport
         self._dst_address = dst_address
         self._ttl_seconds = ttl_seconds
+        self._batch_size = batch_size
         self._cache: dict[str, tuple[int, AdsErrorCode, SymbolInfo]] = {}
         self._cache_monitor_task: asyncio.Task[None] | None = None
 
@@ -175,6 +177,7 @@ class AdsSymbolCache:
                 transport=self._transport,
                 ams_address=self._dst_address,
                 symbol_names=request_list,
+                batch_size=self._batch_size,
             )
             response = await function.execute()
             for (error, symbol_info), symbol_name in zip(

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/aioads/functions/ads_sum_read.py

@@ -12,14 +12,19 @@ from aioads.ams_address import AmsAddress
 from aioads.commands.ads_read import AdsReadCommand, AdsReadResponse
 from aioads.commands.ads_read_write import AdsReadWriteCommand
 from aioads.commands.errors import AdsCommandError
-from aioads.functions.ads_function import AdsFunctionSymbolGroup, IAdsFunction
+from aioads.functions.ads_function import (
+    AdsFunctionSymbolGroup,
+    IAdsFunction,
+)
 from aioads.stream import AdsStream
 from aioads.transport import ITransport
 
 
 class AdsSumRead(IAdsFunction[list[tuple[AdsReadResponse, AdsStream]]]):
     """
-    Ads sum read command that allows batching up to 500 `AdsReadCommand` in a single call
+    Ads sum read command that batches `AdsReadCommand` calls.
+    The PLC accepts at most 500 commands per sum command; larger command lists
+    are transparently split into multiple sum commands of at most `batch_size`.
     """
 
     ERROR_CODE_STRUCT_DEF: Final[Struct] = Struct("<I")
@@ -29,46 +34,60 @@ class AdsSumRead(IAdsFunction[list[tuple[AdsReadResponse, AdsStream]]]):
         transport: ITransport,
         ams_address: AmsAddress,
         commands: list[AdsReadCommand],
+        batch_size: int,
     ) -> None:
         self.transport = transport
         self.ams_address = ams_address
         self.commands = commands
+        self.batch_size = batch_size
 
-    def serialize(self) -> bytes:
+    def serialize(self, commands: list[AdsReadCommand]) -> bytes:
         """
-        serialize all commands to bytes
+        serialize the given commands to bytes
         """
-        return b"".join(command.serialize() for command in self.commands)
+        return b"".join(command.serialize() for command in commands)
 
     async def execute(self) -> list[tuple[AdsReadResponse, AdsStream]]:
         if len(self.commands) == 0:
-            raise ValueError("At least one command is required for ADS Sum Read")
-        if len(self.commands) > 500:
-            raise ValueError("Too many commands for ADS Sum Read, maximum is 500")
+            raise ValueError(
+                "At least one command is required for ADS Sum Read")
 
-        payload = self.serialize()
+        if self.batch_size <= 0 or self.batch_size > 500:
+            raise ValueError("Batch size must be between 1 and 500")
+
+        response: list[tuple[AdsReadResponse, AdsStream]] = []
+        for batch_start in range(0, len(self.commands), self.batch_size):
+            batch = self.commands[batch_start: batch_start + self.batch_size]
+            response.extend(await self._execute_batch(batch))
+        return response
+
+    async def _execute_batch(
+        self, commands: list[AdsReadCommand]
+    ) -> list[tuple[AdsReadResponse, AdsStream]]:
+        payload = self.serialize(commands)
         command = AdsReadWriteCommand(
             transport=self.transport,
             ams_address=self.ams_address,
             idx_group=AdsFunctionSymbolGroup.ADSIGRP_SUM_READ,
-            idx_offset=len(self.commands),
+            idx_offset=len(commands),
             read_length=sum(
-                cmd.length + 4 for cmd in self.commands
+                cmd.length + 4 for cmd in commands
             ),  # +4 for the error code per command
             write_length=len(payload),
             write_data=payload,
         )
         header, read_payload = await command.request()
         if not header.error_code.ok:
-            raise AdsCommandError(header.error_code, "Failed to execute ADS Sum Read")
+            raise AdsCommandError(
+                header.error_code, "Failed to execute ADS Sum Read")
         error_stream = read_payload.sub_stream(
             # 4 bytes per error code
-            len(self.commands)
+            len(commands)
             * self.ERROR_CODE_STRUCT_DEF.size
         )
 
         response: list[tuple[AdsReadResponse, AdsStream]] = []
-        for cmd in self.commands:
+        for cmd in commands:
             error_code = AdsErrorCode(
                 error_stream.read_struct(self.ERROR_CODE_STRUCT_DEF)[0]
             )

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/aioads/functions/ads_sum_read_write.py

@@ -54,7 +54,10 @@ from aioads.ams_address import AmsAddress
 from aioads.commands.ads_read import AdsReadResponse
 from aioads.commands.ads_read_write import AdsReadWriteCommand
 from aioads.commands.errors import AdsCommandError
-from aioads.functions.ads_function import AdsFunctionSymbolGroup, IAdsFunction
+from aioads.functions.ads_function import (
+    AdsFunctionSymbolGroup,
+    IAdsFunction,
+)
 from aioads.stream import AdsStream
 from aioads.transport import ITransport
 
@@ -64,6 +67,8 @@ class AdsSumReadWrite(IAdsFunction[list[tuple[AdsReadResponse, AdsStream]]]):
     ADS Sum Read/Write function to send a READ/WRITE Command in batch.
     This function allows multiple read/write commands to be sent in a single request,
     reducing communication overhead.
+    The PLC accepts at most 500 commands per sum command; larger command lists
+    are transparently split into multiple sum commands of at most `batch_size`.
     """
 
     def __init__(
@@ -71,37 +76,48 @@ class AdsSumReadWrite(IAdsFunction[list[tuple[AdsReadResponse, AdsStream]]]):
         transport: ITransport,
         ams_address: AmsAddress,
         commands: list[AdsReadWriteCommand],
+        batch_size: int,
     ) -> None:
         self.transport = transport
         self.ams_address = ams_address
         self.commands = commands
+        self.batch_size = batch_size
 
-    def serialize(self) -> bytes:
+    def serialize(self, commands: list[AdsReadWriteCommand]) -> bytes:
         """
-        Serialize the ADS Sum Read/Write commands into bytes.
+        Serialize the given ADS Sum Read/Write commands into bytes.
         :return: Serialized bytes of the sum read/write command.
         """
-        data = b"".join(cmd.serialize_header() for cmd in self.commands)
-        data += b"".join(cmd.payload for cmd in self.commands)
+        data = b"".join(cmd.serialize_header() for cmd in commands)
+        data += b"".join(cmd.payload for cmd in commands)
         return data
 
     async def execute(self) -> list[tuple[AdsReadResponse, AdsStream]]:
         """
         Request execution of the ADS Sum Read/Write function.
-        Returns an async generator yielding the responses for each command in the batch.
-        :return: An async generator yielding tuples of (AdsReadResponse, AdsStream) for each command.
+        :return: A list of tuples of (AdsReadResponse, AdsStream) for each command.
         """
         if len(self.commands) == 0:
-            raise ValueError("At least one command is required for ADS Sum Read/Write")
-        if len(self.commands) > 500:
-            raise ValueError("Too many commands for ADS Sum Read/Write, maximum is 500")
+            raise ValueError(
+                "At least one command is required for ADS Sum Read/Write")
+        if self.batch_size <= 0 or self.batch_size > 500:
+            raise ValueError("Batch size must be between 1 and 500")
 
-        payload = self.serialize()
+        response: list[tuple[AdsReadResponse, AdsStream]] = []
+        for batch_start in range(0, len(self.commands), self.batch_size):
+            batch = self.commands[batch_start: batch_start + self.batch_size]
+            response.extend(await self._execute_batch(batch))
+        return response
+
+    async def _execute_batch(
+        self, commands: list[AdsReadWriteCommand]
+    ) -> list[tuple[AdsReadResponse, AdsStream]]:
+        payload = self.serialize(commands)
         total_read_length = sum(
-            cmd.read_length + 8 for cmd in self.commands
+            cmd.read_length + 8 for cmd in commands
         )  # 8 bytes for each error code
         total_write_length = sum(
-            cmd.write_length + (4 * 4) for cmd in self.commands
+            cmd.write_length + (4 * 4) for cmd in commands
         )  # 8 Bytes for the fixed header
         assert total_write_length == len(
             payload
@@ -110,7 +126,7 @@ class AdsSumReadWrite(IAdsFunction[list[tuple[AdsReadResponse, AdsStream]]]):
             transport=self.transport,
             ams_address=self.ams_address,
             idx_group=AdsFunctionSymbolGroup.ADSIGRP_SUM_READ_WRITE,
-            idx_offset=len(self.commands),
+            idx_offset=len(commands),
             read_length=total_read_length,
             write_length=total_write_length,
             write_data=payload,
@@ -121,11 +137,11 @@ class AdsSumReadWrite(IAdsFunction[list[tuple[AdsReadResponse, AdsStream]]]):
                 header.error_code, "Failed to execute ADS Sum Read/Write"
             )
         read_response_stream = read_payload.sub_stream(
-            len(self.commands) * AdsReadResponse.STRUCT_DEF.size
+            len(commands) * AdsReadResponse.STRUCT_DEF.size
         )
 
         response: list[tuple[AdsReadResponse, AdsStream]] = []
-        for _ in self.commands:
+        for _ in commands:
             read_response = AdsReadResponse.deserialize(read_response_stream)
             response.append(
                 (read_response, read_payload.sub_stream(read_response.length))

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/aioads/functions/ads_symbol_info_by_name_ex.py

@@ -10,7 +10,10 @@ from aioads.ads_error_codes import AdsErrorCode
 from aioads.ams_address import AmsAddress
 from aioads.commands.ads_read_write import AdsReadWriteCommand
 from aioads.commands.errors import AdsCommandError
-from aioads.functions.ads_function import AdsFunctionSymbolGroup, IAdsFunction
+from aioads.functions.ads_function import (
+    AdsFunctionSymbolGroup,
+    IAdsFunction,
+)
 from aioads.functions.ads_sum_read_write import AdsSumReadWrite
 from aioads.stream import AdsStream
 from aioads.transport import ITransport
@@ -114,9 +117,12 @@ class SymbolInfo:
             type_name_length,
             comment_length,
         ) = data.read_struct(SymbolInfo.FIXED_STRUCT)
-        symbol_name = data.read(symbol_name_length + 1).rstrip(b"\x00").decode("cp1252")
-        type_name = data.read(type_name_length + 1).rstrip(b"\x00").decode("cp1252")
-        comment = data.read(comment_length + 1).rstrip(b"\x00").decode("cp1252")
+        symbol_name = data.read(symbol_name_length +
+                                1).rstrip(b"\x00").decode("cp1252")
+        type_name = data.read(
+            type_name_length + 1).rstrip(b"\x00").decode("cp1252")
+        comment = data.read(
+            comment_length + 1).rstrip(b"\x00").decode("cp1252")
 
         # Move the stream position to the end of the entry
         data.seek(start_pos + entry_length)
@@ -180,7 +186,8 @@ class SymbolInfoByNameEx(IAdsFunction[SymbolInfo]):
         )
         header, read_payload = await command.request()
         if not header.error_code.ok:
-            raise AdsCommandError(header.error_code, "Failed to read symbol info")
+            raise AdsCommandError(
+                header.error_code, "Failed to read symbol info")
         symbol_info = SymbolInfo.deserialize(read_payload)
         return symbol_info
 
@@ -189,21 +196,21 @@ class SymbolInfoByNameExSumRead(IAdsFunction[list[tuple[AdsErrorCode, SymbolInfo
     """
     This function utilizes the `AdsSumReadWrite` function to
     send multiple `SymbolInfoByNameEx` function calls in a batch.
-    Requests for more symbols than the PLC-side batch limit are
-    transparently split into multiple sum read/write calls.
+    Requests for more symbols than `batch_size` are transparently
+    split into multiple sum read/write calls by `AdsSumReadWrite`.
     """
 
-    BATCH_SIZE = 500
-
     def __init__(
         self,
         transport: ITransport,
         ams_address: AmsAddress,
         symbol_names: list[str],
+        batch_size: int,
     ) -> None:
         self.transport = transport
         self.ams_address = ams_address
         self.symbol_names = symbol_names
+        self.batch_size = batch_size
 
     def create_sub_commands(self) -> list[AdsReadWriteCommand]:
         """
@@ -226,20 +233,19 @@ class SymbolInfoByNameExSumRead(IAdsFunction[list[tuple[AdsErrorCode, SymbolInfo
         return commands
 
     async def execute(self):
-        commands = self.create_sub_commands()
+        command = AdsSumReadWrite(
+            transport=self.transport,
+            ams_address=self.ams_address,
+            commands=self.create_sub_commands(),
+            batch_size=self.batch_size,
+        )
         response = list[tuple[AdsErrorCode, SymbolInfo]]()
-        for batch_start in range(0, len(commands), self.BATCH_SIZE):
-            command = AdsSumReadWrite(
-                transport=self.transport,
-                ams_address=self.ams_address,
-                commands=commands[batch_start : batch_start + self.BATCH_SIZE],
-            )
-            for header, read_payload in await command.execute():
-                # If we have an error and no payload we return a void symbol info
-                # we raise no exception to let the client handle the error for each symbol individually
-                if not header.error_code.ok and read_payload.length == 0:
-                    response.append((header.error_code, SymbolInfo.void()))
-                    continue
-                symbol_info = SymbolInfo.deserialize(read_payload)
-                response.append((header.error_code, symbol_info))
+        for header, read_payload in await command.execute():
+            # If we have an error and no payload we return a void symbol info
+            # we raise no exception to let the client handle the error for each symbol individually
+            if not header.error_code.ok and read_payload.length == 0:
+                response.append((header.error_code, SymbolInfo.void()))
+                continue
+            symbol_info = SymbolInfo.deserialize(read_payload)
+            response.append((header.error_code, symbol_info))
         return response

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aioads"
-version = "0.1.0.dev9"
+version = "0.1.0.dev10"
 description = "An asynchronous Python library for communicating with Beckhoff TwinCAT PLCs"
 authors = [
     { name = "MkKiefer", email = "102972583+MkKiefer@users.noreply.github.com" },

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/tests/integration/test_memory.py

@@ -22,6 +22,7 @@ Like the performance tests, the budgets below are generous upper bounds, not
 benchmarks. A failure means a leak or a pathological regression, not a small
 change. Adjust the constants when they no longer match the test environment.
 """
+import asyncio
 import gc
 import tracemalloc
 
@@ -60,8 +61,29 @@ MEASURED_CYCLES = 5
 CYCLE_GROWTH_MAX_BYTES = 64 * 1024
 
 
-def _heap_bytes() -> int:
-    """Collect garbage and return the currently traced heap size."""
+async def _drain_cancelled_timers() -> None:
+    """
+    Force asyncio to evict cancelled timer handles from its schedule.
+
+    Every transport request arms a `wait_for` timeout; the response arrives
+    long before it fires, so the timer is cancelled — but cancelled
+    `TimerHandle`s stay reachable in the loop's schedule until asyncio's lazy
+    cleanup runs (only once cancelled handles exceed 100 and half the heap).
+    Heap snapshots would otherwise measure a random phase of that saw-tooth
+    (tens of KiB) instead of actual growth. Scheduling and cancelling enough
+    dummy timers pushes the cancelled ratio over the cleanup threshold, so
+    the next loop iteration compacts the schedule deterministically.
+    """
+    loop = asyncio.get_running_loop()
+    handles = [loop.call_later(3600, lambda: None) for _ in range(256)]
+    for handle in handles:
+        handle.cancel()
+    await asyncio.sleep(0)
+
+
+async def _heap_bytes() -> int:
+    """Drain cancelled timers, collect garbage and return the traced heap size."""
+    await _drain_cancelled_timers()
     gc.collect()
     return tracemalloc.get_traced_memory()[0]
 
@@ -102,28 +124,28 @@ class TestMemory(unittest.IsolatedAsyncioTestCase):
 
     async def test_read_symbols_memory_lifecycle(self) -> None:
         """Measure startup cost, runtime growth and cleanup residue."""
-        baseline = _heap_bytes()
+        baseline = await _heap_bytes()
 
         # Part 1: startup - connect (datatype upload) + first cache fill.
         client = create_client(self.config)
         await client.connect()
         await self._read_once(client)
-        startup_cost = _heap_bytes() - baseline
+        startup_cost = await _heap_bytes() - baseline
 
         # Part 2: runtime - steady-state growth and transient peak.
         for _ in range(WARMUP_READS):
             await self._read_once(client)
-        before_reads = _heap_bytes()
+        before_reads = await _heap_bytes()
         tracemalloc.reset_peak()
         for _ in range(MEASURED_READS):
             await self._read_once(client)
         runtime_peak = tracemalloc.get_traced_memory()[1] - before_reads
-        runtime_growth = _heap_bytes() - before_reads
+        runtime_growth = await _heap_bytes() - before_reads
 
         # Part 3: cleanup - disconnect, drop the client, measure the residue.
         await client.disconnect()
         del client
-        residue = _heap_bytes() - baseline
+        residue = await _heap_bytes() - baseline
 
         print(
             f"\nMemory lifecycle report"
@@ -173,11 +195,11 @@ class TestMemory(unittest.IsolatedAsyncioTestCase):
         # The first cycle absorbs one-time allocations that live for the
         # rest of the interpreter (loggers, enum caches, interned strings).
         await one_cycle()
-        baseline = _heap_bytes()
+        baseline = await _heap_bytes()
 
         for _ in range(MEASURED_CYCLES):
             await one_cycle()
-        growth = _heap_bytes() - baseline
+        growth = await _heap_bytes() - baseline
 
         print(
             f"\nConnect cycle report: {MEASURED_CYCLES} cycles grew the heap "

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/tests/unit/functions/test_ads_sum_read.py

@@ -3,6 +3,8 @@
 import unittest
 from unittest.mock import AsyncMock
 
+from parameterized import parameterized
+
 from aioads.commands.ads_read import AdsReadCommand
 from aioads.functions.ads_sum_read import AdsSumRead
 from tests.builders import (
@@ -24,9 +26,12 @@ class TestAdsSumRead(unittest.IsolatedAsyncioTestCase):
             AdsReadCommand(self.transport, self.address, 0x4020, 8, 2),
         ]
 
-    def _function(self, commands) -> AdsSumRead:
+    def _function(self, commands, batch_size: int = 500) -> AdsSumRead:
         return AdsSumRead(
-            transport=self.transport, ams_address=self.address, commands=commands
+            transport=self.transport,
+            ams_address=self.address,
+            commands=commands,
+            batch_size=batch_size,
         )
 
     def test_serialize_concatenates_each_command_payload(self) -> None:
@@ -34,33 +39,65 @@ class TestAdsSumRead(unittest.IsolatedAsyncioTestCase):
         function = self._function(self.commands)
 
         # Act
-        result = function.serialize()
+        result = function.serialize(self.commands)
 
         # Assert
         self.assertEqual(
             result, self.commands[0].serialize() + self.commands[1].serialize()
         )
 
-    async def test_execute_empty_commands_raises_value_error(self) -> None:
+    @parameterized.expand([
+        ("zero", 0),
+        ("above_maximum", 501),
+    ])
+    async def test_execute_batch_size_out_of_range_raises_value_error(
+        self, _name: str, batch_size: int
+    ) -> None:
         # Arrange
-        function = self._function([])
+        function = self._function(self.commands, batch_size=batch_size)
 
         # Act / Assert
         with self.assertRaises(ValueError) as ctx:
             await function.execute()
 
-        self.assertIn("At least one command", str(ctx.exception))
+        self.assertIn("between 1 and 500", str(ctx.exception))
 
-    async def test_execute_too_many_commands_raises_value_error(self) -> None:
+    async def test_execute_empty_commands_raises_value_error(self) -> None:
         # Arrange
-        many = [AdsReadCommand(self.transport, self.address, 0, 0, 1) for _ in range(501)]
-        function = self._function(many)
+        function = self._function([])
 
         # Act / Assert
         with self.assertRaises(ValueError) as ctx:
             await function.execute()
 
-        self.assertIn("maximum is 500", str(ctx.exception))
+        self.assertIn("At least one command", str(ctx.exception))
+
+    async def test_execute_splits_commands_into_batches(self) -> None:
+        # Arrange: 3 commands with batch_size 2 -> one request with 2 commands,
+        # one request with the remaining command
+        commands = self.commands + [
+            AdsReadCommand(self.transport, self.address, 0x4020, 16, 1)
+        ]
+        first_batch_body = (
+            (0).to_bytes(4, "little") + (0).to_bytes(4, "little")
+            + b"\x01\x02\x03\x04" + b"\xaa\xbb"
+        )
+        second_batch_body = (0).to_bytes(4, "little") + b"\xcc"
+        self.transport.request = AsyncMock(
+            side_effect=[
+                (make_ams_header(), make_stream(make_read_payload(first_batch_body))),
+                (make_ams_header(), make_stream(make_read_payload(second_batch_body))),
+            ]
+        )
+        function = self._function(commands, batch_size=2)
+
+        # Act
+        response = await function.execute()
+
+        # Assert
+        self.assertEqual(self.transport.request.await_count, 2)
+        self.assertEqual(len(response), 3)
+        self.assertEqual(response[2][1].read(1), b"\xcc")
 
     async def test_execute_returns_response_and_data_per_command(self) -> None:
         # Arrange: 2 error codes (4 bytes each) followed by 4 + 2 data bytes

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/tests/unit/functions/test_ads_sum_read_write.py

@@ -3,6 +3,8 @@
 import unittest
 from unittest.mock import AsyncMock
 
+from parameterized import parameterized
+
 from aioads.commands.ads_read import AdsReadResponse
 from aioads.commands.ads_read_write import AdsReadWriteCommand
 from aioads.ads_error_codes import AdsErrorCode
@@ -26,9 +28,12 @@ class TestAdsSumReadWrite(unittest.IsolatedAsyncioTestCase):
             AdsReadWriteCommand(self.transport, self.address, 0xF009, 0, 2, 3, b"xyz"),
         ]
 
-    def _function(self, commands) -> AdsSumReadWrite:
+    def _function(self, commands, batch_size: int = 500) -> AdsSumReadWrite:
         return AdsSumReadWrite(
-            transport=self.transport, ams_address=self.address, commands=commands
+            transport=self.transport,
+            ams_address=self.address,
+            commands=commands,
+            batch_size=batch_size,
         )
 
     def test_serialize_places_all_headers_before_all_payloads(self) -> None:
@@ -36,7 +41,7 @@ class TestAdsSumReadWrite(unittest.IsolatedAsyncioTestCase):
         function = self._function(self.commands)
 
         # Act
-        result = function.serialize()
+        result = function.serialize(self.commands)
 
         # Assert
         expected = (
@@ -57,19 +62,52 @@ class TestAdsSumReadWrite(unittest.IsolatedAsyncioTestCase):
 
         self.assertIn("At least one command", str(ctx.exception))
 
-    async def test_execute_too_many_commands_raises_value_error(self) -> None:
+    @parameterized.expand([
+        ("zero", 0),
+        ("above_maximum", 501),
+    ])
+    async def test_execute_batch_size_out_of_range_raises_value_error(
+        self, _name: str, batch_size: int
+    ) -> None:
         # Arrange
-        many = [
-            AdsReadWriteCommand(self.transport, self.address, 0, 0, 1, 0, b"")
-            for _ in range(501)
-        ]
-        function = self._function(many)
+        function = self._function(self.commands, batch_size=batch_size)
 
         # Act / Assert
         with self.assertRaises(ValueError) as ctx:
             await function.execute()
 
-        self.assertIn("maximum is 500", str(ctx.exception))
+        self.assertIn("between 1 and 500", str(ctx.exception))
+
+    async def test_execute_splits_commands_into_batches(self) -> None:
+        # Arrange: 3 commands with batch_size 2 -> one request with 2 commands,
+        # one request with the remaining command
+        commands = self.commands + [
+            AdsReadWriteCommand(self.transport, self.address, 0xF009, 0, 1, 1, b"z")
+        ]
+        first_batch_body = (
+            AdsReadResponse(AdsErrorCode(0), length=4).serialize()
+            + AdsReadResponse(AdsErrorCode(0), length=2).serialize()
+            + b"\x01\x02\x03\x04"
+            + b"\xaa\xbb"
+        )
+        second_batch_body = (
+            AdsReadResponse(AdsErrorCode(0), length=1).serialize() + b"\xcc"
+        )
+        self.transport.request = AsyncMock(
+            side_effect=[
+                (make_ams_header(), make_stream(make_read_payload(first_batch_body))),
+                (make_ams_header(), make_stream(make_read_payload(second_batch_body))),
+            ]
+        )
+        function = self._function(commands, batch_size=2)
+
+        # Act
+        response = await function.execute()
+
+        # Assert
+        self.assertEqual(self.transport.request.await_count, 2)
+        self.assertEqual(len(response), 3)
+        self.assertEqual(response[2][1].read(1), b"\xcc")
 
     async def test_execute_returns_read_response_and_data_per_command(self) -> None:
         # Arrange: per-command (error, length) headers, then per-command payloads

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/tests/unit/functions/test_ads_symbol_info_by_name_ex.py

@@ -107,6 +107,7 @@ class TestSymbolInfoByNameExSumRead(unittest.IsolatedAsyncioTestCase):
             transport=self.transport,
             ams_address=make_ams_address(),
             symbol_names=["main.a", "main.b"],
+            batch_size=500,
         )
 
     def test_create_sub_commands_one_per_symbol_name(self) -> None:

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/tests/unit/test_ads_client.py

@@ -72,7 +72,7 @@ class TestAdsClient(unittest.IsolatedAsyncioTestCase):
         self.transport = make_transport()
         self.address = make_ams_address()
         self.parser = AdsSymbolParser([])
-        self.cache = AdsSymbolCache(self.transport, self.address)
+        self.cache = AdsSymbolCache(self.transport, self.address, batch_size=500)
         self.notification = NotificationManager(
             self.transport, self.address, self.cache, self.parser
         )
@@ -82,6 +82,7 @@ class TestAdsClient(unittest.IsolatedAsyncioTestCase):
             parser=self.parser,
             cache=self.cache,
             notification=self.notification,
+            sum_batch_size=500,
         )
 
     async def test_read_symbol_info_by_name_delegates_to_cache(self) -> None:

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/tests/unit/test_ads_notifications.py

@@ -64,7 +64,7 @@ class TestNotificationManager(unittest.IsolatedAsyncioTestCase):
         self.transport = make_transport()
         self.address = make_ams_address()
         # Real typed collaborators; only the methods under control are replaced.
-        self.cache = AdsSymbolCache(self.transport, self.address)
+        self.cache = AdsSymbolCache(self.transport, self.address, batch_size=500)
         self.parser = AdsSymbolParser([])
         self.manager = NotificationManager(
             transport=self.transport,

{aioads-0.1.0.dev9 → aioads-0.1.0.dev10}/tests/unit/test_ads_symbol_cache.py

@@ -60,6 +60,7 @@ class TestAdsSymbolCache(unittest.IsolatedAsyncioTestCase):
             transport=self.transport,
             dst_address=self.address,
             ttl_seconds=3600,
+            batch_size=500,
         )
         self.info = make_symbol_info("MAIN.VALUE")
 
@@ -98,7 +99,9 @@ class TestAdsSymbolCache(unittest.IsolatedAsyncioTestCase):
     async def test_read_symbol_info_by_name_expired_entry_refetches(self) -> None:
         # Arrange — zero TTL means an entry is never valid on the next lookup.
         # A fresh stream is built per call so the second fetch reads from the start.
-        cache = AdsSymbolCache(self.transport, self.address, ttl_seconds=0)
+        cache = AdsSymbolCache(
+            self.transport, self.address, ttl_seconds=0, batch_size=500
+        )
         self.transport.request = AsyncMock(
             side_effect=lambda **kwargs: single_read_response(self.info)
         )
@@ -149,7 +152,9 @@ class TestAdsSymbolCacheMonitor(unittest.IsolatedAsyncioTestCase):
 
     def setUp(self) -> None:
         self.transport = make_transport()
-        self.cache = AdsSymbolCache(self.transport, make_ams_address())
+        self.cache = AdsSymbolCache(
+            self.transport, make_ams_address(), batch_size=500
+        )
         # Symbol-table-version read keeps the monitor loop body from erroring.
         self.transport.request = AsyncMock(
             return_value=(make_ams_header(), make_stream(make_read_payload(b"\x01")))