python-libphash 1.0.3__cp313-cp313-macosx_11_0_arm64.whl

libphash/__init__.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from .exceptions import (
+    PhashError,
+    AllocationError,
+    DecodeError,
+    InvalidArgumentError,
+)
+from .types import Digest, HashMethod
+from .context import ImageContext
+from .utils import hamming_distance, get_hash, compare_images
+
+__all__ = [
+    "PhashError",
+    "AllocationError",
+    "DecodeError",
+    "InvalidArgumentError",
+    "Digest",
+    "HashMethod",
+    "ImageContext",
+    "hamming_distance",
+    "get_hash",
+    "compare_images",
+]

libphash/_build.py

@@ -0,0 +1,97 @@
+import os
+import glob
+from cffi import FFI
+
+ffibuilder = FFI()
+
+# 1. Define the C definitions exposed to Python
+# We strip macros like PH_API for CFFI parsing
+ffibuilder.cdef("""
+    // Constants
+    #define PH_DIGEST_MAX_BYTES 64
+
+    // Error Codes
+    typedef enum {
+        PH_SUCCESS = 0,
+        PH_ERR_ALLOCATION_FAILED = -1,
+        PH_ERR_DECODE_FAILED = -2,
+        PH_ERR_INVALID_ARGUMENT = -3,
+        PH_ERR_NOT_IMPLEMENTED = -4,
+        PH_ERR_EMPTY_IMAGE = -5,
+        ...
+    } ph_error_t;
+
+    // Types
+    typedef struct ph_context ph_context_t;
+
+    typedef struct {
+        uint8_t data[PH_DIGEST_MAX_BYTES];
+        uint8_t size;
+        uint8_t reserved[7];
+    } ph_digest_t;
+
+    // Lifecycle
+    const char *ph_version(void);
+    ph_error_t ph_create(ph_context_t **out_ctx);
+    void ph_free(ph_context_t *ctx);
+    void ph_context_set_gamma(ph_context_t *ctx, float gamma);
+
+    // Loading
+    ph_error_t ph_load_from_file(ph_context_t *ctx, const char *filepath);
+    ph_error_t ph_load_from_memory(ph_context_t *ctx, const uint8_t *buffer, size_t length);
+
+    // uint64 Hashes
+    ph_error_t ph_compute_ahash(ph_context_t *ctx, uint64_t *out_hash);
+    ph_error_t ph_compute_dhash(ph_context_t *ctx, uint64_t *out_hash);
+    ph_error_t ph_compute_phash(ph_context_t *ctx, uint64_t *out_hash);
+    ph_error_t ph_compute_whash(ph_context_t *ctx, uint64_t *out_hash);
+    ph_error_t ph_compute_mhash(ph_context_t *ctx, uint64_t *out_hash);
+
+    // Digest Hashes
+    ph_error_t ph_compute_bmh(ph_context_t *ctx, ph_digest_t *out_digest);
+    ph_error_t ph_compute_color_hash(ph_context_t *ctx, ph_digest_t *out_digest);
+    ph_error_t ph_compute_radial_hash(ph_context_t *ctx, ph_digest_t *out_digest);
+
+    // Comparison
+    int ph_hamming_distance(uint64_t hash1, uint64_t hash2);
+    int ph_hamming_distance_digest(const ph_digest_t *a, const ph_digest_t *b);
+    double ph_l2_distance(const ph_digest_t *a, const ph_digest_t *b);
+""")
+
+# 2. Configure the Source Compilation
+# We need to find all .c files in the native directory
+curr_dir = os.path.dirname(os.path.abspath(__file__))
+project_root = os.path.abspath(os.path.join(curr_dir, "../../"))
+native_dir = os.path.abspath(os.path.join(project_root, "native", "libphash"))
+
+sources = []
+sources.extend(glob.glob(os.path.join(native_dir, "src", "*.c")))
+sources.extend(glob.glob(os.path.join(native_dir, "src", "hashes", "*.c")))
+
+include_dirs = ["native/libphash/include"]
+source_files = [
+    "native/libphash/src/core.c",
+    "native/libphash/src/image.c",
+    "native/libphash/src/hashes/ahash.c",
+    "native/libphash/src/hashes/bmh.c",
+    "native/libphash/src/hashes/color_hash.c",
+    "native/libphash/src/hashes/common.c",
+    "native/libphash/src/hashes/dhash.c",
+    "native/libphash/src/hashes/mhash.c",
+    "native/libphash/src/hashes/phash.c",
+    "native/libphash/src/hashes/radial.c",
+    "native/libphash/src/hashes/whash.c",
+]
+
+ffibuilder.set_source(
+    "libphash._native",
+    '#include "libphash.h"',
+    sources=source_files,
+    include_dirs=include_dirs,
+    libraries=["m"] if os.name == "posix" else [],
+    extra_compile_args=["-O3", "-Wall", "-fPIC"]
+    if os.name == "posix"
+    else ["/O2", "/W3"],
+)
+if __name__ == "__main__":
+    ffibuilder.compile(verbose=True)

