rosetta-squint 1.0.0__tar.gz

rosetta_squint-1.0.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: rosetta-squint
+Version: 1.0.0
+Summary: Cross-language byte-exact perceptual image hashing — decode + hash in one call
+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: rosetta-squint-hash<2.0,>=1.0.0
+Requires-Dist: Pillow==12.2.*
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# rosetta_squint — Python convenience API
+
+Point at an image file or pass in raw image bytes; get back the same perceptual hash hex string that every other `rosetta-squint` port produces for the same input.
+
+## Install
+
+```bash
+pip install -e ../../hash/python                    # rosetta-squint-hash (wrapper around imagehash)
+pip install -e .                                    # this package
+```
+
+(Not on PyPI yet — both are local.)
+
+## Usage
+
+```python
+import rosetta_squint as rs
+
+# Path on disk
+h = rs.phash("photo.jpg", 8)
+print(h)                                            # "c3f8a1b27d0e4f96"
+
+# Raw image bytes (from an HTTP response, a database BLOB, a multipart upload)
+with open("photo.jpg", "rb") as f:
+    h = rs.phash_bytes(f.read(), 8)
+
+# Every algorithm available has both flavors:
+rs.average_hash(path, 8)       # rs.average_hash_bytes(bytes, 8)
+rs.phash(path, 8)              # rs.phash_bytes(bytes, 8)
+rs.phash_simple(path, 8)       # rs.phash_simple_bytes(bytes, 8)
+rs.dhash(path, 8)              # rs.dhash_bytes(bytes, 8)
+rs.dhash_vertical(path, 8)     # rs.dhash_vertical_bytes(bytes, 8)
+rs.whash_haar(path, 8)         # rs.whash_haar_bytes(bytes, 8)
+rs.whash_db4(path, 8)          # rs.whash_db4_bytes(bytes, 8)
+rs.whash_db4_robust(path, 8)   # rs.whash_db4_robust_bytes(bytes, 8) — cross-port-stable
+rs.colorhash(path, 3)          # rs.colorhash_bytes(bytes, 3) — takes binbits
+rs.crop_resistant_hash(path)   # rs.crop_resistant_hash_bytes(bytes) — no size, returns ImageMultiHash
+
+# Hex round-trips:
+restored = rs.hex_to_hash("c3f8a1b27d0e4f96")
+restored = rs.hex_to_flathash("...", hashsize=3)
+restored = rs.hex_to_multihash("hex1,hex2,hex3")
+```
+
+## Cross-port equivalence
+
+The output of `rs.phash("photo.jpg", 8)` is the same hex string as you'd get from the Rust, Go, Java, JS, or Swift `rosetta-squint` ports given the same byte input. **Verified live for `imagehash.png` at size 8: `ba8c84536bd3c366` across Python, Go, Java, JS, Swift.**
+
+## Decode strategy
+
+| Format | Decoder | Why |
+|---|---|---|
+| BMP, PNG, GIF, JPEG, WebP, TIFF | PIL/Pillow (system) | The canonical Python decoders; the goldens used to validate the 5 native ports were generated by PIL itself, so output matches by construction. |
+| HEIC | ctypes wrapper around system `libheif.so.1` | pillow-heif bundles libheif 1.21.2 in its wheel; the 5 native ports link to system libheif 1.17.6. The wrapper avoids the ±1 px divergence. |
+
+If you already have a `PIL.Image.Image` (from `PIL.Image.open(...)`, a thumbnailer, etc.), use the `rosetta_squint_hash` lower-level API directly — the squint layer's only job is the decode step:
+
+```python
+import rosetta_squint_hash as rih
+from PIL import Image
+img = Image.open("photo.jpg")
+h = rih.phash(img, hash_size=8)
+```
+
+## Dependencies
+
+- `rosetta_squint_hash` (which re-exports `imagehash==4.3.2` + adds `whash_db4_robust`)
+- `Pillow==12.2.*`
+
+Tight pins are intentional. See [`../../hash/python/README.md`](../../hash/python/README.md) under "Version policy" for the upgrade workflow.
+
+## Testing
+
+```bash
+pytest
+```
+
+Tests verify (1) path/bytes parity for every algorithm, (2) chain consistency between `rs.phash(path)` and `imagehash.phash(rs.decode_file(path))`, (3) cross-port byte-exact equality with Go/Java/JS for `imagehash.png`.

rosetta_squint-1.0.0/README.md

@@ -0,0 +1,78 @@
+# rosetta_squint — Python convenience API
+
+Point at an image file or pass in raw image bytes; get back the same perceptual hash hex string that every other `rosetta-squint` port produces for the same input.
+
+## Install
+
+```bash
+pip install -e ../../hash/python                    # rosetta-squint-hash (wrapper around imagehash)
+pip install -e .                                    # this package
+```
+
+(Not on PyPI yet — both are local.)
+
+## Usage
+
+```python
+import rosetta_squint as rs
+
+# Path on disk
+h = rs.phash("photo.jpg", 8)
+print(h)                                            # "c3f8a1b27d0e4f96"
+
+# Raw image bytes (from an HTTP response, a database BLOB, a multipart upload)
+with open("photo.jpg", "rb") as f:
+    h = rs.phash_bytes(f.read(), 8)
+
+# Every algorithm available has both flavors:
+rs.average_hash(path, 8)       # rs.average_hash_bytes(bytes, 8)
+rs.phash(path, 8)              # rs.phash_bytes(bytes, 8)
+rs.phash_simple(path, 8)       # rs.phash_simple_bytes(bytes, 8)
+rs.dhash(path, 8)              # rs.dhash_bytes(bytes, 8)
+rs.dhash_vertical(path, 8)     # rs.dhash_vertical_bytes(bytes, 8)
+rs.whash_haar(path, 8)         # rs.whash_haar_bytes(bytes, 8)
+rs.whash_db4(path, 8)          # rs.whash_db4_bytes(bytes, 8)
+rs.whash_db4_robust(path, 8)   # rs.whash_db4_robust_bytes(bytes, 8) — cross-port-stable
+rs.colorhash(path, 3)          # rs.colorhash_bytes(bytes, 3) — takes binbits
+rs.crop_resistant_hash(path)   # rs.crop_resistant_hash_bytes(bytes) — no size, returns ImageMultiHash
+
+# Hex round-trips:
+restored = rs.hex_to_hash("c3f8a1b27d0e4f96")
+restored = rs.hex_to_flathash("...", hashsize=3)
+restored = rs.hex_to_multihash("hex1,hex2,hex3")
+```
+
+## Cross-port equivalence
+
+The output of `rs.phash("photo.jpg", 8)` is the same hex string as you'd get from the Rust, Go, Java, JS, or Swift `rosetta-squint` ports given the same byte input. **Verified live for `imagehash.png` at size 8: `ba8c84536bd3c366` across Python, Go, Java, JS, Swift.**
+
+## Decode strategy
+
+| Format | Decoder | Why |
+|---|---|---|
+| BMP, PNG, GIF, JPEG, WebP, TIFF | PIL/Pillow (system) | The canonical Python decoders; the goldens used to validate the 5 native ports were generated by PIL itself, so output matches by construction. |
+| HEIC | ctypes wrapper around system `libheif.so.1` | pillow-heif bundles libheif 1.21.2 in its wheel; the 5 native ports link to system libheif 1.17.6. The wrapper avoids the ±1 px divergence. |
+
+If you already have a `PIL.Image.Image` (from `PIL.Image.open(...)`, a thumbnailer, etc.), use the `rosetta_squint_hash` lower-level API directly — the squint layer's only job is the decode step:
+
+```python
+import rosetta_squint_hash as rih
+from PIL import Image
+img = Image.open("photo.jpg")
+h = rih.phash(img, hash_size=8)
+```
+
+## Dependencies
+
+- `rosetta_squint_hash` (which re-exports `imagehash==4.3.2` + adds `whash_db4_robust`)
+- `Pillow==12.2.*`
+
+Tight pins are intentional. See [`../../hash/python/README.md`](../../hash/python/README.md) under "Version policy" for the upgrade workflow.
+
+## Testing
+
+```bash
+pytest
+```
+
+Tests verify (1) path/bytes parity for every algorithm, (2) chain consistency between `rs.phash(path)` and `imagehash.phash(rs.decode_file(path))`, (3) cross-port byte-exact equality with Go/Java/JS for `imagehash.png`.

rosetta_squint-1.0.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rosetta-squint"
+version = "1.0.0"
+description = "Cross-language byte-exact perceptual image hashing — decode + hash in one call"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "BSD-2-Clause" }
+authors = [
+    { name = "Will Metcalf", email = "william.metcalf@gmail.com" },
+]
+# Tight upstream pins — bumped only when we cut a new rosetta-squint release
+# after re-validating goldens. See ../../hash/python/README.md for the policy.
+#
+# Note: `rosetta-squint-hash` is a sibling local package in this repo. Until
+# the project is on PyPI, install it manually from ../../hash/python BEFORE
+# installing this package:
+#     pip install -e ../../hash/python
+#     pip install -e .
+# Once on PyPI, this dependency will be specified normally.
+dependencies = [
+    "rosetta-squint-hash>=1.0.0,<2.0",
+    "Pillow==12.2.*",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[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*"]
+exclude = ["tests*"]
+
+# ─── Static analysis config (consumed by the CI lint job) ─────────────────
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "B"]
+ignore = [
+    "E203",
+    "F403",
+    "F401",
+]
+exclude = ["tests"]
+
+[tool.mypy]
+python_version = "3.9"
+ignore_missing_imports = true
+follow_imports = "silent"

rosetta_squint-1.0.0/rosetta_squint/__init__.py

@@ -0,0 +1,92 @@
+"""rosetta_squint — point at an image (path or bytes), get the same phash
+hex string as every other rosetta-squint port for the same input.
+
+This is the Python implementation of the cross-language perceptual-hash
+convenience API. It depends on `rosetta_squint_hash` (which re-exports
+upstream `imagehash` + adds `whash_db4_robust`) and uses PIL/Pillow for
+decoding most formats. HEIC is decoded via a ctypes wrapper around
+system libheif so that output matches the 5 native ports (which all FFI
+to the same system libheif).
+
+Each public function comes in three flavors:
+- `phash(path_or_image, ...)` — accept a file path str/Path OR a PIL.Image
+- `phash_bytes(bytes, ...)` — accept raw image bytes in memory
+
+API matches the same names in the non-Python rosetta-squint ports
+(`phash`, `dhash`, `average_hash`, `whash_haar`, `colorhash`,
+`crop_resistant_hash`, plus the extensions `whash_db4`, `whash_db4_robust`,
+`phash_simple`, `dhash_vertical`).
+"""
+
+from __future__ import annotations
+
+from ._impl import (
+    # Path-based entries
+    average_hash,
+    colorhash,
+    crop_resistant_hash,
+    dhash,
+    dhash_vertical,
+    phash,
+    phash_simple,
+    whash_db4,
+    whash_db4_robust,
+    whash_haar,
+    # Bytes-based entries
+    average_hash_bytes,
+    colorhash_bytes,
+    crop_resistant_hash_bytes,
+    dhash_bytes,
+    dhash_vertical_bytes,
+    phash_bytes,
+    phash_simple_bytes,
+    whash_db4_bytes,
+    whash_db4_robust_bytes,
+    whash_haar_bytes,
+    # Decode helpers
+    decode_bytes,
+    decode_file,
+)
+
+# Re-export hash types so callers don't need to import rosetta_squint_hash
+# separately.
+from rosetta_squint_hash import (
+    ImageHash,
+    ImageMultiHash,
+    hex_to_flathash,
+    hex_to_hash,
+    hex_to_multihash,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ImageHash",
+    "ImageMultiHash",
+    "hex_to_flathash",
+    "hex_to_hash",
+    "hex_to_multihash",
+    "decode_file",
+    "decode_bytes",
+    "average_hash",
+    "average_hash_bytes",
+    "colorhash",
+    "colorhash_bytes",
+    "crop_resistant_hash",
+    "crop_resistant_hash_bytes",
+    "dhash",
+    "dhash_bytes",
+    "dhash_vertical",
+    "dhash_vertical_bytes",
+    "phash",
+    "phash_bytes",
+    "phash_simple",
+    "phash_simple_bytes",
+    "whash_db4",
+    "whash_db4_bytes",
+    "whash_db4_robust",
+    "whash_db4_robust_bytes",
+    "whash_haar",
+    "whash_haar_bytes",
+    "__version__",
+]

rosetta_squint-1.0.0/rosetta_squint/_impl.py

@@ -0,0 +1,462 @@
+"""Implementation of the rosetta_squint convenience API.
+
+For most formats we use PIL.Image.open() because that's what upstream
+`imagehash` itself uses, so we match imagehash's behavior exactly. For
+HEIC specifically, we decode via a ctypes wrapper around system libheif
+(NOT pillow-heif, which bundles libheif 1.21.2 and diverges ±1 px from
+the system libheif 1.17.6 that the 5 native ports link to).
+"""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import io
+import os
+import stat
+import sys
+from pathlib import Path
+from typing import Union
+
+import imagehash
+import rosetta_squint_hash as rih
+from PIL import Image
+
+
+# Reject path-based decode of files that are too large or are non-regular
+# (e.g., /dev/zero, named pipes, character devices) BEFORE reading bytes.
+# Callers that genuinely need to process images larger than this threshold
+# should decode via rosetta-squint-decode directly after explicit validation.
+MAX_FILE_SIZE = 256 * 1024 * 1024  # 256 MiB
+
+
+def _load_libheif_xplat() -> ctypes.CDLL:
+    """Cross-platform libheif loader.
+
+    Linux:   libheif.so.1
+    macOS:   libheif.dylib (Homebrew unversioned) or libheif.1.dylib
+    Windows: libheif.dll / libheif-1.dll
+    Other:   ctypes.util.find_library fallback
+
+    Raises OSError with a clear message if no candidate loads.
+    """
+    if sys.platform == "darwin":
+        candidates = ["libheif.dylib", "libheif.1.dylib"]
+    elif sys.platform == "win32":
+        candidates = ["libheif.dll", "libheif-1.dll"]
+    else:
+        candidates = ["libheif.so.1", "libheif.so"]
+    # ctypes.util.find_library lets us pick up homebrew/macports/other paths
+    found = ctypes.util.find_library("heif")
+    if found:
+        candidates.append(found)
+    for name in candidates:
+        try:
+            return ctypes.CDLL(name)
+        except OSError:
+            continue
+    raise OSError(
+        f"libheif not found. Tried: {', '.join(candidates)}. "
+        f"Install via your package manager (apt install libheif-dev, "
+        f"brew install libheif, etc.)."
+    )
+
+PathOrBytes = Union[str, Path, bytes, bytearray, memoryview]
+
+
+class HeifError(ctypes.Structure):
+    """C struct heif_error { int32 code; int32 subcode; const char* message; }.
+
+    libheif's fallible functions return this 12-byte struct by value.
+    Declaring restype = ctypes.c_int64 (the previous behaviour) only reads
+    8 of those bytes and reinterprets them as an integer, which silently
+    drops the message pointer and ignores the subcode.
+    """
+    _fields_ = (
+        ("code", ctypes.c_int),
+        ("subcode", ctypes.c_int),
+        ("message", ctypes.c_char_p),
+    )
+
+
+def _check_heif(err: "HeifError", op: str) -> None:
+    """Raise RuntimeError when a libheif error struct indicates failure."""
+    if err.code != 0:
+        msg = err.message.decode("utf-8", "replace") if err.message else ""
+        raise RuntimeError(
+            f"libheif {op} failed: code={err.code} subcode={err.subcode} msg={msg}"
+        )
+
+
+# ─── Decode helpers ──────────────────────────────────────────────────────────
+
+
+def _is_heic(path_or_first_bytes) -> bool:
+    """Detect HEIC by ftyp box brand at offset 4..12 with brand in the
+    HEIC-family set. Mirrors what the 5 native ports do."""
+    if isinstance(path_or_first_bytes, (bytes, bytearray, memoryview)):
+        b = bytes(path_or_first_bytes[:12])
+    else:
+        with open(path_or_first_bytes, "rb") as f:
+            b = f.read(12)
+    if len(b) < 12 or b[4:8] != b"ftyp":
+        return False
+    brand = b[8:12]
+    return brand in (b"heic", b"heix", b"mif1", b"msf1", b"hevc", b"hevx")
+
+
+def _decode_heic_via_system_libheif(data: bytes) -> Image.Image:
+    """Decode HEIC bytes using ctypes around system libheif so the result
+    matches the 5 native ports (which all link to system libheif via
+    FFI). pillow-heif would bundle libheif 1.21.2 and diverge from
+    system libheif 1.17.6 by ±1 px on lossy fixtures."""
+    lib = _load_libheif_xplat()
+    lib.heif_context_alloc.restype = ctypes.c_void_p
+    lib.heif_context_free.argtypes = [ctypes.c_void_p]
+    lib.heif_context_read_from_memory_without_copy.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_char_p,
+        ctypes.c_size_t,
+        ctypes.c_void_p,
+    ]
+    lib.heif_context_read_from_memory_without_copy.restype = HeifError
+    lib.heif_context_get_primary_image_handle.argtypes = [
+        ctypes.c_void_p,
+        ctypes.POINTER(ctypes.c_void_p),
+    ]
+    lib.heif_context_get_primary_image_handle.restype = HeifError
+    lib.heif_image_handle_release.argtypes = [ctypes.c_void_p]
+    lib.heif_image_handle_get_width.argtypes = [ctypes.c_void_p]
+    lib.heif_image_handle_get_width.restype = ctypes.c_int
+    lib.heif_image_handle_get_height.argtypes = [ctypes.c_void_p]
+    lib.heif_image_handle_get_height.restype = ctypes.c_int
+    lib.heif_image_handle_has_alpha_channel.argtypes = [ctypes.c_void_p]
+    lib.heif_image_handle_has_alpha_channel.restype = ctypes.c_int
+    lib.heif_decode_image.argtypes = [
+        ctypes.c_void_p,
+        ctypes.POINTER(ctypes.c_void_p),
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_void_p,
+    ]
+    lib.heif_decode_image.restype = HeifError
+    lib.heif_image_release.argtypes = [ctypes.c_void_p]
+    lib.heif_image_get_plane_readonly.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_int,
+        ctypes.POINTER(ctypes.c_int),
+    ]
+    lib.heif_image_get_plane_readonly.restype = ctypes.c_void_p
+
+    HEIF_COLORSPACE_RGB = 1
+    HEIF_CHROMA_INTERLEAVED_RGB = 10
+    HEIF_CHROMA_INTERLEAVED_RGBA = 11
+    HEIF_CHANNEL_INTERLEAVED = 10
+
+    ctx = lib.heif_context_alloc()
+    if not ctx:
+        raise RuntimeError("heif_context_alloc failed")
+    try:
+        err = lib.heif_context_read_from_memory_without_copy(
+            ctx, data, len(data), None
+        )
+        _check_heif(err, "heif_context_read_from_memory_without_copy")
+        handle_ref = ctypes.c_void_p()
+        err = lib.heif_context_get_primary_image_handle(
+            ctx, ctypes.byref(handle_ref)
+        )
+        # Register the cleanup BEFORE checking the error so that any
+        # partial handle libheif may have written into handle_ref is
+        # released even if _check_heif raises.
+        try:
+            _check_heif(err, "heif_context_get_primary_image_handle")
+            if not handle_ref.value:
+                raise RuntimeError("heif_context_get_primary_image_handle failed")
+            handle = handle_ref.value
+            width = lib.heif_image_handle_get_width(handle)
+            height = lib.heif_image_handle_get_height(handle)
+            if width <= 0 or height <= 0:
+                raise RuntimeError(
+                    f"invalid HEIC dimensions {width}x{height}"
+                )
+            has_alpha = lib.heif_image_handle_has_alpha_channel(handle) != 0
+            chroma = (
+                HEIF_CHROMA_INTERLEAVED_RGBA
+                if has_alpha
+                else HEIF_CHROMA_INTERLEAVED_RGB
+            )
+            mode = "RGBA" if has_alpha else "RGB"
+            channels = 4 if has_alpha else 3
+
+            img_ref = ctypes.c_void_p()
+            err = lib.heif_decode_image(
+                handle, ctypes.byref(img_ref), HEIF_COLORSPACE_RGB, chroma, None
+            )
+            # Same pattern: register cleanup BEFORE the error check so the
+            # image is released even if _check_heif raises.
+            try:
+                _check_heif(err, "heif_decode_image")
+                if not img_ref.value:
+                    raise RuntimeError("heif_decode_image failed")
+                img = img_ref.value
+                stride = ctypes.c_int(0)
+                plane = lib.heif_image_get_plane_readonly(
+                    img, HEIF_CHANNEL_INTERLEAVED, ctypes.byref(stride)
+                )
+                if not plane:
+                    raise RuntimeError("null plane")
+                row_bytes = width * channels
+                if stride.value < row_bytes:
+                    raise RuntimeError(
+                        f"libheif returned stride {stride.value} smaller than "
+                        f"required {row_bytes} (width={width} channels={channels})"
+                    )
+                pixels = bytearray()
+                for y in range(height):
+                    row = ctypes.string_at(plane + y * stride.value, row_bytes)
+                    pixels.extend(row)
+                return Image.frombytes(mode, (width, height), bytes(pixels))
+            finally:
+                if img_ref.value:
+                    lib.heif_image_release(img_ref.value)
+        finally:
+            if handle_ref.value:
+                lib.heif_image_handle_release(handle_ref.value)
+    finally:
+        lib.heif_context_free(ctx)
+
+
+def _read_path_safely(path: Union[str, Path]) -> bytes:
+    """Open `path`, validate stat against the same fd that we read from
+    (closing a TOCTOU window), enforce symlink + regular-file + size
+    guards, and return the bytes. Mirrors the fd-based stat-and-read
+    pattern used in the other 5 squint ports.
+
+    A naive `os.stat(path)` then `open(path).read()` has a classic TOCTOU
+    window: an attacker with write access along the path can swap the
+    target between the two syscalls (file → symlink to /dev/zero, file →
+    larger file, regular file → FIFO). Holding the same fd across stat
+    and read defeats this — fstat reports the inode the read will actually
+    consume.
+
+    The open itself uses ``O_NOFOLLOW`` so that a symlink at ``path``
+    causes the open to fail rather than silently resolving to whatever
+    the symlink currently points at — closing a separate TOCTOU window
+    on the symlink target itself. Callers who genuinely want symlink
+    resolution must do it explicitly (e.g. ``Path(path).resolve()``)
+    before calling this function. Windows has no ``O_NOFOLLOW`` flag;
+    fall back to an ``lstat`` check.
+    """
+    if sys.platform == "win32":
+        # Windows: pre-check with os.lstat. There's a narrow race
+        # between the lstat and the open below, but Windows lacks
+        # O_NOFOLLOW and the alternative (reparse-point flags) would
+        # require ctypes wrapping of CreateFileW.
+        try:
+            st_link = os.lstat(path)
+        except OSError as e:
+            raise OSError(e.errno, f"lstat failed for {path}: {e.strerror}") from e
+        if stat.S_ISLNK(st_link.st_mode):
+            raise ValueError(f"symlink not allowed: {path}")
+        fd = os.open(path, os.O_RDONLY | os.O_BINARY)  # type: ignore[attr-defined]
+    else:
+        try:
+            fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)
+        except OSError as e:
+            # ELOOP (40 on Linux, 62 on macOS) is what O_NOFOLLOW raises
+            # when the final path component is a symlink. Translate to a
+            # clearer error so callers can distinguish symlink rejection
+            # from a generic "not a regular file" or I/O error.
+            import errno as _errno
+            if e.errno == _errno.ELOOP:
+                raise ValueError(f"symlink not allowed: {path}") from e
+            raise
+    # Wrap the bare fd in a Python file object so close-on-GC is automatic.
+    # If `os.fdopen` itself raises (e.g., MemoryError on a stressed system),
+    # the fd would leak — close it explicitly to be safe.
+    try:
+        f = os.fdopen(fd, "rb")
+    except BaseException:
+        os.close(fd)
+        raise
+    try:
+        st = os.fstat(f.fileno())
+        if not stat.S_ISREG(st.st_mode):
+            raise RuntimeError(f"not a regular file: {path}")
+        if st.st_size > MAX_FILE_SIZE:
+            raise RuntimeError(
+                f"input file too large: {st.st_size} bytes "
+                f"(max {MAX_FILE_SIZE} bytes / 256 MiB). For images above this "
+                f"threshold, decode via rosetta-squint-decode directly after "
+                f"explicit validation."
+            )
+        # Read up to MAX_FILE_SIZE+1 so we detect "file grew between fstat
+        # and read" (e.g. concurrent writer appending). The +1 absence is
+        # the contract: if we got more than MAX_FILE_SIZE bytes, reject.
+        data = f.read(MAX_FILE_SIZE + 1)
+        if len(data) > MAX_FILE_SIZE:
+            raise RuntimeError(
+                f"input file too large: {len(data)} bytes "
+                f"(max {MAX_FILE_SIZE} bytes / 256 MiB). For images above this "
+                f"threshold, decode via rosetta-squint-decode directly after "
+                f"explicit validation."
+            )
+        return data
+    finally:
+        f.close()
+
+
+def decode_file(path: Union[str, Path]) -> Image.Image:
+    """Decode a file at `path` into a PIL.Image suitable for hashing.
+    HEIC uses the system-libheif ctypes wrapper; everything else uses
+    PIL.Image.open.
+
+    Refuses symlinks (via ``O_NOFOLLOW`` on POSIX / ``lstat`` on Windows),
+    non-regular files (FIFOs, /dev/zero, character devices, etc.) and
+    files larger than MAX_FILE_SIZE BEFORE reading bytes. The
+    regular-file and size checks run against the same fd as the read,
+    closing the obvious TOCTOU window. Callers who genuinely want symlink
+    resolution must do it explicitly (e.g. ``Path(path).resolve()``)
+    before calling this function.
+    """
+    data = _read_path_safely(path)
+    if _is_heic(data):
+        return _decode_heic_via_system_libheif(data)
+    return Image.open(io.BytesIO(data))
+
+
+def decode_bytes(data: bytes) -> Image.Image:
+    """Decode raw image bytes into a PIL.Image. HEIC bytes use the
+    ctypes wrapper around system libheif; everything else goes through
+    PIL.Image.open."""
+    if isinstance(data, (bytearray, memoryview)):
+        data = bytes(data)
+    if _is_heic(data):
+        return _decode_heic_via_system_libheif(data)
+    return Image.open(io.BytesIO(data))
+
+
+# ─── Convenience hash functions ──────────────────────────────────────────────
+# Each algorithm gets a (path, size) and a (_bytes, size) variant.
+
+
+def average_hash(path: Union[str, Path], hash_size: int = 8) -> imagehash.ImageHash:
+    return rih.average_hash(decode_file(path), hash_size=hash_size)
+
+
+def average_hash_bytes(data: bytes, hash_size: int = 8) -> imagehash.ImageHash:
+    return rih.average_hash(decode_bytes(data), hash_size=hash_size)
+
+
+def phash(
+    path: Union[str, Path],
+    hash_size: int = 8,
+    highfreq_factor: int = 4,
+) -> imagehash.ImageHash:
+    return rih.phash(
+        decode_file(path), hash_size=hash_size, highfreq_factor=highfreq_factor
+    )
+
+
+def phash_bytes(
+    data: bytes, hash_size: int = 8, highfreq_factor: int = 4
+) -> imagehash.ImageHash:
+    return rih.phash(
+        decode_bytes(data), hash_size=hash_size, highfreq_factor=highfreq_factor
+    )
+
+
+def phash_simple(
+    path: Union[str, Path],
+    hash_size: int = 8,
+    highfreq_factor: int = 4,
+) -> imagehash.ImageHash:
+    return rih.phash_simple(
+        decode_file(path), hash_size=hash_size, highfreq_factor=highfreq_factor
+    )
+
+
+def phash_simple_bytes(
+    data: bytes, hash_size: int = 8, highfreq_factor: int = 4
+) -> imagehash.ImageHash:
+    return rih.phash_simple(
+        decode_bytes(data), hash_size=hash_size, highfreq_factor=highfreq_factor
+    )
+
+
+def dhash(path: Union[str, Path], hash_size: int = 8) -> imagehash.ImageHash:
+    return rih.dhash(decode_file(path), hash_size=hash_size)
+
+
+def dhash_bytes(data: bytes, hash_size: int = 8) -> imagehash.ImageHash:
+    return rih.dhash(decode_bytes(data), hash_size=hash_size)
+
+
+def dhash_vertical(
+    path: Union[str, Path], hash_size: int = 8
+) -> imagehash.ImageHash:
+    return rih.dhash_vertical(decode_file(path), hash_size=hash_size)
+
+
+def dhash_vertical_bytes(data: bytes, hash_size: int = 8) -> imagehash.ImageHash:
+    return rih.dhash_vertical(decode_bytes(data), hash_size=hash_size)
+
+
+def whash_haar(
+    path: Union[str, Path], hash_size: int = 8
+) -> imagehash.ImageHash:
+    return rih.whash(
+        decode_file(path),
+        hash_size=hash_size,
+        mode="haar",
+        remove_max_haar_ll=True,
+    )
+
+
+def whash_haar_bytes(data: bytes, hash_size: int = 8) -> imagehash.ImageHash:
+    return rih.whash(
+        decode_bytes(data),
+        hash_size=hash_size,
+        mode="haar",
+        remove_max_haar_ll=True,
+    )
+
+
+def whash_db4(path: Union[str, Path], hash_size: int = 8) -> imagehash.ImageHash:
+    # rih.whash_db4 is the port-local snap-applying override (NOT
+    # rih.whash(mode='db4'), which forwards to upstream imagehash without
+    # the snap-to-threshold tie-break). See spec/SPEC.md §"Threshold
+    # tie-break".
+    return rih.whash_db4(decode_file(path), hash_size=hash_size)
+
+
+def whash_db4_bytes(data: bytes, hash_size: int = 8) -> imagehash.ImageHash:
+    return rih.whash_db4(decode_bytes(data), hash_size=hash_size)
+
+
+def whash_db4_robust(
+    path: Union[str, Path], hash_size: int = 8
+) -> imagehash.ImageHash:
+    return rih.whash_db4_robust(decode_file(path), hash_size=hash_size)
+
+
+def whash_db4_robust_bytes(
+    data: bytes, hash_size: int = 8
+) -> imagehash.ImageHash:
+    return rih.whash_db4_robust(decode_bytes(data), hash_size=hash_size)
+
+
+def colorhash(path: Union[str, Path], binbits: int = 3) -> imagehash.ImageHash:
+    return rih.colorhash(decode_file(path), binbits=binbits)
+
+
+def colorhash_bytes(data: bytes, binbits: int = 3) -> imagehash.ImageHash:
+    return rih.colorhash(decode_bytes(data), binbits=binbits)
+
+
+def crop_resistant_hash(path: Union[str, Path]) -> imagehash.ImageMultiHash:
+    return rih.crop_resistant_hash(decode_file(path))
+
+
+def crop_resistant_hash_bytes(data: bytes) -> imagehash.ImageMultiHash:
+    return rih.crop_resistant_hash(decode_bytes(data))

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

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: rosetta-squint
+Version: 1.0.0
+Summary: Cross-language byte-exact perceptual image hashing — decode + hash in one call
+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: rosetta-squint-hash<2.0,>=1.0.0
+Requires-Dist: Pillow==12.2.*
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# rosetta_squint — Python convenience API
+
+Point at an image file or pass in raw image bytes; get back the same perceptual hash hex string that every other `rosetta-squint` port produces for the same input.
+
+## Install
+
+```bash
+pip install -e ../../hash/python                    # rosetta-squint-hash (wrapper around imagehash)
+pip install -e .                                    # this package
+```
+
+(Not on PyPI yet — both are local.)
+
+## Usage
+
+```python
+import rosetta_squint as rs
+
+# Path on disk
+h = rs.phash("photo.jpg", 8)
+print(h)                                            # "c3f8a1b27d0e4f96"
+
+# Raw image bytes (from an HTTP response, a database BLOB, a multipart upload)
+with open("photo.jpg", "rb") as f:
+    h = rs.phash_bytes(f.read(), 8)
+
+# Every algorithm available has both flavors:
+rs.average_hash(path, 8)       # rs.average_hash_bytes(bytes, 8)
+rs.phash(path, 8)              # rs.phash_bytes(bytes, 8)
+rs.phash_simple(path, 8)       # rs.phash_simple_bytes(bytes, 8)
+rs.dhash(path, 8)              # rs.dhash_bytes(bytes, 8)
+rs.dhash_vertical(path, 8)     # rs.dhash_vertical_bytes(bytes, 8)
+rs.whash_haar(path, 8)         # rs.whash_haar_bytes(bytes, 8)
+rs.whash_db4(path, 8)          # rs.whash_db4_bytes(bytes, 8)
+rs.whash_db4_robust(path, 8)   # rs.whash_db4_robust_bytes(bytes, 8) — cross-port-stable
+rs.colorhash(path, 3)          # rs.colorhash_bytes(bytes, 3) — takes binbits
+rs.crop_resistant_hash(path)   # rs.crop_resistant_hash_bytes(bytes) — no size, returns ImageMultiHash
+
+# Hex round-trips:
+restored = rs.hex_to_hash("c3f8a1b27d0e4f96")
+restored = rs.hex_to_flathash("...", hashsize=3)
+restored = rs.hex_to_multihash("hex1,hex2,hex3")
+```
+
+## Cross-port equivalence
+
+The output of `rs.phash("photo.jpg", 8)` is the same hex string as you'd get from the Rust, Go, Java, JS, or Swift `rosetta-squint` ports given the same byte input. **Verified live for `imagehash.png` at size 8: `ba8c84536bd3c366` across Python, Go, Java, JS, Swift.**
+
+## Decode strategy
+
+| Format | Decoder | Why |
+|---|---|---|
+| BMP, PNG, GIF, JPEG, WebP, TIFF | PIL/Pillow (system) | The canonical Python decoders; the goldens used to validate the 5 native ports were generated by PIL itself, so output matches by construction. |
+| HEIC | ctypes wrapper around system `libheif.so.1` | pillow-heif bundles libheif 1.21.2 in its wheel; the 5 native ports link to system libheif 1.17.6. The wrapper avoids the ±1 px divergence. |
+
+If you already have a `PIL.Image.Image` (from `PIL.Image.open(...)`, a thumbnailer, etc.), use the `rosetta_squint_hash` lower-level API directly — the squint layer's only job is the decode step:
+
+```python
+import rosetta_squint_hash as rih
+from PIL import Image
+img = Image.open("photo.jpg")
+h = rih.phash(img, hash_size=8)
+```
+
+## Dependencies
+
+- `rosetta_squint_hash` (which re-exports `imagehash==4.3.2` + adds `whash_db4_robust`)
+- `Pillow==12.2.*`
+
+Tight pins are intentional. See [`../../hash/python/README.md`](../../hash/python/README.md) under "Version policy" for the upgrade workflow.
+
+## Testing
+
+```bash
+pytest
+```
+
+Tests verify (1) path/bytes parity for every algorithm, (2) chain consistency between `rs.phash(path)` and `imagehash.phash(rs.decode_file(path))`, (3) cross-port byte-exact equality with Go/Java/JS for `imagehash.png`.

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

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+rosetta_squint/__init__.py
+rosetta_squint/_impl.py
+rosetta_squint.egg-info/PKG-INFO
+rosetta_squint.egg-info/SOURCES.txt
+rosetta_squint.egg-info/dependency_links.txt
+rosetta_squint.egg-info/requires.txt
+rosetta_squint.egg-info/top_level.txt
+tests/test_squint.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,5 @@
+rosetta-squint-hash<2.0,>=1.0.0
+Pillow==12.2.*
+
+[test]
+pytest>=7

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

@@ -0,0 +1 @@
+rosetta_squint

rosetta_squint-1.0.0/setup.cfg

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

rosetta_squint-1.0.0/tests/test_squint.py

@@ -0,0 +1,261 @@
+"""Integration tests for rosetta_squint.
+
+Each algorithm is tested in three ways:
+1. Path input returns a non-empty ImageHash
+2. Path input == bytes input (both produce same hex)
+3. Squint output == calling rosetta_squint_hash directly on the decoded
+   PIL.Image (chain consistency — no surprise transformations)
+
+We do NOT compare against `hash/spec/goldens.json` directly because those
+goldens were generated by PIL.Image.open() which is exactly what
+rosetta_squint uses for non-HEIC formats. So spec/goldens.json values
+*should* match rosetta_squint output for PNG/JPEG fixtures — we assert
+this where it adds confidence.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+import rosetta_squint as rs
+
+# Fixtures from the hash side of the merged repo.
+# tests/test_squint.py → tests/ → python/ → squint/ → rosetta-squint/
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+HASH_FIXTURES = REPO_ROOT / "hash" / "spec" / "fixtures"
+HASH_GOLDENS = REPO_ROOT / "hash" / "spec" / "goldens.json"
+DECODE_FIXTURES = REPO_ROOT / "decode" / "spec" / "fixtures"
+
+PNG_FIXTURE = HASH_FIXTURES / "imagehash.png"
+PEPPERS = HASH_FIXTURES / "peppers.png"
+JPEG_FIXTURE = DECODE_FIXTURES / "jpeg" / "valid" / "8x8-grayscale.jpg"
+
+
+def _read(path: Path) -> bytes:
+    return path.read_bytes()
+
+
+# Sanity: fixtures exist where we expect them.
+def test_fixtures_exist():
+    assert PNG_FIXTURE.exists(), f"missing {PNG_FIXTURE}"
+    assert PEPPERS.exists(), f"missing {PEPPERS}"
+    assert JPEG_FIXTURE.exists(), f"missing {JPEG_FIXTURE}"
+
+
+# Path/bytes parity for all 10 algorithms.
+
+@pytest.mark.parametrize(
+    "algo,size_arg,fixture",
+    [
+        ("phash", 8, PEPPERS),
+        ("phash", 16, PEPPERS),
+        ("phash_simple", 8, PEPPERS),
+        ("dhash", 8, PEPPERS),
+        ("dhash_vertical", 8, PEPPERS),
+        ("average_hash", 8, PEPPERS),
+        ("whash_haar", 8, PEPPERS),
+        ("whash_db4", 8, PEPPERS),
+        ("whash_db4_robust", 8, PEPPERS),
+        # colorhash takes binbits, default 3
+        ("colorhash", 3, PEPPERS),
+        # JPEG path through whole pipeline including libjpeg-turbo via PIL
+        ("phash", 8, JPEG_FIXTURE),
+        ("dhash", 8, JPEG_FIXTURE),
+    ],
+)
+def test_path_equals_bytes(algo: str, size_arg: int, fixture: Path):
+    """path and bytes entry points produce identical hex."""
+    fn_path = getattr(rs, algo)
+    fn_bytes = getattr(rs, f"{algo}_bytes")
+    # colorhash uses positional binbits, others use hash_size — both accept positional int
+    h1 = fn_path(fixture, size_arg)
+    h2 = fn_bytes(_read(fixture), size_arg)
+    assert str(h1) == str(h2), (
+        f"{algo} {fixture.name} size={size_arg}: path={h1} bytes={h2}"
+    )
+
+
+def test_crop_resistant_hash_path_equals_bytes():
+    """crop_resistant_hash has no size param; check path/bytes parity."""
+    h_path = rs.crop_resistant_hash(PEPPERS)
+    h_bytes = rs.crop_resistant_hash_bytes(_read(PEPPERS))
+    assert str(h_path) == str(h_bytes)
+
+
+# Chain consistency: rs.phash(path) == imagehash.phash(rs.decode_file(path)).
+
+def test_phash_chain_consistency():
+    import imagehash
+    img = rs.decode_file(PEPPERS)
+    h_chain = imagehash.phash(img, hash_size=8)
+    h_squint = rs.phash(PEPPERS, 8)
+    assert str(h_chain) == str(h_squint)
+
+
+def test_phash_simple_chain_consistency():
+    import imagehash
+    img = rs.decode_file(PEPPERS)
+    h_chain = imagehash.phash_simple(img, hash_size=8)
+    h_squint = rs.phash_simple(PEPPERS, 8)
+    assert str(h_chain) == str(h_squint)
+
+
+def test_dhash_chain_consistency():
+    import imagehash
+    img = rs.decode_file(PEPPERS)
+    h_chain = imagehash.dhash(img, hash_size=8)
+    h_squint = rs.dhash(PEPPERS, 8)
+    assert str(h_chain) == str(h_squint)
+
+
+def test_average_hash_chain_consistency():
+    import imagehash
+    img = rs.decode_file(PEPPERS)
+    h_chain = imagehash.average_hash(img, hash_size=8)
+    h_squint = rs.average_hash(PEPPERS, 8)
+    assert str(h_chain) == str(h_squint)
+
+
+def test_crop_resistant_hash_chain_consistency():
+    import imagehash
+    img = rs.decode_file(PEPPERS)
+    h_chain = imagehash.crop_resistant_hash(img)
+    h_squint = rs.crop_resistant_hash(PEPPERS)
+    assert str(h_chain) == str(h_squint)
+
+
+# Sanity that the hex format is what we expect.
+def test_phash_returns_16_hex_chars_for_size_8():
+    h = rs.phash(PEPPERS, 8)
+    assert len(str(h)) == 16
+    assert all(c in "0123456789abcdef" for c in str(h))
+
+
+# Cross-port live verification: confirm that phash("imagehash.png", 8) yields
+# the same hex string that the Go/Java/JS squint ports report (ba8c84536bd3c366).
+def test_phash_imagehash_png_matches_other_ports():
+    h = rs.phash(PNG_FIXTURE, 8)
+    # This was reported by Go, Java, and JS squint implementations.
+    assert str(h) == "ba8c84536bd3c366", (
+        f"Python rosetta_squint diverged from Go/Java/JS for phash on imagehash.png. "
+        f"Python: {h}, others: ba8c84536bd3c366"
+    )
+
+
+def test_crop_resistant_hash_returns_imagemultihash():
+    h = rs.crop_resistant_hash(PEPPERS)
+    assert hasattr(h, "segment_hashes")
+    # Distance to self must be float, not int.
+    d = h - h
+    assert isinstance(d, float)
+    assert d == 0.0
+
+
+def test_hex_to_multihash_roundtrip():
+    mh = rs.crop_resistant_hash(PEPPERS)
+    s = str(mh)
+    restored = rs.hex_to_multihash(s)
+    assert str(restored) == s
+
+
+# ─── HEIC tests — exercise the ctypes-around-system-libheif bridge ──────────
+#
+# rosetta_squint decodes HEIC via a ctypes wrapper around system libheif
+# (instead of pillow-heif), because pillow-heif bundles libheif 1.21.2 and
+# diverges ±1 px from the system libheif 1.17.6 that the 5 native ports link
+# to. These tests confirm:
+#   (a) HEIC happy-path: decode and hash succeed
+#   (b) HEIC alpha handling: RGBA fixture decodes as RGBA
+#   (c) HEIC negative paths: malformed/AVIF inputs raise rather than panic
+#
+# The HEIC bridge has historically been the largest ctypes-FFI surface in
+# the project — these tests guard against regressions in the HeifError
+# struct handling, handle ownership, plane stride trust, etc. (S-M3, S-M4).
+
+HEIC_RGB = DECODE_FIXTURES / "heic" / "valid" / "16x16.heic"
+HEIC_RGBA = DECODE_FIXTURES / "heic" / "valid" / "16x16-rgba.heic"
+HEIC_LOSSLESS = DECODE_FIXTURES / "heic" / "valid" / "16x16-lossless.heic"
+HEIC_AVIF = DECODE_FIXTURES / "heic" / "invalid" / "avif.heic"
+HEIC_BAD = DECODE_FIXTURES / "heic" / "invalid" / "bad-magic.heic"
+HEIC_TRUNCATED = DECODE_FIXTURES / "heic" / "invalid" / "truncated.heic"
+
+
+def _maybe_skip_heic():
+    """Skip the HEIC tests cleanly if libheif isn't installed at all."""
+    try:
+        from rosetta_squint._impl import _load_libheif_xplat
+        _load_libheif_xplat()
+    except OSError as e:
+        pytest.skip(f"system libheif unavailable — skipping HEIC tests: {e}")
+
+
+def test_heic_decode_rgb_hashes_successfully():
+    _maybe_skip_heic()
+    if not HEIC_RGB.exists():
+        pytest.skip(f"missing fixture {HEIC_RGB}")
+    h = rs.phash(HEIC_RGB, 8)
+    # phash output is always 16 lowercase hex chars
+    assert len(str(h)) == 16
+    assert all(c in "0123456789abcdef" for c in str(h))
+
+
+def test_heic_path_equals_bytes():
+    """HEIC must round-trip through path and bytes APIs identically."""
+    _maybe_skip_heic()
+    if not HEIC_RGB.exists():
+        pytest.skip(f"missing fixture {HEIC_RGB}")
+    h_path = rs.phash(HEIC_RGB, 8)
+    h_bytes = rs.phash_bytes(HEIC_RGB.read_bytes(), 8)
+    assert str(h_path) == str(h_bytes)
+
+
+def test_heic_rgba_decodes():
+    """RGBA HEIC must decode cleanly — exercises has_alpha_channel + RGBA chroma path."""
+    _maybe_skip_heic()
+    if not HEIC_RGBA.exists():
+        pytest.skip(f"missing fixture {HEIC_RGBA}")
+    # Decode independently to verify mode/dimensions; then hash via squint.
+    img = rs.decode_file(HEIC_RGBA)
+    assert img.mode in ("RGB", "RGBA")
+    assert img.size == (16, 16)
+    h = rs.dhash(HEIC_RGBA, 8)
+    assert len(str(h)) == 16
+
+
+def test_heic_lossless_decodes():
+    """Lossless HEIC must decode cleanly."""
+    _maybe_skip_heic()
+    if not HEIC_LOSSLESS.exists():
+        pytest.skip(f"missing fixture {HEIC_LOSSLESS}")
+    h = rs.average_hash(HEIC_LOSSLESS, 8)
+    assert len(str(h)) == 16
+
+
+def test_heic_invalid_avif_raises():
+    """AVIF brand inside a HEIC ftyp is intentionally unsupported in v1."""
+    _maybe_skip_heic()
+    if not HEIC_AVIF.exists():
+        pytest.skip(f"missing fixture {HEIC_AVIF}")
+    with pytest.raises(Exception):  # noqa: BLE001 — any exception is acceptable
+        rs.phash(HEIC_AVIF, 8)
+
+
+def test_heic_invalid_bad_magic_raises():
+    """A file whose ftyp brand isn't in the HEIC family must fail."""
+    _maybe_skip_heic()
+    if not HEIC_BAD.exists():
+        pytest.skip(f"missing fixture {HEIC_BAD}")
+    with pytest.raises(Exception):  # noqa: BLE001
+        rs.phash(HEIC_BAD, 8)
+
+
+def test_heic_invalid_truncated_raises():
+    """A truncated HEIC must surface a libheif diagnostic, not silently produce garbage."""
+    _maybe_skip_heic()
+    if not HEIC_TRUNCATED.exists():
+        pytest.skip(f"missing fixture {HEIC_TRUNCATED}")
+    with pytest.raises(Exception):  # noqa: BLE001
+        rs.phash(HEIC_TRUNCATED, 8)