python-libphash 2.0.1.0__cp315-cp315t-win_amd64.whl

libphash/_digest.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NoReturn, TypeVar, final
+
+from ._algorithms import DigestKind
+from ._errors import PH_SUCCESS, make_error
+from ._native import ffi, lib
+from ._sources import encode_text
+from .exceptions import DigestKindError, InvalidArgumentError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ._native import double_ptr, ph_digest_t_ptr
+
+_N = TypeVar("_N", int, float)
+
+PH_DIGEST_MAX_BYTES: int = int(lib.PH_DIGEST_MAX_BYTES)
+_UINT64_MAX = (1 << 64) - 1
+
+# Comparison -> the kinds it accepts (UNSPECIFIED is accepted by all, as in C).
+_METRIC_KINDS = {
+    "hamming_distance": (DigestKind.BITS,),
+    "l2_distance": (DigestKind.VECTOR, DigestKind.VECTOR16),
+    "histogram_intersection": (DigestKind.HISTOGRAM,),
+    "radial_similarity": (DigestKind.COEFFICIENTS,),
+}
+
+
+@final
+class Digest:
+    """A multi-byte hash: the bytes and the kind that says how they may be compared.
+
+    BMH and mHash give bit vectors, Radial quantized coefficients, ColorHash a
+    histogram, ColorMoments a vector of signed 16-bit features. Each comparison method
+    accepts only the kinds it is meaningful for and raises :class:`DigestKindError` for
+    the others; :meth:`similarity` picks the comparison that belongs to the kind.
+
+    Digests are immutable, hashable, comparable for equality and picklable. ``hex()``
+    and ``from_hex()`` give a text form that keeps the kind.
+    """
+
+    __slots__ = ("_data", "_kind")
+    _data: bytes
+    _kind: DigestKind
+
+    def __init__(self, data: bytes, kind: DigestKind | int) -> None:
+        data = bytes(data)
+        if not 0 < len(data) <= PH_DIGEST_MAX_BYTES:
+            raise InvalidArgumentError(
+                f"a digest holds 1 to {PH_DIGEST_MAX_BYTES} bytes, got {len(data)}"
+            )
+        try:
+            kind = DigestKind(kind)
+        except ValueError:
+            raise InvalidArgumentError(f"unknown digest kind {kind!r}") from None
+        object.__setattr__(self, "_data", data)
+        object.__setattr__(self, "_kind", kind)
+
+    @classmethod
+    def from_uint64(cls, value: int) -> Digest:
+        """Wrap a 64-bit hash as an 8-byte ``BITS`` digest.
+
+        The most significant byte comes first, as in :func:`hash_to_hex`.
+        """
+        return cls(_check_uint64(value).to_bytes(8, "big"), DigestKind.BITS)
+
+    @classmethod
+    def from_hex(cls, text: str) -> Digest:
+        """Parse the text form written by :meth:`hex` (``"<kind>:<hex>"``)."""
+        out = ffi.new("ph_digest_t *")
+        code = lib.ph_digest_from_hex(encode_text(text), out)
+        if code != PH_SUCCESS:
+            raise make_error(code, context=f"parsing digest {text[:40]!r}")
+        return digest_from_c(out)
+
+    @property
+    def data(self) -> bytes:
+        return self._data
+
+    @property
+    def kind(self) -> DigestKind:
+        return self._kind
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __bytes__(self) -> bytes:
+        return self._data
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Digest):
+            return NotImplemented
+        return self._kind == other._kind and self._data == other._data
+
+    def __hash__(self) -> int:
+        return hash((self._kind, self._data))
+
+    def __repr__(self) -> str:
+        return f"Digest.from_hex({self.hex()!r})"
+
+    def __setattr__(self, name: str, value: object) -> NoReturn:
+        raise AttributeError("Digest is immutable")
+
+    def __reduce__(self) -> tuple[type[Digest], tuple[bytes, int]]:
+        return (Digest, (self._data, int(self._kind)))
+
+    def hex(self) -> str:
+        """Return the text form: the kind, a colon, the bytes in lowercase hex.
+
+        For example ``"bits:3fa0..."``; :meth:`from_hex` parses it back.
+        """
+        size = int(lib.PH_DIGEST_HEX_BUFFER_SIZE)
+        out = ffi.new("char[]", size)
+        code = lib.ph_digest_to_hex(digest_to_c(self), out, size)
+        if code != PH_SUCCESS:
+            raise make_error(code, context="encoding digest")
+        return str(ffi.string(out).decode("ascii"))
+
+    # --- Comparisons -----------------------------------------------------------------
+
+    def _pair(
+        self, other: object, metric: str
+    ) -> tuple[ph_digest_t_ptr, ph_digest_t_ptr]:
+        other = _as_digest(other)
+        allowed = _METRIC_KINDS[metric]
+        for d in (self, other):
+            if d._kind != DigestKind.UNSPECIFIED and d._kind not in allowed:
+                _wrong_kind(metric, d._kind)
+        if len(self._data) != len(other._data):
+            raise InvalidArgumentError(
+                f"{metric}: digests of different sizes "
+                f"({len(self._data)} and {len(other._data)} bytes)"
+            )
+        return digest_to_c(self), digest_to_c(other)
+
+    def hamming_distance(self, other: Digest) -> int:
+        """Count the differing bits between two ``BITS`` digests (BMH, mHash)."""
+        a, b = self._pair(other, "hamming_distance")
+        return int(
+            _sentinel(int(lib.ph_hamming_distance_digest(a, b)), "hamming_distance")
+        )
+
+    def l2_distance(self, other: Digest) -> float:
+        """Euclidean distance between two feature vectors (ColorMoments)."""
+        a, b = self._pair(other, "l2_distance")
+        return float(_sentinel(float(lib.ph_l2_distance(a, b)), "l2_distance"))
+
+    def histogram_intersection(self, other: Digest) -> float:
+        """Share of color two ``HISTOGRAM`` digests (ColorHash) have in common.
+
+        The result is 0.0 to 1.0.
+        """
+        a, b = self._pair(other, "histogram_intersection")
+        return _out_double(
+            lib.ph_histogram_intersection, a, b, "histogram_intersection"
+        )
+
+    def radial_similarity(self, other: Digest) -> float:
+        """Peak cross-correlation of two Radial digests, -1.0 to 1.0.
+
+        Raises :class:`NoStructureError` when either digest is flat (all bytes equal),
+        as the Radial hash of an image without angular structure is: any score would be
+        invented. :data:`RADIAL_PCC_THRESHOLD` is the source's cut for "same image".
+        """
+        a, b = self._pair(other, "radial_similarity")
+        return _out_double(lib.ph_radial_similarity, a, b, "radial_similarity")
+
+    def similarity(self, other: Digest) -> float:
+        """Compare with the similarity measure that belongs to the digests' kind.
+
+        ``BITS``: share of equal bits, 0.0 to 1.0. ``HISTOGRAM``: histogram
+        intersection, 0.0 to 1.0. ``COEFFICIENTS``: radial peak correlation, -1.0 to
+        1.0. ``VECTOR16`` (ColorMoments) has no normalized similarity: use
+        :meth:`l2_distance`.
+        """
+        other = _as_digest(other)
+        kind = self._kind if self._kind != DigestKind.UNSPECIFIED else other._kind
+        if kind == DigestKind.BITS:
+            a, b = self._pair(other, "hamming_distance")
+            value = float(lib.ph_similarity_digest(a, b))
+            return float(_sentinel(value, "similarity"))
+        if kind == DigestKind.HISTOGRAM:
+            return self.histogram_intersection(other)
+        if kind == DigestKind.COEFFICIENTS:
+            return self.radial_similarity(other)
+        if kind == DigestKind.UNSPECIFIED:
+            raise DigestKindError(
+                "similarity: neither digest states its kind, so the measure is "
+                "unknown; call hamming_distance(), l2_distance(), "
+                "histogram_intersection() or radial_similarity() explicitly"
+            )
+        raise DigestKindError(
+            f"similarity: {kind.name} digests have no normalized similarity; "
+            "use l2_distance()"
+        )
+
+
+def digest_from_c(c_digest: ph_digest_t_ptr) -> Digest:
+    """Copy a ``ph_digest_t *`` into a Digest."""
+    return Digest(bytes(ffi.buffer(c_digest.data, c_digest.size)), int(c_digest.kind))
+
+
+def digest_to_c(digest: Digest) -> ph_digest_t_ptr:
+    """Return a new ``ph_digest_t *`` holding ``digest``."""
+    data = digest.data
+    c_digest = ffi.new("ph_digest_t *")
+    c_digest.size = len(data)
+    c_digest.kind = int(digest.kind)
+    ffi.memmove(c_digest.data, data, len(data))
+    return c_digest
+
+
+def _as_digest(other: object) -> Digest:
+    if not isinstance(other, Digest):
+        raise TypeError(f"expected a Digest, got {type(other).__name__}")
+    return other
+
+
+def _wrong_kind(metric: str, kind: DigestKind) -> NoReturn:
+    right = {
+        DigestKind.BITS: "hamming_distance() or similarity()",
+        DigestKind.VECTOR: "l2_distance()",
+        DigestKind.VECTOR16: "l2_distance()",
+        DigestKind.HISTOGRAM: "histogram_intersection() or similarity()",
+        DigestKind.COEFFICIENTS: "radial_similarity() or similarity()",
+    }[kind]
+    raise DigestKindError(
+        f"{metric} does not apply to {kind.name} digests; use {right}"
+    )
+
+
+def _sentinel(value: _N, metric: str) -> _N:
+    # The checks in _pair leave the C library nothing to reject; -1 here would be a
+    # contract the binding missed.
+    if value < 0:
+        raise InvalidArgumentError(f"{metric}: the C library rejected the digests")
+    return value
+
+
+def _out_double(
+    func: Callable[[ph_digest_t_ptr, ph_digest_t_ptr, double_ptr], int],
+    a: ph_digest_t_ptr,
+    b: ph_digest_t_ptr,
+    metric: str,
+) -> float:
+    out = ffi.new("double *")
+    code = func(a, b, out)
+    if code != PH_SUCCESS:
+        raise make_error(code, context=metric)
+    return float(out[0])
+
+
+def _check_uint64(value: object) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"a 64-bit hash is an int, got {type(value).__name__}")
+    if not 0 <= value <= _UINT64_MAX:
+        raise InvalidArgumentError(f"a 64-bit hash is in [0, 2**64), got {value}")
+    return value
+
+
+def hamming_distance(a: int, b: int) -> int:
+    """Count the differing bits between two 64-bit hashes, 0 to 64."""
+    return int(lib.ph_hamming_distance(_check_uint64(a), _check_uint64(b)))
+
+
+def similarity(a: int, b: int) -> float:
+    """Share of equal bits between two 64-bit hashes.
+
+    1.0 means identical; unrelated images score near 0.5.
+    """
+    return float(lib.ph_similarity(_check_uint64(a), _check_uint64(b)))
+
+
+def hash_to_hex(value: int) -> str:
+    """Format a 64-bit hash as 16 lowercase hex digits, most significant first."""
+    out = ffi.new("char[]", 17)
+    code = lib.ph_hash_to_hex(_check_uint64(value), out, 17)
+    if code != PH_SUCCESS:
+        raise make_error(code, context="encoding hash")
+    return str(ffi.string(out).decode("ascii"))
+
+
+def hash_from_hex(text: str) -> int:
+    """Parse the 16 hex digits written by :func:`hash_to_hex`."""
+    out = ffi.new("uint64_t *")
+    code = lib.ph_hash_from_hex(encode_text(text), out)
+    if code != PH_SUCCESS:
+        raise make_error(code, context=f"parsing hash {text[:40]!r}")
+    return int(out[0])
+
+
+RADIAL_PCC_THRESHOLD: float = float(lib.PH_RADIAL_PCC_THRESHOLD)