libphash/_native.pyi

@@ -0,0 +1,39 @@
+# src/libphash/_native.pyi
+from typing import Any
+
+class FFI:
+    def new(self, type_name: str, value: Any = None) -> Any: ...
+    def buffer(self, ptr: Any, size: int) -> Any: ...
+    def memmove(self, dest: Any, src: Any, n: int) -> None: ...
+
+class Lib:
+    # Lifecycle
+    def ph_create(self, ctx: Any) -> int: ...
+    def ph_free(self, ctx: Any) -> None: ...
+
+    # Loading
+    def ph_load_from_file(self, ctx: Any, path: bytes) -> int: ...
+    def ph_load_from_memory(self, ctx: Any, data: bytes, size: int) -> int: ...
+
+    # Settings
+    def ph_context_set_gamma(self, ctx: Any, gamma: float) -> None: ...
+
+    # Hashes (uint64)
+    def ph_compute_ahash(self, ctx: Any, out: Any) -> int: ...
+    def ph_compute_dhash(self, ctx: Any, out: Any) -> int: ...
+    def ph_compute_phash(self, ctx: Any, out: Any) -> int: ...
+    def ph_compute_whash(self, ctx: Any, out: Any) -> int: ...
+    def ph_compute_mhash(self, ctx: Any, out: Any) -> int: ...
+
+    # Hashes (Digests)
+    def ph_compute_bmh(self, ctx: Any, out: Any) -> int: ...
+    def ph_compute_color_hash(self, ctx: Any, out: Any) -> int: ...
+    def ph_compute_radial_hash(self, ctx: Any, out: Any) -> int: ...
+
+    # Distances
+    def ph_hamming_distance(self, h1: int, h2: int) -> int: ...
+    def ph_hamming_distance_digest(self, d1: Any, d2: Any) -> int: ...
+    def ph_l2_distance(self, d1: Any, d2: Any) -> float: ...
+
+lib: Lib
+ffi: FFI

libphash/context.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+from pathlib import Path
+from typing import Any, final, Callable
+from ._native import ffi, lib
+from .exceptions import check_error
+from .types import Digest
+
+
+@final
+class ImageContext:
+    _ptr: Any
+    _ctx_ptr_ptr: Any
+
+    def __init__(
+        self, path: str | Path | None = None, bytes_data: bytes | None = None
+    ) -> None:
+        self._ctx_ptr_ptr = ffi.new("ph_context_t **")
+        check_error(lib.ph_create(self._ctx_ptr_ptr))
+        self._ptr = self._ctx_ptr_ptr[0]
+
+        try:
+            if path is not None:
+                self.load_from_file(path)
+            elif bytes_data is not None:
+                self.load_from_memory(bytes_data)
+        except Exception:
+            self.close()
+            raise
+
+    def close(self) -> None:
+        if hasattr(self, "_ptr") and self._ptr is not None:
+            lib.ph_free(self._ptr)
+            self._ptr = None
+
+    def __enter__(self) -> ImageContext:
+        return self
+
+    def __exit__(self, exc_type: type[BaseException] | None, *args: Any) -> None:
+        self.close()
+
+    def load_from_file(self, path: str | Path) -> None:
+        path_obj = Path(path).resolve()
+        if not path_obj.exists():
+            raise FileNotFoundError(f"File not found: {path_obj}")
+        check_error(lib.ph_load_from_file(self._ptr, str(path_obj).encode()))
+
+    def load_from_memory(self, data: bytes) -> None:
+        check_error(lib.ph_load_from_memory(self._ptr, data, len(data)))
+
+    def set_gamma(self, gamma: float) -> None:
+        lib.ph_context_set_gamma(self._ptr, float(gamma))
+
+    # Внутренние хелперы теперь типизированы через Callable
+    def _uint64_prop(self, func: Callable[[Any, Any], int]) -> int:
+        out = ffi.new("uint64_t *")
+        check_error(func(self._ptr, out))
+        return int(out[0])
+
+    def _digest_prop(self, func: Callable[[Any, Any], int]) -> Digest:
+        out = ffi.new("ph_digest_t *")
+        check_error(func(self._ptr, out))
+        return Digest.from_c_struct(out[0])
+
+    @property
+    def ahash(self) -> int:
+        return self._uint64_prop(lib.ph_compute_ahash)
+
+    @property
+    def dhash(self) -> int:
+        return self._uint64_prop(lib.ph_compute_dhash)
+
+    @property
+    def phash(self) -> int:
+        return self._uint64_prop(lib.ph_compute_phash)
+
+    @property
+    def whash(self) -> int:
+        return self._uint64_prop(lib.ph_compute_whash)
+
+    @property
+    def mhash(self) -> int:
+        return self._uint64_prop(lib.ph_compute_mhash)
+
+    @property
+    def bmh(self) -> Digest:
+        return self._digest_prop(lib.ph_compute_bmh)
+
+    @property
+    def color_hash(self) -> Digest:
+        return self._digest_prop(lib.ph_compute_color_hash)
+
+    @property
+    def radial_hash(self) -> Digest:
+        return self._digest_prop(lib.ph_compute_radial_hash)

libphash/exceptions.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+
+class PhashError(Exception):
+    """Base exception for libphash library."""
+
+
+class AllocationError(PhashError):
+    """Raised when memory allocation fails in the C layer."""
+
+
+class DecodeError(PhashError):
+    """Raised when image decoding fails (stb_image error)."""
+
+
+class InvalidArgumentError(PhashError):
+    """Raised when an invalid argument is passed to the C function."""
+
+
+def check_error(err_code: int) -> None:
+    """Map C return codes to Python exceptions."""
+    if err_code == 0:
+        return
+
+    errors: dict[int, tuple[type[PhashError], str]] = {
+        -1: (AllocationError, "Memory allocation failed in libphash"),
+        -2: (DecodeError, "Failed to decode image (stb_image error)"),
+        -3: (InvalidArgumentError, "Invalid argument provided to libphash"),
+        -4: (PhashError, "Feature not implemented"),
+        -5: (PhashError, "Image is empty or invalid"),
+    }
+
+    exc_class, msg = errors.get(
+        err_code, (PhashError, f"Unknown error code: {err_code}")
+    )
+    raise exc_class(msg)

libphash/types.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+from enum import Enum
+from typing import Any, final
+from ._native import ffi, lib
+
+PH_DIGEST_MAX_BYTES: int = 64
+
+
+class HashMethod(Enum):
+    AHASH = "ahash"
+    DHASH = "dhash"
+    PHASH = "phash"
+    WHASH = "whash"
+    MHASH = "mhash"
+
+
+@final
+class Digest:
+    _data: bytes
+    _size: int
+
+    def __init__(self, data: bytes, size: int) -> None:
+        if len(data) > PH_DIGEST_MAX_BYTES:
+            raise ValueError(f"Data exceeds max size ({PH_DIGEST_MAX_BYTES})")
+        self._data = data
+        self._size = size
+
+    @property
+    def data(self) -> bytes:
+        return self._data
+
+    @property
+    def size(self) -> int:
+        return self._size
+
+    @classmethod
+    def from_c_struct(cls, c_digest: Any) -> Digest:
+        # Pyright теперь знает, что у c_digest могут быть поля,
+        # так как мы описали это в .pyi как Any (динамический указатель)
+        size = int(c_digest.size)
+        raw_buffer = ffi.buffer(c_digest.data, size)
+        return cls(bytes(raw_buffer), size)
+
+    def to_c_struct(self) -> Any:
+        c_ptr = ffi.new("ph_digest_t *")
+        c_ptr.size = self._size
+        ffi.memmove(c_ptr.data, self._data, len(self._data))
+        return c_ptr
+
+    def distance_hamming(self, other: Digest) -> int:
+        if self._size != other._size:
+            raise ValueError("Digests must have the same size")
+        return lib.ph_hamming_distance_digest(self.to_c_struct(), other.to_c_struct())
+
+    def distance_l2(self, other: Digest) -> float:
+        if self._size != other._size:
+            raise ValueError("Digests must have the same size")
+        return lib.ph_l2_distance(self.to_c_struct(), other.to_c_struct())

