python-libphash 2.0.1.0__cp315-cp315t-win_amd64.whl

libphash/_config.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+import dataclasses
+import math
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, NoReturn, cast
+
+from ._errors import PH_SUCCESS, check, error_string
+from ._native import ffi, lib
+from .exceptions import InvalidArgumentError
+
+if TYPE_CHECKING:
+    from ._native import ph_context_t_ptr
+
+WHashMode = Literal["fast", "full"]
+AlphaMode = Literal["grey", "white", "black", "ignore"]
+DecodeScale = Literal[1, 2, 4, 8]
+
+_WHASH_MODES = {"fast": lib.PH_WHASH_FAST, "full": lib.PH_WHASH_FULL}
+_ALPHA_MODES = {
+    "grey": lib.PH_ALPHA_BLEND_GREY,
+    "white": lib.PH_ALPHA_BLEND_WHITE,
+    "black": lib.PH_ALPHA_BLEND_BLACK,
+    "ignore": lib.PH_ALPHA_IGNORE,
+}
+_DECODE_SCALES = {
+    1: lib.PH_DECODE_SCALE_FULL,
+    2: lib.PH_DECODE_SCALE_HALF,
+    4: lib.PH_DECODE_SCALE_QUARTER,
+    8: lib.PH_DECODE_SCALE_EIGHTH,
+}
+
+
+@dataclass(frozen=True)
+class Config:
+    """How images are loaded and hashed: every setting of a libphash context.
+
+    The defaults are libphash's. A ``Config`` is checked when it is created, against the
+    ranges the C library accepts, so a bad value fails here with the name of the field
+    and not at the first hash. It is immutable; :meth:`replace` gives a modified copy.
+    The same object configures an :class:`ImageContext`, :func:`hash` and a batch.
+
+    Hash values depend on the settings: two hashes are comparable only when computed
+    with equal configurations (and the same libphash version).
+    """
+
+    #: Gamma applied before the Radial hash's projections; read by Radial only.
+    gamma: float = 1.0
+    #: Relative R, G, B weights of the grayscale conversion.
+    gray_weights: tuple[int, int, int] = (38, 75, 15)
+    #: pHash: side of the DCT grid (``phash_reduction_size``..32).
+    phash_dct_size: int = 32
+    #: pHash: side of the low-frequency block the hash is made of, 4..8 (the hash has
+    #: its square in bits).
+    phash_reduction_size: int = 8
+    #: Radial: number of lines through the center, 40..4096.
+    radial_projections: int = 180
+    #: Radial: points read on each line, 2..4096.
+    radial_samples: int = 128
+    #: Radial: Gaussian blur sigma before the projections, (0, 64/3].
+    radial_sigma: float = 3.5
+    #: BMH: side of the block grid, 2..32 (the digest has its square in bits).
+    bmh_block_size: int = 16
+    #: mHash: scale base (> 1).
+    mhash_alpha: float = 2.0
+    #: mHash: scale exponent (>= 0).
+    mhash_level: float = 1.0
+    #: mHash: normalization side, 62..4096.
+    mhash_size: int = 512
+    #: wHash: ``"fast"`` (16x16, one Haar level) or ``"full"`` (ImageHash's scale).
+    whash_mode: WHashMode = "fast"
+    #: wHash: zero the coarsest LL coefficient (ImageHash's ``remove_max_haar_ll``).
+    whash_remove_max_haar_ll: bool = False
+    #: Decode to one gray channel: faster, but the color algorithms then raise
+    #: RequiresColorError.
+    grayscale: bool = False
+    #: How an alpha channel is resolved: blended over grey, white or black, or ignored.
+    alpha_mode: AlphaMode = "grey"
+    #: Apply the EXIF orientation of JPEG and PNG files and buffers.
+    auto_orient: bool = True
+    #: Largest image accepted, in pixels; 0 leaves only the library's fixed limit.
+    max_pixels: int = 256 * 1024 * 1024
+    #: Decode at 1/1, 1/2, 1/4 or 1/8 of the resolution where the decoder can (JPEG).
+    decode_scale: DecodeScale = 1
+
+    def __post_init__(self) -> None:
+        _check_types(self)
+        ctx = new_context()
+        try:
+            apply_config(self, ctx)
+        finally:
+            lib.ph_free(ctx)
+
+    def replace(self, **changes: Any) -> Config:  # noqa: ANN401 -- checked as a new Config
+        """Return a copy with the given fields changed, checked like a new Config."""
+        return dataclasses.replace(self, **changes)
+
+
+def apply_config(cfg: Config, ctx: ph_context_t_ptr) -> None:
+    """Set every field of ``cfg`` on a ``ph_context_t``."""
+    steps: list[tuple[str, int]] = [
+        ("gamma", lib.ph_context_set_gamma(ctx, cfg.gamma)),
+        ("gray_weights", lib.ph_context_set_gray_weights(ctx, *cfg.gray_weights)),
+        (
+            "phash_dct_size/phash_reduction_size",
+            lib.ph_context_set_phash_params(
+                ctx, cfg.phash_dct_size, cfg.phash_reduction_size
+            ),
+        ),
+        (
+            "radial_projections/radial_samples/radial_sigma",
+            lib.ph_context_set_radial_params(
+                ctx, cfg.radial_projections, cfg.radial_samples, cfg.radial_sigma
+            ),
+        ),
+        (
+            "bmh_block_size",
+            lib.ph_context_set_block_params(ctx, cfg.bmh_block_size),
+        ),
+        (
+            "mhash_alpha/mhash_level/mhash_size",
+            lib.ph_context_set_mhash_params(
+                ctx, cfg.mhash_alpha, cfg.mhash_level, cfg.mhash_size
+            ),
+        ),
+        (
+            "whash_mode",
+            lib.ph_context_set_whash_mode(ctx, _WHASH_MODES[cfg.whash_mode]),
+        ),
+        (
+            "whash_remove_max_haar_ll",
+            lib.ph_context_set_whash_remove_max_haar_ll(
+                ctx, int(cfg.whash_remove_max_haar_ll)
+            ),
+        ),
+        ("grayscale", lib.ph_context_set_load_grayscale(ctx, int(cfg.grayscale))),
+        (
+            "alpha_mode",
+            lib.ph_context_set_alpha_mode(ctx, _ALPHA_MODES[cfg.alpha_mode]),
+        ),
+        ("auto_orient", lib.ph_context_set_auto_orient(ctx, int(cfg.auto_orient))),
+        ("max_pixels", lib.ph_context_set_max_pixels(ctx, cfg.max_pixels)),
+        (
+            "decode_scale",
+            lib.ph_context_set_decode_scale(ctx, _DECODE_SCALES[cfg.decode_scale]),
+        ),
+    ]
+    for name, code in steps:
+        if code != PH_SUCCESS:
+            values = ", ".join(f"{f}={getattr(cfg, f)!r}" for f in name.split("/"))
+            raise InvalidArgumentError(
+                f"Config: {values} is out of range: {error_string(code)}", code=code
+            )
+
+
+def new_context() -> ph_context_t_ptr:
+    out = ffi.new("ph_context_t **")
+    check(lib.ph_create(out), context="creating a context")
+    return out[0]
+
+
+def _check_types(cfg: Config) -> None:
+    # Annotations do not bind an untyped caller: every value is checked as an object.
+    def fail(name: str, expected: str) -> NoReturn:
+        raise InvalidArgumentError(
+            f"Config: {name} must be {expected}, got {getattr(cfg, name)!r}"
+        )
+
+    def value(name: str) -> object:
+        return getattr(cfg, name)
+
+    for name in ("gamma", "radial_sigma", "mhash_alpha", "mhash_level"):
+        v = value(name)
+        if (
+            isinstance(v, bool)
+            or not isinstance(v, (int, float))
+            or not math.isfinite(v)
+        ):
+            fail(name, "a finite number")
+    for name in (
+        "phash_dct_size",
+        "phash_reduction_size",
+        "radial_projections",
+        "radial_samples",
+        "bmh_block_size",
+        "mhash_size",
+        "max_pixels",
+    ):
+        if not _is_int(value(name)):
+            fail(name, "an int")
+    if not (0 <= cfg.max_pixels < 1 << 64):
+        fail("max_pixels", "in [0, 2**64)")
+    weights = value("gray_weights")
+    items = cast("tuple[object, ...]", weights) if isinstance(weights, tuple) else ()
+    if len(items) != 3 or not all(_is_int(w) for w in items):
+        fail("gray_weights", "a tuple of three ints")
+    for name in ("whash_remove_max_haar_ll", "grayscale", "auto_orient"):
+        if not isinstance(value(name), bool):
+            fail(name, "a bool")
+    if value("whash_mode") not in _WHASH_MODES:
+        fail("whash_mode", "one of " + ", ".join(map(repr, _WHASH_MODES)))
+    if value("alpha_mode") not in _ALPHA_MODES:
+        fail("alpha_mode", "one of " + ", ".join(map(repr, _ALPHA_MODES)))
+    scale = value("decode_scale")
+    if not _is_int(scale) or scale not in _DECODE_SCALES:
+        fail("decode_scale", "1, 2, 4 or 8")
+
+
+def _is_int(v: object) -> bool:
+    return isinstance(v, int) and not isinstance(v, bool)

