Skip to content

gh-134635: add zlib.{adler32,crc32}_combine to combine checksums#134650

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
picnixz merged 10 commits into from
May 27, 2025
Merged

gh-134635: add zlib.{adler32,crc32}_combine to combine checksums #134650

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f71608e
expose `zlib.{adler32,crc32}_combine`
picnixz May 25, 2025
c8a96c8
update docs
picnixz May 25, 2025
c67d7ba
Address doc review's feedback
picnixz May 25, 2025
0540501
Update What's New
picnixz May 25, 2025
c5a2c55
add a failing test
picnixz May 25, 2025
cc160a7
update clinic
picnixz May 26, 2025
f3fca34
remove rST syntax in clinic
picnixz May 26, 2025
2c34e5f
add type checks
picnixz May 26, 2025
86746bd
Merge branch 'main' into feat/zlib/crc32-combine-134635
picnixz May 26, 2025
2753b18
Apply suggestions from code review
picnixz May 26, 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
28 changes: 28 additions & 0 deletions Doc/library/zlib.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -44,6 +44,20 @@ The available exception and functions in this module are:
.. versionchanged:: 3.0
The result is always unsigned.

.. function:: adler32_combine(adler1, adler2, len2, /)

Combine two Adler-32 checksums into one.

Given the Adler-32 checksum *adler1* of a sequence ``A`` and the
Adler-32 checksum *adler2* of a sequence ``B`` of length *len2*,
return the Adler-32 checksum of ``A`` and ``B`` concatenated.

This function is typically useful to combine Adler-32 checksums
that were concurrently computed. To compute checksums sequentially, use
:func:`adler32` with the running checksum as the ``value`` argument.

.. versionadded:: next

.. function:: compress(data, /, level=-1, wbits=MAX_WBITS)

Compresses the bytes in *data*, returning a bytes object containing compressed data.
Expand DownExpand Up@@ -136,6 +150,20 @@ The available exception and functions in this module are:
.. versionchanged:: 3.0
The result is always unsigned.

.. function:: crc32_combine(crc1, crc2, len2, /)

Combine two CRC-32 checksums into one.

Given the CRC-32 checksum *crc1* of a sequence ``A`` and the
CRC-32 checksum *crc2* of a sequence ``B`` of length *len2*,
return the CRC-32 checksum of ``A`` and ``B`` concatenated.

This function is typically useful to combine CRC-32 checksums
that were concurrently computed. To compute checksums sequentially, use
:func:`crc32` with the running checksum as the ``value`` argument.

.. versionadded:: next

.. function:: decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

Decompresses the bytes in *data*, returning a bytes object containing the
Expand Down
10 changes: 10 additions & 0 deletions Doc/whatsnew/3.15.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -97,6 +97,16 @@ ssl
(Contributed by Will Childs-Klein in :gh:`133624`.)


zlib
----

* Allow combining two Adler-32 checksums via :func:`~zlib.adler32_combine`.
(Contributed by Callum Attryde and Bénédikt Tran in :gh:`134635`.)

* Allow combining two CRC-32 checksums via :func:`~zlib.crc32_combine`.
(Contributed by Bénédikt Tran in :gh:`134635`.)


.. Add improved modules above alphabetically, not here at the end.

Optimizations
Expand Down
108 changes: 108 additions & 0 deletions Lib/test/test_zlib.py
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -119,6 +119,114 @@ def test_same_as_binascii_crc32(self):
self.assertEqual(binascii.crc32(b'spam'), zlib.crc32(b'spam'))


class ChecksumCombineMixin:
"""Mixin class for testing checksum combination."""

N = 1000
default_iv: int

def parse_iv(self, iv):
"""Parse an IV value.

- The default IV is returned if *iv* is None.
- A random IV is returned if *iv* is -1.
- Otherwise, *iv* is returned as is.
"""
if iv is None:
return self.default_iv
if iv == -1:
return random.randint(1, 0x80000000)
return iv

