python-snap7 3.1.2__py3-none-any.whl → 3.2.1__py3-none-any.whl

snap7/async_client.py

@@ -1,28 +1,34 @@
-"""
-Native async S7 client implementation.
+"""Asynchronous client for the classic S7 protocol.
 
 Uses asyncio streams for non-blocking I/O with an asyncio.Lock() to serialize
 send/receive cycles, ensuring safe concurrent use via asyncio.gather().
+
+``s7.AsyncClient`` and ``snap7.AsyncClient`` expose this same implementation.
 """
 
 import asyncio
 import logging
 import struct
 import time
+from collections.abc import Callable
+from contextvars import ContextVar
 from typing import List, Any, Optional, Tuple, Type
 from types import TracebackType
 from datetime import datetime
 
 from .connection import TPDUSize
-from .s7protocol import S7Protocol, get_return_code_description
-from .datatypes import S7WordLen
+from .s7protocol import S7Protocol, S7UserDataGroup, S7UserDataSubfunction, get_return_code_description
+from .datatypes import S7DataTypes, S7WordLen
 from .error import S7Error, S7ConnectionError, S7ProtocolError, S7TimeoutError
-from .client_base import ClientMixin
+from .client_base import ClientMixin, _instrumented
 from .szl import parse_cp_info_szl, parse_cpu_info_szl, parse_order_code_szl, parse_protection_szl
+from .client import _parse_force_szl
+from .rate_limiter import RateLimitAlgorithm, RateLimitBehavior, RequestRateLimiter
 from .type import (
     Area,
     Block,
     BlocksList,
+    ForceEntry,
     S7CpuInfo,
     TS7BlockInfo,
     S7CpInfo,
@@ -156,7 +162,7 @@ class AsyncISOTCPConnection:
                 raise S7ConnectionError(f"Invalid TPKT version: {version}")
 
             remaining = length - 4
-            if remaining <= 0:
+            if length < 7:
                 raise S7ConnectionError("Invalid TPKT length")
 
             payload = await self._recv_exact(remaining)
@@ -165,6 +171,10 @@ class AsyncISOTCPConnection:
             if len(payload) < 3:
                 raise S7ConnectionError("Invalid COTP DT: too short")
             pdu_len, pdu_type, eot_num = struct.unpack(">BBB", payload[:3])
+            if pdu_len != 2:
+                raise S7ConnectionError("Invalid COTP DT header length")
+            if eot_num & 0x7F:
+                raise S7ConnectionError("Invalid Class 0 COTP TPDU number")
             if pdu_type != self.COTP_DT:
                 raise S7ConnectionError(f"Expected COTP DT, got {pdu_type:#02x}")
             return payload[3:]
@@ -214,6 +224,8 @@ class AsyncISOTCPConnection:
     def _build_tpkt(self, payload: bytes) -> bytes:
         """Build TPKT frame."""
         length = len(payload) + 4
+        if not 7 <= length <= 65535:
+            raise S7ConnectionError("Invalid TPKT length: expected 7..65535 bytes")
         return struct.pack(">BBH", 3, 0, length) + payload
 
     def _parse_cotp_cc(self, data: bytes) -> None:
@@ -285,23 +297,32 @@ class AsyncISOTCPConnection:
 
 
 class AsyncClient(ClientMixin):
-    """
-    Native async S7 client implementation.
+    """Asynchronous client for classic S7 communication.
 
     Uses asyncio streams for non-blocking I/O. An internal asyncio.Lock
     serializes each send+receive cycle so that concurrent coroutines
     (e.g. via asyncio.gather) never interleave on the same TCP socket.
 
+    For new projects, use ``s7.AsyncClient`` instead.
+
     Examples:
-        >>> import snap7
-        >>> async with snap7.AsyncClient() as client:
+        >>> from s7 import AsyncClient
+        >>> async with AsyncClient() as client:
         ...     await client.connect("192.168.1.10", 0, 1)
         ...     data = await client.db_read(1, 0, 4)
     """
 
     MAX_VARS = 20
 