libphash/_context.py

@@ -0,0 +1,388 @@
+from __future__ import annotations
+
+import os
+import threading
+from typing import TYPE_CHECKING, Literal, NoReturn, cast, overload
+
+from ._algorithms import Algorithm, AlgorithmLike, to_algorithm, uint64_flags
+from ._config import Config, apply_config, new_context
+from ._digest import Digest, digest_from_c
+from ._errors import PH_SUCCESS, make_error
+from ._native import ffi, lib
+from ._sources import (
+    READ_FILES_IN_PYTHON,
+    ChannelOrder,
+    PILImage,
+    PixelArray,
+    Pixels,
+    Source,
+    StrPath,
+    SupportsArrayInterface,
+    SupportsRead,
+    encode_path,
+    is_pil_image,
+    pixels_from_array,
+    pixels_from_pil,
+    read_file,
+)
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    from ._native import ph_context_t_ptr
+
+#: Names of the algorithms that produce a 64-bit ``int``.
+Uint64Name = Literal["ahash", "dhash", "phash", "whash"]
+#: Names of the algorithms that produce a :class:`Digest`.
+DigestName = Literal["bmh", "mhash", "radial", "color_hash", "color_moments"]
+#: The algorithms that produce a 64-bit ``int``.
+Uint64Algorithm = Literal[
+    Algorithm.AHASH, Algorithm.DHASH, Algorithm.PHASH, Algorithm.WHASH
+]
+#: The algorithms that produce a :class:`Digest`.
+DigestAlgorithm = Literal[
+    Algorithm.BMH,
+    Algorithm.MHASH,
+    Algorithm.RADIAL,
+    Algorithm.COLOR_HASH,
+    Algorithm.COLOR_MOMENTS,
+]
+
+_UINT64_COMPUTE = {
+    Algorithm.AHASH: lib.ph_compute_ahash,
+    Algorithm.DHASH: lib.ph_compute_dhash,
+    Algorithm.PHASH: lib.ph_compute_phash,
+    Algorithm.WHASH: lib.ph_compute_whash,
+}
+
+
+class ImageContext:
+    """One image and the configuration to hash it with: a libphash ``ph_context_t``.
+
+    Load an image with one of the ``load_*`` methods, then compute any number of hashes
+    from it; loading the next image reuses the context's buffers, which makes a context
+    kept across a loop faster than :func:`hash` per image.
+
+    A context is safe to share between threads: the calls into C are serialized on a
+    lock of the context. Threads that work in parallel each need their own context (or a
+    batch, :func:`hash_files`). Close it with :meth:`close` or a ``with`` block; one
+    left to the garbage collector is freed too.
+    """
+
+    __slots__ = ("__weakref__", "_config", "_lock", "_ptr")
+
+    def __init__(self, config: Config | None = None) -> None:
+        self._lock = threading.Lock()
+        self._config = _config_or_default(config)
+        ptr = new_context()
+        self._ptr: ph_context_t_ptr | None = ffi.gc(ptr, lib.ph_free)
+        apply_config(self._config, self._ptr)
+
+    # --- Lifecycle -------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Free the C context. Idempotent; any later use raises ValueError."""
+        with self._lock:
+            if self._ptr is not None:
+                ffi.release(self._ptr)
+                self._ptr = None
+
+    @property
+    def closed(self) -> bool:
+        return self._ptr is None
+
+    def __enter__(self) -> Self:
+        self._live()
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        if self._ptr is None:
+            return "<ImageContext closed>"
+        if not self.is_loaded:
+            return "<ImageContext empty>"
+        return f"<ImageContext {self.width}x{self.height}x{self.channels}>"
+
+    def __reduce__(self) -> NoReturn:
+        raise TypeError("ImageContext cannot be pickled; pickle its Config instead")
+
+    def __copy__(self) -> NoReturn:
+        raise TypeError(
+            "ImageContext cannot be copied; create one from its Config instead"
+        )
+
+    def __deepcopy__(self, memo: object) -> NoReturn:
+        self.__copy__()
+
+    def _live(self) -> ph_context_t_ptr:
+        ptr = self._ptr
+        if ptr is None:
+            raise ValueError("operation on a closed ImageContext")
+        return ptr
+
+    # --- State -----------------------------------------------------------------------
+
+    @property
+    def config(self) -> Config:
+        return self._config
+
+    @property
+    def is_loaded(self) -> bool:
+        with self._lock:
+            return bool(lib.ph_is_loaded(self._live()))
+
+    def _dimensions(self) -> tuple[int, int, int]:
+        out = ffi.new("int[]", 3)
+        with self._lock:
+            lib.ph_context_get_dimensions(self._live(), out, out + 1, out + 2)
+        return int(out[0]), int(out[1]), int(out[2])
+
+    @property
+    def width(self) -> int:
+        """Width of the loaded image (after orientation and decode scale), 0 if none."""
+        return self._dimensions()[0]
+
+    @property
+    def height(self) -> int:
+        return self._dimensions()[1]
+
+    @property
+    def channels(self) -> int:
+        """3 for color, 1 for grayscale.
+
+        An alpha channel is resolved at load and not kept.
+        """
+        return self._dimensions()[2]
+
+    # --- Loading ---------------------------------------------------------------------
+
+    def load(self, source: Source) -> None:
+        """Load whatever ``source`` is.
+
+        ``source`` is a path, encoded bytes, a binary file object, an array of pixels or
+        a Pillow image. Bytes are always the encoded file, never a path.
+        """
+        if isinstance(source, (str, os.PathLike)):
+            self.load_file(source)
+        elif isinstance(source, (bytes, bytearray)):
+            self.load_bytes(source)
+        elif isinstance(source, memoryview):
+            if source.ndim in (2, 3):
+                self.load_pixels(source)
+            else:
+                self.load_bytes(source)
+        elif is_pil_image(source):
+            self.load_pil(cast("PILImage", source))
+        elif isinstance(source, SupportsArrayInterface):
+            self.load_pixels(source)
+        elif callable(getattr(source, "read", None)):
+            self.load_fileobj(source)
+        else:
+            raise TypeError(
+                "expected a path, bytes, a binary file object, an array of pixels or a "
+                f"Pillow image, got {type(source).__name__}"
+            )
+
+    def load_file(self, path: StrPath) -> None:
+        """Load an image file. On failure the context holds no image."""
+        encoded = encode_path(path)
+        if READ_FILES_IN_PYTHON:
+            self.load_bytes(read_file(path))
+            return
+        with self._lock:
+            ptr = self._live()
+            code = lib.ph_load_from_file(ptr, encoded)
+            if code != PH_SUCCESS:
+                raise make_error(code, detail=self._last_message(ptr), path=path)
+
+    def load_bytes(self, data: bytes | bytearray | memoryview) -> None:
+        """Load an encoded image (JPEG, PNG, WebP, ...) from memory, without a copy.
+
+        The buffer must not change while the call runs. On failure the context holds no
+        image.
+        """
+        try:
+            buf = ffi.from_buffer("const uint8_t[]", data)
+        except TypeError:
+            raise TypeError(
+                f"expected bytes-like encoded image data, got {type(data).__name__}"
+            ) from None
+        with self._lock:
+            ptr = self._live()
+            code = lib.ph_load_from_memory(ptr, buf, len(buf))
+            if code != PH_SUCCESS:
+                raise make_error(code, detail=self._last_message(ptr))
+
+    def load_fileobj(self, fileobj: SupportsRead) -> None:
+        """Read a binary file object to its end and load the bytes.
+
+        The object is an open file, an ``io.BytesIO``, a response body or anything else
+        with a ``read()`` that returns bytes.
+        """
+        self.load_bytes(_read_all(fileobj))
+
+    def load_pixels(
+        self, pixels: PixelArray, channel_order: ChannelOrder = "rgb"
+    ) -> None:
+        """Load decoded pixels.
+
+        ``pixels`` is an 8-bit array of shape (h, w), (h, w, 1), (h, w, 3) or (h, w, 4),
+        e.g. a numpy ``uint8`` array. ``channel_order="bgr"`` reads OpenCV's order. The
+        pixels are copied into the context, and no EXIF orientation applies. On failure
+        the previously loaded image stays loaded.
+        """
+        self._load_pixels(pixels_from_array(pixels, channel_order))
+
+    def load_pil(self, image: PILImage) -> None:
+        """Load a Pillow image.
+
+        :func:`pixels_from_pil` describes how each mode is read.
+        """
+        self._load_pixels(pixels_from_pil(image))
+
+    def _load_pixels(self, px: Pixels) -> None:
+        with self._lock:
+            ptr = self._live()
+            code = lib.ph_load_from_pixels(
+                ptr, px.pointer, px.width, px.height, px.channels, px.stride
+            )
+            if code != PH_SUCCESS:
+                # libphash writes no message for a pixel load.
+                raise make_error(code)
+        del px
+
+    @staticmethod
+    def _last_message(ptr: ph_context_t_ptr) -> str:
+        # Never NULL: an empty string when the last load set no message.
+        msg = lib.ph_get_last_error_message(ptr)
+        return str(ffi.string(msg).decode("utf-8", "replace"))
+
+    # --- Hashing ---------------------------------------------------------------------
+
+    @overload
+    def hash(self, algorithm: Uint64Algorithm | Uint64Name = ...) -> int: ...
+    @overload
+    def hash(self, algorithm: DigestAlgorithm | DigestName) -> Digest: ...
+    @overload
+    def hash(self, algorithm: AlgorithmLike) -> int | Digest: ...
+
+    def hash(self, algorithm: AlgorithmLike = Algorithm.PHASH) -> int | Digest:
+        """Compute one hash of the loaded image.
+
+        Returns an ``int`` for aHash, dHash, pHash and wHash, a :class:`Digest` for the
+        others.
+        """
+        algo = to_algorithm(algorithm)
+        with self._lock:
+            return _compute(self._live(), algo)
+
+    def hashes(self, *algorithms: AlgorithmLike) -> dict[Algorithm, int | Digest]:
+        """Compute several hashes at once, all of the same loaded image.
+
+        The 64-bit ones share their work on the full image (one ``ph_compute_multi``
+        call); digests are computed one by one. No other thread loads an image in
+        between.
+        """
+        algos = [to_algorithm(a) for a in algorithms] or [Algorithm.PHASH]
+        uint64 = sorted({a for a in algos if a in _UINT64_COMPUTE})
+        result: dict[Algorithm, int | Digest] = {}
+        with self._lock:
+            ptr = self._live()
+            if uint64:
+                out = ffi.new("uint64_t[]", len(uint64))
+                code = lib.ph_compute_multi(ptr, uint64_flags(uint64), out)
+                if code != PH_SUCCESS:
+                    raise make_error(
+                        code, context="computing " + ", ".join(map(str, uint64))
+                    )
+                # Slots follow ascending flag bits, which is ascending Algorithm value.
+                result.update(zip(uint64, (int(v) for v in out), strict=True))
+            for algo in algos:
+                if algo not in result:
+                    result[algo] = _compute(ptr, algo)
+        return {a: result[a] for a in algos}
+
+    def ahash(self) -> int:
+        """Average hash: each cell of an 8x8 grayscale reduction against their mean."""
+        return self.hash(Algorithm.AHASH)
+
+    def dhash(self) -> int:
+        """Difference hash: horizontal neighbor comparisons in a 9x8 reduction."""
+        return self.hash(Algorithm.DHASH)
+
+    def phash(self) -> int:
+        """Perceptual hash: the low-frequency DCT block of a reduction.
+
+        Each coefficient is compared with the block's median.
+        """
+        return self.hash(Algorithm.PHASH)
+
+    def whash(self) -> int:
+        """Wavelet hash: the low-frequency Haar band of a reduction.
+
+        Each coefficient is compared with the band's median.
+        """
+        return self.hash(Algorithm.WHASH)
+
+    def bmh(self) -> Digest:
+        """Block mean hash: one bit per block of a ``bmh_block_size`` grid (BITS)."""
+        return self.hash(Algorithm.BMH)
+
+    def mhash(self) -> Digest:
+        """Marr-Hildreth hash: a Laplacian-of-Gaussian response (BITS).
+
+        Nine bits per window, 576 bits in all.
+        """
+        return self.hash(Algorithm.MHASH)
+
+    def radial(self) -> Digest:
+        """Radial variance hash: rotation-tolerant projections (COEFFICIENTS)."""
+        return self.hash(Algorithm.RADIAL)
+
+    def color_hash(self) -> Digest:
+        """Color histogram, compared by histogram intersection (HISTOGRAM)."""
+        return self.hash(Algorithm.COLOR_HASH)
+
+    def color_moments(self) -> Digest:
+        """Color moments per channel (VECTOR16).
+
+        The mean, the standard deviation and the cube root of the third moment.
+        """
+        return self.hash(Algorithm.COLOR_MOMENTS)
+
+
+def _compute(ptr: ph_context_t_ptr, algo: Algorithm) -> int | Digest:
+    """Compute one hash; the caller holds the context's lock."""
+    compute = _UINT64_COMPUTE.get(algo)
+    if compute is not None:
+        out64 = ffi.new("uint64_t *")
+        code = compute(ptr, out64)
+        if code != PH_SUCCESS:
+            raise make_error(code, context=f"computing {algo}")
+        return int(out64[0])
+    digest = ffi.new("ph_digest_t *")
+    code = lib.ph_compute_digest(ptr, int(algo), digest)
+    if code != PH_SUCCESS:
+        raise make_error(code, context=f"computing {algo}")
+    return digest_from_c(digest)
+
+
+def _config_or_default(config: object) -> Config:
+    if config is None:
+        return Config()
+    if not isinstance(config, Config):
+        raise TypeError(f"expected a Config, got {type(config).__name__}")
+    return config
+
+
+def _read_all(fileobj: SupportsRead) -> bytes | bytearray | memoryview:
+    data = cast("object", fileobj.read())  # checked: an untyped read() may return str
+    if isinstance(data, (bytes, bytearray)):
+        return data
+    if isinstance(data, memoryview):
+        return cast("memoryview", data)
+    raise TypeError(
+        f"{type(fileobj).__name__}.read() returned {type(data).__name__}, not bytes"
+    )