rosetta-squint 1.0.0__py3-none-any.whl

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/_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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+rosetta_squint/__init__.py,sha256=WS7jtOcUan-SQlotpcN2dGDyZgG58e6-u8wiRiXVg5A,2391
+rosetta_squint/_impl.py,sha256=OI97L1meX-oDcx5uYIz2C7GIPvnOQxKCoeErH5k5vRk,17858
+rosetta_squint-1.0.0.dist-info/METADATA,sha256=zrNzNFx7Z_MCdxrZltPjegom3TjOKJ7rSXzzzxW_EmY,4026
+rosetta_squint-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rosetta_squint-1.0.0.dist-info/top_level.txt,sha256=esQHc93VdXUXumPzwgdtqIqxhKO80WG_bzYg94LPNt4,15
+rosetta_squint-1.0.0.dist-info/RECORD,,

rosetta_squint-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rosetta_squint-1.0.0.dist-info/top_level.txt

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