modbus-crc 2.0__py3-none-any.whl

modbus_crc/__init__.py

@@ -0,0 +1,55 @@
+"""
+CRC-16 calculation for the Modbus protocol.
+
+The checksum is CRC-16/MODBUS: polynomial 0xA001 (reflected 0x8005),
+initial value 0xFFFF, no final XOR, transmitted low byte first.
+
+Copyright (c) 2026 webtoucher
+Distributed under the BSD 3-Clause license. See LICENSE for more info.
+"""
+
+from typing import Union
+
+__all__ = ["crc16", "add_crc", "check_crc"]
+
+__version__ = "2.0"
+
+BytesLike = Union[bytes, bytearray, memoryview]
+
+
+def _build_crc_table(polynomial: int = 0xA001) -> tuple:
+    """Build the 256-entry lookup table for CRC-16/MODBUS."""
+    table = []
+    for index in range(256):
+        crc = index
+        for _ in range(8):
+            crc = (crc >> 1) ^ polynomial if crc & 1 else crc >> 1
+        table.append(crc)
+    return tuple(table)
+
+
+_CRC_TABLE = _build_crc_table()
+
+
+def _crc_register(data: BytesLike) -> int:
+    """Return the raw 16-bit CRC register value of data."""
+    crc = 0xFFFF
+    for byte in data:
+        crc = (crc >> 8) ^ _CRC_TABLE[(crc ^ byte) & 0xFF]
+    return crc
+
+
+def crc16(data: BytesLike) -> bytes:
+    """Calculate CRC-16/MODBUS of data, low byte first as on the wire."""
+    crc = _crc_register(data)
+    return bytes((crc & 0xFF, crc >> 8))
+
+
+def add_crc(package: BytesLike) -> bytes:
+    """Return package with CRC-16/MODBUS appended."""
+    return bytes(package) + crc16(package)
+
+
+def check_crc(package: BytesLike) -> bool:
+    """Return True if package carries a valid trailing CRC-16/MODBUS."""
+    return _crc_register(package) == 0

modbus_crc-2.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: modbus-crc
+Version: 2.0
+Summary: CRC-16 calculation for Modbus protocol
+Author-email: Alexey Kuznetsov <webtoucher@ya.ru>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/webtoucher/modbus-crc
+Project-URL: Repository, https://github.com/webtoucher/modbus-crc
+Project-URL: Issues, https://github.com/webtoucher/modbus-crc/issues
+Keywords: modbus,crc,crc16,checksum,serial,rtu
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# Modbus CRC-16
+
+![License](https://img.shields.io/badge/License-BSD%203--Clause-green)
+[![Downloads](https://img.shields.io/pypi/dm/modbus-crc.svg?color=orange)](https://pypi.python.org/pypi/modbus-crc)
+[![Latest Version](https://img.shields.io/pypi/v/modbus-crc.svg)](https://pypi.python.org/pypi/modbus-crc)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/modbus-crc.svg)](https://pypi.python.org/pypi/modbus-crc)
+[![tests](https://github.com/webtoucher/modbus-crc/actions/workflows/tests.yml/badge.svg)](https://github.com/webtoucher/modbus-crc/actions/workflows/tests.yml)
+
+CRC-16 calculation library for Modbus protocol. Tiny, dependency-free and fast: a single
+256-entry lookup table, no runtime dependencies, type hints included.
+
+## Algorithm
+
+The checksum is **CRC-16/MODBUS**:
+
+| Parameter             | Value                                     |
+|-----------------------|-------------------------------------------|
+| Width                 | 16 bits                                   |
+| Polynomial            | `0x8005` (reflected: `0xA001`)            |
+| Initial value         | `0xFFFF`                                  |
+| Reflect in / out      | yes / yes                                 |
+| Final XOR             | `0x0000`                                  |
+| Check (`"123456789"`)  | `0x4B37`, transmitted as `b'\x37\x4B'`   |
+| Byte order on wire    | low byte first                            |
+
+## Installation
+
+Install it with pip:
+
+```shell
+$ pip install modbus-crc
+```
+
+Or you can add it as dependency in requirements.txt file of your python application:
+
+```
+modbus-crc~=2.0
+```
+
+## Usage
+
+For signing byte package use `add_crc`:
+
+```python
+from modbus_crc import add_crc
+
+signed_package = add_crc(b'\x00\x12\x34\xAB\xCD\xEF')
+```
+
+Result is `b'\x00\x12\x34\xAB\xCD\xEF\xD2\xD4'`. For validation signed package use `check_crc`:
+
+```python
+from modbus_crc import check_crc
+
+if not check_crc(b'\x00\x12\x34\xAB\xCD\xEF\xD2\xD4'):
+    raise SomeException()
+```
+
+To get the checksum alone (low byte first, exactly as it is transmitted on the wire), use `crc16`:
+
+```python
+from modbus_crc import crc16
+
+crc16(b'\x01\x03\x00\x00\x00\x0A')  # b'\xC5\xCD'
+```
+
+Here is a real Modbus RTU request — "read 10 holding registers from slave 1":
+
+```python
+add_crc(b'\x01\x03\x00\x00\x00\x0A')  # b'\x01\x03\x00\x00\x00\x0A\xC5\xCD'
+```
+
+`check_crc` validates the whole signed frame, so it works with data read straight from
+the serial port, without splitting off the trailing bytes:
+
+```python
+check_crc(b'\x01\x03\x00\x00\x00\x0A\xC5\xCD')  # True
+check_crc(b'\x01\x03\x00\x00\x00\x0A\xC5\xCE')  # False
+```
+
+## API
+
+All three functions accept `bytes`, `bytearray` and `memoryview` (declared as `BytesLike`).
+
+| Function                        | Returns | Description                                                     |
+|---------------------------------|---------|-----------------------------------------------------------------|
+| `crc16(data)`                   | `bytes` | 2-byte checksum of `data`, low byte first                       |
+| `add_crc(package)`              | `bytes` | `package` with the checksum appended; input type is normalized  |
+| `check_crc(package)`            | `bool`  | `True` if `package` carries a valid trailing checksum           |
+
+Notes:
+
+- `add_crc` always returns `bytes`, even for `bytearray` and `memoryview` input.
+- `check_crc(b'')` is `False`: an empty package has no valid checksum.
+- Functions are pure: they keep no state between calls. The lookup table is built once,
+  at import time.
+
+## Compatibility
+
+- Python **3.9 and newer**, including free-threaded builds. Tested on 3.9 and 3.15 and
+  in CI on every version from 3.9 to 3.15.
+- No runtime dependencies.
+- Type hints are shipped with the package (`py.typed`, PEP 561), so mypy and pyright
+  see real signatures instead of `Any`.
+
+## Development
+
+```shell
+$ python -m venv .venv
+$ .venv\Scripts\activate          # Windows; on POSIX: source .venv/bin/activate
+$ pip install -e ".[dev]"          # installs the package and pytest
+$ python -m pytest
+```
+
+The test suite covers:
+
+- canonical Modbus frames with published checksums,
+- an independent bit-by-bit implementation written from the specification, used as an
+  oracle against the fast table-driven code (including random payloads up to 1 KiB),
+- edge cases: empty package, one-byte packages, `bytearray` / `memoryview` input,
+- detection of every single-byte corruption of a signed frame.
+
+Project layout:
+
+```
+modbus_crc/__init__.py    the whole library
+tests/test_modbus_crc.py  test suite
+pyproject.toml            metadata, build config and pytest settings
+.github/workflows/        CI: tests on Python 3.9-3.15, sdist/wheel build check
+```
+
+To build and verify a release:
+
+```shell
+$ pip install build twine
+$ python -m build
+$ python -m twine check dist/*
+```
+
+## Migrating from 1.x
+
+The public API is unchanged, so most projects need no code changes. What did change:
+
+- **Python 3.9+ is required.** Python 2 support and the legacy `setup.py` / `setup.cfg`
+  are gone; metadata now lives in `pyproject.toml` (PEP 621).
+- **`LOW_BYTES` and `HIGH_BYTES` were removed.** Those were two 256-byte tables with
+  inverted naming that leaked from the implementation. The lookup table is now generated
+  at import time and is private — use the documented functions instead.
+- **`add_crc` always returns `bytes`.** Previously `add_crc(bytearray(...))` returned a
+  `bytearray`; the result type is now stable regardless of the input type.
+- **`modbus_crc.__version__` is available** and is the single source of truth for the
+  package version.
+- **The package ships `py.typed`**, so type checkers no longer treat it as untyped.
+- **Faster and clearer internals:** one table instead of two, a single 16-bit register
+  instead of two byte variables, no `int()` call per byte (over 20% faster per KB on
+  CPython 3.11).
+
+## License
+
+Distributed under the BSD 3-Clause license. See [LICENSE.md](LICENSE.md) for details.

modbus_crc-2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+modbus_crc/__init__.py,sha256=1IrVei-2BOf9Fm9dcjp6LuscdbLr5hTITbCrXU9HrVQ,1492
+modbus_crc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modbus_crc-2.0.dist-info/licenses/LICENSE.md,sha256=Y4f1dDEJp690QgZ4S1ilY4Lbb-2re6hUdAeLA2sMXIg,1495
+modbus_crc-2.0.dist-info/METADATA,sha256=u3CfUcbJ4RGcN5MEwOYE7qR6b4FCYdhfyViCp_r22Cw,6968
+modbus_crc-2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+modbus_crc-2.0.dist-info/top_level.txt,sha256=AafRKooQK4rOOe2tq8tnLq-AIG3v0zqAiYuzoSvlY6c,11
+modbus_crc-2.0.dist-info/RECORD,,

modbus_crc-2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

modbus_crc-2.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,13 @@
+Copyright (c) 2023, Alexey Kuznetsov
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+* Neither the names of Alexey Kuznetsov or webtoucher nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

modbus_crc-2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+modbus_crc