def checksum(self, data, init=None):
"""Compute the checksum of data with a given initial value.

The *init* value is parsed by ``parse_iv``.
"""
iv = self.parse_iv(init)
return self._checksum(data, iv)

def _checksum(self, data, init):
raise NotImplementedError

def combine(self, a, b, blen):
"""Combine two checksums together."""
raise NotImplementedError

def get_random_data(self, data_len, *, iv=None):
"""Get a triplet (data, iv, checksum)."""
data = random.randbytes(data_len)
init = self.parse_iv(iv)
checksum = self.checksum(data, init)
return data, init, checksum

def test_combine_empty(self):
for _ in range(self.N):
a, iv, checksum = self.get_random_data(32, iv=-1)
res = self.combine(iv, self.checksum(a), len(a))
self.assertEqual(res, checksum)

def test_combine_no_iv(self):
for _ in range(self.N):
a, _, chk_a = self.get_random_data(32)
b, _, chk_b = self.get_random_data(64)
res = self.combine(chk_a, chk_b, len(b))
self.assertEqual(res, self.checksum(a + b))

def test_combine_no_iv_invalid_length(self):
a, _, chk_a = self.get_random_data(32)
b, _, chk_b = self.get_random_data(64)
checksum = self.checksum(a + b)
for invalid_len in [1, len(a), 48, len(b) + 1, 191]:
invalid_res = self.combine(chk_a, chk_b, invalid_len)
self.assertNotEqual(invalid_res, checksum)

self.assertRaises(TypeError, self.combine, 0, 0, "len")

def test_combine_with_iv(self):
for _ in range(self.N):
a, iv_a, chk_a_with_iv = self.get_random_data(32, iv=-1)
chk_a_no_iv = self.checksum(a)
b, iv_b, chk_b_with_iv = self.get_random_data(64, iv=-1)
chk_b_no_iv = self.checksum(b)

# We can represent c = COMBINE(CHK(a, iv_a), CHK(b, iv_b)) as:
#
# c = CHK(CHK(b'', iv_a) + CHK(a) + CHK(b'', iv_b) + CHK(b))
# = COMBINE(
# COMBINE(CHK(b'', iv_a), CHK(a)),
# COMBINE(CHK(b'', iv_b), CHK(b)),
# )
# = COMBINE(COMBINE(iv_a, CHK(a)), COMBINE(iv_b, CHK(b)))
tmp0 = self.combine(iv_a, chk_a_no_iv, len(a))
tmp1 = self.combine(iv_b, chk_b_no_iv, len(b))
expected = self.combine(tmp0, tmp1, len(b))
checksum = self.combine(chk_a_with_iv, chk_b_with_iv, len(b))
self.assertEqual(checksum, expected)


class CRC32CombineTestCase(ChecksumCombineMixin, unittest.TestCase):

default_iv = 0

def _checksum(self, data, init):
return zlib.crc32(data, init)

def combine(self, a, b, blen):
return zlib.crc32_combine(a, b, blen)


class Adler32CombineTestCase(ChecksumCombineMixin, unittest.TestCase):

default_iv = 1

def _checksum(self, data, init):
return zlib.adler32(data, init)

def combine(self, a, b, blen):
return zlib.adler32_combine(a, b, blen)


# Issue #10276 - check that inputs >=4 GiB are handled correctly.
class ChecksumBigBufferTestCase(unittest.TestCase):

Expand Down
3 changes: 3 additions & 0 deletions Misc/NEWS.d/next/Library/2025-05-25-13-46-37.gh-issue-134635.ZlPrlX.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
:mod:`zlib`: Allow to combine Adler-32 and CRC-32 checksums via
:func:`~zlib.adler32_combine` and :func:`~zlib.crc32_combine`. Patch by
Callum Attryde and Bénédikt Tran.
120 changes: 119 additions & 1 deletion Modules/clinic/zlibmodule.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading