Perception 0.8.5__tar.gz → 0.9.0__tar.gz

{perception-0.8.5 → perception-0.9.0}/.github/workflows/release.yaml

@@ -4,6 +4,9 @@ on:
     types: [published]
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   build-wheels:
     runs-on: ${{ matrix.os }}

{perception-0.8.5 → perception-0.9.0}/.pre-commit-config.yaml

@@ -24,3 +24,17 @@ repos:
     rev: v1.8.0
     hooks:
       - id: mypy
+        # Limit to package sources; `[tool.mypy] exclude` is ignored when
+        # pre-commit passes file paths as arguments.
+        files: ^perception/
+        # mirrors-mypy runs in an isolated env, so re-list any deps mypy
+        # needs to follow imports / type-check our code. Keep in sync
+        # with the dev dependency group in pyproject.toml.
+        additional_dependencies:
+          - numpy>=1.26.4,<3.0.0
+          - pandas
+          - pandas-stubs
+          - scipy
+          - typing_extensions>=4.0,<5.0
+          - types-pillow
+          - types-tqdm

{perception-0.8.5 → perception-0.9.0}/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2026-05-13
+This release moves heavyweight dependencies behind optional extras so they are not installed for users who only need core hashing functionality, and standardizes the error users see when an extra is missing.
+
+### Breaking changes
+- `faiss-cpu`, `networkit`, and `networkx` are no longer core dependencies. They are pulled in by the new `approximate-deduplication` extra (`pip install perception[approximate-deduplication]`), which is required to use `perception.approximate_deduplication` or `perception.local_descriptor_deduplication`.
+- `pandas` is no longer a core dependency. It is pulled in by the `approximate-deduplication` and `benchmarking` extras (the only modules that use it). Code that imports `perception.benchmarking`, `perception.approximate_deduplication`, `perception.local_descriptor_deduplication`, or `perception.testing` should install the appropriate extra.
+
+### Enhancements
+- All optional-dependency import sites — across the `approximate-deduplication`, `benchmarking`, `matching`, and `pdq` extras — now raise a uniform, actionable `ImportError` pointing at the correct `pip install perception[<extra>]` command when the relevant extra is not installed. This is implemented via a single helper, `perception._optional.import_optional`.
+- `typing_extensions` is now an explicit core dependency (it was previously transitive via `faiss-cpu` / `pandas`).
+
 ## [0.4.0] - 2020-10-17
 This release switches from using false positive rates in benchmarking to reporting precision, which is more intuitive.
 
@@ -33,4 +44,4 @@ This release adds significantly more support for video.
 This release adds more support for hashing videos (including TMK L2 and TMK L2). As part of that, it also includes a re-factor to separate `benchmarking.BenchmarkDataset` and `benchmarking.BenchmarkTransforms` into image and video variants.
 
 ## [0.1.0] - 2019-11-04
-Initial release
+Initial release

