Enforce keyword only parameters. (#2448)

API_changes.rst

@@ -7,6 +7,7 @@ API changes 3.8.0
 - ModbusSlaveContext, remove zero_mode parameter.
 - Remove skip_encode parameter.
 - rename ModbusExceptions enums to legal constants.
+- enforce client keyword only parameters (positional not allowed).
 
 
 API changes 3.7.0

doc/source/roadmap.rst

@@ -21,8 +21,8 @@ The following bullet points are what the maintainers focus on:
     - on dev:
         - skip_encode, zero_mode parameters removed
         - Simplify PDU bit classes
-    - Simplify PDU classes
-    - Simplify transaction manager (central control point)
+        - Simplify PDU classes
+        - Simplify transaction manager (central control point)
     - Remove ModbusControlBlock
     - new transaction handling
     - transaction 100% coverage

examples/client_async.py

@@ -125,9 +125,9 @@ async def run_async_client(client, modbus_calls=None):
 
 async def run_a_few_calls(client):
     """Test connection works."""
-    rr = await client.read_coils(32, 1, slave=1)
+    rr = await client.read_coils(32, count=1, slave=1)
     assert len(rr.bits) == 8
-    rr = await client.read_holding_registers(4, 2, slave=1)
+    rr = await client.read_holding_registers(4, count=2, slave=1)
     assert rr.registers[0] == 17
     assert rr.registers[1] == 17
 

examples/client_async_calls.py

@@ -59,7 +59,7 @@
 async def async_template_call(client):
     """Show complete modbus call, async version."""
     try:
-        rr = await client.read_coils(1, 1, slave=SLAVE)
+        rr = await client.read_coils(1, count=1, slave=SLAVE)
     except ModbusException as exc:
         txt = f"ERROR: exception in pymodbus {exc}"
         _logger.error(txt)
@@ -80,30 +80,30 @@ async def async_template_call(client):
 async def async_handle_coils(client):
     """Read/Write coils."""
     _logger.info("### Reading Coil different number of bits (return 8 bits multiples)")
-    rr = await client.read_coils(1, 1, slave=SLAVE)
+    rr = await client.read_coils(1, count=1, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert len(rr.bits) == 8
 
-    rr = await client.read_coils(1, 5, slave=SLAVE)
+    rr = await client.read_coils(1, count=5, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert len(rr.bits) == 8
 
-    rr = await client.read_coils(1, 12, slave=SLAVE)
+    rr = await client.read_coils(1, count=12, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert len(rr.bits) == 16
 
-    rr = await client.read_coils(1, 17, slave=SLAVE)
+    rr = await client.read_coils(1, count=17, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert len(rr.bits) == 24
 
     _logger.info("### Write false/true to coils and read to verify")
     await client.write_coil(0, True, slave=SLAVE)
-    rr = await client.read_coils(0, 1, slave=SLAVE)
+    rr = await client.read_coils(0, count=1, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.bits[0]  # test the expected value
 
     await client.write_coils(1, [True] * 21, slave=SLAVE)
-    rr = await client.read_coils(1, 21, slave=SLAVE)
+    rr = await client.read_coils(1, count=21, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     resp = [True] * 21
     # If the returned output quantity is not a multiple of eight,
@@ -114,15 +114,15 @@ async def async_handle_coils(client):
 
     _logger.info("### Write False to address 1-8 coils")
     await client.write_coils(1, [False] * 8, slave=SLAVE)
-    rr = await client.read_coils(1, 8, slave=SLAVE)
+    rr = await client.read_coils(1, count=8, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.bits == [False] * 8  # test the expected value
 
 
 async def async_handle_discrete_input(client):
     """Read discrete inputs."""
     _logger.info("### Reading discrete input, Read address:0-7")
-    rr = await client.read_discrete_inputs(0, 8, slave=SLAVE)
+    rr = await client.read_discrete_inputs(0, count=8, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert len(rr.bits) == 8
 
@@ -131,17 +131,17 @@ async def async_handle_holding_registers(client):
     """Read/write holding registers."""
     _logger.info("### write holding register and read holding registers")
     await client.write_register(1, 10, slave=SLAVE)
-    rr = await client.read_holding_registers(1, 1, slave=SLAVE)
+    rr = await client.read_holding_registers(1, count=1, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.registers[0] == 10
 
     await client.write_registers(1, [10] * 8, slave=SLAVE)
-    rr = await client.read_holding_registers(1, 8, slave=SLAVE)
+    rr = await client.read_holding_registers(1, count=8, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.registers == [10] * 8
 
     await client.write_registers(1, [10], slave=SLAVE)
-    rr = await client.read_holding_registers(1, 1, slave=SLAVE)
+    rr = await client.read_holding_registers(1, count=1, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.registers == [10]
 
@@ -153,29 +153,29 @@ async def async_handle_holding_registers(client):
         "values": [256, 128, 100, 50, 25, 10, 5, 1],
     }
     await client.readwrite_registers(slave=SLAVE, **arguments)
-    rr = await client.read_holding_registers(1, 8, slave=SLAVE)
+    rr = await client.read_holding_registers(1, count=8, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.registers == arguments["values"]
 
 async def async_write_registers_mypy(client):
     """Read/write holding registers."""
     regs1: list[int] = [10] * 8
     await client.write_registers(1, regs1, slave=SLAVE)
-    rr = await client.read_holding_registers(1, len(regs1), slave=SLAVE)
+    rr = await client.read_holding_registers(1, count=len(regs1), slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.registers == regs1
 
     regs2: list[bytes] = [b'\x01\x02', b'\x03\x04']
     await client.write_registers(1, regs2, slave=SLAVE)
-    rr = await client.read_holding_registers(1, len(regs2), slave=SLAVE)
+    rr = await client.read_holding_registers(1, count=len(regs2), slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.registers == regs2
 
 
 async def async_handle_input_registers(client):
     """Read input registers."""
     _logger.info("### read input registers")
-    rr = await client.read_input_registers(1, 8, slave=SLAVE)
+    rr = await client.read_input_registers(1, count=8, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert len(rr.registers) == 8
 

examples/client_calls.py

@@ -59,7 +59,7 @@
 def template_call(client):
     """Show complete modbus call, sync version."""
     try:
-        rr = client.read_coils(32, 1, slave=SLAVE)
+        rr = client.read_coils(32, count=1, slave=SLAVE)
     except client_sync.ModbusException as exc:
         txt = f"ERROR: exception in pymodbus {exc}"
         _logger.error(txt)
@@ -80,30 +80,30 @@ def template_call(client):
 def handle_coils(client):
     """Read/Write coils."""
     _logger.info("### Reading Coil different number of bits (return 8 bits multiples)")
-    rr = client.read_coils(1, 1, slave=SLAVE)
+    rr = client.read_coils(1, count=1, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert len(rr.bits) == 8
 
-    rr = client.read_coils(1, 5, slave=SLAVE)
+    rr = client.read_coils(1, count=5, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert len(rr.bits) == 8
 
-    rr = client.read_coils(1, 12, slave=SLAVE)
+    rr = client.read_coils(1, count=12, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert len(rr.bits) == 16
 
-    rr = client.read_coils(1, 17, slave=SLAVE)
+    rr = client.read_coils(1, count=17, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert len(rr.bits) == 24
 
     _logger.info("### Write false/true to coils and read to verify")
     client.write_coil(0, True, slave=SLAVE)
-    rr = client.read_coils(0, 1, slave=SLAVE)
+    rr = client.read_coils(0, count=1, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.bits[0]  # test the expected value
 
     client.write_coils(1, [True] * 21, slave=SLAVE)
-    rr = client.read_coils(1, 21, slave=SLAVE)
+    rr = client.read_coils(1, count=21, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     resp = [True] * 21
     # If the returned output quantity is not a multiple of eight,
@@ -114,15 +114,15 @@ def handle_coils(client):
 
     _logger.info("### Write False to address 1-8 coils")
     client.write_coils(1, [False] * 8, slave=SLAVE)
-    rr = client.read_coils(1, 8, slave=SLAVE)
+    rr = client.read_coils(1, count=8, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.bits == [False] * 8  # test the expected value
 
 
 def handle_discrete_input(client):
     """Read discrete inputs."""
     _logger.info("### Reading discrete input, Read address:0-7")
-    rr = client.read_discrete_inputs(0, 8, slave=SLAVE)
+    rr = client.read_discrete_inputs(0, count=8, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert len(rr.bits) == 8
 
@@ -131,12 +131,12 @@ def handle_holding_registers(client):
     """Read/write holding registers."""
     _logger.info("### write holding register and read holding registers")
     client.write_register(1, 10, slave=SLAVE)
-    rr = client.read_holding_registers(1, 1, slave=SLAVE)
+    rr = client.read_holding_registers(1, count=1, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.registers[0] == 10
 
     client.write_registers(1, [10] * 8, slave=SLAVE)
-    rr = client.read_holding_registers(1, 8, slave=SLAVE)
+    rr = client.read_holding_registers(1, count=8, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.registers == [10] * 8
 
@@ -148,15 +148,15 @@ def handle_holding_registers(client):
         "values": [256, 128, 100, 50, 25, 10, 5, 1],
     }
     client.readwrite_registers(slave=SLAVE, **arguments)
-    rr = client.read_holding_registers(1, 8, slave=SLAVE)
+    rr = client.read_holding_registers(1, count=8, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert rr.registers == arguments["values"]
 
 
 def handle_input_registers(client):
     """Read input registers."""
     _logger.info("### read input registers")
-    rr = client.read_input_registers(1, 8, slave=SLAVE)
+    rr = client.read_input_registers(1, count=8, slave=SLAVE)
     assert not rr.isError()  # test that call was OK
     assert len(rr.registers) == 8
 

examples/client_payload.py

@@ -97,7 +97,7 @@ async def run_payload_calls(client):
         # ----------------------------------------------------------------------- #
         print("Reading Registers:")
         count = len(payload)
-        rr = await client.read_holding_registers(address, count, slave=slave)
+        rr = await client.read_holding_registers(address, count=count, slave=slave)
         assert not rr.isError()
         print(rr.registers)
         print("\n")

examples/client_performance.py

@@ -37,7 +37,7 @@ def run_sync_client_test():
 
     start_time = time.time()
     for _i in range(LOOP_COUNT):
-        rr = client.read_input_registers(1, REGISTER_COUNT, slave=1)
+        rr = client.read_input_registers(1, count=REGISTER_COUNT, slave=1)
         if rr.isError():
             print(f"Received Modbus library error({rr})")
             break
@@ -64,7 +64,7 @@ async def run_async_client_test():
 
     start_time = time.time()
     for _i in range(LOOP_COUNT):
-        rr = await client.read_input_registers(1, REGISTER_COUNT, slave=1)
+        rr = await client.read_input_registers(1, count=REGISTER_COUNT, slave=1)
         if rr.isError():
             print(f"Received Modbus library error({rr})")
             break

examples/client_sync.py

@@ -128,9 +128,9 @@ def run_sync_client(client, modbus_calls=None):
 def run_a_few_calls(client):
     """Test connection works."""
     try:
-        rr = client.read_coils(32, 1, slave=1)
+        rr = client.read_coils(32, count=1, slave=1)
         assert len(rr.bits) == 8
-        rr = client.read_holding_registers(4, 2, slave=1)
+        rr = client.read_holding_registers(4, count=2, slave=1)
         assert rr.registers[0] == 17
         assert rr.registers[1] == 17
     except ModbusException as exc:

examples/simple_async_client.py

@@ -69,7 +69,7 @@ async def run_async_simple_client(comm, host, port, framer=FramerType.SOCKET):
     print("get and verify data")
     try:
         # See all calls in client_calls.py
-        rr = await client.read_coils(1, 1, slave=1)
+        rr = await client.read_coils(1, count=1, slave=1)
     except ModbusException as exc:
         print(f"Received ModbusException({exc}) from library")
         client.close()

examples/simple_sync_client.py

@@ -68,7 +68,7 @@ def run_sync_simple_client(comm, host, port, framer=FramerType.SOCKET):
 
     print("get and verify data")
     try:
-        rr = client.read_coils(1, 1, slave=1)
+        rr = client.read_coils(1, count=1, slave=1)
     except ModbusException as exc:
         print(f"Received ModbusException({exc}) from library")
         client.close()

examples/simulator.py

@@ -23,7 +23,7 @@ async def read_registers(
     client, addr, count, is_int, curval=None, minval=None, maxval=None
 ):
     """Run modbus call."""
-    rr = await client.read_holding_registers(addr, count, slave=1)
+    rr = await client.read_holding_registers(addr, count=count, slave=1)
     assert not rr.isError()
     if count == 1:
         value = rr.registers[0]