python-snap7 3.2.0__tar.gz → 3.3.0__tar.gz

python_snap7-3.3.0/CHANGES.md

@@ -0,0 +1,424 @@
+CHANGES
+========
+
+3.3.0
+-----
+
+### New features
+
+* Add the typed DB accessors (`db_read_int`, `db_write_real`, `db_read_string`, ...,
+  `db_read_array`/`db_write_array`) and the tag helpers (`read_tag`, `write_tag`,
+  `read_tags`) to `AsyncClient`, matching the synchronous `Client`, as well as
+  `is_alive`, `connect_routed`, and `read_diagnostic_buffer`. (#922)
+
+### Bug fixes
+
+* `get_string` and `get_wstring` now raise `ValueError` when the buffer is shorter than the declared current length,
+  instead of silently returning a truncated value (#945).
+* USERDATA responses whose last-data-unit byte is neither `0x00` nor `0x01` are rejected with `S7ProtocolError`
+  instead of being treated as "more data" (#946).
+* `get_wstring` compared the declared maximum in bytes with the 16382-character limit, so any WSTRING with a
+  capacity of 8192 characters or more was rejected, including ones written by `set_wstring` (#923).
+* The get-block-info request now places the trailing `A` after the block number, as native Snap7 does
+  (`'0' type '00001' 'A'`), instead of before it. The bundled server parses the new layout (#929).
+* `set_plc_datetime` encoded the weekday as Monday=1, but S7 DATE_AND_TIME counts Sunday=1 .. Saturday=7, so every
+  day was off by one position. The bundled server's clock reply uses the same convention now (#932).
+* `set_plc_datetime` now raises `ValueError` for years outside 1990-2089 instead of silently sending a different
+  year, since the two-digit S7 year cannot represent them (#933).
+* `parse_get_clock_response` now accepts the ten-byte S7 clock reply (reserved, century, then the time with milliseconds)
+  that native Snap7 and PLCs send, and still accepts the legacy eight-byte form. The bundled server emits the
+  ten-byte form (#934).
+* `parse_response` now fails on any nonzero S7 header error word, as native Snap7 does, instead of only when the error
+  class is nonzero. Read and upload responses with error class 0 and a nonzero error code were previously treated as
+  successes while the write path rejected them (#930).
+* `parse_list_blocks_response` now requires exactly the seven four-byte block-type entries (28 bytes) that native Snap7
+  expects, with distinct, known type codes. Empty or partial tables and duplicate entries are rejected instead of being
+  reported as zero block counts (#939).
+* `set_plc_datetime` and the session-password calls now accept the null acknowledgement (return code 0x0A, no data) that
+  real PLCs send for services that return no data, instead of failing with "Object does not exist". The bundled
+  server acknowledges these services the same way (#940).
+* Compress now uses the PI service `_GARB` and copy RAM to ROM uses file system `EP` with `_MODU`, matching real
+  engineering tools and native Snap7, instead of the invented `_MSZL`. The bundled server recognises the new
+  requests (#941).
+* Read-SZL requests now carry the `0xFF`/octet-string data header and continuation requests the 12-byte parameter
+  block (method `0x12`) that real engineering tools send; both previously used the header of a request without data
+  and an 8-byte parameter block (#942).
+* `get_order_code` no longer keeps the trailing space padding of the order code on S7-1200/1500 CPUs, for example
+  `6ES7 212-1BE40-0XB0 ` is now `6ES7 212-1BE40-0XB0` (#949).
+
+### Documentation
+
+* Add a "Tested and Verified Hardware" section to the PLC support matrix, listing the CPUs, firmware versions and
+  python-snap7 versions the real-PLC acceptance suite has passed on (S7-1200 CPU 1212C V4.7.3, S7-1500 CPU 1511F-1 PN
+  V2.9.7). (#947)
+
+3.2.1
+-----
+
+Bug-fix and packaging release, with a few small additions.
+
+### Packaging
+
+* Include the full test suite (`tests/__init__.py`, `tests/conftest.py`, PLC setup
+  files), examples, docs, and `CHANGES.md` in the source distribution (#912, #913).
+* Remove leftover HarpoS7 test fixtures and transpiler from the S7CommPlus
+  split (#914).
+
+### New features
+
+* Add an `on_operation` callback to the synchronous and asynchronous clients,
+  invoked after each PLC operation with its name, duration, and whether it
+  raised, plus an example Prometheus metrics exporter (#843, #901).
+* Add a safe, Gherkin-based real-PLC acceptance program with restored scratch
+  writes and sanitized JSON/JUnit reports (#840, #892, #908).
+
+### Bug fixes
+
+* Match the classic Snap7 upload wire layout, collect every upload fragment, and
+  reject malformed, truncated, or mismatched S7/USERDATA responses (#903).
+* Use the PLC-driven request/response sequence for block download and match
+  classic S7 wire vectors for list-blocks-of-type, set clock, get block info,
+  and password requests (#904).
+* Fix the return type annotations of `snap7.util.get_byte` and `get_word`, which
+  return `int`, not `bytes`/`bytearray` (#910).
+
+3.2.0
+-----
+
+Feature and robustness release for the classic S7 protocol implementation.
+
+### Packaging
+
+* Move S7CommPlus support to the standalone
+  [`s7commplus`](https://github.com/gijzelaerr/s7commplus) package. The `s7`
+  import remains available as an alias for the classic `snap7` package.
+
+### New features
+
+* Add configurable request rate limiting to synchronous and asynchronous
+  clients, including fixed-interval and token-bucket modes (#823).
+* Add synchronous and asynchronous APIs for forcing I/O bits, cancelling
+  forces, and reading the PLC force table (#796, #800).
+* Add synchronous and asynchronous session password set/clear APIs for
+  password-protected PLCs (#792, #799).
+* Support LOGO reconnection, heartbeat, rate-limiting, and connection callback
+  options while preserving explicit TSAPs (#875).
+* Add an experimental serial PPI client for S7-200 PLCs, including V-memory,
+  system-memory, I/O, counter, and timer access (#824).
+
+### Bug fixes
+
+* Parse structured and flat SZL 0x0011 records correctly when reading order
+  codes and firmware versions from S7-1500 and classic PLCs (#783, #789).
+* Dispatch server callbacks and queue protocol events for client requests
+  instead of reporting only the server start event (#853, #856).
+* Validate classic S7 TPKT bounds and COTP Class 0 headers in synchronous and
+  asynchronous clients (#874).
+* Reject incomplete reads and mismatched or missing read/write
+  acknowledgements (#874).
+* Size read/write chunks in whole elements and preserve ctypes write
+  datatypes; correct BIT lengths and timer/counter index addressing (#874).
+* Validate `write_multi_vars()` inputs consistently and preserve each item's
+  declared datatype (#855, #874).
+* Echo the calling and called TSAP values in server connection confirmations,
+  and restart the receive deadline after each complete TPKT header (#893).
+* Return S7 item errors for reads from unregistered server areas or addresses
+  outside registered memory instead of returning fabricated data (#896).
+
+3.1.2
+-----
+
+Corrective bug fix and robustness release replacing the yanked 3.1.1 release.
+
+### Corrections
+
+* Withdraw the vulnerability and CWE characterizations published with 3.1.1.
+  Independent review found that those descriptions overstated or incorrectly
+  described the affected code paths.
+
+### Robustness fixes
+
+* Bound the server to 64 simultaneous clients by default, enforce the existing
+  `MaxClients` parameter, and allow `max_clients` configuration.
+* Validate block-download targets and declared sizes before allocating transfer
+  state, cap accumulated data at the declared size and registered area's
+  capacity, and clean up abandoned upload/download state on disconnect.
+* Correct block-download address parsing so the requested DB number is used
+  instead of silently falling back to DB1.
+* Bound COTP request reassembly to 1 MiB and apply one absolute deadline across
+  all fragments of a request.
+* Apply COTP TPDU-size validation consistently to sync and async clients.
+* Add regression tests for invalid PDU negotiation, TPDU-size validation,
+  connection limits, request reassembly, and block-download limits.
+
+3.1.1 (yanked)
+----------------
+
+This release was yanked because its security descriptions were inaccurate and
+some of its input-hardening changes were incomplete. Use 3.1.2 instead.
+
+### Robustness changes
+
+* Validate COTP TPDU-size encodings in the synchronous client.
+* Normalize implausibly small negotiated PDU lengths and ensure read/write
+  chunk sizes remain positive.
+* Stop finalizing downloads into unregistered server memory areas. This did not
+  bound the download accumulator and was completed in 3.1.2.
+
+### Bug fixes
+
+* Fix `connection_type` not applied in TSAP composition during
+  `connect()` (#766)
+* Fix auto-reconnect not triggered on multi-block read path (#787)
+* Support multi-byte string encodings (GBK, UTF-8) in `get_string`,
+  `set_string`, `get_fstring`, `set_fstring` (#788)
+* Thread encoding parameter through `read_tag` / `write_tag` /
+  `read_tags` (#786)
+* Server: reassemble COTP-fragmented requests; include TPDU size
+  parameter in Connection Confirm so clients don't fall back to the
+  128-byte ISO 8073 default (#804)
+* Server: fix `INT` and `DINT` word lengths returning wrong byte count
+  in read requests (#804)
+
+### Thanks
+
+* [@b1163646804](https://github.com/b1163646804) — multi-byte encoding
+  support and testing (#788)
+* [@domelg](https://github.com/domelg) — server COTP fragmentation and
+  INT/DINT byte count bug reports (#804)
+
+3.1.0
+-----
+
+Feature and bug fix release for the pure Python S7 communication library.
+
+### New features
+
+* **AsyncClient** for `asyncio` support (#593)
+* **Unified Tag API**: `client.read_tag("DB1.DBD0:REAL")` with PLC4X /
+  Siemens STEP7 syntax (#697)
+* **Dual-dialect tag parsing**: PLC4X and nodeS7 tag formats with
+  auto-detection (#701)
+* **Multi-variable read optimizer** with parallel dispatch (experimental, #641)
+* **S7 routing** for multi-subnet PLC access (experimental, #639)
+* **Heartbeat monitoring** and auto-reconnect with exponential backoff (#635)
+* **Structured logging** with PLC connection context (`snap7.log`, #688)
+* **PROFINET DCP** network discovery (#634)
+* **CLI tools** for PLC interaction (`pip install "python-snap7[cli]"`, #631)
+* **Demo server** exposing real host metrics (#704)
+* Typed DB access methods (`db_read_bool`, `db_read_int`, etc., #632)
+* Symbolic addressing — read/write by tag name (experimental, #638)
+* Diagnostic buffer reading (#690)
+* Array read/write helpers (`db_read_array`, `db_write_array`, #693)
+* Missing data type setters: `set_lint`, `set_ulint`, `set_ltime`, `set_ltod`, `set_ldt` (#693)
+* Property-based testing with Hypothesis (#636)
+
+### Bug fixes
+
+* Fix `AttributeError` from `__del__` during interpreter shutdown (#707)
+* Fix server SZL 0x001C response to match real PLC format (#694)
+* Fix `connection_type` in TSAP composition during connect (#766)
+* Accept `memoryview` in setter and getter type annotations (#647)
+* Zero-pad milliseconds in `get_time` (#716)
+* Fix PI service PDU format for PLC control commands (#743)
+* Fix `get_cpu_info` and `S7SZL.__str__` (#692)
+* Fix partner S7 Communication Setup and bsend/brecv PDU format (#669)
+* Fix `get_dtl` microsecond parsing (4-byte nanosecond field)
+* Fix `set_date` unsigned short for day count
+* Fix `set_tod` float precision loss
+* Validate BMP range in `set_wstring`
+* Fix async `get_cpu_info` SZL offsets (#702)
+* Fix demo primary-IP guess with VPN/tunnel interfaces (#708)
+* Fix mypy errors in server SZL list (#695)
+* Robustness: 210+ S7 error codes, auto PDU splitting, stale packet retry (#580)
+
+### Improvements
+
+* Set `TCP_NODELAY` and `SO_KEEPALIVE` on all sockets (#677)
+* Export `get_ulint`, `get_lint`, `get_date_time_object` from `snap7.util` (#652)
+* 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
+-----
+
+Major release: python-snap7 is now a pure Python S7 communication library.
+This version completely breaks with the previous approach of wrapping the C snap7
+shared library. The entire S7 protocol stack is now implemented in pure Python,
+greatly improving portability and making it easier to install and extend.
+
+* **Breaking**: The C snap7 library is no longer required or used
+* Complete rewrite of the S7 protocol stack in pure Python
+* Native Python implementation of TPKT (RFC 1006) and COTP (ISO 8073) layers
+* Native S7 protocol PDU encoding/decoding
+* Pure Python server implementation for testing and simulation
+* No platform-specific binary dependencies — works on any platform that runs Python
+* Improved error handling and connection management
+* Full type annotations with mypy strict mode
+* CLI interface for running an S7 server emulator (`pip install "python-snap7[cli]"`)
+
+If you experience issues with 3.0, please report them on the
+[issue tracker](https://github.com/gijzelaerr/python-snap7/issues) with a clear
+description and the version you are using. As a workaround, pin to the last
+pre-3.0 release:
+
+    $ pip install "python-snap7<3"
+
+### Thanks
+
+Special thanks to the following people for testing, reporting issues, and providing
+feedback during the 3.0 development:
+
+* [@lupaulus](https://github.com/lupaulus) — extensive testing and bug reports
+* [@spreeker](https://github.com/spreeker) — testing and feedback
+* [@nikteliy](https://github.com/nikteliy) — review and feedback on the rewrite
+* [@amorelettronico](https://github.com/amorelettronico) — testing
+* [@razour08](https://github.com/razour08) — testing
+* [@core-engineering](https://github.com/core-engineering) — bug reports (#553)
+* [@AndreasScharf](https://github.com/AndreasScharf) — bug reports (#572)
+* [@Robatronic](https://github.com/Robatronic) — bug reports (#574)
+* [@hirotasoshu](https://github.com/hirotasoshu) — feedback (#545)
+* [@PoitrasJ](https://github.com/PoitrasJ) — bug reports (#479)
+
+1.2
+---
+
+* fix wheel tag for linux x86_64 by @nikteliy in https://github.com/gijzelaerr/python-snap7/pull/297
+* Fixed typo area doesn't exist areas does by @Ofloo in https://github.com/gijzelaerr/python-snap7/pull/306
+* add get_time and set_time in util by @Yingliangzhe in https://github.com/gijzelaerr/python-snap7/pull/308
+* modification of TIME data type by @Yingliangzhe in https://github.com/gijzelaerr/python-snap7/pull/311
+* added DATE_AND_TIME Value as Datetime object by @zsisamci in https://github.com/gijzelaerr/python-snap7/pull/312
+* #273 by @nikteliy in https://github.com/gijzelaerr/python-snap7/pull/321
+* Add byte type parsing to DB_Row API + set parsing case insensitive by @LoicGRENON in https://github.com/gijzelaerr/python-snap7/pull/315
+* added missing types in  WordLen by @zsisamci in https://github.com/gijzelaerr/python-snap7/pull/326
+* Add support for read/write unsigned value from bytearray by @LoicGRENON in https://github.com/gijzelaerr/python-snap7/pull/316
+* fixing ip string paramters to c function by @zsisamci in https://github.com/gijzelaerr/python-snap7/pull/329
+* Add py.typed marker file by @mthuurne in https://github.com/gijzelaerr/python-snap7/pull/342
+* require correct package name, fixes issue #344 by @gijzelaerr in https://github.com/gijzelaerr/python-snap7/pull/345
+* Fix warnings by @nikteliy in https://github.com/gijzelaerr/python-snap7/pull/350
+* Update license identifier by @Shortfinga in https://github.com/gijzelaerr/python-snap7/pull/349
+* Update client db_write docs by @pwablito in https://github.com/gijzelaerr/python-snap7/pull/352
+* Fix db_offset calculation error by @lubbbert in https://github.com/gijzelaerr/python-snap7/pull/351
+* fix #355 by @swamper123 in https://github.com/gijzelaerr/python-snap7/pull/359
+* fix #272 by @swamper123 in https://github.com/gijzelaerr/python-snap7/pull/360
+* fix get_time for small values by @swamper123 in https://github.com/gijzelaerr/python-snap7/pull/358
+* add more getter methods for utils by @swamper123 in https://github.com/gijzelaerr/python-snap7/pull/357
+* Prepare for 1.2 by @gijzelaerr in https://github.com/gijzelaerr/python-snap7/pull/364
+
+### New Contributors
+
+* @Ofloo made their first contribution in https://github.com/gijzelaerr/python-snap7/pull/306
+* @zsisamci made their first contribution in https://github.com/gijzelaerr/python-snap7/pull/312
+* @LoicGRENON made their first contribution in https://github.com/gijzelaerr/python-snap7/pull/315
+* @mthuurne made their first contribution in https://github.com/gijzelaerr/python-snap7/pull/342
+* @Shortfinga made their first contribution in https://github.com/gijzelaerr/python-snap7/pull/349
+* @pwablito made their first contribution in https://github.com/gijzelaerr/python-snap7/pull/352
+* @lubbbert made their first contribution in https://github.com/gijzelaerr/python-snap7/pull/351
+
+**Full Changelog**: https://github.com/gijzelaerr/python-snap7/compare/1.1...1.2
+
+1.1
+---
+
+* Make a binary wheel for all platforms (#232)
+* Improve doc strings of all functions (#242)
+
+Special thanks for this release to
+ * Fabian Beitler
+ * Nikteliy
+ * Lautaro Nahuel Dapino
+
+1.0
+---
+
+ *  Drop python 2 support  (#214)
+ *  Feature request: ReadSZL()  (#196)
+ *  Keep argument format across the functions  (#193)
+ *  Drop Python2 Tests  (#167)
+ *  Support for S5TIME  (#163)
+ *  Add type annotations  (#157)
+ *  client.full_upload() return bytearray size 65536  (#127)
+ *  Some client tests segfault on Linux  (#26)
+ *  Not all functions are implemented yet  (#25)
+
+special thanks to [Fabian Beitler](https://github.com/swamper123) and
+[Nikteliy](https://github.com/nikteliy>) for their contributions to the 1.0 release!
+
+
+
+
+0.11
+----
+
+ * Update read_multi.py (#132)
+ * Added fixes to snap7/client.py read_area function to allow for Counter and Timer Reads  (#121)
+ * Post to a public docker repository? (#119)
+ * Implementation of Cli_SetDateTime, Cli_GetDateTime enhancement (#114)
+
+
+0.10
+----
+
+ * Fix OSX travis build #99
+ * util.get_int() broken #101
+ * Compatibility issue with Python3 #109
+ * Logo 8 improvements bug #105
+
+
+0.7
+---
+
+* util.get_int() broken (#65, #71)
+* fix Add files via upload bug (#59)
+
+Special thanks to Pelle van der Heide for solving issues
+
+
+0.6
+---
+
+* Add __del__ to client, server and partner (#69)
+* Add files via upload (#59)
+
+Special thanks to xybsoft for solving issues
+
+0.5
+---
+
+* adding some missing functions
+* fixing Python3 support (issue #43)
+* improving the documentation
+
+0.4
+---
+
+More functions added:
+
+* client.plc_stop
+* client.plc_cold_start
+* client.plc_hot_start
+* client.read_multi_vars
+
+0.2.1
+-----
+
+Small fix, README.rst was not included in sdist
+
+
+0.2
+---
+
+- Add support for Windows
+- Add functions added in Snap7 1.1.0
+- Add missing client functions
+- fix some partner functions
+- simplified API
+
+0.1
+---
+
+- Initial release.

python_snap7-3.3.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.rst
+include CHANGES.md
+include LICENSE
+include tox.ini
+graft tests
+prune tests/fixtures
+graft example
+graft doc
+global-exclude *.py[cod] __pycache__

{python_snap7-3.2.0/python_snap7.egg-info → python_snap7-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-snap7
-Version: 3.2.0
+Version: 3.3.0
 Summary: Pure Python S7 communication library for Siemens PLCs
 Author-email: Gijs Molenaar <gijsmolenaar@gmail.com>
 License-Expression: MIT
@@ -24,6 +24,7 @@ License-File: LICENSE
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-bdd<10,>=8.1; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
 Requires-Dist: pytest-html; extra == "test"
 Requires-Dist: hypothesis; extra == "test"
@@ -74,6 +75,26 @@ using the classic S7 protocol. It supports S7-300 and S7-400 controllers, as
 well as S7-1200 and S7-1500 controllers with PUT/GET access enabled. It
 supports Python 3.10+ on Windows, Linux, and macOS without native dependencies.
 
+S7-1200 and S7-1500
+===================
+
+On S7-1200 and S7-1500 controllers, python-snap7 only works when PUT/GET access
+is enabled in TIA Portal, and it cannot access optimized data blocks. PUT/GET
+is unauthenticated and disabled by default, so leaving it disabled is the more
+secure configuration.
+
+If PUT/GET is disabled, or you need optimized data blocks or symbolic access,
+use `s7commplus <https://github.com/gijzelaerr/s7commplus>`_ instead::
+
+   pip install s7commplus
+
+s7commplus is a separate, younger project that implements S7CommPlus, the
+protocol these controllers speak natively. Check the
+`firmware versions validated so far <https://s7commplus.readthedocs.io/en/latest/connections.html>`_
+before relying on it, and see the
+`PLC support matrix <https://python-snap7.readthedocs.io/en/latest/plc-support.html>`_
+for what python-snap7 supports on each controller family.
+
 Installation
 ============
 
@@ -101,3 +122,8 @@ Documentation
 
 Read the full documentation at
 `python-snap7.readthedocs.io <https://python-snap7.readthedocs.io/en/latest/>`_.
+
+The safe volunteer hardware-test procedure is in
+`Real-PLC acceptance testing <doc/real-plc-testing.rst>`_.
+The CPUs and firmware versions it has passed on are listed under
+`Tested and Verified Hardware <doc/plc-support.rst>`_.

{python_snap7-3.2.0 → python_snap7-3.3.0}/README.rst

@@ -22,6 +22,26 @@ using the classic S7 protocol. It supports S7-300 and S7-400 controllers, as
 well as S7-1200 and S7-1500 controllers with PUT/GET access enabled. It
 supports Python 3.10+ on Windows, Linux, and macOS without native dependencies.
 
+S7-1200 and S7-1500
+===================
+
+On S7-1200 and S7-1500 controllers, python-snap7 only works when PUT/GET access
+is enabled in TIA Portal, and it cannot access optimized data blocks. PUT/GET
+is unauthenticated and disabled by default, so leaving it disabled is the more
+secure configuration.
+
+If PUT/GET is disabled, or you need optimized data blocks or symbolic access,
+use `s7commplus <https://github.com/gijzelaerr/s7commplus>`_ instead::
+
+   pip install s7commplus
+
+s7commplus is a separate, younger project that implements S7CommPlus, the
+protocol these controllers speak natively. Check the
+`firmware versions validated so far <https://s7commplus.readthedocs.io/en/latest/connections.html>`_
+before relying on it, and see the
+`PLC support matrix <https://python-snap7.readthedocs.io/en/latest/plc-support.html>`_
+for what python-snap7 supports on each controller family.
+
 Installation
 ============
 
@@ -49,3 +69,8 @@ Documentation
 
 Read the full documentation at
 `python-snap7.readthedocs.io <https://python-snap7.readthedocs.io/en/latest/>`_.
+
+The safe volunteer hardware-test procedure is in
+`Real-PLC acceptance testing <doc/real-plc-testing.rst>`_.
+The CPUs and firmware versions it has passed on are listed under
+`Tested and Verified Hardware <doc/plc-support.rst>`_.

python_snap7-3.3.0/doc/API/client-base.rst

@@ -0,0 +1,9 @@
+Shared Client Internals
+=======================
+
+Pure-computation and compatibility methods shared by ``Client`` and
+``AsyncClient``. Applications normally access these methods through one of the
+concrete clients.
+
+.. automodule:: snap7.client_base
+   :members:

python_snap7-3.3.0/doc/API/client.rst

@@ -0,0 +1,45 @@
+Client
+======
+
+The ``s7`` package implements the classic S7 protocol for S7-300/400 PLCs and
+PUT/GET access on S7-1200/1500.
+
+Use ``Client`` for synchronous applications::
+
+   from s7 import Client
+
+   with Client() as client:
+       client.connect("192.168.1.10", 0, 1)
+       data = client.db_read(1, 0, 4)
+
+Use ``AsyncClient`` when the surrounding application uses ``asyncio``::
+
+   import asyncio
+   from s7 import AsyncClient
+
+   async def main():
+       async with AsyncClient() as client:
+           await client.connect("192.168.1.10", 0, 1)
+           data = await client.db_read(1, 0, 4)
+
+   asyncio.run(main())
+
+Both clients expose the same main PLC operations, including area and DB
+access, block transfer, CPU information and control, clock access, force
+operations, and session passwords. Methods that perform I/O are coroutines on
+``AsyncClient``. See :doc:`../advanced` for the less common operations.
+
+s7.Client
+---------
+
+.. automodule:: snap7.client
+   :members:
+   :inherited-members:
+
+s7.AsyncClient
+--------------
+
+.. automodule:: snap7.async_client
+   :members:
+   :inherited-members:
+   :exclude-members: AsyncISOTCPConnection

python_snap7-3.3.0/doc/API/connection.rst

@@ -0,0 +1,8 @@
+Connection
+==========
+
+The connection module implements the ISO on TCP transport layer (TPKT/COTP)
+used for S7 communication.
+
+.. automodule:: snap7.connection
+   :members:

python_snap7-3.3.0/doc/API/datatypes.rst

@@ -0,0 +1,7 @@
+Data Types
+==========
+
+The datatypes module provides S7 data type definitions and address encoding.
+
+.. automodule:: snap7.datatypes
+   :members:

python_snap7-3.3.0/doc/API/demo.rst

@@ -0,0 +1,9 @@
+Demo Server
+===========
+
+Implementation of the optional live host-metrics demo used by ``s7 demo``.
+Install ``python-snap7[demo]`` before running it. This module is intended for
+examples and integration testing, not production monitoring.
+
+.. automodule:: snap7.demo
+   :members:

python_snap7-3.3.0/doc/API/discovery.rst

@@ -0,0 +1,7 @@
+Discovery
+=========
+
+.. automodule:: snap7.discovery
+   :members:
+   :undoc-members:
+   :show-inheritance:

python_snap7-3.3.0/doc/API/error.rst

@@ -0,0 +1,5 @@
+Errors
+======
+
+.. automodule:: snap7.error
+   :members:

python_snap7-3.3.0/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 s7.log import JSONFormatter
+
+   handler = logging.StreamHandler()
+   handler.setFormatter(JSONFormatter())
+   logging.getLogger("snap7").addHandler(handler)
+
+API reference
+-------------
+
+.. automodule:: snap7.log
+   :members:

python_snap7-3.3.0/doc/API/logo.rst

@@ -0,0 +1,5 @@
+Logo
+====
+
+.. autoclass:: snap7.logo.Logo
+   :members: