Implement Hasher functionality #12 (#16)

* Implement Hasher functionality #12

* upgrade deps and bump version to 0.2.0

* debug gh pytest not running on arm

* disable index when installing pycrc32 package for testing

* debugging arm install

* debug log platform

* update CI workflow

* fix README

Author: code-inflation

.github/workflows/CI.yml

@@ -25,8 +25,8 @@ jobs:
       matrix:
         target: [x86_64, x86, aarch64, armv7, s390x, ppc64le]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
         with:
           python-version: '3.10'
       - name: Build wheels
@@ -42,21 +42,37 @@ jobs:
           name: wheels
           path: dist
       - name: pytest
+        if: ${{ startsWith(matrix.target, 'x86_64') }}
         shell: bash
         run: |
           set -e
-          pip install pycrc32 --find-links dist --force-reinstall
+          pip install pycrc32 --find-links dist --force-reinstall --no-index
           pip install pytest
           pytest
+      - name: pytest
+        if: ${{ !startsWith(matrix.target, 'x86') && matrix.target != 'ppc64' }}
+        uses: uraimo/[email protected]
+        with:
+          arch: ${{ matrix.target }}
+          distro: ubuntu22.04
+          githubToken: ${{ github.token }}
+          install: |
+            apt-get update
+            apt-get install -y --no-install-recommends python3 python3-pip
+            pip3 install -U pip pytest
+          run: |
+            set -e
+            pip3 install pycrc32 --find-links dist --force-reinstall --no-index
+            pytest
 
   windows:
     runs-on: windows-latest
     strategy:
       matrix:
         target: [x64, x86]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
         with:
           python-version: '3.10'
           architecture: ${{ matrix.target }}
@@ -72,10 +88,11 @@ jobs:
           name: wheels
           path: dist
       - name: pytest
+        if: ${{ !startsWith(matrix.target, 'aarch64') }}
         shell: bash
         run: |
           set -e
-          pip install pycrc32 --find-links dist --force-reinstall
+          pip install pycrc32 --find-links dist --force-reinstall --no-index
           pip install pytest
           pytest
 
@@ -85,8 +102,8 @@ jobs:
       matrix:
         target: [x86_64, aarch64]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
         with:
           python-version: '3.10'
       - name: Build wheels
@@ -101,17 +118,18 @@ jobs:
           name: wheels
           path: dist
       - name: pytest
+        if: ${{ !startsWith(matrix.target, 'aarch64') }}
         shell: bash
         run: |
           set -e
-          pip install pycrc32 --find-links dist --force-reinstall
+          pip install pycrc32 --find-links dist --force-reinstall --no-index
           pip install pytest
           pytest
 
   sdist:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
       - name: Build sdist
         uses: PyO3/maturin-action@v1
         with:

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "pycrc32"
-version = "0.1.3"
+version = "0.2.0"
 edition = "2021"
 authors = ["cybuerg <[email protected]>"]
 description = "Python module for SIMD-accelerated CRC32 checksum computation"

Cargo.toml

@@ -21,6 +21,57 @@ data = b"123456789"
 print(f"crc32 for {data!r} is {crc32(data)}")
 ```
 
+### Advanced Checksum Calculation with `Hasher`
+For scenarios that require more flexibility, such as processing large amounts of data or computing the checksum in stages, you can use the `Hasher` class:
+```python
+from pycrc32 import Hasher
+
+# Create a new Hasher instance
+hasher = Hasher()
+
+# Update the hasher with data chunks
+hasher.update(b"123456")
+hasher.update(b"789")
+
+# Finalize the computation and get the checksum
+checksum = hasher.finalize()
+print(f"Checksum: {checksum}")
+
+# Reset the hasher to compute another checksum
+hasher.reset()
+hasher.update(b"The quick brown fox jumps over the lazy dog")
+new_checksum = hasher.finalize()
+print(f"New checksum: {new_checksum}")
+```
+
+You can also initialize a `Hasher` with a specific initial CRC32 state:
+```python
+initial_crc = 12345678
+hasher = Hasher.with_initial(initial_crc)
+
+hasher.update(b"additional data")
+final_checksum = hasher.finalize()
+print(f"Final checksum with initial state: {final_checksum}")
+```
+
+To combine checksums from different data blocks without needing to concatenate the data, use the `combine` method:
+```python
+hasher1 = Hasher()
+hasher1.update(b"Data block 1")
+checksum1 = hasher1.finalize()
+
+hasher2 = Hasher()
+hasher2.update(b"Data block 2")
+checksum2 = hasher2.finalize()
+
+# Combine checksums from hasher1 into hasher2
+hasher1.combine(hasher2)  # Combine the state of hasher2 into hasher1
+
+# The final checksum after combination
+combined_checksum = hasher1.finalize()
+print(f"Combined checksum: {combined_checksum}")
+```
+
 ## Speed
 The performance of `pycrc32` has been benchmarked on a trusty old Intel i7-8550U using 32MB of random input data. Below is a comparison of the median computation times across different libraries:
 

README.md

@@ -1 +1 @@
-from .pycrc32 import crc32
+from .pycrc32 import Hasher, crc32

pycrc32/__init__.py

@@ -1,6 +1,6 @@
 import pytest
 
-from pycrc32 import crc32
+from pycrc32 import Hasher, crc32
 
 
 @pytest.mark.parametrize(
@@ -14,3 +14,66 @@
 )
 def test_crc32(input_bytes, expected_crc):
     assert crc32(input_bytes) == expected_crc
+
+
+@pytest.mark.parametrize(
+    "input_bytes,expected_crc",
+    [
+        (b"123456789", 3421780262),
+        (b"", 0),
+        (b"a", 3904355907),
+        (b"The quick brown fox jumps over the lazy dog", 1095738169),
+    ],
+)
+def test_Hasher_simple_usage(input_bytes, expected_crc):
+    hasher = Hasher()
+    hasher.update(input_bytes)
+    assert hasher.finalize() == expected_crc
+
+
+def test_Hasher_with_initial():
+    initial_crc = 3421780262  # CRC for "123456789"
+    additional_data = b" continuation"
+    combined_crc = crc32(b"123456789 continuation")
+
+    hasher = Hasher.with_initial(initial_crc)
+    hasher.update(additional_data)
+    assert hasher.finalize() == combined_crc
+
+
+def test_Hasher_reset():
+    input_bytes = b"The quick brown fox jumps over the lazy dog"
+    hasher = Hasher()
+    hasher.update(input_bytes)
+    first_crc = hasher.finalize()
+
+    # Reset and reuse the hasher for the same input
+    hasher.reset()
+    hasher.update(input_bytes)
+    second_crc = hasher.finalize()
+
+    assert first_crc == 1095738169
+    assert second_crc == 1095738169
+
+
+@pytest.mark.parametrize(
+    "input_bytes1,input_bytes2",
+    [
+        (b"123456789", b" continuation"),
+        (b"The quick brown fox", b" jumps over the lazy dog"),
+    ],
+)
+def test_Hasher_combine(input_bytes1, input_bytes2):
+    hasher1 = Hasher()
+    hasher1.update(input_bytes1)
+    crc1 = hasher1.finalize()
+
+    hasher2 = Hasher()
+    hasher2.update(input_bytes2)
+    hasher2.finalize()
+
+    combined_crc = crc32(input_bytes1 + input_bytes2)
+    hasher_combined = Hasher.with_initial(crc1)
+    hasher_combined.update(input_bytes2)
+
+    assert hasher_combined.finalize() == combined_crc