4.0 polish: docs, examples, property tests, stress tests, optimizer fix (#696)

Documentation:
- Add logging doc page (API/log.rst) to index
- Update CHANGES.md with all recent features (block transfer, array
  helpers, setters, cpu_info fix)
- Add s7 examples (s7_basic.py, s7_symbols.py, s7_server.py)

Optimizer fix:
- Exclude counter (0x1C) and timer (0x1D) areas from byte-range
  merging — they use element-based addressing

SymbolTable:
- Accept both snap7.Client and s7.Client (use Any type hint)

Property-based tests (Hypothesis):
- Round-trip tests for all 20 getter/setter pairs
- Found and fixed float precision bug in set_ltime/set_ltod/set_ldt
  (use integer arithmetic instead of float multiplication)

Multi-client stress tests:
- Concurrent reads from 4 clients
- Concurrent writer + reader on same DB
- Rapid connect/disconnect cycles

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: gijzelaerr

CHANGES.md

@@ -20,6 +20,13 @@ Major release: new `s7` package with S7CommPlus protocol support.
 * Multi-variable read optimizer with parallel dispatch (experimental)
 * S7 routing for multi-subnet PLC access (experimental)
 * Symbolic addressing via SymbolTable (experimental)
+* S7CommPlus CPU state reading and block transfer (upload/download)
+* Array read/write helpers (`db_read_array`, `db_write_array`)
+* Missing data type setters: `set_lint`, `set_ulint`, `set_ltime`, `set_ltod`, `set_ldt`
+* Optimized `SymbolTable.read_many()` with multi-variable batching
+* Optimizer excludes counter/timer areas from byte-range merging
+* Fixed `get_cpu_info` field offsets for real S7-300/1500 (thanks @qzertywsx)
+* Fixed `S7SZL.__str__` attribute name typo (thanks @qzertywsx)
 * Dependabot auto-merge for dependency updates
 * Documentation restructured: API Reference + Internals sections
 

doc/API/log.rst

@@ -0,0 +1,33 @@
+Logging
+=======
+
+Structured logging with PLC connection context for multi-PLC environments.
+
+The :class:`~snap7.log.PLCLoggerAdapter` automatically injects PLC host,
+rack, and slot into every log message:
+
+.. code-block:: python
+
+   import logging
+   logging.basicConfig(level=logging.DEBUG)
+
+   from s7 import Client
+   client = Client()
+   client.connect("192.168.1.10", 0, 1)
+   # Logs: [192.168.1.10 R0/S1] Connected to 192.168.1.10:102 ...
+
+For JSON output (ELK, Datadog, Loki):
+
+.. code-block:: python
+
+   from snap7.log import JSONFormatter
+
+   handler = logging.StreamHandler()
+   handler.setFormatter(JSONFormatter())
+   logging.getLogger("snap7").addHandler(handler)
+
+API reference
+-------------
+
+.. automodule:: snap7.log
+   :members:

doc/index.rst

@@ -46,6 +46,7 @@ Welcome to python-snap7's documentation!
    API/util
    API/symbols
    API/optimizer
+   API/log
    API/type
 
 .. toctree::

example/s7_basic.py

@@ -0,0 +1,26 @@
+"""Basic s7 Client example — auto-detects S7CommPlus vs legacy S7.
+
+Usage:
+    python example/s7_basic.py 192.168.1.10
+"""
+
+import sys
+from s7 import Client
+
+address = sys.argv[1] if len(sys.argv) > 1 else "192.168.1.10"
+
+client = Client()
+client.connect(address, 0, 1)
+
+print(f"Connected via {client.protocol.value}")
+
+# Read 4 bytes from DB1
+data = client.db_read(1, 0, 4)
+print(f"DB1.DBB0-3: {data.hex()}")
+
+# Write and read back
+client.db_write(1, 0, bytearray([0x01, 0x02, 0x03, 0x04]))
+data = client.db_read(1, 0, 4)
+print(f"After write: {data.hex()}")
+
+client.disconnect()

example/s7_server.py

@@ -0,0 +1,37 @@
+"""s7 Server emulator example — run a PLC simulator for testing.
+
+Usage:
+    python example/s7_server.py
+"""
+
+import struct
+import time
+from ctypes import c_char
+
+from s7 import Server
+from snap7.type import SrvArea
+
+server = Server()
+
+# Register DB1 with test data on the legacy server
+db1_data = bytearray(100)
+struct.pack_into(">f", db1_data, 0, 23.5)  # temperature
+struct.pack_into(">h", db1_data, 4, 42)  # set point
+db1_array = (c_char * 100).from_buffer(db1_data)
+server.legacy_server.register_area(SrvArea.DB, 1, db1_array)
+
+# Register DB1 on S7CommPlus server too
+server.register_raw_db(1, bytearray(db1_data))
+
+# Start both servers
+server.start(tcp_port=1102, s7commplus_port=11020)
+
+print("Server running on port 1102 (legacy) and 11020 (S7CommPlus)")
+print("Press Ctrl+C to stop")
+
+try:
+    while True:
+        time.sleep(1)
+except KeyboardInterrupt:
+    server.stop()
+    print("Server stopped")

example/s7_symbols.py

@@ -0,0 +1,36 @@
+"""Symbolic addressing example — read/write by tag name.
+
+Usage:
+    python example/s7_symbols.py 192.168.1.10
+"""
+
+import sys
+from s7 import Client, SymbolTable
+
+address = sys.argv[1] if len(sys.argv) > 1 else "192.168.1.10"
+
+# Define symbols (or use SymbolTable.from_csv("tags.csv"))
+symbols = SymbolTable(
+    {
+        "Motor1.Speed": {"db": 1, "offset": 0, "type": "REAL"},
+        "Motor1.Running": {"db": 1, "offset": 4, "bit": 0, "type": "BOOL"},
+        "SetPoint": {"db": 1, "offset": 6, "type": "INT"},
+    }
+)
+
+client = Client()
+client.connect(address, 0, 1)
+
+# Read by name
+speed = symbols.read(client, "Motor1.Speed")
+running = symbols.read(client, "Motor1.Running")
+print(f"Speed: {speed!r}, Running: {running!r}")
+
+# Write by name
+symbols.write(client, "SetPoint", 1500)
+
+# Batch read (uses optimizer when available)
+values = symbols.read_many(client, ["Motor1.Speed", "SetPoint"])
+print(f"Batch: {values}")
+
+client.disconnect()

snap7/optimizer.py

@@ -14,6 +14,11 @@
 
 logger = logging.getLogger(__name__)
 
+# Areas that support contiguous-block merging.  Counter (0x1C) and Timer
+# (0x1D) use element-based addressing, not byte-based, so merging them
+# as contiguous byte ranges would produce incorrect reads.
+_MERGEABLE_AREAS: frozenset[int] = frozenset({0x81, 0x82, 0x83, 0x84})  # PE, PA, MK, DB
+
 
 @dataclass
 class ReadItem:
@@ -116,10 +121,11 @@ def merge_items(sorted_items: list[ReadItem], max_gap: int = 5, max_block_size:
         item_end = item.byte_offset + item.byte_length
 
         same_region = item.area == block.area and item.db_number == block.db_number
+        mergeable = block.area in _MERGEABLE_AREAS
         gap = item.byte_offset - block_end
         new_length = max(block_end, item_end) - block.start_offset
 
-        if same_region and gap <= max_gap and new_length <= max_block_size:
+        if same_region and mergeable and gap <= max_gap and new_length <= max_block_size:
             # Merge: extend block to cover the new item
             block.byte_length = new_length
             block.items.append(item)

snap7/util/setters.py

@@ -809,7 +809,8 @@ def set_ltime(bytearray_: Buffer, byte_index: int, value: timedelta) -> Buffer:
         >>> data = bytearray(8)
         >>> set_ltime(data, 0, timedelta(seconds=1))
     """
-    nanoseconds = int(value.total_seconds() * 1_000_000_000)
+    # Use integer arithmetic to avoid float precision loss
+    nanoseconds = (value.days * 86400 + value.seconds) * 1_000_000_000 + value.microseconds * 1000
     bytearray_[byte_index : byte_index + 8] = struct.pack(">q", nanoseconds)
     return bytearray_
 
@@ -836,7 +837,7 @@ def set_ltod(bytearray_: Buffer, byte_index: int, value: timedelta) -> Buffer:
     """
     if value.days >= 1:
         raise ValueError("LTOD value must be less than 24 hours")
-    nanoseconds = int(value.total_seconds() * 1_000_000_000)
+    nanoseconds = (value.days * 86400 + value.seconds) * 1_000_000_000 + value.microseconds * 1000
     bytearray_[byte_index : byte_index + 8] = struct.pack(">Q", nanoseconds)
     return bytearray_
 
@@ -864,6 +865,6 @@ def set_ldt(bytearray_: Buffer, byte_index: int, value: datetime) -> Buffer:
     """
     epoch = datetime(1970, 1, 1)
     delta = value - epoch
-    nanoseconds = int(delta.total_seconds() * 1_000_000_000)
+    nanoseconds = (delta.days * 86400 + delta.seconds) * 1_000_000_000 + delta.microseconds * 1000
     bytearray_[byte_index : byte_index + 8] = struct.pack(">Q", nanoseconds)
     return bytearray_

snap7/util/symbols.py

@@ -23,7 +23,6 @@
 from pathlib import Path
 from typing import Any, Dict, Union
 
-from snap7.client import Client
 from snap7.type import ValueType
 from snap7.util import (
     get_bool,
@@ -485,7 +484,7 @@ def __contains__(self, tag: str) -> bool:
     # Read / write
     # ------------------------------------------------------------------
 
-    def read(self, client: Client, tag: str) -> ValueType:
+    def read(self, client: Any, tag: str) -> ValueType:
         """Read a single tag value from the PLC.
 
         Args:
@@ -500,7 +499,7 @@ def read(self, client: Client, tag: str) -> ValueType:
         data = client.db_read(addr.db, addr.byte_offset, size)
         return self._get_value(data, 0, addr)
 
-    def write(self, client: Client, tag: str, value: Any) -> None:
+    def write(self, client: Any, tag: str, value: Any) -> None:
         """Write a single tag value to the PLC.
 
         Args:
@@ -524,7 +523,7 @@ def write(self, client: Client, tag: str, value: Any) -> None:
         self._set_value(data, 0, addr, value)
         client.db_write(addr.db, addr.byte_offset, data)
 
-    def read_many(self, client: Client, tags: list[str]) -> Dict[str, ValueType]:
+    def read_many(self, client: Any, tags: list[str]) -> Dict[str, ValueType]:
         """Read multiple tags in batched requests.
 
         Groups tags by DB number and uses :meth:`~snap7.client.Client.read_multi_vars`