Skip to content

Commit bff5593

Browse files
gijzelaerrclaude
gijzelaerr
and
claude
committed
Restructure API docs for consistency
- Merge s7commplus.rst + async_client.rst into client.rst so Client, Server, and Partner all follow the same pattern: recommended (s7) first, then legacy (snap7) below - Add s7.Partner to partner.rst (was only showing snap7.Partner) - Group low-level modules (connection, s7protocol, datatypes, discovery) under a separate "Internals" section in the sidebar - Keep user-facing modules (client, server, partner, logo, util, type) in the main API Reference section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent c92faa7 commit bff5593

6 files changed

Lines changed: 166 additions & 160 deletions

File tree

‎doc/API/async_client.rst‎

Lines changed: 0 additions & 47 deletions
This file was deleted.

‎doc/API/client.rst‎

Lines changed: 132 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,137 @@
1-
Client (legacy)
2-
===============
1+
Client
2+
======
33

4-
The ``snap7.Client`` is the legacy S7 protocol client. It supports S7-300,
5-
S7-400, S7-1200 and S7-1500 PLCs via the classic PUT/GET interface.
4+
The ``s7`` package is the recommended entry point for communicating with any
5+
supported Siemens S7 PLC. It provides a unified client that works with all
6+
PLC models -- S7-300, S7-400, S7-1200 and S7-1500 -- and automatically
7+
selects the best protocol (S7CommPlus or legacy S7).
68

7-
For new projects, we recommend using :doc:`s7commplus` (``s7.Client``) instead,
8-
which works with all PLC models and automatically selects the best protocol.
9+
Synchronous client
10+
------------------
11+
12+
.. code-block:: python
13+
14+
from s7 import Client
15+
16+
client = Client()
17+
client.connect("192.168.1.10", 0, 1)
18+
data = client.db_read(1, 0, 4)
19+
print(client.protocol) # Protocol.S7COMMPLUS or Protocol.LEGACY
20+
client.disconnect()
21+
22+
Asynchronous client
23+
-------------------
24+
25+
.. code-block:: python
26+
27+
import asyncio
28+
from s7 import AsyncClient
29+
30+
async def main():
31+
client = AsyncClient()
32+
await client.connect("192.168.1.10", 0, 1)
33+
data = await client.db_read(1, 0, 4)
34+
await client.disconnect()
35+
36+
asyncio.run(main())
37+
38+
V2 connection with TLS
39+
----------------------
40+
41+
S7-1500 PLCs with firmware 2.x use S7CommPlus V2, which requires TLS. Pass
42+
``use_tls=True`` to the ``connect()`` method:
43+
44+
.. code-block:: python
45+
46+
from s7 import Client
47+
48+
client = Client()
49+
client.connect("192.168.1.10", 0, 1, use_tls=True)
50+
data = client.db_read(1, 0, 4)
51+
client.disconnect()
52+
53+
For PLCs with custom certificates, provide the certificate paths:
54+
55+
.. code-block:: python
56+
57+
client.connect(
58+
"192.168.1.10", 0, 1,
59+
use_tls=True,
60+
tls_cert="/path/to/client.pem",
61+
tls_key="/path/to/client.key",
62+
tls_ca="/path/to/ca.pem",
63+
)
64+
65+
Password authentication
66+
-----------------------
67+
68+
Password-protected PLCs require the ``password`` keyword argument:
69+
70+
.. code-block:: python
71+
72+
from s7 import Client
73+
74+
client = Client()
75+
client.connect("192.168.1.10", 0, 1, use_tls=True, password="my_plc_password")
76+
data = client.db_read(1, 0, 4)
77+
client.disconnect()
78+
79+
Protocol selection
80+
------------------
81+
82+
By default the client uses ``Protocol.AUTO`` which tries S7CommPlus first.
83+
You can force a specific protocol:
84+
85+
.. code-block:: python
86+
87+
from s7 import Client, Protocol
88+
89+
# Force legacy S7 only
90+
client = Client()
91+
client.connect("192.168.1.10", 0, 1, protocol=Protocol.LEGACY)
92+
93+
# Force S7CommPlus (raises on failure)
94+
client.connect("192.168.1.10", 0, 1, protocol=Protocol.S7COMMPLUS)
95+
96+
Concurrent async reads
97+
----------------------
98+
99+
An internal ``asyncio.Lock`` serialises each send/receive cycle so that
100+
multiple coroutines can safely share a single connection:
101+
102+
.. code-block:: python
103+
104+
results = await asyncio.gather(
105+
client.db_read(1, 0, 4),
106+
client.db_read(1, 10, 4),
107+
)
108+
109+
----
110+
111+
s7.Client
112+
---------
113+
114+
.. automodule:: s7.client
115+
:members:
116+
117+
s7.AsyncClient
118+
--------------
119+
120+
.. automodule:: s7.async_client
121+
:members:
122+
123+
snap7.Client (legacy)
124+
---------------------
125+
126+
The ``snap7.Client`` is the legacy S7 protocol client. For new projects, use
127+
``s7.Client`` above instead.
9128

10129
.. automodule:: snap7.client
11130
:members:
131+
132+
snap7.AsyncClient (legacy)
133+
--------------------------
134+
135+
.. automodule:: snap7.async_client
136+
:members:
137+
:exclude-members: AsyncISOTCPConnection

‎doc/API/partner.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,32 @@
11
Partner
22
=======
33

4+
The ``Partner`` class implements S7 peer-to-peer communication for
5+
bidirectional data exchange using BSend/BRecv. Both partners have equal
6+
rights and can send data asynchronously.
7+
8+
.. code:: python
9+
10+
from s7 import Partner
11+
12+
partner = Partner(active=True)
13+
partner.port = 102
14+
partner.r_id = 0x00000001
15+
partner.start_to("0.0.0.0", "192.168.1.10", 0x1300, 0x1301)
16+
partner.set_send_data(b"Hello")
17+
partner.b_send()
18+
partner.stop()
19+
20+
----
21+
22+
s7.Partner
23+
----------
24+
25+
.. automodule:: s7.partner
26+
:members:
27+
28+
snap7.Partner (legacy)
29+
----------------------
30+
431
.. automodule:: snap7.partner
532
:members:

‎doc/API/s7commplus.rst‎

Lines changed: 0 additions & 103 deletions
This file was deleted.

‎doc/connecting.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ when needed. You can also force a specific protocol:
9797
# Force S7CommPlus (raises on failure)
9898
client.connect("192.168.1.10", 0, 1, protocol=Protocol.S7COMMPLUS)
9999
100-
See :doc:`API/s7commplus` for details on TLS and password authentication.
100+
See :doc:`API/client` for details on TLS and password authentication.
101101

102102
S7-200 / Logo (TSAP Connection)
103103
--------------------------------

‎doc/index.rst‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,14 +39,17 @@ Welcome to python-snap7's documentation!
3939
:maxdepth: 2
4040
:caption: API Reference
4141

42-
API/s7commplus
4342
API/client
44-
API/async_client
4543
API/server
4644
API/partner
4745
API/logo
48-
API/type
4946
API/util
47+
API/type
48+
49+
.. toctree::
50+
:maxdepth: 2
51+
:caption: Internals
52+
5053
API/connection
5154
API/s7protocol
5255
API/datatypes

0 commit comments

Comments
 (0)