Prepare 4.0 release: README, docs, changelog, s7 exports (#678)

Comprehensive cleanup for the 4.0 release:

README:
- 3.0 (current release) section first with snap7 examples
- 4.0 (unreleased) section with s7 examples and S7CommPlus headline
- Clear note that pip install gives 3.0, not 4.0
- Experimental features listed separately (optimizer, routing, symbols)
- Changelog with all 4.0 features

Documentation:
- Update limitations.rst: V3 supported, V4 is the gap
- Update plc-support.rst: S7-1500 FW 3.x+ now fully supported
- Add symbols.rst doc page for SymbolTable (experimental)
- Add symbols to API Reference section in index.rst

s7 package:
- Export SymbolTable from s7.__init__ so users can do `from s7 import SymbolTable`

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

Author: gijzelaerr

CHANGES.md

@@ -1,6 +1,33 @@
 CHANGES
 =======
 
+4.0.0 (unreleased)
+-------------------
+
+Major release: new `s7` package with S7CommPlus protocol support.
+
+* New `s7` package as recommended entry point with protocol auto-detection
+* S7CommPlus V1, V2 (TLS), and V3 support for S7-1200/1500
+* S7CommPlus area read/write (M, I, Q, counters, timers)
+* S7CommPlus PLC start/stop via INVOKE
+* S7CommPlus object browsing via EXPLORE
+* S7CommPlus live symbol browsing (`client.browse()`) and datablock listing (experimental)
+* TIA Portal XML import for SymbolTable (`SymbolTable.from_tia_xml()`) (experimental)
+* Partner BSend/BRecv with correct PBC format, async receive, PDU reference echo
+* TCP_NODELAY and SO_KEEPALIVE on all sockets for lower latency
+* Structured logging with PLC connection context (`snap7.log`)
+* Command-line interface (`snap7-cli` / `s7`)
+* Multi-variable read optimizer with parallel dispatch (experimental)
+* S7 routing for multi-subnet PLC access (experimental)
+* Symbolic addressing via SymbolTable (experimental)
+* Dependabot auto-merge for dependency updates
+* Documentation restructured: API Reference + Internals sections
+
+### Thanks
+
+* [@hs2bws-hash](https://github.com/hs2bws-hash) — extensive real PLC testing of Partner BSend/BRecv (#668)
+* [@QuakeString](https://github.com/QuakeString) — read optimizer inspiration via python-snap7-optimized fork
+
 3.0.0
 -----
 

README.rst

@@ -48,19 +48,20 @@ Connect to any S7 PLC::
 No native libraries or platform-specific dependencies are required.
 
 
-Version 4.0 -- New ``s7`` Package (unreleased)
-===============================================
+Version 4.0 -- S7CommPlus & the ``s7`` Package (unreleased)
+============================================================
 
 .. note::
 
    Version 4.0 is **not yet released**. Installing with ``pip install python-snap7``
    gives you version 3.0, which uses the ``snap7`` package shown above.
-   To try 4.0 early, install from the development branch (see below).
+   To try 4.0 early, install from the development branch::
 
-Version 4.0 introduces the new ``s7`` package as the standard entry point. It
-works with **all supported PLC models** (S7-300, S7-400, S7-1200, S7-1500),
-adds S7CommPlus protocol support (required for S7-1200/1500 with PUT/GET
-disabled), and automatically selects the best protocol::
+       $ pip install git+https://github.com/gijzelaerr/python-snap7.git@master
+
+**S7CommPlus protocol support** -- the headline feature of 4.0. S7CommPlus is
+required for communicating with S7-1200 and S7-1500 PLCs that have PUT/GET
+disabled. python-snap7 now supports S7CommPlus V1, V2 (with TLS), and V3::
 
    from s7 import Client
 
@@ -69,32 +70,34 @@ disabled), and automatically selects the best protocol::
    data = client.db_read(1, 0, 4)
    client.disconnect()
 
-The ``s7.Client`` automatically tries S7CommPlus first (for S7-1200/1500) and
-falls back to legacy S7 when needed. The existing ``snap7`` package continues
-to work unchanged.
+The new ``s7`` package is the recommended entry point for all new projects. It
+automatically tries S7CommPlus first (for S7-1200/1500) and falls back to legacy
+S7 when needed. The existing ``snap7`` package continues to work unchanged.
 
-**Help us test!** Version 4.0 needs more real-world testing before release. If
-you have access to any of the following PLCs, we would greatly appreciate
-testing and feedback:
+**Other new features in 4.0:**
 
-* S7-1200 (any firmware version)
-* S7-1500 (any firmware version)
-* S7-1500 with TLS enabled
-* S7-300
-* S7-400
-* S7-1200/1500 with PUT/GET disabled (S7CommPlus-only)
-* LOGO! 0BA8 and newer
+* **Command-line interface** (``s7 read``, ``s7 write``, ``s7 info``)
+* **Partner BSend/BRecv** for peer-to-peer communication with S7-1500
+* **TCP socket optimization** (TCP_NODELAY, SO_KEEPALIVE) for lower latency
+* **S7CommPlus area read/write** for M, I, Q, counters, timers (not just DBs)
+* **Structured logging** with PLC connection context for multi-PLC environments
 
-Please report your results -- whether it works or not -- on the
-`issue tracker <https://github.com/gijzelaerr/python-snap7/issues>`_.
+**Experimental features** (API may change):
 
-To install the development version::
+* **Multi-variable read optimizer** -- merges scattered reads into minimal PDU
+  exchanges with parallel dispatch
+* **S7 routing** -- connect to PLCs on remote subnets via a gateway PLC
+* **Symbolic addressing** -- read/write by tag name instead of raw addresses
+* **Live symbol browsing** -- resolve tag names directly from the PLC
+* **TIA Portal XML import** -- import symbol tables from TIA Portal exports
 
-   $ pip install git+https://github.com/gijzelaerr/python-snap7.git@master
+**Help us test!** If you have access to any Siemens S7 PLC, we would greatly
+appreciate testing and feedback. Please report results on the
+`issue tracker <https://github.com/gijzelaerr/python-snap7/issues>`_.
 
 
-Version 3.0 -- Pure Python Rewrite
-====================================
+Version 3.0 -- Pure Python Rewrite (current release)
+=====================================================
 
 Version 3.0 was a ground-up rewrite of python-snap7. The library no longer wraps
 the C snap7 shared library -- instead, the entire S7 protocol stack (TPKT, COTP,

doc/API/symbols.rst

@@ -0,0 +1,38 @@
+Symbolic Addressing
+===================
+
+.. warning::
+
+   Symbolic addressing is **experimental** and its API may change in future
+   versions.
+
+The :class:`~snap7.util.symbols.SymbolTable` class maps human-readable tag
+names to PLC addresses, enabling read/write by name instead of raw byte offsets.
+
+.. code-block:: python
+
+   from s7 import Client, SymbolTable
+
+   symbols = SymbolTable.from_csv("tags.csv")
+   client = Client()
+   client.connect("192.168.1.10", 0, 1)
+
+   value = symbols.read(client, "Motor1.Speed")
+   symbols.write(client, "Motor1.Speed", 1500.0)
+
+CSV format::
+
+   tag_name,db_number,byte_offset,data_type
+   Motor1.Speed,1,0,REAL
+   Motor1.Running,1,4.0,BOOL
+   SetPoint,1,6,INT
+
+Also supports JSON::
+
+   symbols = SymbolTable.from_json("tags.json")
+
+API reference
+-------------
+
+.. automodule:: snap7.util.symbols
+   :members:

doc/index.rst

@@ -44,6 +44,7 @@ Welcome to python-snap7's documentation!
    API/partner
    API/logo
    API/util
+   API/symbols
    API/optimizer
    API/type
 

doc/limitations.rst

@@ -24,7 +24,7 @@ are **not possible** with this protocol:
    * - Create PLC backups
      - Full project backup requires TIA Portal. python-snap7 can upload
        individual blocks, but this is not a complete backup.
-   * - S7CommPlus V3
-     - python-snap7 supports S7CommPlus V1 and V2 (with TLS) via the ``s7``
-       package. V3 is not yet supported. For PLCs that only support V3, enable
-       PUT/GET as a fallback or use OPC UA.
+   * - S7CommPlus V4
+     - python-snap7 supports S7CommPlus V1, V2, and V3 via the ``s7``
+       package. V4 is not yet supported. For PLCs that require V4, use OPC UA
+       as an alternative.

doc/plc-support.rst

@@ -65,8 +65,8 @@ Supported PLCs
      - PUT/GET only
      - No
      - V3
-     - **PUT/GET only**
-     - S7CommPlus V3 uses proprietary crypto; not yet supported.
+     - **Full**
+     - ``s7.Client`` supports S7CommPlus V3.
    * - S7-1500R/H
      - ~2019
      - No
@@ -144,12 +144,11 @@ Siemens has evolved their PLC communication protocols over time:
      - Certificate-based
      - S7-1500 FW 3.x+
 
-python-snap7 implements the **classic S7 protocol** and **S7CommPlus V1/V2**.
+python-snap7 implements the **classic S7 protocol** and **S7CommPlus V1, V2, and V3**.
 The ``s7`` package is the recommended entry point -- it automatically selects
 the best protocol for your PLC. The classic protocol remains available on most
-PLC families via the PUT/GET mechanism. S7CommPlus V3 is not yet supported;
-for PLCs that require it (such as the S7-1500R/H), consider using OPC UA as
-an alternative.
+PLC families via the PUT/GET mechanism. S7CommPlus V4 is not yet supported;
+for PLCs that require it, consider using OPC UA as an alternative.
 
 
 Alternatives for Unsupported PLCs

s7/__init__.py

@@ -20,6 +20,7 @@
 
 from snap7.type import Area, Block, WordLen, SrvEvent, SrvArea
 from snap7.util.db import Row, DB
+from snap7.util.symbols import SymbolTable
 
 __all__ = [
     "Client",
@@ -35,4 +36,5 @@
     "SrvArea",
     "Row",
     "DB",
+    "SymbolTable",
 ]