Skip to content

Clarify documentation on reconnect_delay #2769

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 10, 2025
Merged

Clarify documentation on reconnect_delay #2769

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
dbf9c12
Clarify documentation
wlcrs Sep 9, 2025
d8e4cd7
Add float to parameter documentation
wlcrs Sep 9, 2025
b37f070
remove explicit mention of float
wlcrs Sep 10, 2025
e2c33da
Add millisecond info.
janiversen Sep 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions pymodbus/client/serial.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,9 @@ class AsyncModbusSerialClient(ModbusBaseClient):
:param stopbits: Number of stop bits 1, 1.5, 2.
:param handle_local_echo: Discard local echo from dongle.
:param name: Set communication name, used in logging
:param reconnect_delay: Minimum delay in seconds.milliseconds before reconnecting.
:param reconnect_delay_max: Maximum delay in seconds.milliseconds before reconnecting.
:param timeout: Timeout for connecting and receiving data, in seconds.
:param reconnect_delay: Minimum delay before reconnecting, in seconds (float).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This do not give the information a user is looking for.

much better would be something like (fractions are milliseconds).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current wording and the one that you are proposing now are both incorrect: the part behind the comma is a fraction of a second.

If you interpret the current wording seconds.milliseconds literally, 5 milliseconds can be written as 0.5 and 25 milliseconds as 0.25 , which is of course incorrect.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that the current interpretation is not mathematically correct, but (float) does not add useful information.

10 times (fraction of a second) is milliseconds...but I am not trying to be precise, just give users a hint, that milliseconds can be used.

Your issue was a good example you thought it was only milliseconds even though you knew it was a float.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

, but (float) does not add useful information.

At my university, data types are one of the first concepts covered in the Python Programming 101 course. "float" is a concept that every Python programmer should be familiar with: it clearly tells the programmer that the value is a floating-point number, or to be mathematically precise: a real number.

10 times (fraction of a second) is millisecond

I don't understand what you mean. This sentence does not make any sense.

but I am not trying to be precise, just give users a hint, that milliseconds can be used.

they can use any fraction of a second, not only milliseconds. Your 'hint' is currently confusing at best.

Your issue was a good example you thought it was only milliseconds even though you knew it was a float.

That is not a fair example. I started using this feature in my own library when migrating to pymodbus 3.0.0 . The documentation then read:

https://github.com/pymodbus-dev/pymodbus/blob/d7834aca6d80cd93d2b97ce00e867e52ee64ff61/pymodbus/client/base.py#L34C5-L34C82

Your API_CHANGES.rst never mentioned that this unit had been changed!

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we in for a tug war, or do you want this PR merged.

1 second is 1000 milliseconds, so 3,125 is 3 seconds and 125 milliseconds or 3125 milliseconds if you prefer.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I want this wording merged. I don't think there is a better way to describe these parameters.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But as you pointed out, the type is float, so adding (float) does not give extra information. You could still describe the decimal part, which is milliseconds, I leave wording to you.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But as you pointed out, the type is float, so adding (float) does not give extra information.

I've removed the (float) again

You could still describe the decimal part, which is milliseconds, I leave wording to you.

I don't agree:

  • 0.5 is equal to 500 milliseconds
  • 0.06 is equal to 60 milliseconds
  • 0.007 is equal to 7 milliseconds
  • 0.0008 is equal to 0.8 milliseconds.

The decimal part is thus in no way, shape or form milliseconds.

Documentation must be as clear and concise as possible, "in seconds" is what I consider the clearest and least confusing way to state what you must define here. Adding any other unit to the explanation is confusing at best and wrong at worst.

You already had that exact wording in place for the regular timeout parameter. So this PR in effect now just brings the documentation of the 3 parameters in line with each other.

:param reconnect_delay_max: Maximum delay before reconnecting, in seconds (float).
:param timeout: Timeout for connecting and receiving data, in seconds (float).
:param retries: Max number of retries per request.
:param trace_packet: Called with bytestream received/to be sent
:param trace_pdu: Called with PDU received/to be sent
Expand Down Expand Up @@ -134,7 +134,7 @@ class ModbusSerialClient(ModbusBaseSyncClient):
:param name: Set communication name, used in logging
:param reconnect_delay: Not used in the sync client
:param reconnect_delay_max: Not used in the sync client
:param timeout: Timeout for connecting and receiving data, in seconds.
:param timeout: Timeout for connecting and receiving data, in seconds (float).
:param retries: Max number of retries per request.
:param trace_packet: Called with bytestream received/to be sent
:param trace_pdu: Called with PDU received/to be sent
Expand Down
8 changes: 4 additions & 4 deletions pymodbus/client/tcp.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,9 @@ class AsyncModbusTcpClient(ModbusBaseClient):
:param port: Port used for communication
:param name: Set communication name, used in logging
:param source_address: source address of client
:param reconnect_delay: Minimum delay in seconds.milliseconds before reconnecting.
:param reconnect_delay_max: Maximum delay in seconds.milliseconds before reconnecting.
:param timeout: Timeout for connecting and receiving data, in seconds.
:param reconnect_delay: Minimum delay before reconnecting, in seconds (float).
:param reconnect_delay_max: Maximum delay before reconnecting, in seconds (float).
:param timeout: Timeout for connecting and receiving data, in seconds (float).
:param retries: Max number of retries per request.
:param trace_packet: Called with bytestream received/to be sent
:param trace_pdu: Called with PDU received/to be sent
Expand Down Expand Up @@ -114,7 +114,7 @@ class ModbusTcpClient(ModbusBaseSyncClient):
:param source_address: source address of client
:param reconnect_delay: Not used in the sync client
:param reconnect_delay_max: Not used in the sync client
:param timeout: Timeout for connecting and receiving data, in seconds.
:param timeout: Timeout for connecting and receiving data, in seconds (float).
:param retries: Max number of retries per request.
:param trace_packet: Called with bytestream received/to be sent
:param trace_pdu: Called with PDU received/to be sent
Expand Down
8 changes: 4 additions & 4 deletions pymodbus/client/tls.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,9 @@ class AsyncModbusTlsClient(AsyncModbusTcpClient):
:param port: Port used for communication
:param name: Set communication name, used in logging
:param source_address: Source address of client
:param reconnect_delay: Minimum delay in seconds.milliseconds before reconnecting.
:param reconnect_delay_max: Maximum delay in seconds.milliseconds before reconnecting.
:param timeout: Timeout for connecting and receiving data, in seconds.
:param reconnect_delay: Minimum delay before reconnecting, in seconds (float).
:param reconnect_delay_max: Maximum delay before reconnecting, in seconds (float).
:param timeout: Timeout for connecting and receiving data, in seconds (float).
:param retries: Max number of retries per request.
:param trace_packet: Called with bytestream received/to be sent
:param trace_pdu: Called with PDU received/to be sent
Expand Down Expand Up @@ -134,7 +134,7 @@ class ModbusTlsClient(ModbusTcpClient):
:param source_address: Source address of client
:param reconnect_delay: Not used in the sync client
:param reconnect_delay_max: Not used in the sync client
:param timeout: Timeout for connecting and receiving data, in seconds.
:param timeout: Timeout for connecting and receiving data, in seconds (float).
:param retries: Max number of retries per request.
:param trace_packet: Called with bytestream received/to be sent
:param trace_pdu: Called with PDU received/to be sent
Expand Down
8 changes: 4 additions & 4 deletions pymodbus/client/udp.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,9 @@ class AsyncModbusUdpClient(ModbusBaseClient):
:param port: Port used for communication.
:param name: Set communication name, used in logging
:param source_address: source address of client,
:param reconnect_delay: Minimum delay in seconds.milliseconds before reconnecting.
:param reconnect_delay_max: Maximum delay in seconds.milliseconds before reconnecting.
:param timeout: Timeout for connecting and receiving data, in seconds.
:param reconnect_delay: Minimum delay before reconnecting, in seconds (float).
:param reconnect_delay_max: Maximum delay before reconnecting, in seconds (float).
:param timeout: Timeout for connecting and receiving data, in seconds (float).
:param retries: Max number of retries per request.
:param trace_packet: Called with bytestream received/to be sent
:param trace_pdu: Called with PDU received/to be sent
Expand Down Expand Up @@ -115,7 +115,7 @@ class ModbusUdpClient(ModbusBaseSyncClient):
:param source_address: source address of client,
:param reconnect_delay: Not used in the sync client
:param reconnect_delay_max: Not used in the sync client
:param timeout: Timeout for connecting and receiving data, in seconds.
:param timeout: Timeout for connecting and receiving data, in seconds (float).
:param retries: Max number of retries per request.
:param trace_packet: Called with bytestream received/to be sent
:param trace_pdu: Called with PDU received/to be sent
Expand Down