rosetta-squint-hash 1.0.0__tar.gz

rosetta_squint_hash-1.0.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: rosetta-squint-hash
+Version: 1.0.0
+Summary: Cross-port-stable extensions to Python imagehash, mirroring the 5 ports of rosetta-squint-hash
+Author-email: Will Metcalf <william.metcalf@gmail.com>
+License: BSD-2-Clause
+Project-URL: Homepage, https://github.com/wmetcalf/rosetta-squint
+Project-URL: Repository, https://github.com/wmetcalf/rosetta-squint
+Project-URL: Issues, https://github.com/wmetcalf/rosetta-squint/issues
+Project-URL: Changelog, https://github.com/wmetcalf/rosetta-squint/blob/main/CHANGELOG.md
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: imagehash==4.3.2
+Requires-Dist: numpy<2.0,>=1.26
+Requires-Dist: Pillow==12.2.*
+Requires-Dist: PyWavelets<2.0,>=1.5
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: unpinned
+Requires-Dist: imagehash<5.0,>=4.3.2; extra == "unpinned"
+Requires-Dist: Pillow<14,>=12.2; extra == "unpinned"
+
+# rosetta_squint_hash — Python port (extensions over `imagehash`)
+
+A thin wrapper around the Python [`imagehash`](https://pypi.org/project/ImageHash/) package (4.3.2+) that adds the cross-port-stable extensions implemented across the 5 ports of `rosetta-squint-hash` (Rust, Go, Java, JS/TS, Swift).
+
+The v1 surface that's actually different from upstream `imagehash` is **one function**: `whash_db4_robust`. Everything else (`phash`, `dhash`, `whash(mode='haar')`, `whash(mode='db4')`, `phash_simple`, `dhash_vertical`, `colorhash`, `crop_resistant_hash`, hex round-trip) is re-exported from upstream unchanged.
+
+## Why this package exists
+
+Python `imagehash.whash(mode='db4')` and our 5 ports' `whashDb4` produce **the same hash** for ~93% of test fixtures. The other ~7% are pathological synthetic inputs (checkerboards, high-contrast geometric icons) where the algorithm computes a wavelet LL band whose values are mathematically exactly 0 — but float64 rounding produces tiny noise (~1e-17). The "is `coef > median`" comparison then depends on which side of zero the noise lands, which depends on the order of float additions, which depends on SIMD/FMA and compiler.
+
+PyWavelets' C+SIMD inner loop, Rust's f64 accumulation, Java's double loops, Go's column-first traversal, JS's Number arithmetic, and Swift's Double accumulation can disagree by ~10 bits out of 256 on those inputs. **Every implementation is "right" per IEEE 754 — the input is at a tie point.**
+
+`whash_db4_robust` resolves this by snapping `|coef| < 1e-12` to exactly 0 *before* the median + threshold step. All implementations now agree (cross-port stable) at the cost of those specific inputs producing different hex than `imagehash.whash(mode='db4')`.
+
+For real photos this never triggers; both functions return identical output.
+
+## Install
+
+```bash
+pip install -e .              # from python/
+```
+
+Not yet on PyPI.
+
+### Version policy
+
+The wrapper pins upstream dependencies to the exact versions our goldens were validated against:
+
+| Dep | Pinned to | Why |
+|---|---|---|
+| `imagehash` | `==4.3.2` | Algorithm output is what generates `spec/goldens.json`. New upstream release → potential drift → release of `rosetta-squint-hash` after re-validation. |
+| `Pillow` | `==10.4.*` | PIL's Lanczos resize, `Image.crop` rounding, `ImageFilter.GaussianBlur` box-radius formula, and grayscale conversion are all involved in our hash pipeline. A Pillow major-version bump can change any of these and silently break parity with the 5 other ports. |
+| `PyWavelets` | `>=1.5,<2.0` | db4 filter coefficients are mathematical constants; less drift risk, but bound the major version. |
+| `numpy` | `>=1.26,<2.0` | NumPy 2.0 changed some default dtypes and behaviors; pin to 1.x. |
+
+This is intentional. The upstream-tracker workflow (`.github/workflows/upstream-tracker.yml`) catches new upstream releases weekly and surfaces the goldens diff so a human can decide whether to bump and re-release.
+
+If you need to share a Python environment with packages requiring different Pillow / imagehash versions, install with the unpinned extra:
+
+```bash
+pip install rosetta-squint-hash[unpinned]
+```
+
+**Caveat:** with `[unpinned]` the cross-port byte-exact guarantee is no longer enforced by the wrapper — verify your own output matches `spec/goldens.json` before relying on it. The 5 non-Python ports are unaffected (they don't link to Pillow at all).
+
+## Usage
+
+```python
+import rosetta_squint_hash as rih
+from PIL import Image
+
+img = Image.open("photo.jpg")
+
+# Drop-in upstream imagehash:
+h_strict = rih.whash(img, mode="db4")            # matches imagehash exactly
+
+# Our cross-port-stable variant:
+h_robust = rih.whash_db4_robust(img, hash_size=8)
+
+print(str(h_strict))                              # hex, identical to imagehash.whash output
+print(str(h_robust))                              # hex, identical to Rust/Go/Java/JS/Swift output
+
+# On a real photo, the two agree:
+assert str(h_strict) == str(h_robust)
+
+# On a checkerboard, they will differ:
+checker = Image.open("spec/fixtures/checker-256.png")
+print(rih.whash(checker, mode="db4"))             # SIMD-dependent
+print(rih.whash_db4_robust(checker, hash_size=8)) # same on every platform
+```
+
+## When to pick which
+
+| Use case | Function |
+|---|---|
+| Matching against existing hashes stored from Python `imagehash` | `rih.whash(img, mode="db4")` |
+| Cross-language storage/lookup where every port (Python, Rust, Go, Java, JS, Swift) must produce the same hex for the same input | `rih.whash_db4_robust(img)` |
+| Hashing photographs (untrusted or trusted) | Either; output is identical for non-pathological inputs |
+| Hashing synthetic test inputs or geometric patterns | `rih.whash_db4_robust` if cross-port matters |
+
+## API
+
+```python
+def whash_db4_robust(
+    image: PIL.Image.Image,
+    hash_size: int = 8,
+    image_scale: int | None = None,
+) -> imagehash.ImageHash:
+    """Cross-port-stable variant of imagehash.whash(mode='db4').
+
+    See docstring in rosetta_squint_hash/_impl.py for the full algorithm.
+    """
+
+WHASH_DB4_ROBUST_EPS: float = 1e-12  # the ε threshold; fixed across ports
+```
+
+All other names re-exported from `imagehash` are accessible as `rosetta_squint_hash.<name>`.
+
+## Testing
+
+```bash
+cd python
+pip install -e ".[test]"
+pytest
+```
+
+Tests verify `whash_db4_robust` output against `spec/goldens.json` — the same goldens the 5 non-Python ports test against. The Python reference produces the goldens, so this is a self-consistency check; the value comes from confirming the per-port implementations match.
+
+## License
+
+BSD-2-Clause.

rosetta_squint_hash-1.0.0/README.md

@@ -0,0 +1,111 @@
+# rosetta_squint_hash — Python port (extensions over `imagehash`)
+
+A thin wrapper around the Python [`imagehash`](https://pypi.org/project/ImageHash/) package (4.3.2+) that adds the cross-port-stable extensions implemented across the 5 ports of `rosetta-squint-hash` (Rust, Go, Java, JS/TS, Swift).
+
+The v1 surface that's actually different from upstream `imagehash` is **one function**: `whash_db4_robust`. Everything else (`phash`, `dhash`, `whash(mode='haar')`, `whash(mode='db4')`, `phash_simple`, `dhash_vertical`, `colorhash`, `crop_resistant_hash`, hex round-trip) is re-exported from upstream unchanged.
+
+## Why this package exists
+
+Python `imagehash.whash(mode='db4')` and our 5 ports' `whashDb4` produce **the same hash** for ~93% of test fixtures. The other ~7% are pathological synthetic inputs (checkerboards, high-contrast geometric icons) where the algorithm computes a wavelet LL band whose values are mathematically exactly 0 — but float64 rounding produces tiny noise (~1e-17). The "is `coef > median`" comparison then depends on which side of zero the noise lands, which depends on the order of float additions, which depends on SIMD/FMA and compiler.
+
+PyWavelets' C+SIMD inner loop, Rust's f64 accumulation, Java's double loops, Go's column-first traversal, JS's Number arithmetic, and Swift's Double accumulation can disagree by ~10 bits out of 256 on those inputs. **Every implementation is "right" per IEEE 754 — the input is at a tie point.**
+
+`whash_db4_robust` resolves this by snapping `|coef| < 1e-12` to exactly 0 *before* the median + threshold step. All implementations now agree (cross-port stable) at the cost of those specific inputs producing different hex than `imagehash.whash(mode='db4')`.
+
+For real photos this never triggers; both functions return identical output.
+
+## Install
+
+```bash
+pip install -e .              # from python/
+```
+
+Not yet on PyPI.
+
+### Version policy
+
+The wrapper pins upstream dependencies to the exact versions our goldens were validated against:
+
+| Dep | Pinned to | Why |
+|---|---|---|
+| `imagehash` | `==4.3.2` | Algorithm output is what generates `spec/goldens.json`. New upstream release → potential drift → release of `rosetta-squint-hash` after re-validation. |
+| `Pillow` | `==10.4.*` | PIL's Lanczos resize, `Image.crop` rounding, `ImageFilter.GaussianBlur` box-radius formula, and grayscale conversion are all involved in our hash pipeline. A Pillow major-version bump can change any of these and silently break parity with the 5 other ports. |
+| `PyWavelets` | `>=1.5,<2.0` | db4 filter coefficients are mathematical constants; less drift risk, but bound the major version. |
+| `numpy` | `>=1.26,<2.0` | NumPy 2.0 changed some default dtypes and behaviors; pin to 1.x. |
+
+This is intentional. The upstream-tracker workflow (`.github/workflows/upstream-tracker.yml`) catches new upstream releases weekly and surfaces the goldens diff so a human can decide whether to bump and re-release.
+
+If you need to share a Python environment with packages requiring different Pillow / imagehash versions, install with the unpinned extra:
+
+```bash
+pip install rosetta-squint-hash[unpinned]
+```
+
+**Caveat:** with `[unpinned]` the cross-port byte-exact guarantee is no longer enforced by the wrapper — verify your own output matches `spec/goldens.json` before relying on it. The 5 non-Python ports are unaffected (they don't link to Pillow at all).
+
+## Usage
+
+```python
+import rosetta_squint_hash as rih
+from PIL import Image
+
+img = Image.open("photo.jpg")
+
+# Drop-in upstream imagehash:
+h_strict = rih.whash(img, mode="db4")            # matches imagehash exactly
+
+# Our cross-port-stable variant:
+h_robust = rih.whash_db4_robust(img, hash_size=8)
+
+print(str(h_strict))                              # hex, identical to imagehash.whash output
+print(str(h_robust))                              # hex, identical to Rust/Go/Java/JS/Swift output
+
+# On a real photo, the two agree:
+assert str(h_strict) == str(h_robust)
+
+# On a checkerboard, they will differ:
+checker = Image.open("spec/fixtures/checker-256.png")
+print(rih.whash(checker, mode="db4"))             # SIMD-dependent
+print(rih.whash_db4_robust(checker, hash_size=8)) # same on every platform
+```
+
+## When to pick which
+
+| Use case | Function |
+|---|---|
+| Matching against existing hashes stored from Python `imagehash` | `rih.whash(img, mode="db4")` |
+| Cross-language storage/lookup where every port (Python, Rust, Go, Java, JS, Swift) must produce the same hex for the same input | `rih.whash_db4_robust(img)` |
+| Hashing photographs (untrusted or trusted) | Either; output is identical for non-pathological inputs |
+| Hashing synthetic test inputs or geometric patterns | `rih.whash_db4_robust` if cross-port matters |
+
+## API
+
+```python
+def whash_db4_robust(
+    image: PIL.Image.Image,
+    hash_size: int = 8,
+    image_scale: int | None = None,
+) -> imagehash.ImageHash:
+    """Cross-port-stable variant of imagehash.whash(mode='db4').
+
+    See docstring in rosetta_squint_hash/_impl.py for the full algorithm.
+    """
+
+WHASH_DB4_ROBUST_EPS: float = 1e-12  # the ε threshold; fixed across ports
+```
+
+All other names re-exported from `imagehash` are accessible as `rosetta_squint_hash.<name>`.
+
+## Testing
+
+```bash
+cd python
+pip install -e ".[test]"
+pytest
+```
+
+Tests verify `whash_db4_robust` output against `spec/goldens.json` — the same goldens the 5 non-Python ports test against. The Python reference produces the goldens, so this is a self-consistency check; the value comes from confirming the per-port implementations match.
+
+## License
+
+BSD-2-Clause.

rosetta_squint_hash-1.0.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rosetta-squint-hash"
+version = "1.0.0"
+description = "Cross-port-stable extensions to Python imagehash, mirroring the 5 ports of rosetta-squint-hash"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "BSD-2-Clause" }
+authors = [
+    { name = "Will Metcalf", email = "william.metcalf@gmail.com" },
+]
+# Tight pinning policy: the cross-port byte-exact guarantee depends on the
+# specific upstream versions our spec/goldens.json was generated against.
+# A Pillow/imagehash/PyWavelets/numpy/scipy upgrade *may* change algorithm
+# output in ways that diverge from our 5 non-Python ports. We only relax
+# these pins when we cut a new rosetta-squint-hash release after re-running
+# all goldens against the new versions. See "Version policy" in README.
+#
+# To intentionally use looser pins (e.g. for compatibility with another
+# dependency in your environment), install with:
+#   pip install rosetta-squint-hash[unpinned]
+# and verify your output matches against spec/goldens.json yourself.
+dependencies = [
+    "imagehash==4.3.2",
+    "numpy>=1.26,<2.0",
+    "Pillow==12.2.*",       # tested against 12.2.0; allow patch-level only
+    "PyWavelets>=1.5,<2.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7",
+]
+# Opt-in escape hatch for users who need to share a Python environment with
+# packages requiring a different Pillow or imagehash version. Caveat
+# emptor — cross-port byte-exact parity is no longer guaranteed.
+unpinned = [
+    "imagehash>=4.3.2,<5.0",
+    "Pillow>=12.2,<14",
+]
+
+[project.urls]
+Homepage = "https://github.com/wmetcalf/rosetta-squint"
+Repository = "https://github.com/wmetcalf/rosetta-squint"
+Issues = "https://github.com/wmetcalf/rosetta-squint/issues"
+Changelog = "https://github.com/wmetcalf/rosetta-squint/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+include = ["rosetta_squint_hash*"]
+exclude = ["tests*"]
+
+# ─── Static analysis config (consumed by the CI lint job) ─────────────────
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+# Default rule set is conservative (pyflakes + pycodestyle E). The wrapper
+# is small so we don't need the full pyupgrade/bugbear pack; promote any of
+# these once the baseline is clean.
+select = ["E", "F", "W", "B"]
+ignore = [
+    # E501 line-too-long is enforced by line-length above; keep the rule on
+    # but ignore long URLs in comments via noqa per-line.
+    "E203",
+    # Allow `from X import *` for the re-export module (it's the whole point).
+    "F403",
+    "F401",
+]
+exclude = ["tests"]
+
+[tool.mypy]
+python_version = "3.9"
+ignore_missing_imports = true
+follow_imports = "silent"
+# strict=true is enforced via the CLI flag in CI (continue-on-error there so
+# baseline issues don't block) — keep this file lenient so the dev-side
+# `mypy rosetta_squint_hash` invocation works out of the box.

rosetta_squint_hash-1.0.0/rosetta_squint_hash/__init__.py

@@ -0,0 +1,97 @@
+"""rosetta_squint_hash — cross-port-stable variants of Python `imagehash`.
+
+This package re-exports the public surface of `imagehash` (PyPI 4.3.2+) and
+overrides every hash algorithm with a port-local wrapper. Two classes of
+overrides:
+
+1. **RGBA composite overrides** — every hash function (``average_hash``,
+   ``dhash``, ``dhash_vertical``, ``whash``, ``colorhash``,
+   ``crop_resistant_hash``, plus the four below) first composites RGBA / LA
+   input against opaque black using the truncated 8-bit formula
+   ``out_c = (src_c * alpha) // 255``. PIL's default ``convert('L')`` /
+   ``convert('HSV')`` on RGBA inputs would simply *drop* the alpha channel
+   without compositing, which diverges from every native port (Rust, Go,
+   Java, JS, Swift) on any partial-alpha input.
+
+2. **Snap-applying overrides** — ``phash``, ``phash_simple``, ``whash_db4``,
+   ``whash_db4_robust`` apply both the RGBA composite *and* a
+   snap-to-threshold tie-break (``bit = v > threshold + SNAP_EPS``). The
+   snap eliminates ULP-level FP-noise divergence between this Python
+   reference and the matching Rust / Go / Java / JS / Swift ports,
+   especially at large hash sizes (32, 64) where many DCT / wavelet
+   coefficients cluster within ULP of the threshold.
+
+The behaviour at sizes 4, 8, and 16 is *intentionally* allowed to drift
+from upstream `imagehash` for certain pathological inputs — see
+``spec/SPEC.md`` §"Threshold tie-break" for the rationale.
+
+Also provides:
+
+- ``whash_db4_robust`` — the original snap-to-zero extension for
+  pathological symmetric inputs. Now additionally applies the snap-to-
+  threshold tie-break and the RGBA composite preamble.
+
+Callers who need byte-exact upstream parity on any input (and are willing
+to give up cross-port stability for partial-alpha or near-threshold
+inputs) should ``import imagehash`` directly.
+
+See ``spec/SPEC.md`` for the full pipeline-by-pipeline specification.
+"""
+
+from __future__ import annotations
+
+# Re-export the upstream public surface that we DON'T override (constants,
+# hash classes, hex helpers). Every algorithm name is imported from
+# ._impl below as a port-local override.
+from imagehash import (  # noqa: F401
+    ANTIALIAS,
+    ImageHash,
+    ImageMultiHash,
+    hex_to_flathash,
+    hex_to_hash,
+    hex_to_multihash,
+    old_hex_to_hash,
+)
+
+from ._impl import (  # noqa: F401
+    SNAP_EPS,
+    WHASH_DB4_ROBUST_EPS,
+    average_hash,
+    colorhash,
+    crop_resistant_hash,
+    dhash,
+    dhash_vertical,
+    phash,
+    phash_simple,
+    whash,
+    whash_db4,
+    whash_db4_robust,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ANTIALIAS",
+    "ImageHash",
+    "ImageMultiHash",
+    "hex_to_flathash",
+    "hex_to_hash",
+    "hex_to_multihash",
+    "old_hex_to_hash",
+    # RGBA-compositing overrides
+    "average_hash",
+    "colorhash",
+    "crop_resistant_hash",
+    "dhash",
+    "dhash_vertical",
+    "whash",
+    # Snap + composite overrides
+    "phash",
+    "phash_simple",
+    "whash_db4",
+    "whash_db4_robust",
+    # Constants
+    "WHASH_DB4_ROBUST_EPS",
+    "SNAP_EPS",
+    "__version__",
+]

rosetta_squint_hash-1.0.0/rosetta_squint_hash/_impl.py

@@ -0,0 +1,394 @@
+"""Implementation of rosetta_squint_hash extensions and port-local algorithm
+overrides.
+
+This module provides:
+
+- ``WHASH_DB4_ROBUST_EPS`` / ``whash_db4_robust``: the original snap-to-zero
+  extension on top of ``imagehash.whash(mode='db4')`` for pathological
+  symmetric inputs.
+- ``SNAP_EPS``: the cross-port snap-to-threshold tie-break constant.
+- ``phash`` / ``phash_simple`` / ``whash_db4``: port-local replacements for
+  the matching upstream ``imagehash`` functions that apply the snap-to-
+  threshold tie-break. ``rosetta_squint_hash`` exports THESE (not the upstream
+  ones) so callers get cross-port stable hashes at every supported size.
+- ``average_hash`` / ``dhash`` / ``dhash_vertical`` / ``whash`` /
+  ``colorhash`` / ``crop_resistant_hash``: port-local wrappers around the
+  matching upstream functions that first composite RGBA → RGB on opaque
+  black using the same truncated 8-bit formula
+  (``out_c = floor((src_c * alpha) / 255)``) that the 5 native ports use.
+  PIL's ``image.convert('L')`` / ``convert('HSV')`` on an RGBA input would
+  simply *drop* the alpha channel, leaving the source RGB unchanged — which
+  diverges from every native port on any partially-transparent input.
+
+See ``__init__.py`` docstring and ``spec/SPEC.md`` §"Threshold tie-break"
+for the rationale.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pywt
+import scipy.fftpack
+import imagehash
+from PIL import Image
+
+
+def _composite_over_black_truncated(image: Image.Image) -> Image.Image:
+    """Composite an RGBA / LA image onto opaque black using truncated 8-bit
+    alpha-premultiplication (``out_c = (src_c * alpha) // 255``).
+
+    This matches the formula every native port uses (Rust ``img_rgb::to_rgb``,
+    JS ``toRgb`` with ``Math.trunc((r * a) / 255)``, Swift ``ImgRGB.toRGB``,
+    and — after the matching fix — the Go ``imgrgb.ToRGB`` and Java
+    ``BufferedImageRgb.convertToIntRgb``).
+
+    Why not PIL's own composite operations? Both ``Image.paste(mask=alpha)``
+    and ``Image.alpha_composite`` use round-half-up rounding (i.e.
+    ``(src_c * alpha + 127) // 255``). The 1-bit difference on partial-alpha
+    pixels cascades through the downstream Lanczos / DCT / wavelet pipelines
+    into ±1 LSB hash differences, which the differential fuzzer surfaces as
+    cross-port disagreements. The truncated form is therefore the normative
+    cross-port formula for this project.
+
+    Non-RGBA / non-LA inputs are returned in ``RGB`` mode via the standard
+    PIL ``convert('RGB')`` (which is a no-op fast path for already-RGB
+    images), so callers can immediately apply ``convert('L')`` /
+    ``convert('HSV')`` / etc. without further mode checks.
+
+    Args:
+        image: PIL Image in any mode.
+
+    Returns:
+        PIL Image in mode ``RGB``, with any partial alpha already
+        composited against opaque black. Caller is free to mutate (a new
+        image is returned).
+    """
+    mode = image.mode
+    if mode == "RGBA":
+        arr = np.asarray(image, dtype=np.uint16)
+        alpha = arr[..., 3:4]
+        rgb = (arr[..., :3] * alpha) // 255
+        return Image.fromarray(rgb.astype(np.uint8), "RGB")
+    if mode == "LA":
+        # Grayscale-with-alpha — same truncated multiply, then duplicate L
+        # into all three RGB channels so downstream ``convert('L')`` /
+        # ``convert('HSV')`` behave identically to native ports (which only
+        # ever see RGB inputs).
+        arr = np.asarray(image, dtype=np.uint16)
+        alpha = arr[..., 1:2]
+        luma = (arr[..., 0:1] * alpha) // 255
+        rgb = np.repeat(luma, 3, axis=-1)
+        return Image.fromarray(rgb.astype(np.uint8), "RGB")
+    if mode == "RGB":
+        return image
+    # Palette ("P") with transparency, "1", "L", "I", "F", "CMYK", "YCbCr",
+    # etc. — let PIL handle the convert; alpha (if any embedded in a "P"
+    # palette index) is not composited because non-RGBA / non-LA inputs don't
+    # carry a separate alpha plane this composite step is responsible for.
+    # Native ports' decoders also expand "P" without alpha here.
+    return image.convert("RGB")
+
+WHASH_DB4_ROBUST_EPS: float = 1e-12
+"""ε threshold for snap-to-zero. Coefficients with ``|c| < EPS`` are snapped
+to exactly 0 before median + threshold, eliminating ULP-level tie-point
+ambiguity on pathological symmetric inputs.
+
+Fixed across all 6 ports — do not vary per-call without coordinating a spec
+change."""
+
+SNAP_EPS: float = 1e-10
+"""ε threshold for the snap-to-threshold tie-break. Used by ``phash``,
+``phash_simple``, ``whash_db4``, and ``whash_db4_robust`` to deterministically
+map near-threshold coefficients to bit 0 (``bit = v > threshold + SNAP_EPS``).
+
+Sized to comfortably exceed cross-port FP accumulation noise (~1e-12 for DCT
+on uint8 inputs, ~1e-15 for db4 wavedec2 on uint8/255 inputs) while staying
+far below any meaningful signal. See ``spec/SPEC.md`` §"Threshold tie-break"."""
+
+
+def phash(image: Image.Image, hash_size: int = 8, highfreq_factor: int = 4) -> imagehash.ImageHash:
+    """Port-local ``phash`` with snap-to-threshold tie-break and cross-port
+    alpha compositing.
+
+    Identical to ``imagehash.phash`` except:
+    - any RGBA / LA input is first composited against opaque black via the
+      truncated 8-bit formula (see :func:`_composite_over_black_truncated`),
+      matching all 5 native ports rather than PIL's default alpha-drop;
+    - the per-bit comparison is ``v > median + SNAP_EPS`` (deterministic
+      bit 0 on ties) instead of strict ``v > median``. This eliminates
+      cross-port FP-noise divergence at large hash sizes (32, 64) where
+      many DCT coefficients land within one ULP of the median.
+    """
+    if hash_size < 2:
+        raise ValueError("Hash size must be greater than or equal to 2")
+    image = _composite_over_black_truncated(image)
+    img_size = hash_size * highfreq_factor
+    L = image.convert("L").resize((img_size, img_size), imagehash.ANTIALIAS)
+    pixels = np.asarray(L, dtype=np.float64)
+    dct = scipy.fftpack.dct(scipy.fftpack.dct(pixels, axis=0), axis=1)
+    block = dct[:hash_size, :hash_size]
+    med = np.median(block)
+    diff = block > med + SNAP_EPS
+    return imagehash.ImageHash(diff)
+
+
+def phash_simple(image: Image.Image, hash_size: int = 8, highfreq_factor: int = 4) -> imagehash.ImageHash:
+    """Port-local ``phash_simple`` with snap-to-threshold tie-break and
+    cross-port alpha compositing. See :func:`phash` for the rationale of
+    both deviations from upstream.
+    """
+    if hash_size < 2:
+        raise ValueError("Hash size must be greater than or equal to 2")
+    image = _composite_over_black_truncated(image)
+    img_size = hash_size * highfreq_factor
+    L = image.convert("L").resize((img_size, img_size), imagehash.ANTIALIAS)
+    pixels = np.asarray(L, dtype=np.float64)
+    dct = scipy.fftpack.dct(pixels)
+    dctlowfreq = dct[:hash_size, 1:hash_size + 1]
+    mean = dctlowfreq.mean()
+    diff = dctlowfreq > mean + SNAP_EPS
+    return imagehash.ImageHash(diff)
+
+
+def whash_db4(
+    image: Image.Image,
+    hash_size: int = 8,
+    image_scale: int | None = None,
+) -> imagehash.ImageHash:
+    """Port-local ``whash(mode='db4')`` with snap-to-threshold tie-break and
+    cross-port alpha compositing.
+
+    Pipeline matches ``imagehash.whash(image, hash_size, mode='db4',
+    remove_max_haar_ll=True)`` exactly, except (a) any RGBA / LA input is
+    first composited against opaque black via the truncated 8-bit formula
+    (see :func:`_composite_over_black_truncated`) and (b) the per-bit
+    comparison is ``v > median + SNAP_EPS`` instead of strict
+    ``v > median``. See :func:`phash` for the rationale.
+    """
+    if image_scale is not None:
+        assert image_scale & (image_scale - 1) == 0, "image_scale must be power of 2"
+    else:
+        image_natural_scale = 2 ** int(np.log2(min(image.size)))
+        image_scale = max(image_natural_scale, hash_size)
+
+    ll_max_level = int(np.log2(image_scale))
+    level = int(np.log2(hash_size))
+    assert hash_size & (hash_size - 1) == 0, "hash_size must be power of 2"
+    assert level <= ll_max_level, "hash_size in a wrong range"
+    dwt_level = ll_max_level - level
+
+    image = _composite_over_black_truncated(image)
+    L = image.convert("L").resize((image_scale, image_scale), imagehash.ANTIALIAS)
+    pixels = np.asarray(L) / 255.0
+
+    coeffs = pywt.wavedec2(pixels, "haar", level=ll_max_level)
+    coeffs = list(coeffs)
+    coeffs[0] *= 0
+    pixels = pywt.waverec2(coeffs, "haar")
+
+    coeffs = pywt.wavedec2(pixels, "db4", level=dwt_level)
+    dwt_low = coeffs[0]
+
+    med = np.median(dwt_low)
+    diff = dwt_low > med + SNAP_EPS
+    return imagehash.ImageHash(diff)
+
+
+def whash_db4_robust(
+    image: Image.Image,
+    hash_size: int = 8,
+    image_scale: int | None = None,
+) -> imagehash.ImageHash:
+    """Cross-port-stable variant of ``imagehash.whash(mode='db4')``.
+
+    Identical pipeline to ``imagehash.whash(image, hash_size, mode='db4',
+    remove_max_haar_ll=True)`` up to producing the LL band; then applies
+    BOTH stabilization steps::
+
+        dwt_low = np.where(np.abs(dwt_low) < WHASH_DB4_ROBUST_EPS, 0.0, dwt_low)
+        ...
+        diff = dwt_low > median + SNAP_EPS
+
+    The first step (snap-to-zero) handles pathological symmetric inputs whose
+    LL band is mathematically 0 + ULP-level noise; the second (snap-to-
+    threshold) handles natural images whose LL band has many coefficients
+    clustered near the median.
+
+    Effect:
+
+    - Real-world photographs: LL coefficients are O(0.1)–O(10) so neither snap
+      kicks in for non-tie values; output equals :func:`whash_db4` (modulo
+      bit assignments on ties).
+    - Pathological symmetric inputs: both snaps collapse near-zero / near-
+      median coefficients to a deterministic bit 0, so all 6 ports produce
+      identical hashes.
+
+    **Caveat:** for pathological inputs the output differs from upstream
+    ``imagehash.whash(mode='db4')``. Trade-off: cross-port stability vs.
+    upstream parity. Use this when stable hashing across language
+    implementations matters more than matching pre-existing imagehash output.
+
+    Args:
+        image: PIL Image.
+        hash_size: power-of-2 hash output side. Default 8.
+        image_scale: pre-resize scale (power of 2). Default = max image
+            natural scale, ``hash_size``.
+
+    Returns:
+        ``imagehash.ImageHash`` of shape ``(hash_size, hash_size)``.
+
+    Raises:
+        AssertionError: if ``hash_size`` is not a power of 2, or if
+            ``image_scale`` is provided and not a power of 2, or if
+            ``hash_size`` exceeds the allowed range for the input.
+    """
+    if image_scale is not None:
+        assert image_scale & (image_scale - 1) == 0, "image_scale must be power of 2"
+    else:
+        image_natural_scale = 2 ** int(np.log2(min(image.size)))
+        image_scale = max(image_natural_scale, hash_size)
+
+    ll_max_level = int(np.log2(image_scale))
+    level = int(np.log2(hash_size))
+    assert hash_size & (hash_size - 1) == 0, "hash_size must be power of 2"
+    assert level <= ll_max_level, "hash_size in a wrong range"
+    dwt_level = ll_max_level - level
+
+    image = _composite_over_black_truncated(image)
+    L = image.convert("L").resize((image_scale, image_scale), imagehash.ANTIALIAS)
+    pixels = np.asarray(L) / 255.0
+
+    coeffs = pywt.wavedec2(pixels, "haar", level=ll_max_level)
+    coeffs = list(coeffs)
+    coeffs[0] *= 0
+    pixels = pywt.waverec2(coeffs, "haar")
+
+    coeffs = pywt.wavedec2(pixels, "db4", level=dwt_level)
+    dwt_low = coeffs[0]
+
+    # First stabilization: snap |c| < WHASH_DB4_ROBUST_EPS to exactly 0.
+    dwt_low = np.where(np.abs(dwt_low) < WHASH_DB4_ROBUST_EPS, 0.0, dwt_low)
+
+    med = np.median(dwt_low)
+    # Second stabilization: snap coefficients within SNAP_EPS of the median
+    # to bit 0 via `v > median + SNAP_EPS`.
+    diff = dwt_low > med + SNAP_EPS
+    return imagehash.ImageHash(diff)
+
+
+# ─── RGBA-composite overrides for the remaining 6 upstream algorithms ────────
+#
+# These wrappers exist solely to apply :func:`_composite_over_black_truncated`
+# before forwarding into the upstream ``imagehash`` implementation. The
+# upstream functions otherwise call ``image.convert('L')`` (or
+# ``convert('HSV')``) directly on RGBA inputs, which would strip the alpha
+# channel without compositing. The 5 native ports all composite — see the
+# spec / triage report for the cross-port disagreement that motivated this.
+#
+# We DO forward to the upstream function (rather than re-implementing each
+# pipeline) so any future upstream bugfix in the body of e.g. ``dhash``
+# remains live. Only the alpha-handling preamble is overridden.
+
+
+def average_hash(image: Image.Image, hash_size: int = 8, mean=np.mean) -> imagehash.ImageHash:
+    """Port-local ``average_hash`` with cross-port alpha compositing.
+
+    Identical to ``imagehash.average_hash`` except RGBA / LA inputs are
+    composited against opaque black using the truncated 8-bit formula
+    before the upstream algorithm runs. See
+    :func:`_composite_over_black_truncated`.
+    """
+    return imagehash.average_hash(
+        _composite_over_black_truncated(image), hash_size=hash_size, mean=mean
+    )
+
+
+def dhash(image: Image.Image, hash_size: int = 8) -> imagehash.ImageHash:
+    """Port-local ``dhash`` with cross-port alpha compositing.
+
+    See :func:`average_hash` for the rationale.
+    """
+    return imagehash.dhash(
+        _composite_over_black_truncated(image), hash_size=hash_size
+    )
+
+
+def dhash_vertical(image: Image.Image, hash_size: int = 8) -> imagehash.ImageHash:
+    """Port-local ``dhash_vertical`` with cross-port alpha compositing.
+
+    See :func:`average_hash` for the rationale.
+    """
+    return imagehash.dhash_vertical(
+        _composite_over_black_truncated(image), hash_size=hash_size
+    )
+
+
+def whash(
+    image: Image.Image,
+    hash_size: int = 8,
+    image_scale: int | None = None,
+    mode: str = "haar",
+    remove_max_haar_ll: bool = True,
+) -> imagehash.ImageHash:
+    """Port-local ``whash`` with cross-port alpha compositing.
+
+    Identical to ``imagehash.whash`` except RGBA / LA inputs are composited
+    against opaque black using the truncated 8-bit formula before the
+    upstream algorithm runs. Callers using ``mode='db4'`` should prefer
+    :func:`whash_db4` (which additionally applies the snap-to-threshold
+    tie-break) for cross-port stable hashes; this :func:`whash` wrapper is
+    here so ``whash(mode='haar')`` callers also get correct RGBA semantics
+    without needing to know the underlying machinery.
+    """
+    return imagehash.whash(
+        _composite_over_black_truncated(image),
+        hash_size=hash_size,
+        image_scale=image_scale,
+        mode=mode,
+        remove_max_haar_ll=remove_max_haar_ll,
+    )
+
+
+def colorhash(image: Image.Image, binbits: int = 3) -> imagehash.ImageHash:
+    """Port-local ``colorhash`` with cross-port alpha compositing.
+
+    ``imagehash.colorhash`` internally calls both ``image.convert('L')`` and
+    ``image.convert('HSV')`` on the input; PIL's RGBA→HSV conversion likewise
+    strips alpha rather than compositing. We composite first so the HSV
+    histogram is computed from the same RGB pixels the 5 native ports use.
+    """
+    return imagehash.colorhash(
+        _composite_over_black_truncated(image), binbits=binbits
+    )
+
+
+def crop_resistant_hash(
+    image: Image.Image,
+    hash_func=None,
+    limit_segments: int | None = None,
+    segment_threshold: int = 128,
+    min_segment_size: int = 500,
+    segmentation_image_size: int = 300,
+) -> imagehash.ImageMultiHash:
+    """Port-local ``crop_resistant_hash`` with cross-port alpha compositing.
+
+    Composites the input once at the top of the pipeline so the
+    segmentation pass *and* each per-segment hash both see RGB pixels with
+    alpha already premultiplied against black. The default ``hash_func`` is
+    :func:`dhash` (the port-local snap/composite-applying wrapper, not
+    upstream's ``imagehash.dhash``) so per-segment hashes also see the
+    cross-port semantics — but on the composited RGB input that's already a
+    no-op for the alpha path, so the wrapper is only providing the
+    composite preamble belt-and-braces.
+    """
+    composited = _composite_over_black_truncated(image)
+    if hash_func is None:
+        hash_func = dhash
+    return imagehash.crop_resistant_hash(
+        composited,
+        hash_func=hash_func,
+        limit_segments=limit_segments,
+        segment_threshold=segment_threshold,
+        min_segment_size=min_segment_size,
+        segmentation_image_size=segmentation_image_size,
+    )

rosetta_squint_hash-1.0.0/rosetta_squint_hash.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: rosetta-squint-hash
+Version: 1.0.0
+Summary: Cross-port-stable extensions to Python imagehash, mirroring the 5 ports of rosetta-squint-hash
+Author-email: Will Metcalf <william.metcalf@gmail.com>
+License: BSD-2-Clause
+Project-URL: Homepage, https://github.com/wmetcalf/rosetta-squint
+Project-URL: Repository, https://github.com/wmetcalf/rosetta-squint
+Project-URL: Issues, https://github.com/wmetcalf/rosetta-squint/issues
+Project-URL: Changelog, https://github.com/wmetcalf/rosetta-squint/blob/main/CHANGELOG.md
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: imagehash==4.3.2
+Requires-Dist: numpy<2.0,>=1.26
+Requires-Dist: Pillow==12.2.*
+Requires-Dist: PyWavelets<2.0,>=1.5
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: unpinned
+Requires-Dist: imagehash<5.0,>=4.3.2; extra == "unpinned"
+Requires-Dist: Pillow<14,>=12.2; extra == "unpinned"
+
+# rosetta_squint_hash — Python port (extensions over `imagehash`)
+
+A thin wrapper around the Python [`imagehash`](https://pypi.org/project/ImageHash/) package (4.3.2+) that adds the cross-port-stable extensions implemented across the 5 ports of `rosetta-squint-hash` (Rust, Go, Java, JS/TS, Swift).
+
+The v1 surface that's actually different from upstream `imagehash` is **one function**: `whash_db4_robust`. Everything else (`phash`, `dhash`, `whash(mode='haar')`, `whash(mode='db4')`, `phash_simple`, `dhash_vertical`, `colorhash`, `crop_resistant_hash`, hex round-trip) is re-exported from upstream unchanged.
+
+## Why this package exists
+
+Python `imagehash.whash(mode='db4')` and our 5 ports' `whashDb4` produce **the same hash** for ~93% of test fixtures. The other ~7% are pathological synthetic inputs (checkerboards, high-contrast geometric icons) where the algorithm computes a wavelet LL band whose values are mathematically exactly 0 — but float64 rounding produces tiny noise (~1e-17). The "is `coef > median`" comparison then depends on which side of zero the noise lands, which depends on the order of float additions, which depends on SIMD/FMA and compiler.
+
+PyWavelets' C+SIMD inner loop, Rust's f64 accumulation, Java's double loops, Go's column-first traversal, JS's Number arithmetic, and Swift's Double accumulation can disagree by ~10 bits out of 256 on those inputs. **Every implementation is "right" per IEEE 754 — the input is at a tie point.**
+
+`whash_db4_robust` resolves this by snapping `|coef| < 1e-12` to exactly 0 *before* the median + threshold step. All implementations now agree (cross-port stable) at the cost of those specific inputs producing different hex than `imagehash.whash(mode='db4')`.
+
+For real photos this never triggers; both functions return identical output.
+
+## Install
+
+```bash
+pip install -e .              # from python/
+```
+
+Not yet on PyPI.
+
+### Version policy
+
+The wrapper pins upstream dependencies to the exact versions our goldens were validated against:
+
+| Dep | Pinned to | Why |
+|---|---|---|
+| `imagehash` | `==4.3.2` | Algorithm output is what generates `spec/goldens.json`. New upstream release → potential drift → release of `rosetta-squint-hash` after re-validation. |
+| `Pillow` | `==10.4.*` | PIL's Lanczos resize, `Image.crop` rounding, `ImageFilter.GaussianBlur` box-radius formula, and grayscale conversion are all involved in our hash pipeline. A Pillow major-version bump can change any of these and silently break parity with the 5 other ports. |
+| `PyWavelets` | `>=1.5,<2.0` | db4 filter coefficients are mathematical constants; less drift risk, but bound the major version. |
+| `numpy` | `>=1.26,<2.0` | NumPy 2.0 changed some default dtypes and behaviors; pin to 1.x. |
+
+This is intentional. The upstream-tracker workflow (`.github/workflows/upstream-tracker.yml`) catches new upstream releases weekly and surfaces the goldens diff so a human can decide whether to bump and re-release.
+
+If you need to share a Python environment with packages requiring different Pillow / imagehash versions, install with the unpinned extra:
+
+```bash
+pip install rosetta-squint-hash[unpinned]
+```
+
+**Caveat:** with `[unpinned]` the cross-port byte-exact guarantee is no longer enforced by the wrapper — verify your own output matches `spec/goldens.json` before relying on it. The 5 non-Python ports are unaffected (they don't link to Pillow at all).
+
+## Usage
+
+```python
+import rosetta_squint_hash as rih
+from PIL import Image
+
+img = Image.open("photo.jpg")
+
+# Drop-in upstream imagehash:
+h_strict = rih.whash(img, mode="db4")            # matches imagehash exactly
+
+# Our cross-port-stable variant:
+h_robust = rih.whash_db4_robust(img, hash_size=8)
+
+print(str(h_strict))                              # hex, identical to imagehash.whash output
+print(str(h_robust))                              # hex, identical to Rust/Go/Java/JS/Swift output
+
+# On a real photo, the two agree:
+assert str(h_strict) == str(h_robust)
+
+# On a checkerboard, they will differ:
+checker = Image.open("spec/fixtures/checker-256.png")
+print(rih.whash(checker, mode="db4"))             # SIMD-dependent
+print(rih.whash_db4_robust(checker, hash_size=8)) # same on every platform
+```
+
+## When to pick which
+
+| Use case | Function |
+|---|---|
+| Matching against existing hashes stored from Python `imagehash` | `rih.whash(img, mode="db4")` |
+| Cross-language storage/lookup where every port (Python, Rust, Go, Java, JS, Swift) must produce the same hex for the same input | `rih.whash_db4_robust(img)` |
+| Hashing photographs (untrusted or trusted) | Either; output is identical for non-pathological inputs |
+| Hashing synthetic test inputs or geometric patterns | `rih.whash_db4_robust` if cross-port matters |
+
+## API
+
+```python
+def whash_db4_robust(
+    image: PIL.Image.Image,
+    hash_size: int = 8,
+    image_scale: int | None = None,
+) -> imagehash.ImageHash:
+    """Cross-port-stable variant of imagehash.whash(mode='db4').
+
+    See docstring in rosetta_squint_hash/_impl.py for the full algorithm.
+    """
+
+WHASH_DB4_ROBUST_EPS: float = 1e-12  # the ε threshold; fixed across ports
+```
+
+All other names re-exported from `imagehash` are accessible as `rosetta_squint_hash.<name>`.
+
+## Testing
+
+```bash
+cd python
+pip install -e ".[test]"
+pytest
+```
+
+Tests verify `whash_db4_robust` output against `spec/goldens.json` — the same goldens the 5 non-Python ports test against. The Python reference produces the goldens, so this is a self-consistency check; the value comes from confirming the per-port implementations match.
+
+## License
+
+BSD-2-Clause.

rosetta_squint_hash-1.0.0/rosetta_squint_hash.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+rosetta_squint_hash/__init__.py
+rosetta_squint_hash/_impl.py
+rosetta_squint_hash.egg-info/PKG-INFO
+rosetta_squint_hash.egg-info/SOURCES.txt
+rosetta_squint_hash.egg-info/dependency_links.txt
+rosetta_squint_hash.egg-info/requires.txt
+rosetta_squint_hash.egg-info/top_level.txt
+tests/test_reexports.py
+tests/test_whash_db4_robust.py

rosetta_squint_hash-1.0.0/rosetta_squint_hash.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rosetta_squint_hash-1.0.0/rosetta_squint_hash.egg-info/requires.txt

@@ -0,0 +1,11 @@
+imagehash==4.3.2
+numpy<2.0,>=1.26
+Pillow==12.2.*
+PyWavelets<2.0,>=1.5
+
+[test]
+pytest>=7
+
+[unpinned]
+imagehash<5.0,>=4.3.2
+Pillow<14,>=12.2

rosetta_squint_hash-1.0.0/rosetta_squint_hash.egg-info/top_level.txt

@@ -0,0 +1 @@
+rosetta_squint_hash

rosetta_squint_hash-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rosetta_squint_hash-1.0.0/tests/test_reexports.py

@@ -0,0 +1,218 @@
+"""Verify that rosetta_squint_hash re-exports the upstream `imagehash` surface
+correctly: each public function/class is importable, callable with the same
+signature, and produces byte-exact output identical to calling `imagehash`
+directly (since it IS the same function — these tests guard against
+accidental wrapping or shadowing).
+
+These also serve as a self-consistency check: running them against
+spec/goldens.json proves the goldens were generated by the same upstream
+version we're now re-exporting.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+from pathlib import Path
+
+import numpy as np
+import pytest
+from PIL import Image
+
+import imagehash
+import rosetta_squint_hash as rih
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+SPEC = REPO_ROOT / "spec"
+GOLDENS_PATH = SPEC / "goldens.json"
+DECODED_DIR = SPEC / "decoded"
+FIXTURES_DIR = SPEC / "fixtures"
+
+
+def _load_goldens() -> dict:
+    return json.loads(GOLDENS_PATH.read_text())
+
+
+def _load_predecoded(fixture_name: str) -> Image.Image:
+    path = DECODED_DIR / f"{fixture_name}.rgb.bin"
+    blob = path.read_bytes()
+    w, h = struct.unpack("<II", blob[:8])
+    rgb = np.frombuffer(blob[8:], dtype=np.uint8).reshape((h, w, 3))
+    return Image.fromarray(rgb, mode="RGB")
+
+
+def _sized_cases(algo: str) -> list[tuple[str, int, str]]:
+    g = _load_goldens()
+    algo_entry = g["algorithms"][algo]
+    out: list[tuple[str, int, str]] = []
+    for fix, sizes in sorted(algo_entry["fixtures"].items()):
+        for size_str, hex_str in sorted(sizes.items(), key=lambda kv: int(kv[0])):
+            if hex_str is None:
+                continue
+            out.append((fix, int(size_str), hex_str))
+    return out
+
+
+# --- Re-export identity checks ---
+
+def test_imagehash_version_matches_pin():
+    """Detect upstream version drift early."""
+    # Spec pins 4.3.2; allow any 4.3.x.
+    assert imagehash.__version__.startswith("4.3."), imagehash.__version__
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        "ImageHash",
+        "ImageMultiHash",
+        "hex_to_flathash",
+        "hex_to_hash",
+        "hex_to_multihash",
+        "old_hex_to_hash",
+    ],
+)
+def test_reexport_identity(name: str):
+    """Each name on rih MUST be the same object as the one on imagehash —
+    not a wrapper or alias. This list now only covers non-algorithm
+    re-exports (hash classes, hex helpers). Every algorithm name (phash,
+    phash_simple, whash_db4, whash_db4_robust, average_hash, dhash,
+    dhash_vertical, whash, colorhash, crop_resistant_hash) is a port-local
+    wrapper — see :func:`test_algorithm_override_is_not_upstream`."""
+    assert getattr(rih, name) is getattr(imagehash, name), (
+        f"{name}: rih.{name} is not imagehash.{name}"
+    )
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        # Snap-applying overrides (also composite RGBA)
+        "phash",
+        "phash_simple",
+        "whash_db4",
+        "whash_db4_robust",
+        # RGBA-compositing overrides (forward to upstream after composite)
+        "average_hash",
+        "dhash",
+        "dhash_vertical",
+        "whash",
+        "colorhash",
+        "crop_resistant_hash",
+    ],
+)
+def test_algorithm_override_is_not_upstream(name: str):
+    """Every algorithm exposed on rih must be a port-local wrapper, NOT the
+    upstream ``imagehash`` function. The snap-applying overrides apply
+    SNAP_EPS / EPS; the rest apply the RGBA → RGB composite preamble. Both
+    classes are necessary for cross-port byte-exact parity."""
+    if hasattr(imagehash, name):
+        assert getattr(rih, name) is not getattr(imagehash, name), (
+            f"{name}: rih.{name} must be a port-local override, not the upstream function"
+        )
+    assert callable(getattr(rih, name))
+
+
+def test_extension_constant_exposed():
+    assert isinstance(rih.WHASH_DB4_ROBUST_EPS, float)
+    assert rih.WHASH_DB4_ROBUST_EPS == 1e-12
+    assert isinstance(rih.SNAP_EPS, float)
+    assert rih.SNAP_EPS == 1e-10
+
+
+def test_extension_function_exposed():
+    assert callable(rih.whash_db4_robust)
+
+
+# --- End-to-end byte-exact checks via re-exported functions ---
+
+@pytest.mark.parametrize("fixture,size,expected_hex", _sized_cases("average_hash"),
+                          ids=lambda v: str(v))
+def test_reexport_average_hash_matches_goldens(fixture: str, size: int, expected_hex: str):
+    """`rih.average_hash` must produce the same hex as the frozen golden."""
+    img = _load_predecoded(fixture)
+    h = rih.average_hash(img, hash_size=size)
+    assert str(h) == expected_hex, (
+        f"{fixture} size={size}: rih.average_hash diverged from imagehash 4.3.2 — "
+        f"either upstream changed or the re-export is wrapped"
+    )
+
+
+@pytest.mark.parametrize("fixture,size,expected_hex", _sized_cases("phash"),
+                          ids=lambda v: str(v))
+def test_reexport_phash_matches_goldens(fixture: str, size: int, expected_hex: str):
+    img = _load_predecoded(fixture)
+    h = rih.phash(img, hash_size=size)
+    assert str(h) == expected_hex
+
+
+@pytest.mark.parametrize("fixture,size,expected_hex", _sized_cases("dhash"),
+                          ids=lambda v: str(v))
+def test_reexport_dhash_matches_goldens(fixture: str, size: int, expected_hex: str):
+    img = _load_predecoded(fixture)
+    h = rih.dhash(img, hash_size=size)
+    assert str(h) == expected_hex
+
+
+@pytest.mark.parametrize("fixture,size,expected_hex", _sized_cases("phash_simple"),
+                          ids=lambda v: str(v))
+def test_reexport_phash_simple_matches_goldens(fixture: str, size: int, expected_hex: str):
+    img = _load_predecoded(fixture)
+    h = rih.phash_simple(img, hash_size=size)
+    assert str(h) == expected_hex
+
+
+@pytest.mark.parametrize("fixture,size,expected_hex", _sized_cases("dhash_vertical"),
+                          ids=lambda v: str(v))
+def test_reexport_dhash_vertical_matches_goldens(fixture: str, size: int, expected_hex: str):
+    img = _load_predecoded(fixture)
+    h = rih.dhash_vertical(img, hash_size=size)
+    assert str(h) == expected_hex
+
+
+@pytest.mark.parametrize("fixture,size,expected_hex", _sized_cases("whash_haar"),
+                          ids=lambda v: str(v))
+def test_reexport_whash_haar_matches_goldens(fixture: str, size: int, expected_hex: str):
+    img = _load_predecoded(fixture)
+    h = rih.whash(img, hash_size=size, mode="haar", remove_max_haar_ll=True)
+    assert str(h) == expected_hex
+
+
+# --- crop_resistant_hash + ImageMultiHash via re-export ---
+
+def _multihash_cases() -> list[tuple[str, str]]:
+    g = _load_goldens()
+    algo = g["algorithms"].get("crop_resistant_hash")
+    if not algo:
+        return []
+    return [(fix, sizes["default"]) for fix, sizes in sorted(algo["fixtures"].items())]
+
+
+@pytest.mark.parametrize("fixture,expected_hex", _multihash_cases(),
+                          ids=lambda v: str(v))
+def test_reexport_crop_resistant_hash_matches_goldens(fixture: str, expected_hex: str):
+    """Verifies that imagehash.crop_resistant_hash via the re-export still
+    produces what's in goldens.json. If this fails after an `imagehash`
+    upgrade, the goldens are stale and need regeneration."""
+    img = Image.open(FIXTURES_DIR / fixture)
+    multihash = rih.crop_resistant_hash(img)
+    assert str(multihash) == expected_hex
+
+
+def test_imagemultihash_subtract_returns_float():
+    """Documented invariant: ImageMultiHash distance is float, not int."""
+    img = Image.open(FIXTURES_DIR / "peppers.png")
+    a = rih.crop_resistant_hash(img)
+    b = rih.crop_resistant_hash(img)
+    d = a - b
+    assert isinstance(d, float), f"distance is {type(d).__name__}, expected float"
+    assert d == 0.0, "identical images should have distance 0.0"
+
+
+def test_hex_to_multihash_round_trip():
+    img = Image.open(FIXTURES_DIR / "peppers.png")
+    mh = rih.crop_resistant_hash(img)
+    s = str(mh)
+    restored = rih.hex_to_multihash(s)
+    assert str(restored) == s, "hex round-trip failed"

rosetta_squint_hash-1.0.0/tests/test_whash_db4_robust.py

@@ -0,0 +1,104 @@
+"""Group-2 byte-exact tests: rosetta_squint_hash.whash_db4_robust output
+matches spec/goldens.json on all 21 fixtures × 2 sizes. The goldens are
+generated from this same Python implementation (via spec/regenerate.py),
+so this is a self-consistency check.
+
+The value of running this test is that the other 5 ports (Rust, Go, Java,
+JS, Swift) test against the same goldens — so all 6 implementations
+agreeing means cross-port stability.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+from pathlib import Path
+
+import numpy as np
+import pytest
+from PIL import Image
+
+import rosetta_squint_hash as rih
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+SPEC = REPO_ROOT / "spec"
+GOLDENS_PATH = SPEC / "goldens.json"
+FIXTURES_DIR = SPEC / "fixtures"
+DECODED_DIR = SPEC / "decoded"
+
+
+def _load_goldens() -> dict:
+    return json.loads(GOLDENS_PATH.read_text())
+
+
+def _load_predecoded(fixture_name: str) -> Image.Image:
+    """Read the spec/decoded/<fixture>.rgb.bin and reconstruct a PIL Image."""
+    path = DECODED_DIR / f"{fixture_name}.rgb.bin"
+    blob = path.read_bytes()
+    w, h = struct.unpack("<II", blob[:8])
+    rgb = np.frombuffer(blob[8:], dtype=np.uint8).reshape((h, w, 3))
+    return Image.fromarray(rgb, mode="RGB")
+
+
+def _algorithm_cases(algo_name: str) -> list[tuple[str, int, str]]:
+    goldens = _load_goldens()
+    algo = goldens["algorithms"][algo_name]
+    cases: list[tuple[str, int, str]] = []
+    for fixture, sizes in sorted(algo["fixtures"].items()):
+        for size_str, hex_str in sorted(sizes.items(), key=lambda kv: int(kv[0])):
+            if hex_str is None:
+                continue  # fixtures too small for this size
+            cases.append((fixture, int(size_str), hex_str))
+    return cases
+
+
+@pytest.mark.parametrize(
+    "fixture,size,expected_hex",
+    _algorithm_cases("whash_db4_robust"),
+    ids=lambda v: str(v),
+)
+def test_whash_db4_robust_matches_goldens(fixture: str, size: int, expected_hex: str):
+    """Every fixture × size produces the exact hex committed in goldens.json."""
+    img = _load_predecoded(fixture)
+    h = rih.whash_db4_robust(img, hash_size=size)
+    assert str(h) == expected_hex, (
+        f"fixture={fixture} size={size}\n"
+        f"  got      {h}\n"
+        f"  expected {expected_hex}"
+    )
+
+
+def test_strict_and_robust_match_on_real_photo():
+    """For a real photograph, whash and whash_db4_robust must agree.
+    Demonstrates that the snap-to-zero step does NOT affect non-pathological
+    inputs — only pathological synthetic patterns trigger it."""
+    img = _load_predecoded("peppers.png")
+    h_strict = rih.whash(img, mode="db4")
+    h_robust = rih.whash_db4_robust(img)
+    assert str(h_strict) == str(h_robust), (
+        f"real photo whash output disagreed:\n"
+        f"  strict {h_strict}\n"
+        f"  robust {h_robust}"
+    )
+
+
+def test_strict_and_robust_differ_on_checker():
+    """For a perfectly symmetric input (checker pattern), the strict and
+    robust variants should produce different hashes. The strict variant's
+    output depends on PyWavelets' SIMD path; the robust variant's output is
+    cross-port stable."""
+    img = _load_predecoded("checker-256.png")
+    h_strict = rih.whash(img, hash_size=16, mode="db4")
+    h_robust = rih.whash_db4_robust(img, hash_size=16)
+    assert str(h_strict) != str(h_robust), (
+        "Expected strict and robust to disagree on the checker pattern; "
+        "if they agree, the snap-to-zero step is not actually doing anything "
+        "and the test is meaningless."
+    )
+
+
+def test_eps_constant():
+    """Ensure the epsilon constant is the same value used by the 5 other
+    ports (1e-12). Hardcoded — must NOT vary per-call."""
+    assert rih.WHASH_DB4_ROBUST_EPS == 1e-12