Bugfix/fix mypy errors (#13)

* Fix mypy arg-type errors

Add read_image_rgb helper that raises FileNotFoundError when
cv2.imread returns None, and count queries during iteration in
top_k_accuracy instead of calling len() on an Iterable.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Fix mypy assignment errors

Add missing '| None' to parameters defaulting to None, declare
attribute placeholders with their real types, and correct the
similarity_func type: it returns a similarity matrix (np.ndarray),
not a float. ImageEncoderBase now requires a feature extractor and
defaults similarity_func to cosine_similarity instead of None.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Fix mypy attr-defined errors

Import FeatureExtractorBase and SimilarityMetric from their defining
module, annotate the _pca/_clustering_model placeholders, and replace
property fget/fset class access with a protected _set_clustering_model
method that subclass setters call directly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Fix mypy import-untyped errors

Add per-module ignore_missing_imports overrides for third-party
libraries that ship without type stubs or a py.typed marker.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Fix mypy misc error

Use non-inplace division in RootSIFT since in-place true division is
not defined for the integer dtypes cv2 may return.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Fix mypy no-any-return errors

Wrap untyped sklearn results in np.asarray, type the Lambda
extractor's callable precisely, validate the submodule returned by
getattr, and convert scipy .mat labels to int explicitly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Fix mypy no-untyped-call errors

Annotate setup_logging, _set_clustering_model, _register_hook,
download_oxford_flowers_data and the SIFT/RootSIFT constructors, and
replace torch's untyped private Module._get_name() with
type(...).__name__.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Fix mypy no-untyped-def errors

Annotate all remaining functions: typed decorator pattern for
_check_output_shape and _tupleize_first_arg, an Encoder protocol for
eval functions, property getter/setter annotations, and **kwargs
types. similarity_score now honestly returns the np.ndarray
similarity matrix it always produced at runtime.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Fix mypy operator and return-value errors

Type list_conv_layers as returning Conv2d layers so out_channels is
an int instead of the Tensor | Module union from Module.__getattr__.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Fix mypy safe-super errors

Remove no-op super().__call__ invocations of the abstract base
method from the feature extractors.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Fix mypy type-arg errors

Parameterize the bare generic types: list[Any] for the heatmap matrix
and Dataset[tuple[np.ndarray, int, str]] for OxfordFlowerDataset.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Fix remaining mypy assignment errors

Annotate the hook buffer as Tensor | None, widen the VLAD descriptor
vector annotation, and use a separate variable for the spatial
coordinates array.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* bumpy Python version up to 3.12

* fixed div by zero error in top_k_accuracy

* fixed wrong api in docstring (compute_vector -> encode)


---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: MechaCritter

CONTRIBUTING.md

@@ -35,7 +35,7 @@ This project uses [uv](https://github.com/astral-sh/uv) instead of `pip` for man
 
 ### Prerequisites
 
-- Python >= 3.10
+- Python >= 3.12
 - [uv](https://github.com/astral-sh/uv)
 
 ### Steps

README.md

@@ -7,7 +7,7 @@
 ![License](https://img.shields.io/badge/license-MIT-brightgreen)
 ![Version](https://img.shields.io/badge/version-0.1.3-blue)
 ![Status](https://img.shields.io/badge/status-pre--release-orange)
-![Python](https://img.shields.io/badge/Python-3.10%2B-brightgreen)
+![Python](https://img.shields.io/badge/Python-3.12%2B-brightgreen)
 ![Contributions](https://img.shields.io/badge/contributions-welcome-brightgreen)
 
 # Welcome to `pyvisim`!

pyproject.toml

@@ -11,7 +11,7 @@ license = {text = "MIT"}
 authors = [
     {name = "Nhat Huy Vu", email = "vunhathuy234@gmail.com"}
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.12"
 classifiers = [
     "Programming Language :: Python :: 3",
     "Operating System :: OS Independent",
@@ -62,7 +62,7 @@ fmt = [
 ]
 
 [tool.mypy]
-python_version = "3.14"
+python_version = "3.12"
 strict = true
 warn_return_any = true
 warn_unused_configs = true
@@ -77,8 +77,21 @@ no_implicit_optional = true
 check_untyped_defs = true
 exclude = ["^build/", "^dist/", "^\\.venv/", "^venv/"]
 
+# Third-party libraries that ship without type stubs or a py.typed marker.
+[[tool.mypy.overrides]]
+module = [
+  "joblib.*",
+  "scipy.*",
+  "seaborn.*",
+  "sklearn.*",
+  "torchvision.*",
+  "tqdm.*",
+  "yaml.*",
+]
+ignore_missing_imports = true
+
 [tool.ruff]
-target-version = "py314"
+target-version = "py312"
 line-length = 88
 
 [tool.ruff.lint]

pyvisim/_base_classes.py

@@ -17,13 +17,13 @@ class SimilarityMetric(abc.ABC):
     @abc.abstractmethod
     def similarity_score(
         self, image1: Iterable[np.ndarray], image2: Iterable[np.ndarray]
-    ):
+    ) -> np.ndarray:
         """
         Compute a similarity score between two images.
 
         :param image1: First image
         :param image2: Second image
-        :return: A similarity score
+        :return: A similarity score matrix
         """
         pass
 
@@ -39,7 +39,7 @@ class FeatureExtractorBase(abc.ABC):
     _logger = logging.getLogger("Feature_Extractor")
 
     @abc.abstractmethod
-    def __call__(self, image: np.ndarray):
+    def __call__(self, image: np.ndarray, /) -> np.ndarray:
         """
         Extracts features from an image.
 

pyvisim/_config.py

@@ -17,7 +17,10 @@
 
 
 # - Logging - #
-def setup_logging(default_path=LOGGER_FILE, default_level=logging.WARNING):
+def setup_logging(
+    default_path: str | pathlib.Path = LOGGER_FILE,
+    default_level: int = logging.WARNING,
+) -> None:
     """Setup logging configuration"""
     try:
         with open(default_path) as f:

pyvisim/_utils.py

@@ -1,5 +1,6 @@
-from typing import Literal
+from typing import Any, Literal
 
+import cv2
 import matplotlib.pyplot as plt
 import numpy as np
 import seaborn as sns
@@ -13,6 +14,20 @@
 from sklearn.metrics.pairwise import cosine_similarity as cs
 
 
+def read_image_rgb(path: str) -> np.ndarray:
+    """
+    Read an image from disk and convert it to RGB.
+
+    :param path: Path to the image file.
+    :return: Image as a NumPy array (H, W, C) in RGB order.
+    :raises FileNotFoundError: If the image cannot be read from the given path.
+    """
+    image = cv2.imread(path)
+    if image is None:
+        raise FileNotFoundError(f"Could not read image at '{path}'.")
+    return cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+
+
 def cosine_similarity(x: np.ndarray, y: np.ndarray) -> np.ndarray:
     """
     Compute the cosine similarity between two matrices.
@@ -33,7 +48,7 @@ def cosine_similarity(x: np.ndarray, y: np.ndarray) -> np.ndarray:
             f"Cosine similarity requires at least 2 features. Got {x.shape[-1]} features for x and {y.shape[-1]} features for y."
         )
 
-    return cs(x, y)
+    return np.asarray(cs(x, y))
 
 
 def plot_image(image: np.ndarray | torch.Tensor, title: str = "Image") -> None:
@@ -59,7 +74,7 @@ def cluster_and_return_labels(
     data: np.ndarray,
     method: Literal["kmeans", "dbscan", "spectral"] = "kmeans",
     n_clusters: int | None = None,
-    **kwargs,
+    **kwargs: Any,
 ) -> np.ndarray:
     """
     Clusters 'data' using the specified method.
@@ -74,12 +89,12 @@ def cluster_and_return_labels(
         if n_clusters is None:
             raise ValueError("n_clusters must be specified for KMeans.")
         model = KMeans(n_clusters=n_clusters, random_state=42, **kwargs)
-        return model.fit_predict(data)
+        return np.asarray(model.fit_predict(data))
 
     if method == "dbscan":
         # DBSCAN doesn't need n_clusters (but can accept eps, min_samples)
         model = DBSCAN(**kwargs)
-        return model.fit_predict(data)
+        return np.asarray(model.fit_predict(data))
 
     if method == "spectral":
         if n_clusters is None:
@@ -90,7 +105,7 @@ def cluster_and_return_labels(
             random_state=42,
             **kwargs,
         )
-        return model.fit_predict(data)
+        return np.asarray(model.fit_predict(data))
 
     raise ValueError(f"Unknown method: {method}")
 
@@ -100,7 +115,7 @@ def cluster_images_and_generate_statistics(
     true_labels: np.ndarray,
     n_clusters: int,
     method: Literal["kmeans", "dbscan", "spectral"] = "kmeans",
-    **kwargs,
+    **kwargs: Any,
 ) -> dict[str, float]:
     """
     Clusters the given features and computes RI, ARI and NMI.
@@ -127,7 +142,7 @@ def cluster_images_and_generate_statistics(
 
 
 def plot_and_save_heatmap(
-    matrix: list | np.ndarray | torch.Tensor,
+    matrix: list[Any] | np.ndarray | torch.Tensor,
     figsize: tuple[int, int] | None = None,
     x_tick_labels: list[str] | None = None,
     y_tick_labels: list[str] | None = None,

pyvisim/datasets/datasets.py

@@ -2,7 +2,6 @@
 import os
 from multiprocessing import Process
 
-import cv2
 import numpy as np
 import requests
 import scipy
@@ -12,6 +11,7 @@
 from tqdm import tqdm
 
 from pyvisim._config import setup_logging
+from pyvisim._utils import read_image_rgb
 
 setup_logging()
 
@@ -35,7 +35,7 @@
 NUM_VAL_IMG = 1020
 
 
-def _download_and_process_file(url: str, dest: str, extract_dir: str):
+def _download_and_process_file(url: str, dest: str, extract_dir: str) -> None:
     """
     Downloads a file and processes it (e.g., extraction if it's a zip or tar.gz file).
     """
@@ -53,7 +53,7 @@ def _download_and_process_file(url: str, dest: str, extract_dir: str):
         os.remove(dest)
 
 
-def _download_file_with_progress(url: str, dest: str):
+def _download_file_with_progress(url: str, dest: str) -> None:
     """
     Download a file with a progress bar.
     """
@@ -78,7 +78,7 @@ def _download_file_with_progress(url: str, dest: str):
     logger.info(f"Downloaded file to {dest}")
 
 
-def _extract_zip(zip_file: str, extract_to: str):
+def _extract_zip(zip_file: str, extract_to: str) -> None:
     """
     Extract a zip archive.
     """
@@ -97,7 +97,7 @@ def _extract_zip(zip_file: str, extract_to: str):
                 progress_bar.update(1)
 
 
-def _extract_tar(tar_file: str, extract_to: str):
+def _extract_tar(tar_file: str, extract_to: str) -> None:
     """
     Extract a tar.gz archive.
     """
@@ -184,7 +184,7 @@ def _check_data_integrity() -> bool:
     return True
 
 
-def download_oxford_flowers_data():
+def download_oxford_flowers_data() -> None:
     """
     Downloads the 102 flowers dataset and organizes it into the desired structure,
     under `destination/oxford_flower_dataset/`.
@@ -207,7 +207,7 @@ def download_oxford_flowers_data():
     logger.info("Oxford Flowers dataset downloaded and processed successfully.")
 
 
-class OxfordFlowerDataset(Dataset):
+class OxfordFlowerDataset(Dataset[tuple[np.ndarray, int, str]]):
     """
     Oxford Flower Dataset. It can be found at: https://www.robots.ox.ac.uk/~vgg/data/flowers/102/index.html.
 
@@ -249,7 +249,7 @@ def _load_labels(self, labels_file: str) -> list[int]:
         :return: List of labels.
         """
         mat_data = scipy.io.loadmat(labels_file)
-        return mat_data["labels"].squeeze().tolist()
+        return [int(label) for label in mat_data["labels"].squeeze()]
 
     def _load_image_paths(self) -> list[str]:
         """
@@ -319,7 +319,7 @@ def __getitem__(self, idx: int) -> tuple[np.ndarray, int, str]:
         img_path = self.image_paths[idx]
         label = self.labels[idx] if self.labels else -1
 
-        image = cv2.cvtColor(cv2.imread(img_path), cv2.COLOR_BGR2RGB)
+        image = read_image_rgb(img_path)
 
         if self.transform:
             image = self.transform(image)