libphash/utils.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+from ._native import lib  # type: ignore
+from .context import ImageContext
+from .types import HashMethod
+
+
+def hamming_distance(h1: int, h2: int) -> int:
+    """Calculate Hamming distance between two uint64 hashes."""
+    return int(lib.ph_hamming_distance(int(h1), int(h2)))  # type: ignore
+
+
+def get_hash(path: str | Path, method: HashMethod = HashMethod.PHASH) -> int:
+    """Convenience function to get a hash for a file."""
+    with ImageContext(path=path) as ctx:
+        return cast(int, getattr(ctx, method.value))
+
+
+def compare_images(
+    path1: str | Path, path2: str | Path, method: HashMethod = HashMethod.PHASH
+) -> int:
+    """Convenience function to compare two images."""
+    with ImageContext(path=path1) as ctx1, ImageContext(path=path2) as ctx2:
+        h1 = cast(int, getattr(ctx1, method.value))
+        h2 = cast(int, getattr(ctx2, method.value))
+        return hamming_distance(h1, h2)

python_libphash-1.0.3.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: python-libphash
+Version: 1.0.3
+Summary: High-performance perceptual hashing library (CFFI bindings)
+Author-email: gudoshnikovn <gudoshnikov-na@yandex.ru>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gudoshnikovn/python-libphash
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cffi>=1.15.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# python-libphash
+
+High-performance Python bindings for [libphash](https://github.com/gudoshnikovn/libphash), a C library for perceptual image hashing.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+## Overview
+
+`libphash` provides multiple algorithms to generate "perceptual hashes" of images. Unlike cryptographic hashes (like MD5 or SHA256), perceptual hashes change only slightly if the image is resized, compressed, or has minor color adjustments. This makes them ideal for finding duplicate or similar images.
+
+### Supported Algorithms
+
+*   **64-bit Hashes (uint64):**
+    *   `ahash`: Average Hash
+    *   `dhash`: Difference Hash
+    *   `phash`: Perceptual Hash (DCT based)
+    *   `whash`: Wavelet Hash
+    *   `mhash`: Median Hash
+*   **Digest Hashes (Multi-byte):**
+    *   `bmh`: Block Mean Hash
+    *   `color_hash`: Color Moment Hash
+    *   `radial_hash`: Radial Variance Hash
+
+## Installation
+
+### Prerequisites
+*   A C compiler (GCC/Clang or MSVC)
+*   Python 3.8 or higher
+
+### Install from source
+```bash
+git clone --recursive https://github.com/yourusername/python-libphash.git
+cd python-libphash
+pip install .
+```
+
+## Quick Start
+
+### Basic Usage
+```python
+from libphash import ImageContext, HashMethod, hamming_distance
+
+# Use the context manager for automatic memory management
+with ImageContext("photo.jpg") as ctx:
+    # Get standard 64-bit hashes
+    phash_val = ctx.phash
+    dhash_val = ctx.dhash
+    
+    print(f"pHash: {phash_val:016x}")
+    print(f"dHash: {dhash_val:016x}")
+
+# Compare two images
+from libphash import compare_images
+distance = compare_images("image1.jpg", "image2.jpg", method=HashMethod.PHASH)
+print(f"Hamming Distance: {distance}")
+```
+
+### Working with Digests (Advanced Hashes)
+Algorithms like Radial Hash or Color Hash return a `Digest` object instead of a single integer.
+
+```python
+with ImageContext("photo.jpg") as ctx:
+    digest = ctx.radial_hash
+    print(f"Digest size: {digest.size} bytes")
+    print(f"Raw data: {digest.data.hex()}")
+
+# Comparing digests
+with ImageContext("photo_v2.jpg") as ctx2:
+    digest2 = ctx2.radial_hash
+    
+    # Hamming distance for bit-wise comparison
+    h_dist = digest.distance_hamming(digest2)
+    
+    # L2 (Euclidean) distance for similarity
+    l2_dist = digest.distance_l2(digest2)
+```
+
+## API Reference
+
+### `ImageContext`
+The main class for loading images and computing hashes.
+*   `__init__(path=None, bytes_data=None)`: Load an image from a file path or memory.
+*   `set_gamma(gamma: float)`: Set gamma correction (useful for Radial Hash).
+*   **Properties**: `ahash`, `dhash`, `phash`, `whash`, `mhash` (returns `int`).
+*   **Properties**: `bmh`, `color_hash`, `radial_hash` (returns `Digest`).
+
+### `Digest`
+*   `data`: The raw `bytes` of the hash.
+*   `size`: Length of the hash in bytes.
+*   `distance_hamming(other)`: Calculates bit-wise distance.
+*   `distance_l2(other)`: Calculates Euclidean distance.
+
+### Utilities
+*   `hamming_distance(h1: int, h2: int)`: Returns the number of differing bits between two 64-bit integers.
+*   `get_hash(path, method)`: Quick way to get a hash without manual context management.
+*   `compare_images(path1, path2, method)`: Returns the Hamming distance between two image files.
+
+## Performance
+Since the core logic is implemented in C and uses `stb_image` for decoding, `libphash` is significantly faster than pure-Python alternatives. It also uses CFFI's "out-of-line" mode for minimal overhead.
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details.
+

python_libphash-1.0.3.dist-info/RECORD

@@ -0,0 +1,14 @@
+libphash/__init__.py,sha256=tqi8ZA7pA1gksrE5pkTYBbIdsB6nFAwNwrYNM_7dpR0,495
+libphash/_build.py,sha256=3JRNepyK7gyYlkD_U0RX505Z-Spn2dJ_wtja0Z7wrM4,3279
+libphash/types.py,sha256=r1gnlvBwCSFgUY5UWe4ZIcm0Zbi4omE9nF8LwIfcV2A,1772
+libphash/_native.abi3.so,sha256=Q_uCYFeYebG33n67He4K7jPA03I_9ymgCBxvkt08kJI,227664
+libphash/context.py,sha256=eCKZNuuadStVmpnI8UcyF_SbKzNaWFTmjv9ryA8zG0c,2879
+libphash/utils.py,sha256=BGYIXyyWluBHlUmPVcStDxP0hTXIFHe1HNd4eoWaQsE,995
+libphash/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+libphash/exceptions.py,sha256=HOo1nWh9jucqgH1c1rkxhZJoYO8EvmO6g3aENrbGn8U,1071
+libphash/_native.pyi,sha256=BUSKo-ZUJyWu-3ftjmVe3nfII-6bOMvte_TCE0kn8lE,1406
+python_libphash-1.0.3.dist-info/RECORD,,
+python_libphash-1.0.3.dist-info/WHEEL,sha256=KreXLeNnYSLDPpk7qnNyKd0DQEhtY-je-mdlEpkBMmo,109
+python_libphash-1.0.3.dist-info/top_level.txt,sha256=_Iys95-wvePR99MGJ1ikgjscpcotnUJ2m3JzmLvCG7w,9
+python_libphash-1.0.3.dist-info/METADATA,sha256=JLoS7kRLWhDRukE0gU8xmJ3VvXfkvmKpAgK7WUubb1c,4377
+python_libphash-1.0.3.dist-info/licenses/LICENSE,sha256=rRPeBnIMO5vVEJAMWDi-pAR4_AD3id6WwDG02zUnYzQ,1069

python_libphash-1.0.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: false
+Tag: cp313-cp313-macosx_11_0_arm64
+

python_libphash-1.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gudoshnikovn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_libphash-1.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+libphash