-    def __init__(self) -> None:
+    def __init__(
+        self,
+        *,
+        max_requests_per_second: float = 0,
+        rate_limit_algorithm: RateLimitAlgorithm = "fixed",
+        rate_limit_behavior: RateLimitBehavior = "block",
+        rate_limit_burst: int | None = None,
+        on_operation: Optional[Callable[[str, float, bool], None]] = None,
+    ) -> None:
         self.connection: Optional[AsyncISOTCPConnection] = None
         self.protocol = S7Protocol()
         self.connected = False
@@ -318,8 +339,16 @@ class AsyncClient(ClientMixin):
 
         self._exec_time = 0
         self._last_error = 0
+        self._on_operation = on_operation
+        self._operation_depth: ContextVar[int] = ContextVar("snap7_async_client_operation_depth", default=0)
 
         self._lock = asyncio.Lock()
+        self._rate_limiter = RequestRateLimiter(
+            max_requests_per_second,
+            algorithm=rate_limit_algorithm,
+            behavior=rate_limit_behavior,
+            burst_capacity=rate_limit_burst,
+        )
 
         self._params = {
             Parameter.RemotePort: 102,
@@ -339,6 +368,11 @@ class AsyncClient(ClientMixin):
             raise S7ConnectionError("Not connected to PLC")
         return self.connection
 
+    async def _send_data(self, conn: AsyncISOTCPConnection, request: bytes) -> None:
+        """Apply the per-client rate limit and send one S7 request PDU."""
+        await self._rate_limiter.acquire_async()
+        await conn.send_data(request)
+
     async def _send_receive(self, request: bytes, max_stale_retries: int = 3) -> dict[str, Any]:
         """Send a request and receive/parse the response, holding the lock.
 
@@ -358,7 +392,7 @@ class AsyncClient(ClientMixin):
         expected_seq = struct.unpack(">H", request[4:6])[0]
 
         async with self._lock:
-            await conn.send_data(request)
+            await self._send_data(conn, request)
 
             for attempt in range(max_stale_retries + 1):
                 response_data = await conn.receive_data()
@@ -510,6 +544,7 @@ class AsyncClient(ClientMixin):
     # Core read / write
     # ---------------------------------------------------------------
 
+    @_instrumented("read_area")
     async def read_area(self, area: Area, db_number: int, start: int, size: int) -> bytearray:
         """Read data from memory area.
 
@@ -525,7 +560,7 @@ class AsyncClient(ClientMixin):
         else:
             word_len = S7WordLen.BYTE
 
-        max_chunk = self._max_read_size()
+        max_chunk = self._read_chunk_count(word_len)
         if size <= max_chunk:
             request = self.protocol.build_read_request(
                 area=s7_area, db_number=db_number, start=start, word_len=word_len, count=size
@@ -541,7 +576,11 @@ class AsyncClient(ClientMixin):
         while remaining > 0:
             chunk_size = min(remaining, max_chunk)
             request = self.protocol.build_read_request(
-                area=s7_area, db_number=db_number, start=start + offset, word_len=word_len, count=chunk_size
+                area=s7_area,
+                db_number=db_number,
+                start=start + offset * self._element_address_step(word_len),
+                word_len=word_len,
+                count=chunk_size,
             )
             response = await self._send_receive(request)
             values = self.protocol.extract_read_data(response, word_len, chunk_size)
@@ -552,6 +591,7 @@ class AsyncClient(ClientMixin):
         self._exec_time = int((time.time() - start_time) * 1000)
         return result
 
+    @_instrumented("write_area")
     async def write_area(self, area: Area, db_number: int, start: int, data: bytearray) -> int:
         """Write data to memory area.
 
@@ -567,7 +607,7 @@ class AsyncClient(ClientMixin):
         else:
             word_len = S7WordLen.BYTE
 
-        max_chunk = self._max_write_size()
+        max_chunk = self._write_chunk_bytes(word_len, len(data))
         if len(data) <= max_chunk:
             request = self.protocol.build_write_request(
                 area=s7_area, db_number=db_number, start=start, word_len=word_len, data=bytes(data)
@@ -583,7 +623,11 @@ class AsyncClient(ClientMixin):
             chunk_size = min(remaining, max_chunk)
             chunk_data = data[offset : offset + chunk_size]
             request = self.protocol.build_write_request(
-                area=s7_area, db_number=db_number, start=start + offset, word_len=word_len, data=bytes(chunk_data)
+                area=s7_area,
+                db_number=db_number,
+                start=start + offset // S7DataTypes.get_size_bytes(word_len) * self._element_address_step(word_len),
+                word_len=word_len,
+                data=bytes(chunk_data),
             )
             response = await self._send_receive(request)
             self.protocol.check_write_response(response)
@@ -593,6 +637,7 @@ class AsyncClient(ClientMixin):
         self._exec_time = int((time.time() - start_time) * 1000)
         return 0
 
+    @_instrumented("read_multi_vars")
     async def read_multi_vars(self, items: List[dict[str, Any]]) -> Tuple[int, list[bytearray]]:
         """Read multiple variables (sequentially, one read_area per item).
 
@@ -617,6 +662,7 @@ class AsyncClient(ClientMixin):
             results.append(data)
         return (0, results)
 
+    @_instrumented("write_multi_vars")
     async def write_multi_vars(self, items: List[dict[str, Any]]) -> int:
         """Write multiple variables (sequentially, one write_area per item).
 
@@ -650,6 +696,7 @@ class AsyncClient(ClientMixin):
 
         request = self.protocol.build_list_blocks_request()
         response = await self._send_receive(request)
+        self.protocol.check_userdata_response(response, S7UserDataGroup.BLOCK_INFO, S7UserDataSubfunction.LIST_ALL)
 
         data_info = response.get("data", {})
         return_code = data_info.get("return_code", 0xFF) if isinstance(data_info, dict) else 0xFF
@@ -682,6 +729,7 @@ class AsyncClient(ClientMixin):
 
         request = self.protocol.build_list_blocks_of_type_request(type_code)
         response = await self._send_receive(request)
+        self.protocol.check_userdata_response(response, S7UserDataGroup.BLOCK_INFO, S7UserDataSubfunction.LIST_BLOCKS_OF_TYPE)
 
         data_info = response.get("data", {})
         return_code = data_info.get("return_code", 0xFF) if isinstance(data_info, dict) else 0xFF
@@ -703,10 +751,11 @@ class AsyncClient(ClientMixin):
 
             async with self._lock:
                 followup = self.protocol.build_userdata_followup_request(group, subfunction, sequence_number)
-                await conn.send_data(followup)
+                await self._send_data(conn, followup)
                 response_data = await conn.receive_data()
 
             response = self.protocol.parse_response(response_data)
+            self.protocol.check_userdata_response(response, S7UserDataGroup.BLOCK_INFO, S7UserDataSubfunction.LIST_BLOCKS_OF_TYPE)
 
             data_info = response.get("data", {})
             return_code = data_info.get("return_code", 0xFF) if isinstance(data_info, dict) else 0xFF
@@ -742,6 +791,7 @@ class AsyncClient(ClientMixin):
 
         request = self.protocol.build_get_block_info_request(type_code, db_number)
         response = await self._send_receive(request)
+        self.protocol.check_userdata_response(response, S7UserDataGroup.BLOCK_INFO, S7UserDataSubfunction.BLOCK_INFO)
 
         data_info = response.get("data", {})
         return_code = data_info.get("return_code", 0xFF) if isinstance(data_info, dict) else 0xFF
@@ -771,6 +821,7 @@ class AsyncClient(ClientMixin):
     # Upload / Download / Delete
     # ---------------------------------------------------------------
 
+    @_instrumented("upload")
     async def upload(self, block_num: int) -> bytearray:
         """Upload block from PLC (3-step: START_UPLOAD, UPLOAD, END_UPLOAD)."""
         if not self.get_connected():
@@ -782,19 +833,27 @@ class AsyncClient(ClientMixin):
         response = await self._send_receive(request)
 
         upload_info = self.protocol.parse_start_upload_response(response)
-        upload_id = upload_info.get("upload_id", 1)
-
-        request = self.protocol.build_upload_request(upload_id)
-        response = await self._send_receive(request)
+        upload_id = upload_info["upload_id"]
 
-        block_data = self.protocol.parse_upload_response(response)
+        block_data = bytearray()
+        for fragment_index in range(1000):
+            request = self.protocol.build_upload_request(upload_id)
+            response = await self._send_receive(request)
+            fragment, is_last = self.protocol.parse_upload_fragment(response, first_fragment=fragment_index == 0)
+            block_data.extend(fragment)
+            if is_last:
+                break
+        else:
+            raise S7ProtocolError("Upload response exceeded fragment limit")
 
         request = self.protocol.build_end_upload_request(upload_id)
         response = await self._send_receive(request)
+        self.protocol.check_end_upload_response(response)
 
         logger.info(f"Uploaded {len(block_data)} bytes from block {block_num}")
-        return bytearray(block_data)
+        return block_data
 
+    @_instrumented("download")
     async def download(self, data: bytearray, block_num: int = -1) -> int:
         """Download block to PLC."""
         if not self.get_connected():
@@ -809,44 +868,33 @@ class AsyncClient(ClientMixin):
             else:
                 block_num = 1
 
-        # Step 1: Request download
         request = self.protocol.build_download_request(block_type, block_num, bytes(data))
-        await self._send_receive(request)
-
-        # Step 2: Download block (send data)
-        param_data = struct.pack(">BBB", 0x1B, 0x01, 0x00)
-        data_section = struct.pack(">HH", len(data), 0x00FB) + bytes(data)
-        header = struct.pack(
-            ">BBHHHH",
-            0x32,
-            0x01,
-            0x0000,
-            self.protocol._next_sequence(),
-            len(param_data),
-            len(data_section),
-        )
-
         async with self._lock:
-            await conn.send_data(header + param_data + data_section)
+            await self._send_data(conn, request)
             response_data = await conn.receive_data()
-        self.protocol.parse_response(response_data)
-
-        # Step 3: Download ended
-        param_data = struct.pack(">B", 0x1C)
-        header = struct.pack(
-            ">BBHHHH",
-            0x32,
-            0x01,
-            0x0000,
-            self.protocol._next_sequence(),
-            len(param_data),
-            0x0000,
-        )
+            response = self.protocol.parse_response(response_data)
+            if response["sequence"] != int.from_bytes(request[4:6], "big") or response.get("raw_parameters") != bytes((0x1A,)):
+                raise S7ProtocolError("Invalid request-download acknowledgement")
+
+            offset = 0
+            max_slice = self.pdu_length - 18
+            if max_slice <= 0:
+                raise S7ProtocolError("Negotiated PDU is too small for download")
+            for _ in range(1000):
+                request_data = await conn.receive_data()
+                sequence = self.protocol.parse_download_service_request(request_data, 0x1B, block_num)
+                fragment = bytes(data[offset : offset + max_slice])
+                offset += len(fragment)
+                is_last = offset == len(data)
+                await self._send_data(conn, self.protocol.build_download_fragment_response(sequence, is_last, fragment))
+                if is_last:
+                    break
+            else:
+                raise S7ProtocolError("Download exceeded fragment limit")
 
-        async with self._lock:
-            await conn.send_data(header + param_data)
-            response_data = await conn.receive_data()
-        self.protocol.parse_response(response_data)
+            request_data = await conn.receive_data()
+            sequence = self.protocol.parse_download_service_request(request_data, 0x1C, block_num)
+            await self._send_data(conn, self.protocol.build_download_ended_response(sequence))
 
         logger.info(f"Downloaded {len(data)} bytes to block {block_num}")
         return 0
@@ -894,32 +942,27 @@ class AsyncClient(ClientMixin):
         response = await self._send_receive(request)
 
         upload_info = self.protocol.parse_start_upload_response(response)
-        upload_id = upload_info.get("upload_id", 1)
+        upload_id = upload_info["upload_id"]
 
-        request = self.protocol.build_upload_request(upload_id)
-        response = await self._send_receive(request)
-        block_data = self.protocol.parse_upload_response(response)
+        block_data = bytearray()
+        for fragment_index in range(1000):
+            request = self.protocol.build_upload_request(upload_id)
+            response = await self._send_receive(request)
+            fragment, is_last = self.protocol.parse_upload_fragment(
+                response, first_fragment=fragment_index == 0, include_block_header=True
+            )
+            block_data.extend(fragment)
+            if is_last:
+                break
+        else:
+            raise S7ProtocolError("Upload response exceeded fragment limit")
 
         request = self.protocol.build_end_upload_request(upload_id)
         response = await self._send_receive(request)
+        self.protocol.check_end_upload_response(response)
 
-        block_header = struct.pack(
-            ">BBHBBBBHH",
-            0x70,
-            block_type.value,
-            block_num,
-            0x00,
-            0x00,
-            0x00,
-            0x00,
-            len(block_data) + 14,
-            len(block_data),
-        )
-        block_footer = b"\x00" * 4
-        full_block = bytearray(block_header + block_data + block_footer)
-
-        logger.info(f"Full upload of block {block_type.name} {block_num}: {len(full_block)} bytes")
-        return full_block, len(full_block)
+        logger.info(f"Full upload of block {block_type.name} {block_num}: {len(block_data)} bytes")
+        return block_data, len(block_data)
 
     # ---------------------------------------------------------------
     # PLC control
@@ -957,6 +1000,7 @@ class AsyncClient(ClientMixin):
 
         request = self.protocol.build_get_clock_request()
         response = await self._send_receive(request)
+        self.protocol.check_userdata_response(response, S7UserDataGroup.TIME, S7UserDataSubfunction.GET_CLOCK)
         return self.protocol.parse_get_clock_response(response)
 
     async def set_plc_datetime(self, dt: datetime) -> int:
@@ -965,7 +1009,8 @@ class AsyncClient(ClientMixin):
             raise S7ConnectionError("Not connected to PLC")
 
         request = self.protocol.build_set_clock_request(dt)
-        await self._send_receive(request)
+        response = await self._send_receive(request)
+        self.protocol.check_userdata_response(response, S7UserDataGroup.TIME, S7UserDataSubfunction.SET_CLOCK)
         logger.info(f"Set PLC datetime to {dt}")
         return 0
 
@@ -995,6 +1040,7 @@ class AsyncClient(ClientMixin):
 
         request = self.protocol.build_read_szl_request(ssl_id, index)
         response = await self._send_receive(request)
+        self.protocol.check_userdata_response(response, S7UserDataGroup.SZL, S7UserDataSubfunction.READ_SZL)
 
         data_info = response.get("data", {})
         return_code = data_info.get("return_code", 0xFF) if isinstance(data_info, dict) else 0xFF
@@ -1017,10 +1063,11 @@ class AsyncClient(ClientMixin):
 
             async with self._lock:
                 followup = self.protocol.build_userdata_followup_request(group, subfunction, sequence_number)
-                await conn.send_data(followup)
+                await self._send_data(conn, followup)
                 response_data = await conn.receive_data()
 
             response = self.protocol.parse_response(response_data)
+            self.protocol.check_userdata_response(response, S7UserDataGroup.SZL, S7UserDataSubfunction.READ_SZL)
 
             data_info = response.get("data", {})
             return_code = data_info.get("return_code", 0xFF) if isinstance(data_info, dict) else 0xFF
@@ -1073,6 +1120,109 @@ class AsyncClient(ClientMixin):
             raise S7ConnectionError("Not connected to PLC")
         return parse_protection_szl(await self.read_szl(0x0232, 0))
 
+    # ---------------------------------------------------------------
+    # Force I/O
+    # ---------------------------------------------------------------
+
+    _FORCE_AREAS: frozenset[int] = frozenset({Area.PE, Area.PA})
+
+    async def force_bit(self, area: Area, byte_offset: int, bit: int, value: bool) -> None:
+        """Force a single I/O bit in the process image.
+
+        Async equivalent of :meth:`snap7.client.Client.force_bit`.
+        """
+        if area not in self._FORCE_AREAS:
+            raise ValueError(f"Force is only supported for PE (inputs) and PA (outputs), got {area!r}")
+        if not 0 <= bit <= 7:
+            raise ValueError(f"Bit must be 0-7, got {bit}")
+
+        current = await self.read_area(area, 0, byte_offset, 1)
+        if value:
+            current[0] |= 1 << bit
+        else:
+            current[0] &= ~(1 << bit)
+        await self.write_area(area, 0, byte_offset, current)
+        logger.info(f"Forced {area.name} byte {byte_offset} bit {bit} = {value}")
+
+    async def cancel_force(self, area: Area, byte_offset: int, bit: int) -> None:
+        """Cancel a forced I/O bit by clearing it in the process image.
+
+        Async equivalent of :meth:`snap7.client.Client.cancel_force`.
+        """
+        if area not in self._FORCE_AREAS:
+            raise ValueError(f"Cancel force is only supported for PE (inputs) and PA (outputs), got {area!r}")
+        if not 0 <= bit <= 7:
+            raise ValueError(f"Bit must be 0-7, got {bit}")
+
+        current = await self.read_area(area, 0, byte_offset, 1)
+        current[0] &= ~(1 << bit)
+        await self.write_area(area, 0, byte_offset, current)
+        logger.info(f"Cancelled force on {area.name} byte {byte_offset} bit {bit}")
+
+    async def read_force_table(self) -> list[ForceEntry]:
+        """Read the PLC force table via SZL 0x0025.
+
+        Async equivalent of :meth:`snap7.client.Client.read_force_table`.
+        """
+        if not self.get_connected():
+            raise S7ConnectionError("Not connected to PLC")
+
+        try:
+            szl = await self.read_szl(0x0025, 0x0000)
+        except (S7ProtocolError, RuntimeError):
+            logger.debug("SZL 0x0025 not available; returning empty force table")
+            return []
+
+        raw = bytes(szl.Data[: szl.Header.LengthDR])
+        return _parse_force_szl(raw)
+
+    async def set_session_password(self, password: str) -> int:
+        """Set the session password to unlock a password-protected PLC.
+
+        Sends an S7 USERDATA request (function group 5, subfunction 1)
+        with the encoded password.
+
+        Args:
+            password: Plaintext password (max 8 ASCII characters).
+
+        Returns:
+            0 on success.
+
+        Raises:
+            ~snap7.error.S7ConnectionError: If not connected.
+            ~snap7.error.S7ProtocolError: If the PLC rejects the password.
+        """
+        if not self.get_connected():
+            raise S7ConnectionError("Not connected to PLC")
+
+        encoded = self.protocol.encode_password(password)
+        request = self.protocol.build_set_session_password_request(encoded)
+        response = await self._send_receive(request)
+        self.protocol.check_userdata_response(response, S7UserDataGroup.SECURITY, S7UserDataSubfunction.SET_SESSION_PASSWORD)
+        logger.info("Session password set successfully")
+        return 0
+
+    async def clear_session_password(self) -> int:
+        """Clear the session password, returning to the default protection level.
+
+        Sends an S7 USERDATA request (function group 5, subfunction 2).
+
+        Returns:
+            0 on success.
+
+        Raises:
+            ~snap7.error.S7ConnectionError: If not connected.
+            ~snap7.error.S7ProtocolError: If the PLC rejects the request.
+        """
+        if not self.get_connected():
+            raise S7ConnectionError("Not connected to PLC")
+
+        request = self.protocol.build_clear_session_password_request()
+        response = await self._send_receive(request)
+        self.protocol.check_userdata_response(response, S7UserDataGroup.SECURITY, S7UserDataSubfunction.CLEAR_SESSION_PASSWORD)
+        logger.info("Session password cleared successfully")
+        return 0
+
     async def compress(self, timeout: int) -> int:
         """Compress PLC memory."""
         if not self.get_connected():
@@ -1100,7 +1250,7 @@ class AsyncClient(ClientMixin):
         conn = self._get_connection()
 
         async with self._lock:
-            await conn.send_data(bytes(data))
+            await self._send_data(conn, bytes(data))
             response = await conn.receive_data()
         return bytearray(response)
 

snap7/cli.py

@@ -15,9 +15,8 @@ from typing import Optional
 
 try:
     import click
-except ImportError:
-    print("CLI dependencies not installed. Try: pip install python-snap7[cli]")
-    raise
+except ImportError as exc:
+    raise ImportError("CLI dependencies not installed. Install them with: pip install python-snap7[cli]") from exc
 
 from snap7 import __version__
 from snap7.client import Client