hdiffpatch 2.3.0__tar.gz → 2.5.0__tar.gz

hdiffpatch-2.5.0/.gitmodules

@@ -0,0 +1,37 @@
+[submodule "hdiffpatch/_c_src/HDiffPatch"]
+	path = hdiffpatch/_c_src/HDiffPatch
+	url = https://github.com/sisong/HDiffPatch.git
+[submodule "hdiffpatch/_c_src/libmd5"]
+	path = hdiffpatch/_c_src/libmd5
+	url = https://github.com/sisong/libmd5.git
+[submodule "hdiffpatch/_c_src/lzma"]
+	path = hdiffpatch/_c_src/lzma
+	url = https://github.com/sisong/lzma.git
+[submodule "hdiffpatch/_c_src/zstd"]
+	path = hdiffpatch/_c_src/zstd
+	url = https://github.com/sisong/zstd.git
+[submodule "hdiffpatch/_c_src/zlib"]
+	path = hdiffpatch/_c_src/zlib
+	url = https://github.com/sisong/zlib.git
+[submodule "hdiffpatch/_c_src/bzip2"]
+	path = hdiffpatch/_c_src/bzip2
+	url = https://github.com/sisong/bzip2.git
+[submodule "hdiffpatch/_c_src/libdeflate"]
+	path = hdiffpatch/_c_src/libdeflate
+	url = https://github.com/sisong/libdeflate.git
+[submodule "hdiffpatch/_c_src/tamp"]
+	path = hdiffpatch/_c_src/tamp
+	url = https://github.com/BrianPugh/tamp.git
+[submodule "hdiffpatch/_c_src/lz4"]
+	path = hdiffpatch/_c_src/lz4
+	url = https://github.com/lz4/lz4.git
+[submodule "hdiffpatch/_c_src/tinyuz"]
+	path = hdiffpatch/_c_src/tinyuz
+	url = https://github.com/BrianPugh/tinyuz.git
+[submodule "hdiffpatch/_c_src/brotli"]
+	path = hdiffpatch/_c_src/brotli
+	url = https://github.com/google/brotli.git
+[submodule "hdiffpatch/_c_src/lzham_codec"]
+	path = hdiffpatch/_c_src/lzham_codec
+	url = https://github.com/BrianPugh/lzham_codec.git
+	branch = portability

hdiffpatch-2.5.0/CLAUDE.md

@@ -0,0 +1,113 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+hdiffpatch-python is a high-performance Python wrapper around the [HDiffPatch](https://github.com/sisong/HDiffPatch) C++ library providing efficient binary diff/patch operations with comprehensive compression support. The project uses Cython for C++ integration and supports Python 3.10+. It is a library only — there is no CLI.
+
+## Development Commands
+
+### Setup and Installation
+
+```bash
+# Install development dependencies
+uv sync
+
+# Build Cython extensions (required after initial sync)
+uv run python rebuild.py
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+### Testing
+This project uses the `pytest` framework for unit testing:
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run specific test file
+uv run pytest tests/test_compression.py
+
+# Run specific test function
+uv run pytest tests/test_compression.py::TestCompressionTypes::test_compression_type_constants
+
+# Run tests with coverage
+uv run pytest --cov=hdiffpatch --cov-report=html
+
+# Run tests matching a keyword
+uv run pytest -k "compression"
+```
+
+### Code Quality
+
+```bash
+# Run all pre-commit hooks; this only runs on files tracked by git.
+uv run pre-commit run --all-files
+```
+
+Linting/typing is configured in `pyproject.toml`: ruff (line length 120, numpy docstring convention, target Python 3.10) and pyright (checks `tests/`).
+
+## Architecture
+
+### Build pipeline
+
+- **`cythonize.py`**: compiles `hdiffpatch/_c_extension.pyx` to C++ with optimization directives.
+- **`rebuild.py`**: runs `cythonize.py`, then reinstalls the package in editable mode. This is the one command to run after editing `.pyx` files.
+- **`setup.py`**: builds a single extension module (`hdiffpatch._c_extension`) that statically embeds all C/C++ dependencies from `hdiffpatch/_c_src/` (HDiffPatch, zlib, libdeflate, lzma, zstd, bzip2, tamp, lz4, tinyuz, brotli, lzham, libmd5) with `-O3` and platform-specific optimizations. Compression plugins are enabled via preprocessor defines (e.g. `_CompressPlugin_lzma`).
+
+### Package layout
+
+- **`hdiffpatch/_c_extension.pyx`**: the entire Cython interface — core functions, constants, and the `HDiffPatchError` exception. `hdiffpatch/_c_extension.pyi` is the hand-maintained type stub; keep it in sync when changing the `.pyx` API.
+- **`hdiffpatch/_base_config.py`** + per-algorithm config modules (`_zlib_config.py`, `_lzma_config.py`, `_zstd_config.py`, `_bzip2_config.py`, `_tamp_config.py`, `_xz_config.py`, `_lz4_config.py`, `_tuz_config.py`, `_brotli_config.py`, `_lzham_config.py`): frozen attrs classes for fine-grained compression settings. `BaseConfig` defines classmethod presets (`fast`, `balanced`, `best_compression`, `minimal_memory`) that subclasses implement.
+- **`hdiffpatch/__init__.py`**: assembles the public API; `__version__` is managed by setuptools-scm — don't edit it.
+
+### Public API
+
+```python
+diff(old_data: bytes, new_data: bytes, compression=None, *, validate=True, big_cache_match=False) -> bytes
+apply(old_data: bytes, diff_data: bytes) -> bytes      # auto-detects compression from diff header
+recompress(diff_data: bytes, compression=None) -> bytes  # re-encode an existing diff (incl. hdiffz output)
+```
+
+- `compression` accepts a `CompressionType` literal string (`"none"`, `"zlib"`, `"lzma"`, `"lzma2"`, `"zstd"`, `"bzip2"`, `"tamp"`, `"xz"`, `"lz4"`, `"lz4hc"`, `"tuz"`, `"brotli"`, `"lzham"`), a config object (e.g. `ZStdConfig(level=22)`), or `None`.
+- There is a single exception type, `HDiffPatchError`, raised for all diff/patch/compression failures.
+- Uses Literal types instead of Enums for simplicity and type checker compatibility.
+
+### Tests
+
+- `tests/conftest.py` provides a comprehensive fixture system (e.g. `simple_text_data`, `binary_data`, `random_data`, `compression_types`, `all_compression_types`) — use these for consistent test data.
+- `tests/binaries/` holds real MicroPython firmware images and hdiffz-produced diffs used by `test_binary_compatibility.py` to verify compatibility with upstream HDiffPatch tooling.
+- `tools/micropython-binary-demo.py` is a demo script exercising the same firmware-diff use case.
+
+### Adding a codec
+
+A new codec touches every codec list, and missing one fails quietly (a test fixture skips it, or the lite API rejects it):
+
+- `setup.py`: sources, include dirs, and the `-D_CompressPlugin_*` define. Vendor the library as a submodule under `hdiffpatch/_c_src/`; the sdist picks submodules up through setuptools-scm.
+- `_c_extension.pyx`: the extern plugin declarations, the `TCompressPlugin_*` struct, `CompressionType`, `COMPRESSION_*`, `_valid_compression_types`, `get_compress_plugin`/`get_decompress_plugin` (which must also accept the diff header's upstream name, e.g. `"7zXZ"`), a `create_custom_*_plugin`, and `_resolve_compression_to_plugin`. If upstream's `hpi_compressType` has a byte for it, also add it to `LiteCompressionType` (the runtime lite set is derived from it), `_lite_compress_type_tag`, `_lite_header_decompress_plugin` and `_lite_normalize_compression`.
+- The `.pyi` stub, `__init__.py` exports, a `_<codec>_config.py` module, the `compression_types`/`all_compression_types` fixtures, the sorted "Valid options" message in `tests/test_exceptions.py`, and the lite lists in `tests/test_diff_lite.py`/`tests/test_recompress_lite.py`.
+
+Gotchas:
+
+- Encoders with `threads > 1` (lzma2, xz, tinyuz, lzham) call the output stream's `write()` from worker threads, and upstream plugins default to 4 threads. Stream callbacks must never touch Python objects; write through upstream's C++ `TVectorAsStreamOutput` like `diff`/`recompress` do.
+- Multithreaded LZHAM output varies between runs (upstream's plugin can't set `LZHAM_COMP_FLAG_DETERMINISTIC_PARSING`), so byte-identity tests use `LzhamConfig()` (1 thread), never the `"lzham"` string.
+- lzham_codec is abandoned upstream; the submodule tracks the `portability` branch of BrianPugh/lzham_codec, so portability fixes go there.
+- Test Linux aarch64/GCC locally with Docker: copy the repo into a `python:3.13` container, `pip install --no-build-isolation .` (with `SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0`), then run pytest. Windows/MSVC is CI-only.
+
+## Development Memories
+
+- Always run `uv run python rebuild.py` after `uv sync` for development setup
+- After changing Cython code: just run `uv run python rebuild.py` (handles cythonize automatically)
+- Always use `uv run python` instead of just `python` for running python code
+- Always prefer `pathlib.Path` over `os.path`
+- Only add comments if the action isn't immediately obvious from function or method names
+- **All docstrings must follow numpy-style format** with proper Parameters, Returns, and Raises sections
+- TAMP compression is supported as a first-class compression type alongside zlib, zstd, etc.
+- All compression types should be tested with round-trip validation
+- Use the comprehensive fixture system in `conftest.py` for consistent test data
+- Run `uv run pre-commit run --all-files` before asking to commit to ensure pre-commit passes all checks. It skips untracked files, so `git add` new files first.
+- `uv run python` rebuilds the package before running anything, so a helper script can't run while the tree doesn't build (e.g. mid-rebase with conflict markers); use `uv run --no-project python` for those.
+- When writing unit tests, prefer to use pytest functionality (such as `parametrize`)

hdiffpatch-2.5.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: hdiffpatch
+Version: 2.5.0
+Summary: Python wrapper around HDiffPatch C++ library for efficient binary diff/patch operations.
+Author: Brian Pugh
+License-Expression: Apache-2.0
+Project-URL: homepage, https://github.com/BrianPugh/hdiffpatch-python
+Project-URL: repository, https://github.com/BrianPugh/hdiffpatch-python
+Project-URL: documentation, https://hdiffpatch.readthedocs.io
+Keywords: binary,diff,patch,compression,hdiffpatch,delta,update
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Cython
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Archiving :: Compression
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: attrs>=21.3.0
+Dynamic: license-file
+
+<div align="center">
+
+![Python compat](https://img.shields.io/badge/%3E=python-3.10-blue.svg)
+[![PyPI](https://img.shields.io/pypi/v/hdiffpatch.svg)](https://pypi.org/project/hdiffpatch/)
+[![ReadTheDocs](https://readthedocs.org/projects/hdiffpatch-python/badge/?version=latest)](https://hdiffpatch-python.readthedocs.io)
+[![GHA Status](https://github.com/BrianPugh/hdiffpatch-python/actions/workflows/tests.yaml/badge.svg?branch=main)](https://github.com/BrianPugh/hdiffpatch-python/actions?query=workflow%3Atests)
+
+</div>
+
+---
+
+**Documentation:** https://hdiffpatch-python.readthedocs.io
+
+**Source Code:** https://github.com/BrianPugh/hdiffpatch-python
+
+---
+
+**hdiffpatch-python** is a Python wrapper around the [HDiffPatch](https://github.com/sisong/HDiffPatch) C++ library, providing fast binary diff and patch operations with a variety of compression options.
+
+# Installation
+
+hdiffpatch requires Python >=3.10 and can be installed via:
+
+```console
+pip install hdiffpatch
+```
+
+# Quick Start
+
+**hdiffpatch** primarily provides 3 simple functions:
+
+* `diff` for creating a patch.
+* `apply` for applying a patch.
+* `recompress` for changing an existing patch's compression.
+
+```python
+import hdiffpatch
+
+old = b"The quick brown fox jumps over the lazy dog."
+new = b"The quick brown fox leaps over the sleepy dog."
+
+# Create a compressed patch that transforms old -> new.
+patch = hdiffpatch.diff(old, new, compression="zstd")
+
+# Later (e.g. on another device), reconstruct new from old + patch.
+assert hdiffpatch.apply(old, patch) == new
+
+# Re-encode an existing patch with a different compression algorithm.
+patch_lzma = hdiffpatch.recompress(patch, compression="lzma")
+assert hdiffpatch.apply(old, patch_lzma) == new
+```
+
+A patch is typically much smaller than the new data itself, making **hdiffpatch** ideal for bandwidth-constrained applications like over-the-air firmware updates.
+
+## Lite-format diffs for HPatchLite
+
+For extremely memory-constrained devices, `diff_lite` produces the compact "lite" format consumed by HDiffPatch's tiny on-device applier, [HPatchLite](https://github.com/sisong/HPatchLite) (`hpatch_lite_patch`). Every codec with a compress-type byte in the lite header is accepted: `"none"`, `"zlib"`, `"lzma"`, `"lzma2"`, `"zstd"`, `"bzip2"`, `"lz4"`, `"lz4hc"`, `"tuz"` (tinyuz), `"brotli"`, `"lzham"`, and `"tamp"` (the last under the vendor-specific byte `0xF0`). `hpatch_lite_patch` does no decompression itself, so pick a codec whose decoder fits on your device; `"lzma"`, `"zlib"`, and `"tamp"` are the small ones.
+
+```python
+import hdiffpatch
+
+lite = hdiffpatch.diff_lite(old, new, compression="lzma")
+restored = hdiffpatch.apply_lite(old, lite)   # == new
+```
+
+`apply_lite` is the lite-format counterpart of `apply`: it drives the vendored HPatchLite applier (the same code path a device runs) to reconstruct the new data. The codec is auto-detected from the self-describing lite header, so `apply_lite` takes no `compression` argument.
+
+`recompress_lite` is the lite-format counterpart of `recompress`. It re-encodes an existing lite diff with another lite codec without redoing the match search, and for a diff made by `diff_lite` the result is byte-identical to calling `diff_lite` with that codec directly (except for multithreaded LZHAM, whose output varies from run to run; an inplace-variant diff, which `diff_lite` doesn't produce, keeps its header), so a diff needed under several codecs can be computed once uncompressed and then recompressed per codec:
+
+```python
+base = hdiffpatch.diff_lite(old, new)
+lite_tamp = hdiffpatch.recompress_lite(base, "tamp")
+assert lite_tamp == hdiffpatch.diff_lite(old, new, compression="tamp")
+```
+
+Lite diffs are **not** interchangeable with `diff`/`apply` — they can only be applied by an HPatchLite-family patcher (`apply_lite` here, or an HPatchLite build on the target device), and the standard `apply` rejects them.
+
+See the [documentation](https://hdiffpatch-python.readthedocs.io) for fine-grained compression configuration, diff recompression, and performance benchmarks.

hdiffpatch-2.5.0/README.md

@@ -0,0 +1,78 @@
+<div align="center">
+
+![Python compat](https://img.shields.io/badge/%3E=python-3.10-blue.svg)
+[![PyPI](https://img.shields.io/pypi/v/hdiffpatch.svg)](https://pypi.org/project/hdiffpatch/)
+[![ReadTheDocs](https://readthedocs.org/projects/hdiffpatch-python/badge/?version=latest)](https://hdiffpatch-python.readthedocs.io)
+[![GHA Status](https://github.com/BrianPugh/hdiffpatch-python/actions/workflows/tests.yaml/badge.svg?branch=main)](https://github.com/BrianPugh/hdiffpatch-python/actions?query=workflow%3Atests)
+
+</div>
+
+---
+
+**Documentation:** https://hdiffpatch-python.readthedocs.io
+
+**Source Code:** https://github.com/BrianPugh/hdiffpatch-python
+
+---
+
+**hdiffpatch-python** is a Python wrapper around the [HDiffPatch](https://github.com/sisong/HDiffPatch) C++ library, providing fast binary diff and patch operations with a variety of compression options.
+
+# Installation
+
+hdiffpatch requires Python >=3.10 and can be installed via:
+
+```console
+pip install hdiffpatch
+```
+
+# Quick Start
+
+**hdiffpatch** primarily provides 3 simple functions:
+
+* `diff` for creating a patch.
+* `apply` for applying a patch.
+* `recompress` for changing an existing patch's compression.
+
+```python
+import hdiffpatch
+
+old = b"The quick brown fox jumps over the lazy dog."
+new = b"The quick brown fox leaps over the sleepy dog."
+
+# Create a compressed patch that transforms old -> new.
+patch = hdiffpatch.diff(old, new, compression="zstd")
+
+# Later (e.g. on another device), reconstruct new from old + patch.
+assert hdiffpatch.apply(old, patch) == new
+
+# Re-encode an existing patch with a different compression algorithm.
+patch_lzma = hdiffpatch.recompress(patch, compression="lzma")
+assert hdiffpatch.apply(old, patch_lzma) == new
+```
+
+A patch is typically much smaller than the new data itself, making **hdiffpatch** ideal for bandwidth-constrained applications like over-the-air firmware updates.
+
+## Lite-format diffs for HPatchLite
+
+For extremely memory-constrained devices, `diff_lite` produces the compact "lite" format consumed by HDiffPatch's tiny on-device applier, [HPatchLite](https://github.com/sisong/HPatchLite) (`hpatch_lite_patch`). Every codec with a compress-type byte in the lite header is accepted: `"none"`, `"zlib"`, `"lzma"`, `"lzma2"`, `"zstd"`, `"bzip2"`, `"lz4"`, `"lz4hc"`, `"tuz"` (tinyuz), `"brotli"`, `"lzham"`, and `"tamp"` (the last under the vendor-specific byte `0xF0`). `hpatch_lite_patch` does no decompression itself, so pick a codec whose decoder fits on your device; `"lzma"`, `"zlib"`, and `"tamp"` are the small ones.
+
+```python
+import hdiffpatch
+
+lite = hdiffpatch.diff_lite(old, new, compression="lzma")
+restored = hdiffpatch.apply_lite(old, lite)   # == new
+```
+
+`apply_lite` is the lite-format counterpart of `apply`: it drives the vendored HPatchLite applier (the same code path a device runs) to reconstruct the new data. The codec is auto-detected from the self-describing lite header, so `apply_lite` takes no `compression` argument.
+
+`recompress_lite` is the lite-format counterpart of `recompress`. It re-encodes an existing lite diff with another lite codec without redoing the match search, and for a diff made by `diff_lite` the result is byte-identical to calling `diff_lite` with that codec directly (except for multithreaded LZHAM, whose output varies from run to run; an inplace-variant diff, which `diff_lite` doesn't produce, keeps its header), so a diff needed under several codecs can be computed once uncompressed and then recompressed per codec:
+
+```python
+base = hdiffpatch.diff_lite(old, new)
+lite_tamp = hdiffpatch.recompress_lite(base, "tamp")
+assert lite_tamp == hdiffpatch.diff_lite(old, new, compression="tamp")
+```
+
+Lite diffs are **not** interchangeable with `diff`/`apply` — they can only be applied by an HPatchLite-family patcher (`apply_lite` here, or an HPatchLite build on the target device), and the standard `apply` rejects them.
+
+See the [documentation](https://hdiffpatch-python.readthedocs.io) for fine-grained compression configuration, diff recompression, and performance benchmarks.

hdiffpatch-2.5.0/docs/source/Performance.rst

@@ -0,0 +1,87 @@
+Performance
+===========
+
+* :func:`hdiffpatch.diff` is the expensive operation: it searches for matches between ``old_data`` and ``new_data``, and its cost grows with input size. :func:`hdiffpatch.apply` is comparatively cheap (10-60x faster in the benchmark below).
+
+  * ``validate=True`` (the default) round-trips the freshly created diff through :func:`hdiffpatch.apply` and verifies that it reproduces ``new_data`` exactly. This adds only a few percent on top of creating the diff, and catches any data-compromising bug in the diff/compression stack before a corrupt diff is stored or shipped — leave it enabled.
+
+* :func:`hdiffpatch.recompress` re-encodes an existing diff without redoing the expensive diff computation, paying only for the recompression itself. To produce the same diff with several compression algorithms, create it once and recompress it per target instead of calling :func:`hdiffpatch.diff` repeatedly:
+
+.. code-block:: python
+
+   base = hdiffpatch.diff(old_data, new_data, compression="none")
+   diff_zstd = hdiffpatch.recompress(base, compression="zstd")
+   diff_lzma = hdiffpatch.recompress(base, compression="lzma")
+
+* ``big_cache_match=True`` on :func:`hdiffpatch.diff` and :func:`hdiffpatch.diff_lite` speeds up the match search (see below).
+
+Big-cache matching
+------------------
+
+``big_cache_match`` maps to HDiffPatch's ``isUseBigCacheMatch``. Before matching, it hashes every 5-byte window of ``old_data`` into a bloom filter, and the matcher uses that filter to reject most candidate positions without a suffix-array search. It is a matching-stage option only, so it works the same for every compression type and has no effect on :func:`hdiffpatch.apply`, :func:`hdiffpatch.recompress`, or their lite counterparts.
+
+Trade-offs:
+
+* **Output:** byte-identical to ``big_cache_match=False``. Diff size and compression ratio don't change, and a diff made either way can be cached or compared against the other.
+* **Speed:** on 0.65-2 MB firmware images, the match search is about 15-30% faster. On the RPI_PICO pair used in the benchmarks below (measured separately, best of 9, ``validate=False``; the tables below use the default ``big_cache_match=False``), :func:`hdiffpatch.diff` went from 26.8 to 19.6 ms and :func:`hdiffpatch.diff_lite` from 26.3 to 18.9 ms. On ESP32 images of 1.3-2 MB the gain was 15-25%. Building the filter is one extra pass over ``old_data``; upstream warns that this build is slow, but it paid for itself at every size measured, down to 4 KB inputs.
+* **Memory:** the filter holds at least 4 bits per byte of ``old_data``, rounded up to a power of 2, so 0.5-1 byte per byte of ``old_data`` (a 2 MB image costs 1 MB). That sits on top of the suffix array the matcher always builds (4 bytes per byte of ``old_data`` below 2 GB, 8 above), and in the firmware measurements peak memory didn't grow measurably. For multi-GB inputs, budget up to ``len(old_data)`` extra bytes.
+* **Threads:** the filter is built on the calling thread, like the rest of the match search, with the GIL released.
+
+The default stays ``False`` to keep the upstream default and the existing memory profile for very large inputs. For firmware-sized inputs, turning it on is a free speedup.
+
+Benchmarks
+----------
+
+Diffing two consecutive MicroPython RPI_PICO firmware releases (~650 KB each, best of 5 runs, Apple M3). Each compression type uses its default settings. Absolute times vary by machine and input; the ratios are the point. Regenerate with ``uv run python tools/benchmark.py``.
+
+* **diff** — create the compressed diff from scratch: :func:`hdiffpatch.diff` with ``validate=False``.
+* **apply** — apply that diff to the old file with :func:`hdiffpatch.apply`.
+* **recompress** — re-encode a precomputed uncompressed diff into this compression with :func:`hdiffpatch.recompress`; compare against the *diff* column to see what skipping the diff computation saves.
+* **diff size / % of new file** — the compressed diff in bytes, and relative to the new file's size (lower is better).
+
+===========  =========  ==========  ===============  =========  =============
+compression  diff (ms)  apply (ms)  recompress (ms)  diff size  % of new file
+===========  =========  ==========  ===============  =========  =============
+none              25.8         0.4                —    161,041          24.1%
+zlib              32.0         0.9              5.3     99,772          14.9%
+lzma              36.6         3.3             10.9     92,647          13.9%
+lzma2             37.0         3.3             10.9     92,656          13.9%
+xz                36.6         3.6             11.4     92,865          13.9%
+zstd              42.4         0.6             16.0     97,520          14.6%
+bzip2             34.7         4.1              8.6    102,686          15.4%
+brotli            29.9         1.1              3.7     98,925          14.8%
+lzham             38.2         1.6             12.3     97,500          14.6%
+lz4               26.7         0.5              0.1    131,067          19.6%
+lz4hc             30.0         0.6              2.6    120,571          18.1%
+tuz              104.5         1.2             76.0    104,363          15.6%
+tamp              43.4         1.2             16.3    110,711          16.6%
+===========  =========  ==========  ===============  =========  =============
+
+``validate=True`` measured 27.4 ms against 26.9 ms with ``validate=False`` (uncompressed diff) — a few percent of overhead.
+
+Standard vs. lite
+~~~~~~~~~~~~~~~~~~
+
+HPatchLite is HDiffPatch's tiny on-device applier format (``hpatch_lite_patch``), built for minimal device RAM/flash. :func:`hdiffpatch.diff_lite` and :func:`hdiffpatch.apply_lite` produce and consume it; it is **not** interchangeable with :func:`hdiffpatch.diff`/:func:`hdiffpatch.apply`. The trade-off is a slightly larger diff for a much smaller device-side footprint, which does not appear in host apply times. Every codec with a lite compress-type byte is supported (none/zlib/lzma/lzma2/zstd/bzip2/lz4/lz4hc/tuz/brotli/lzham/tamp); the table covers the ones small enough to decode on a microcontroller.
+
+:func:`hdiffpatch.recompress_lite` is the lite counterpart of :func:`hdiffpatch.recompress`: it re-encodes an existing lite diff's body without redoing the match search, and for a diff made by :func:`hdiffpatch.diff_lite` its output is byte-identical to calling :func:`hdiffpatch.diff_lite` with the target codec. The *lite recompress* column times re-encoding a precomputed uncompressed lite diff, so to produce one lite diff under several codecs:
+
+.. code-block:: python
+
+   base = hdiffpatch.diff_lite(old, new)
+   lite_lzma = hdiffpatch.recompress_lite(base, "lzma")
+   lite_tamp = hdiffpatch.recompress_lite(base, "tamp")
+
+===========  =============  ==============  ====================  ==============  ===============  ========  =========  ========
+compression  std diff (ms)  lite diff (ms)  lite recompress (ms)  std apply (ms)  lite apply (ms)  std size  lite size  lite/std
+===========  =============  ==============  ====================  ==============  ===============  ========  =========  ========
+none                  28.9            27.3                     —             0.5              0.2   161,041    637,195    395.7%
+zlib                  34.1           131.4                 108.9             1.0              1.0    99,772    106,275    106.5%
+lzma                  40.5            72.0                  41.8             3.6              3.4    92,647     96,859    104.5%
+lz4                   29.3            27.3                   0.4             0.5              0.2   131,067    148,758    113.5%
+lz4hc                 29.8           128.8                 102.9             0.5              0.3   120,571    121,172    100.5%
+tuz                  105.4           758.0                 724.4             1.2              2.1   104,363    105,910    101.5%
+tamp                  43.2            67.7                  40.0             1.2              1.5   110,711    125,726    113.6%
+===========  =============  ==============  ====================  ==============  ===============  ========  =========  ========
+
+The ``none`` row is a ~4x outlier because the uncompressed lite encoding stores many literal new-data bytes; with a codec those literals compress and the gap collapses to ~0.5-14%, so lite should be used with compression.

hdiffpatch-2.5.0/hdiffpatch/__init__.py

@@ -0,0 +1,109 @@
+# Don't manually change, let setuptools-scm handle it.
+__version__ = "0.0.0"
+
+__all__ = [
+    # Types and constants
+    "COMPRESSION_BROTLI",
+    "COMPRESSION_BZIP2",
+    "COMPRESSION_LZ4",
+    "COMPRESSION_LZ4HC",
+    "COMPRESSION_LZHAM",
+    "COMPRESSION_LZMA",
+    "COMPRESSION_LZMA2",
+    "COMPRESSION_NONE",
+    "COMPRESSION_TAMP",
+    "COMPRESSION_XZ",
+    "COMPRESSION_TUZ",
+    "COMPRESSION_ZLIB",
+    "COMPRESSION_ZSTD",
+    "CompressionType",
+    "LiteCompressionType",
+    # Exceptions
+    "HDiffPatchError",
+    # Core functions
+    "diff",
+    "diff_lite",
+    "apply",
+    "apply_lite",
+    "recompress",
+    "recompress_lite",
+    # Configuration classes
+    "BaseConfig",
+    "BrotliConfig",
+    "BZip2Config",
+    "ZlibConfig",
+    "ZlibStrategy",
+    "Lz4Config",
+    "Lz4HCConfig",
+    "LzhamConfig",
+    "LzmaConfig",
+    "Lzma2Config",
+    "TampConfig",
+    "XzConfig",
+    "TuzConfig",
+    "ZStdConfig",
+]
+
+from ._base_config import (
+    BaseConfig,
+)
+from ._brotli_config import (
+    BrotliConfig,
+)
+from ._bzip2_config import (
+    BZip2Config,
+)
+from ._c_extension import (
+    # Types and constants
+    COMPRESSION_BROTLI,
+    COMPRESSION_BZIP2,
+    COMPRESSION_LZ4,
+    COMPRESSION_LZ4HC,
+    COMPRESSION_LZHAM,
+    COMPRESSION_LZMA,
+    COMPRESSION_LZMA2,
+    COMPRESSION_NONE,
+    COMPRESSION_TAMP,
+    COMPRESSION_TUZ,
+    COMPRESSION_XZ,
+    COMPRESSION_ZLIB,
+    COMPRESSION_ZSTD,
+    CompressionType,
+    # Exceptions
+    HDiffPatchError,
+    LiteCompressionType,
+    # Core functions
+    apply,
+    apply_lite,
+    diff,
+    diff_lite,
+    recompress,
+    recompress_lite,
+)
+from ._lz4_config import (
+    Lz4Config,
+    Lz4HCConfig,
+)
+from ._lzham_config import (
+    LzhamConfig,
+)
+from ._lzma_config import (
+    Lzma2Config,
+    LzmaConfig,
+)
+from ._tamp_config import (
+    TampConfig,
+)
+from ._tuz_config import (
+    TuzConfig,
+)
+from ._xz_config import (
+    XzConfig,
+)
+from ._zlib_config import (
+    ZlibConfig,
+    ZlibStrategy,
+)
+from ._zstd_config import (
+    ZStdConfig,
+)

hdiffpatch-2.5.0/hdiffpatch/_brotli_config.py

@@ -0,0 +1,93 @@
+"""BrotliConfig class for configuring brotli compression parameters."""
+
+import attrs
+
+from ._base_config import BaseConfig
+
+
+@attrs.frozen
+class BrotliConfig(BaseConfig):
+    """Configuration for brotli compression parameters.
+
+    Parameters
+    ----------
+    level : int, default=9
+        Compression quality (0-11). Higher values give better compression but
+        are slower. 0 = fastest, 11 = best compression.
+    window : int, default=24
+        Window size as log2 (10-30). Larger windows give better compression
+        but use more memory. Windows above 24 use brotli's "large window"
+        extension, which standard (RFC 7932) brotli decoders reject. The
+        encoder shrinks the window to fit the input when the input is smaller.
+
+    Examples
+    --------
+    Fast compression with a small window
+
+    >>> config = BrotliConfig(level=1, window=16)
+
+    Best compression
+
+    >>> config = BrotliConfig(level=11, window=24)
+    """
+
+    level: int = attrs.field(
+        default=9,
+        validator=attrs.validators.and_(
+            attrs.validators.instance_of(int),
+            attrs.validators.ge(0),
+            attrs.validators.le(11),
+        ),
+    )
+    window: int = attrs.field(
+        default=24,
+        validator=attrs.validators.and_(
+            attrs.validators.instance_of(int),
+            attrs.validators.ge(10),
+            attrs.validators.le(30),
+        ),
+    )
+
+    @classmethod
+    def fast(cls) -> "BrotliConfig":
+        """Create a BrotliConfig optimized for speed.
+
+        Returns
+        -------
+        BrotliConfig
+            Configuration optimized for speed
+        """
+        return cls(level=1, window=18)
+
+    @classmethod
+    def balanced(cls) -> "BrotliConfig":
+        """Create a BrotliConfig with balanced speed/compression.
+
+        Returns
+        -------
+        BrotliConfig
+            Configuration with balanced speed/compression tradeoff
+        """
+        return cls(level=6, window=22)
+
+    @classmethod
+    def best_compression(cls) -> "BrotliConfig":
+        """Create a BrotliConfig optimized for best compression.
+
+        Returns
+        -------
+        BrotliConfig
+            Configuration optimized for best compression
+        """
+        return cls(level=11, window=24)
+
+    @classmethod
+    def minimal_memory(cls) -> "BrotliConfig":
+        """Create a BrotliConfig with minimal memory usage.
+
+        Returns
+        -------
+        BrotliConfig
+            Configuration with minimal memory usage
+        """
+        return cls(level=6, window=10)