libphash/_errors.py

@@ -0,0 +1,109 @@
+"""Turning a ``ph_error_t`` into the exception of :mod:`libphash.exceptions`."""
+
+from __future__ import annotations
+
+import errno
+import os
+from typing import TYPE_CHECKING
+
+from ._native import ffi, lib
+from .exceptions import (
+    AllocationError,
+    BatchCancelledError,
+    CorruptDataError,
+    DecoderUnavailableError,
+    EmptyImageError,
+    ImageIOError,
+    ImageTooLargeError,
+    InvalidArgumentError,
+    NoStructureError,
+    PhashError,
+    RequiresColorError,
+    UnsupportedFormatError,
+)
+
+if TYPE_CHECKING:
+    from ._sources import StrPath
+
+PH_SUCCESS = int(lib.PH_SUCCESS)
+PH_ERR_IO = int(lib.PH_ERR_IO)
+PH_ERR_CANCELLED = int(lib.PH_ERR_CANCELLED)
+
+
+# The OSError subclasses an ImageIOError is raised as, so that ``except
+# FileNotFoundError`` catches a missing image file. Their repr is ImageIOError's.
+class FileNotFoundImageError(ImageIOError, FileNotFoundError):
+    pass
+
+
+class PermissionDeniedImageError(ImageIOError, PermissionError):
+    pass
+
+
+class IsADirectoryImageError(ImageIOError, IsADirectoryError):
+    pass
+
+
+_CLASSES: dict[int, type[PhashError]] = {
+    int(lib.PH_ERR_ALLOCATION_FAILED): AllocationError,
+    int(lib.PH_ERR_INVALID_ARGUMENT): InvalidArgumentError,
+    int(lib.PH_ERR_EMPTY_IMAGE): EmptyImageError,
+    int(lib.PH_ERR_IMAGE_TOO_LARGE): ImageTooLargeError,
+    int(lib.PH_ERR_UNSUPPORTED_FORMAT): UnsupportedFormatError,
+    int(lib.PH_ERR_CORRUPT_DATA): CorruptDataError,
+    int(lib.PH_ERR_DECODER_UNAVAILABLE): DecoderUnavailableError,
+    PH_ERR_IO: ImageIOError,
+    int(lib.PH_ERR_REQUIRES_COLOR): RequiresColorError,
+    PH_ERR_CANCELLED: BatchCancelledError,
+    int(lib.PH_ERR_NO_STRUCTURE): NoStructureError,
+}
+
+
+def error_string(code: int) -> str:
+    """Return the C library's one-line description of a ``ph_error_t``."""
+    return str(ffi.string(lib.ph_get_error_string(code)).decode())
+
+
+def make_error(
+    code: int, *, context: str = "", detail: str = "", path: StrPath | None = None
+) -> PhashError:
+    """Build the exception for a ``ph_error_t``.
+
+    ``context`` says what the binding was doing ("computing phash"); ``detail`` is the C
+    library's message for a load, and is passed only by the load functions, the only
+    ones that write it.
+    """
+    cls = _CLASSES.get(code, PhashError)
+    message = detail or error_string(code)
+    if context:
+        message = f"{context}: {message}"
+    if cls is ImageIOError:
+        return _io_error(message, code, detail, path)
+    return cls(message, code=code, detail=detail)
+
+
+def _io_error(
+    message: str, code: int, detail: str, path: StrPath | None
+) -> ImageIOError:
+    err: int | None = None
+    cls: type[ImageIOError] = ImageIOError
+    if path is not None:
+        # The C library reports every unusable path as PH_ERR_IO; the file system tells
+        # which OSError it is. isdir() and exists() answer False for a path they cannot
+        # check, so access() sees only paths that exist.
+        if os.path.isdir(path):
+            err, cls = errno.EISDIR, IsADirectoryImageError
+        elif not os.path.exists(path):
+            err, cls = errno.ENOENT, FileNotFoundImageError
+        elif not os.access(path, os.R_OK):
+            err, cls = errno.EACCES, PermissionDeniedImageError
+    exc = cls(message, code=code, detail=detail)
+    exc.errno = err
+    exc.filename = os.fsdecode(path) if path is not None else None
+    return exc
+
+
+def check(code: int, *, context: str = "") -> None:
+    """Raise the exception for ``code`` unless it is ``PH_SUCCESS``."""
+    if code != PH_SUCCESS:
+        raise make_error(code, context=context)