{perception-0.8.5/Perception.egg-info → perception-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Perception
-Version: 0.8.5
+Version: 0.9.0
 Summary: Perception provides flexible, well-documented, and comprehensively tested tooling for perceptual hashing research, development, and production use.
 Author-email: Thorn <info@wearethorn.org>
 License-Expression: Apache-2.0
@@ -9,19 +9,22 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy<3.0.0,>=1.26.4
 Requires-Dist: opencv-contrib-python-headless<5.0.0,>=4.10.0
-Requires-Dist: faiss-cpu<2.0.0,>=1.8.0
-Requires-Dist: networkit<12.0.0,>=11.1; sys_platform != "darwin"
-Requires-Dist: networkx<4.0,>=3.0; sys_platform == "darwin"
-Requires-Dist: pandas
 Requires-Dist: Pillow
 Requires-Dist: pywavelets<2.0.0,>=1.5.0
 Requires-Dist: validators<1.0.0,>=0.22.0
 Requires-Dist: rich<14.0.0,>=13.7.0
 Requires-Dist: scipy
 Requires-Dist: tqdm<5.0.0,>=4.67.1
+Requires-Dist: typing_extensions<5.0,>=4.0
+Provides-Extra: approximate-deduplication
+Requires-Dist: faiss-cpu<2.0.0,>=1.8.0; extra == "approximate-deduplication"
+Requires-Dist: networkit<12.0.0,>=11.1; sys_platform != "darwin" and extra == "approximate-deduplication"
+Requires-Dist: networkx<4.0,>=3.0; sys_platform == "darwin" and extra == "approximate-deduplication"
+Requires-Dist: pandas; extra == "approximate-deduplication"
 Provides-Extra: benchmarking
 Requires-Dist: matplotlib; extra == "benchmarking"
 Requires-Dist: albumentations<3.0.0,>=2.0.8; extra == "benchmarking"
+Requires-Dist: pandas; extra == "benchmarking"
 Requires-Dist: tabulate; extra == "benchmarking"
 Requires-Dist: scikit-learn; extra == "benchmarking"
 Requires-Dist: ffmpeg-python; extra == "benchmarking"
@@ -50,6 +53,10 @@ Dynamic: license-file
 
 `perception` provides optional extras for additional functionality:
 
+- `approximate-deduplication` – FAISS-based approximate-nearest-neighbor
+  deduplication and graph community/clique detection (used by
+  `perception.approximate_deduplication` and
+  `perception.local_descriptor_deduplication`)
 - `benchmarking` – tools for benchmarking perceptual hashes
 - `matching` – async matching utilities
 - `pdq` – Facebook's PDQ hash support

{perception-0.8.5 → perception-0.9.0/Perception.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Perception
-Version: 0.8.5
+Version: 0.9.0
 Summary: Perception provides flexible, well-documented, and comprehensively tested tooling for perceptual hashing research, development, and production use.
 Author-email: Thorn <info@wearethorn.org>
 License-Expression: Apache-2.0
@@ -9,19 +9,22 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy<3.0.0,>=1.26.4
 Requires-Dist: opencv-contrib-python-headless<5.0.0,>=4.10.0
-Requires-Dist: faiss-cpu<2.0.0,>=1.8.0
-Requires-Dist: networkit<12.0.0,>=11.1; sys_platform != "darwin"
-Requires-Dist: networkx<4.0,>=3.0; sys_platform == "darwin"
-Requires-Dist: pandas
 Requires-Dist: Pillow
 Requires-Dist: pywavelets<2.0.0,>=1.5.0
 Requires-Dist: validators<1.0.0,>=0.22.0
 Requires-Dist: rich<14.0.0,>=13.7.0
 Requires-Dist: scipy
 Requires-Dist: tqdm<5.0.0,>=4.67.1
+Requires-Dist: typing_extensions<5.0,>=4.0
+Provides-Extra: approximate-deduplication
+Requires-Dist: faiss-cpu<2.0.0,>=1.8.0; extra == "approximate-deduplication"
+Requires-Dist: networkit<12.0.0,>=11.1; sys_platform != "darwin" and extra == "approximate-deduplication"
+Requires-Dist: networkx<4.0,>=3.0; sys_platform == "darwin" and extra == "approximate-deduplication"
+Requires-Dist: pandas; extra == "approximate-deduplication"
 Provides-Extra: benchmarking
 Requires-Dist: matplotlib; extra == "benchmarking"
 Requires-Dist: albumentations<3.0.0,>=2.0.8; extra == "benchmarking"
+Requires-Dist: pandas; extra == "benchmarking"
 Requires-Dist: tabulate; extra == "benchmarking"
 Requires-Dist: scikit-learn; extra == "benchmarking"
 Requires-Dist: ffmpeg-python; extra == "benchmarking"
@@ -50,6 +53,10 @@ Dynamic: license-file
 
 `perception` provides optional extras for additional functionality:
 
+- `approximate-deduplication` – FAISS-based approximate-nearest-neighbor
+  deduplication and graph community/clique detection (used by
+  `perception.approximate_deduplication` and
+  `perception.local_descriptor_deduplication`)
 - `benchmarking` – tools for benchmarking perceptual hashes
 - `matching` – async matching utilities
 - `pdq` – Facebook's PDQ hash support

{perception-0.8.5 → perception-0.9.0}/Perception.egg-info/SOURCES.txt

@@ -34,6 +34,7 @@ docs/examples/deduplication.rst
 docs/examples/detecting_csam.rst
 docs/examples/index.rst
 perception/__init__.py
+perception/_optional.py
 perception/extensions.cpp
 perception/extensions.pyx
 perception/local_descriptor_deduplication.py

{perception-0.8.5 → perception-0.9.0}/Perception.egg-info/requires.txt

@@ -1,23 +1,27 @@
 numpy<3.0.0,>=1.26.4
 opencv-contrib-python-headless<5.0.0,>=4.10.0
-faiss-cpu<2.0.0,>=1.8.0
-pandas
 Pillow
 pywavelets<2.0.0,>=1.5.0
 validators<1.0.0,>=0.22.0
 rich<14.0.0,>=13.7.0
 scipy
 tqdm<5.0.0,>=4.67.1
+typing_extensions<5.0,>=4.0
+
+[approximate-deduplication]
+faiss-cpu<2.0.0,>=1.8.0
+pandas
 
-[:sys_platform != "darwin"]
+[approximate-deduplication:sys_platform != "darwin"]
 networkit<12.0.0,>=11.1
 
-[:sys_platform == "darwin"]
+[approximate-deduplication:sys_platform == "darwin"]
 networkx<4.0,>=3.0
 
 [benchmarking]
 matplotlib
 albumentations<3.0.0,>=2.0.8
+pandas
 tabulate
 scikit-learn
 ffmpeg-python

{perception-0.8.5 → perception-0.9.0}/README.md

@@ -16,6 +16,10 @@
 
 `perception` provides optional extras for additional functionality:
 
+- `approximate-deduplication` – FAISS-based approximate-nearest-neighbor
+  deduplication and graph community/clique detection (used by
+  `perception.approximate_deduplication` and
+  `perception.local_descriptor_deduplication`)
 - `benchmarking` – tools for benchmarking perceptual hashes
 - `matching` – async matching utilities
 - `pdq` – Facebook's PDQ hash support

perception-0.9.0/perception/_optional.py

@@ -0,0 +1,42 @@
+"""Helpers for importing optional dependencies with friendly error messages."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+
+def import_optional(package: str, *, extra: str) -> Any:
+    """Import ``package`` or raise ``ImportError`` pointing at ``extra``.
+
+    Returns the imported module typed as ``Any`` so that attribute access
+    (including in type annotations like ``pd.DataFrame``) is not flagged
+    by static type checkers when the optional package is not installed in
+    the type-checking environment.
+
+    Parameters
+    ----------
+    package:
+        The importable module name (e.g. ``"faiss"``, ``"pandas"``).
+    extra:
+        The name of the ``perception`` extra that provides ``package``
+        (e.g. ``"approximate-deduplication"``).
+    """
+    try:
+        return importlib.import_module(package)
+    except (
+        ModuleNotFoundError
+    ) as exc:  # pragma: no cover - exercised only without extra installed
+        # Only convert to the friendly "install the extra" hint when the
+        # missing module is the optional package itself (or a submodule of
+        # it). If the optional package is installed but one of its own
+        # imports failed, re-raise the original error so the real cause is
+        # not hidden.
+        missing = exc.name or ""
+        top_level = package.split(".", 1)[0]
+        if missing != top_level and not missing.startswith(top_level + "."):
+            raise
+        raise ImportError(
+            f"`{package}` is required for this functionality. Install the "
+            f"'{extra}' extra with `pip install perception[{extra}]`."
+        ) from exc

{perception-0.8.5 → perception-0.9.0}/perception/approximate_deduplication/__init__.py

@@ -3,12 +3,15 @@ import math
 import os.path as op
 import typing
 
-import faiss
 import numpy as np
 import tqdm
 import typing_extensions
 
-from ._graph_backend import get_graph_backend
+from perception._optional import import_optional
+
+faiss = import_optional("faiss", extra="approximate-deduplication")
+
+from ._graph_backend import get_graph_backend  # noqa: E402  (must follow faiss check)
 
 LOGGER = logging.getLogger(__name__)
 DEFAULT_PCT_PROBE = 0

{perception-0.8.5 → perception-0.9.0}/perception/approximate_deduplication/_graph_backend.py

@@ -2,6 +2,8 @@ import sys
 import typing
 from abc import ABC, abstractmethod
 
+from perception._optional import import_optional
+
 
 class GraphBackend(ABC):
     @abstractmethod
@@ -28,9 +30,7 @@ class GraphBackend(ABC):
 
 class NetworkitGraphBackend(GraphBackend):
     def __init__(self):
-        import networkit as nk
-
-        self.nk = nk
+        self.nk = import_optional("networkit", extra="approximate-deduplication")
 
     def build_graph(
         self, node_count: int, edges: typing.Iterable[tuple[int, int]]
@@ -83,9 +83,7 @@ class NetworkitGraphBackend(GraphBackend):
 
 class NetworkxGraphBackend(GraphBackend):
     def __init__(self):
-        import networkx as nx
-
-        self.nx = nx
+        self.nx = import_optional("networkx", extra="approximate-deduplication")
 
     def build_graph(
         self, node_count: int, edges: typing.Iterable[tuple[int, int]]

{perception-0.8.5 → perception-0.9.0}/perception/approximate_deduplication/index.py

@@ -1,13 +1,20 @@
 import time
 import typing
 import warnings
+from typing import TYPE_CHECKING
 
-import faiss
 import numpy as np
-import pandas as pd
 import typing_extensions
 
 import perception.hashers.tools as pht
+from perception._optional import import_optional
+
+if TYPE_CHECKING:
+    import pandas as pd
+else:
+    pd = import_optional("pandas", extra="approximate-deduplication")
+
+faiss = import_optional("faiss", extra="approximate-deduplication")
 
 
 class QueryInput(typing_extensions.TypedDict):

{perception-0.8.5 → perception-0.9.0}/perception/approximate_deduplication/serve.py

@@ -4,14 +4,16 @@ import json
 import logging
 import typing
 
-import aiohttp.web
 import numpy as np
-from pythonjsonlogger import jsonlogger
 
 import perception.hashers.tools as pht
+from perception._optional import import_optional
 
 from .index import ApproximateNearestNeighbors
 
+aiohttp_web = import_optional("aiohttp.web", extra="matching")
+jsonlogger = import_optional("pythonjsonlogger.jsonlogger", extra="matching")
+
 
 def is_similarity_valid(data, index: ApproximateNearestNeighbors):
     """Validates input to the similarity endpoint."""
@@ -54,13 +56,13 @@ async def similarity(request):
     try:
         request_data = await request.json()
     except json.JSONDecodeError:
-        return aiohttp.web.json_response({"reason": "Malformed JSON"}, status=400)
+        return aiohttp_web.json_response({"reason": "Malformed JSON"}, status=400)
 
     index = request.app["index"]
     try:
         assert is_similarity_valid(request_data, index)
     except Exception:
-        return aiohttp.web.json_response({"reason": "Invalid JSON request"}, status=400)
+        return aiohttp_web.json_response({"reason": "Invalid JSON request"}, status=400)
 
     async with request.app["query_semaphore"]:
         matches = await asyncio.get_event_loop().run_in_executor(
@@ -78,7 +80,7 @@ async def similarity(request):
         )
         matches = json.loads(json.dumps({"queries": matches}))
 
-    return aiohttp.web.json_response(matches)
+    return aiohttp_web.json_response(matches)
 
 
 def get_logger(name, log_level):
@@ -133,7 +135,7 @@ async def serve(
     """
     logger = get_logger(name="serve", log_level=log_level)
     logger.info("Initializing web service")
-    app = aiohttp.web.Application()
+    app = aiohttp_web.Application()
     app.router.add_post("/v1/similarity", similarity, name="similarity")
 
     # Store globals in the application object
@@ -144,8 +146,8 @@ async def serve(
     app["index"] = index
     app["query_semaphore"] = asyncio.Semaphore(concurrency)
     logger.info("Entering web service listener loop.")
-    runner = aiohttp.web.AppRunner(app, logger=logger)
+    runner = aiohttp_web.AppRunner(app, logger=logger)
     await runner.setup()
-    site = aiohttp.web.TCPSite(runner, host, port)
+    site = aiohttp_web.TCPSite(runner, host, port)
     await site.start()
     return site

{perception-0.8.5 → perception-0.9.0}/perception/benchmarking/common.py

@@ -7,15 +7,22 @@ import uuid
 import warnings
 import zipfile
 from abc import ABC
+from typing import TYPE_CHECKING
 
-import matplotlib.pyplot as plt
 import numpy as np
-import pandas as pd
 import tqdm
 from scipy import spatial, stats
 
+from .._optional import import_optional
 from ..hashers.tools import compute_md5, string_to_vector
 
+if TYPE_CHECKING:
+    import matplotlib.pyplot as plt
+    import pandas as pd
+else:
+    plt = import_optional("matplotlib.pyplot", extra="benchmarking")
+    pd = import_optional("pandas", extra="benchmarking")
+
 try:
     from . import extensions  # type: ignore
 except ImportError: