tmodbus 0.1.0__tar.gz

tmodbus-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.python-version
+
+# coverage
+.coverage
+
+# ruff
+.ruff_cache/
+
+# pytest
+.pytest_cache/
+
+# docs
+docs/_build/
+
+# version file
+src/tmodbus/_version.py

tmodbus-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: tmodbus
+Version: 0.1.0
+Summary: A modern, strongly typed Modbus client library.
+Author: wlcrs
+Keywords: modbus,modbus-rtu,modbus-tcp
+Requires-Python: >=3.12
+Provides-Extra: async-rtu
+Requires-Dist: pyserial-asyncio-fast>=0.16; extra == 'async-rtu'
+Provides-Extra: smart
+Requires-Dist: tenacity>=9.1.2; extra == 'smart'
+Description-Content-Type: text/markdown
+
+# tModbus
+[![Release](https://img.shields.io/github/v/release/wlcrs/tmodbus.svg)](https://github.com/wlcrs/tmodbus/releases)
+[![Python Versions](https://img.shields.io/pypi/pyversions/tmodbus)](https://pypi.org/p/tmodbus/)
+[![Testing](https://github.com/wlcrs/tmodbus/actions/workflows/tests.yml/badge.svg)](https://github.com/wlcrs/tmodbus/actions/workflows/tests.yml)
+
+## About
+
+A modern Python Modbus library that is fully **t**yped and well-**t**ested.
+
+Modbus is based on the [_master/slave_](https://en.wikipedia.org/wiki/Master%E2%80%93slave_(technology)) communication pattern.
+We choose to use the terminology _client_ and _server_ instead, as it is more clear.
+
+## Features
+
+- Pure Python library with minimal dependencies
+- Fully **t**yped
+- Full **t**est coverage
+- Support for both Modbus TCP and RTU clients
+- Support for TCP over SSL connections
+- Auto reconnect and retry functionality (which can be enabled optionally)
+- Extensible with custom Modbus functions and exception codes
+- Open source (BSD)
+
+## Supported function codes
+
+* Read coils (`0x01`)
+* Read discrete inputs (`0x02`)
+* Read holding registers (`0x03`)
+* Read input registers (`0x04`)
+* Write single coil (`0x05`)
+* Write single register (`0x06`)
+* Write multiple coils (`0x0f`)
+* Write multiple registers (`0x10`)
+* Read device identification (`0x2B / 0x0E`)
+
+## Examples
+
+A simple example of an Async TCP client:
+
+```python
+import asyncio
+
+from tmodbus import create_async_tcp_client
+
+
+async def main() -> None:
+    """Show example of reading a Modbus register."""
+    async with create_async_tcp_client("127.0.0.1", 502, unit_id=1) as client:
+        response = await client.read_holding_registers(start_address=100, quantity=2)
+        print("Contents of holding registers 100 and 101: ", response)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
+Various examples for Modbus RTU and TCP can be found in the [examples](./examples) folder.
+
+## Dependencies
+
+**async-rtu**
+
+This library uses [pyserial-asyncio-fast](https://pypi.org/project/pyserial-asyncio-fast/) to
+access the serial port when using async RTU.
+
+Use `pip install tmodbus[async-rtu]` to install.
+
+**smart**
+
+This library uses [tenacity](https://github.com/jd/tenacity) to implement the reconnect and retry-logic,
+giving you access to a powerful API to customize the retry behavior of this library.
+
+Use `pip install tmodbus[smart]` to install.
+
+## Changelog & releases
+
+This repository keeps a change log using [GitHub's releases](https://github.com/wlcrs/tmodbus/releases)
+functionality. The format of the log is based on
+[Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
+
+Releases are based on [Semantic Versioning](http://semver.org/spec/v2.0.0.html), and use the format
+of `MAJOR.MINOR.PATCH`. In a nutshell, the version will be incremented
+based on the following:
+
+- `MAJOR`: Incompatible or major changes.
+- `MINOR`: Backwards-compatible new features and enhancements.
+- `PATCH`: Backwards-compatible bugfixes and package updates.
+
+## Contributing
+
+This is an active open-source project. We are always open to people who want to
+use the code or contribute to it.
+
+We've set up a separate document for our
+[contribution guidelines](.github/CONTRIBUTING.md).
+
+Thank you for being involved! :heart_eyes:
+
+### Setting up a development environment
+
+This Python project is fully managed using the [uv] dependency manager.
+
+You need at least:
+
+- Python 3.12+
+- [uv][uv-install]
+
+To install all packages, including all development requirements:
+
+```bash
+uv sync  --all-extras --dev
+```
+
+As this repository uses the [pre-commit][pre-commit] framework, all changes
+are linted and tested with each commit. You can run all checks and tests
+manually, using the following command:
+
+```bash
+uv run pre-commit run --all-files
+```
+
+To run just the Python tests:
+
+```bash
+uv run pytest
+```
+
+
+## Protocol-Specification
+
+- [Modbus Application Protocol Specification v1.1b3 (PDF)](http://modbus.org/docs/Modbus_Application_Protocol_V1_1b3.pdf)
+- [Modbus over serial line specification and implementation guide v1.02 (PDF)](http://modbus.org/docs/Modbus_over_serial_line_V1_02.pdf)
+- [Modbus Messaging on TCP/IP Implementation Guide v1.0b (PDF)](http://modbus.org/docs/Modbus_Messaging_Implementation_Guide_V1_0b.pdf)
+
+
+[uv-install]: https://docs.astral.sh/uv/getting-started/installation/
+[uv]: https://docs.astral.sh/uv/
+[pre-commit]: https://pre-commit.com/

tmodbus-0.1.0/README.md

@@ -0,0 +1,139 @@
+# tModbus
+[![Release](https://img.shields.io/github/v/release/wlcrs/tmodbus.svg)](https://github.com/wlcrs/tmodbus/releases)
+[![Python Versions](https://img.shields.io/pypi/pyversions/tmodbus)](https://pypi.org/p/tmodbus/)
+[![Testing](https://github.com/wlcrs/tmodbus/actions/workflows/tests.yml/badge.svg)](https://github.com/wlcrs/tmodbus/actions/workflows/tests.yml)
+
+## About
+
+A modern Python Modbus library that is fully **t**yped and well-**t**ested.
+
+Modbus is based on the [_master/slave_](https://en.wikipedia.org/wiki/Master%E2%80%93slave_(technology)) communication pattern.
+We choose to use the terminology _client_ and _server_ instead, as it is more clear.
+
+## Features
+
+- Pure Python library with minimal dependencies
+- Fully **t**yped
+- Full **t**est coverage
+- Support for both Modbus TCP and RTU clients
+- Support for TCP over SSL connections
+- Auto reconnect and retry functionality (which can be enabled optionally)
+- Extensible with custom Modbus functions and exception codes
+- Open source (BSD)
+
+## Supported function codes
+
+* Read coils (`0x01`)
+* Read discrete inputs (`0x02`)
+* Read holding registers (`0x03`)
+* Read input registers (`0x04`)
+* Write single coil (`0x05`)
+* Write single register (`0x06`)
+* Write multiple coils (`0x0f`)
+* Write multiple registers (`0x10`)
+* Read device identification (`0x2B / 0x0E`)
+
+## Examples
+
+A simple example of an Async TCP client:
+
+```python
+import asyncio
+
+from tmodbus import create_async_tcp_client
+
+
+async def main() -> None:
+    """Show example of reading a Modbus register."""
+    async with create_async_tcp_client("127.0.0.1", 502, unit_id=1) as client:
+        response = await client.read_holding_registers(start_address=100, quantity=2)
+        print("Contents of holding registers 100 and 101: ", response)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
+Various examples for Modbus RTU and TCP can be found in the [examples](./examples) folder.
+
+## Dependencies
+
+**async-rtu**
+
+This library uses [pyserial-asyncio-fast](https://pypi.org/project/pyserial-asyncio-fast/) to
+access the serial port when using async RTU.
+
+Use `pip install tmodbus[async-rtu]` to install.
+
+**smart**
+
+This library uses [tenacity](https://github.com/jd/tenacity) to implement the reconnect and retry-logic,
+giving you access to a powerful API to customize the retry behavior of this library.
+
+Use `pip install tmodbus[smart]` to install.
+
+## Changelog & releases
+
+This repository keeps a change log using [GitHub's releases](https://github.com/wlcrs/tmodbus/releases)
+functionality. The format of the log is based on
+[Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
+
+Releases are based on [Semantic Versioning](http://semver.org/spec/v2.0.0.html), and use the format
+of `MAJOR.MINOR.PATCH`. In a nutshell, the version will be incremented
+based on the following:
+
+- `MAJOR`: Incompatible or major changes.
+- `MINOR`: Backwards-compatible new features and enhancements.
+- `PATCH`: Backwards-compatible bugfixes and package updates.
+
+## Contributing
+
+This is an active open-source project. We are always open to people who want to
+use the code or contribute to it.
+
+We've set up a separate document for our
+[contribution guidelines](.github/CONTRIBUTING.md).
+
+Thank you for being involved! :heart_eyes:
+
+### Setting up a development environment
+
+This Python project is fully managed using the [uv] dependency manager.
+
+You need at least:
+
+- Python 3.12+
+- [uv][uv-install]
+
+To install all packages, including all development requirements:
+
+```bash
+uv sync  --all-extras --dev
+```
+
+As this repository uses the [pre-commit][pre-commit] framework, all changes
+are linted and tested with each commit. You can run all checks and tests
+manually, using the following command:
+
+```bash
+uv run pre-commit run --all-files
+```
+
+To run just the Python tests:
+
+```bash
+uv run pytest
+```
+
+
+## Protocol-Specification
+
+- [Modbus Application Protocol Specification v1.1b3 (PDF)](http://modbus.org/docs/Modbus_Application_Protocol_V1_1b3.pdf)
+- [Modbus over serial line specification and implementation guide v1.02 (PDF)](http://modbus.org/docs/Modbus_over_serial_line_V1_02.pdf)
+- [Modbus Messaging on TCP/IP Implementation Guide v1.0b (PDF)](http://modbus.org/docs/Modbus_Messaging_Implementation_Guide_V1_0b.pdf)
+
+
+[uv-install]: https://docs.astral.sh/uv/getting-started/installation/
+[uv]: https://docs.astral.sh/uv/
+[pre-commit]: https://pre-commit.com/

tmodbus-0.1.0/examples/async_rtu_client.py

@@ -0,0 +1,49 @@
+"""Example of an asynchronous RTU Modbus client using tmodbus."""
+
+import asyncio
+
+from tmodbus import create_async_rtu_client
+from tmodbus.exceptions import InvalidResponseError, ModbusConnectionError, ModbusResponseError
+
+
+async def example_rtu_client() -> None:
+    """Asynchronous RTU Modbus client example."""
+    # Replace with your Modbus server's IP and por
+    port = "/dev/ttyUSB0"
+    baudrate = 9600  # Adjust baudrate as needed
+
+    unit_id = 1  # Modbus unit ID of the target device
+
+    # The create_async_rtu_client function returns an instance of AsyncModbusClient
+    client = create_async_rtu_client(port, baudrate=baudrate, unit_id=unit_id)
+
+    try:
+        await client.connect()
+        # Read 2 holding registers starting at address 100
+        coils_response = await client.read_holding_registers(start_address=100, quantity=2)
+
+        print("Contents of holding registers 100 and 101: ", coils_response)
+
+        # Write value 123 to holding register at address 1
+        await client.write_single_register(address=1, value=123)
+
+        # Write values [10, 20, 30] to holding registers starting at address 10
+        await client.write_multiple_registers(start_address=10, values=[10, 20, 30])
+
+    except ModbusResponseError as e:
+        print(f"The server responded with error code {e.error_code:#04x} for function {e.function_code:#04x}")
+    except InvalidResponseError as e:
+        print(f"Received invalid response: {e}")
+    except ModbusConnectionError as e:
+        print(f"A connection error occurred: {e}")
+    finally:
+        await client.disconnect()
+
+    # Alternatively, you can use the client as an async context manager
+    # which automatically handles connection and disconnection
+    async with create_async_rtu_client(port, baudrate=baudrate, unit_id=unit_id) as client2:
+        print("Status of coils 0-7: ", await client2.read_coils(start_address=0, quantity=8))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_rtu_client())

tmodbus-0.1.0/examples/async_tcp_client.py

@@ -0,0 +1,58 @@
+"""Example of an asynchronous TCP Modbus client using tmodbus."""
+
+import asyncio
+
+from tmodbus import create_async_tcp_client
+from tmodbus.exceptions import InvalidResponseError, ModbusConnectionError, ModbusResponseError
+
+
+async def example_tcp_client() -> None:
+    """Asynchronous TCP Modbus client example."""
+    # Replace with your Modbus server's IP and port
+    host = "127.0.0.1"
+    port = 502
+
+    unit_id = 1  # Modbus unit ID of the target device
+
+    # The create_async_tcp_client function returns an instance of AsyncModbusClient
+    client = create_async_tcp_client(host, port, unit_id=unit_id)
+
+    try:
+        await client.connect()
+        # Read 2 holding registers starting at address 100
+        response = await client.read_holding_registers(start_address=100, quantity=2)
+
+        print("Contents of holding registers 100 and 101: ", response)
+
+        client_for_unit_id_2 = client.for_unit_id(2)
+        response2 = await client_for_unit_id_2.read_holding_registers(start_address=100, quantity=2)
+        print("Contents of holding registers 100 and 101 for unit ID 2: ", response2)
+
+        response6 = await client.for_unit_id(6).read_float(start_address=1)
+        print("Float value at address 1 for unit ID 6: ", response6)
+
+        # Write value 123 to holding register at address 1
+        await client.write_single_register(address=1, value=123)
+        print("Wrote 123 to holding register at address 1")
+
+        # Write values [10, 20, 30] to holding registers starting at address 10
+        await client.write_multiple_registers(start_address=10, values=[10, 20, 30])
+        print("Wrote [10, 20, 30] to holding registers starting at address 10")
+
+    except ModbusResponseError as e:
+        print(f"The server responded with error code {e.error_code:#04x} for function {e.function_code:#04x}")
+    except InvalidResponseError as e:
+        print(f"Received invalid response: {e}")
+    except ModbusConnectionError as e:
+        print(f"A connection error occurred: {e}")
+    finally:
+        await client.disconnect()
+
+    # Alternatively, you can use the client as an async context manager
+    # which automatically handles connection and disconnection
+    async with create_async_tcp_client(host, port, unit_id=unit_id) as client2:
+        print("Status of coils 0-7: ", await client2.read_coils(start_address=0, quantity=8))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_tcp_client())

tmodbus-0.1.0/examples/async_tcp_tls_client.py

@@ -0,0 +1,60 @@
+"""Example of an asynchronous TCP Modbus client over an SSL connection using tmodbus."""
+
+import asyncio
+import ssl
+
+from tmodbus import create_async_tcp_client
+from tmodbus.exceptions import InvalidResponseError, ModbusConnectionError, ModbusResponseError
+
+
+async def example_tcp_client() -> None:
+    """Asynchronous TCP Modbus client example."""
+    # Replace with your Modbus server's IP and port
+    host = "127.0.0.1"
+    port = 502
+
+    unit_id = 1  # Modbus unit ID of the target device
+
+    # You can pass any additional parameters supported by `asyncio.open_connection`
+    # For example, to use an SSL context, you can set `ssl=True` or provide a custom SSLContext
+
+    # The create_async_tcp_client function returns an instance of AsyncModbusClient
+    client = create_async_tcp_client(host, port, unit_id=unit_id, ssl=True)
+
+    try:
+        await client.connect()
+        # Read 2 holding registers starting at address 100
+        coils_response = await client.read_holding_registers(start_address=100, quantity=2)
+
+        print("Contents of holding registers 100 and 101: ", coils_response)
+
+        # Write value 123 to holding register at address 1
+        await client.write_single_register(address=1, value=123)
+
+        # Write values [10, 20, 30] to holding registers starting at address 10
+        await client.write_multiple_registers(start_address=10, values=[10, 20, 30])
+
+    except ModbusResponseError as e:
+        print(f"The server responded with error code {e.error_code:#04x} for function {e.function_code:#04x}")
+    except InvalidResponseError as e:
+        print(f"Received invalid response: {e}")
+    except ModbusConnectionError as e:
+        print(f"A connection error occurred: {e}")
+    finally:
+        await client.disconnect()
+
+    # Alternatively, you can use the client as an async context manager
+    # which automatically handles connection and disconnection.
+    # We also demonstrate passing of a custom SSL context here.
+
+    ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    ssl_context.load_default_certs(purpose=ssl.Purpose.SERVER_AUTH)
+    ssl_context.check_hostname = True
+    ssl_context.verify_mode = ssl.CERT_REQUIRED
+
+    async with create_async_tcp_client(host, port, unit_id=unit_id, ssl=ssl_context) as client2:
+        print("Status of coils 0-7: ", await client2.read_coils(start_address=0, quantity=8))
+
+
+if __name__ == "__main__":
+    asyncio.run(example_tcp_client())

tmodbus-0.1.0/examples/ruff.toml

@@ -0,0 +1,7 @@
+# This extend our general Ruff rules
+extend = "../pyproject.toml"
+
+lint.extend-ignore = [
+  "INP001", # not a package
+  "T201", # use print statements in examples
+]

tmodbus-0.1.0/pyproject.toml

@@ -0,0 +1,125 @@
+[project]
+name = "tmodbus"
+authors= [{name="wlcrs"}]
+description = "A modern, strongly typed Modbus client library."
+readme = "README.md"
+requires-python = ">=3.12"
+keywords = ["modbus", "modbus-tcp", "modbus-rtu"]
+dynamic = ["version"]
+
+
+[project.optional-dependencies]
+
+async-rtu = [
+    "pyserial-asyncio-fast>=0.16",
+]
+
+smart = [
+    "tenacity>=9.1.2",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+only-packages = true
+
+[tool.hatch.build.targets.sdist]
+only-include = ["examples", "src", "tests"]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/tmodbus/_version.py"
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+ignore = [
+  "ANN401", # Opinioated warning on disallowing dynamically typed expressions
+  "D203", # Conflicts with other rules
+  "D213", # Conflicts with other rules
+  "PLR2004", # Just annoying, not really useful
+  "S101", # allow asserts
+
+  # Conflicts with the Ruff formatter
+  "COM812",
+  "ISC001",
+
+]
+select = ["ALL"]
+
+[tool.mypy]
+# Specify the target platform details in config, so your developers are
+# free to run mypy on Windows, Linux, or macOS and get consistent
+# results.
+platform = "linux"
+python_version = "3.12"
+
+# show error messages from unrelated files
+follow_imports = "normal"
+
+# suppress errors about unsatisfied imports
+ignore_missing_imports = true
+
+# be strict
+check_untyped_defs = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_decorators = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+no_implicit_reexport = true
+strict_optional = true
+warn_incomplete_stub = true
+warn_no_return = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unused_configs = true
+warn_unused_ignores = true
+
+
+[tool.pytest.ini_options]
+addopts = "--cov"
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+plugins = ["covdefaults"]
+source = ["tmodbus"]
+omit = [
+  "src/tmodbus/_version.py", # automatically generated by hatch-vcs
+]
+[tool.coverage.report]
+show_missing = true
+fail_under = 100
+
+
+[tool.uv]
+prerelease = "allow"
+
+[dependency-groups]
+dev = [
+  "codespell==2.4.1",
+  "covdefaults==2.3.0",
+  "coverage[toml]==7.10.7",
+  "mypy==1.18.2",
+  "pre-commit==4.3.0",
+  "pre-commit-hooks==6.0.0",
+  "pytest==8.4.2",
+  "pytest-asyncio==1.2.0",
+  "pytest-cov==7.0.0",
+  "ruff==0.13.3",
+  "yamllint==1.37.1",
+]
+
+docs = [
+  "sphinx>=8.2.3",
+  "sphinx-rtd-theme>=3.0.2",
+  "sphinx-autobuild",
+  "sphinxcontrib-mermaid",
+]