docs: fixed additional typing errors

Author: mdevolde

aztec_tool/codewords.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 from functools import cached_property
-from typing import List, Optional
+from typing import List, Optional, Tuple
 
 import numpy as np
+import numpy.typing as npt
 import reedsolo
 
 from .enums import AztecTableType, AztecType, ReadingDirection
@@ -26,7 +27,7 @@ class CodewordReader:
     """Read the data spiral, apply Reed-Solomon correction and decode code-words.
 
     :param matrix: Square binary matrix (0/1) representing the Aztec symbol.
-    :type matrix: numpy.ndarray
+    :type matrix: npt.NDArray[np.int_]
     :param layers: Number of data layers (excluding the bull's-eye).
     :type layers: int
     :param data_words: Expected count of data code-words (script does *not* include ECC words).
@@ -54,7 +55,7 @@ class CodewordReader:
 
     def __init__(
         self,
-        matrix: np.ndarray,
+        matrix: npt.NDArray[np.int_],
         layers: int,
         data_words: int,
         aztec_type: AztecType,
@@ -93,15 +94,15 @@ def _is_reference(self, r: int, c: int) -> bool:
         centre = self.matrix.shape[0] // 2
         return bool((r - centre) % 16 == 0 or (c - centre) % 16 == 0)
 
-    def _read_bits(self) -> np.ndarray:
-        bitmap = []
+    def _read_bits(self) -> npt.NDArray[np.int_]:
+        bitmap: List[int] = []
         square_size = self.matrix.shape[0]
         reading_direction = ReadingDirection.BOTTOM
-        start_point = (
+        start_point: Tuple[int, int] = (
             0,
             0,
         )  # We start reading from the top left corner to the bottom left corner
-        end_point = (
+        end_point: Tuple[int, int] = (
             square_size
             - 1
             - 2,  # - 2 because the two last lines are readed in a different direction
@@ -120,15 +121,15 @@ def _read_bits(self) -> np.ndarray:
                             not self._is_reference(i, start_point[1])
                             or self.aztec_type == AztecType.COMPACT
                         ):
-                            bitmap.append(
+                            bitmap.extend(
                                 self.matrix[i, start_point[1] : end_point[1] + 1]
                             )
                     elif reading_direction == ReadingDirection.RIGHT:
                         if (
                             not self._is_reference(start_point[0], i)
                             or self.aztec_type == AztecType.COMPACT
                         ):
-                            bitmap.append(
+                            bitmap.extend(
                                 self.matrix[start_point[0] : end_point[0] - 1 : -1, i]
                             )
                     elif reading_direction == ReadingDirection.TOP:
@@ -138,7 +139,7 @@ def _read_bits(self) -> np.ndarray:
                             )
                             or self.aztec_type == AztecType.COMPACT
                         ):
-                            bitmap.append(
+                            bitmap.extend(
                                 self.matrix[
                                     start_point[0] - i + apply_to_borns,
                                     start_point[1] : end_point[1] - 1 : -1,
@@ -151,7 +152,7 @@ def _read_bits(self) -> np.ndarray:
                             )
                             or self.aztec_type == AztecType.COMPACT
                         ):
-                            bitmap.append(
+                            bitmap.extend(
                                 self.matrix[
                                     start_point[0] : end_point[0] + 1,
                                     start_point[1] - i + apply_to_borns,
@@ -198,14 +199,14 @@ def _read_bits(self) -> np.ndarray:
                 "no data modules extracted - check bull's-eye/layer count"
             )
 
-        return np.concatenate(bitmap).astype(int)
+        return np.array(bitmap, dtype=int)
 
     @cached_property
-    def bitmap(self) -> np.ndarray:
+    def bitmap(self) -> npt.NDArray[np.int_]:
         """Raw bit-stream extracted from the symbol (before ECC correction)."""
         return self._read_bits()
 
-    def _correct(self) -> List[int]:
+    def _correct(self) -> npt.NDArray[np.int_]:
         if self.layers <= 2:
             cw_size = 6
         elif self.layers <= 8:
@@ -248,15 +249,15 @@ def _correct(self) -> List[int]:
         except reedsolo.ReedSolomonError as exc:
             raise ReedSolomonError(str(exc)) from exc
 
-        corrected_bits = []
+        corrected_bits: List[int] = []
         for sym in full_codeword:
             for shift in range(cw_size - 1, -1, -1):
                 corrected_bits.append((sym >> shift) & 1)
 
-        return corrected_bits
+        return np.array(corrected_bits, dtype=int)
 
     @cached_property
-    def corrected_bits(self) -> List[int]:
+    def corrected_bits(self) -> npt.NDArray[np.int_]:
         """Bit-stream after Reed-Solomon decoding and bit-stuff removal."""
         return self._correct()
 
@@ -269,7 +270,7 @@ def _bits_to_bytes(cls, bits: List[int]) -> bytes:
         return bytes(cls._bits_to_int(bits[i : i + 8]) for i in range(0, len(bits), 8))
 
     def _remove_stuff_bits(
-        self, bits: List[int], cw_size: int, data_words: int
+        self, bits: npt.NDArray[np.int_], cw_size: int, data_words: int
     ) -> List[int]:
         """Remove the stuffing bits from the bit-stream.
 
@@ -279,7 +280,7 @@ def _remove_stuff_bits(
         Remove also the padding bits at the beginning of the stream.
 
         :param bits: The bit-stream to clean.
-        :type bits: List[int]
+        :type bits: npt.NDArray[np.int_]
         :param cw_size: The size of the code-words (6, 8, 10 or 12).
         :type cw_size: int
         :param data_words: The number of data code-words in the symbol.
@@ -288,7 +289,7 @@ def _remove_stuff_bits(
         :return: The cleaned bit-stream without the stuffed bits and the padding bits.
         :rtype: List[int]
         """
-        cleaned = []
+        cleaned: List[int] = []
         i = 0
         words_seen = 0
         while words_seen < data_words and i < len(bits):
@@ -324,7 +325,7 @@ def _decode(self) -> str:
             bits = self._remove_stuff_bits(self.bitmap, codeword_size, self.data_words)
 
         i = 0
-        chars = []
+        chars: List[str] = []
         current_mode = AztecTableType.UPPER  # Default mode is UPPER
         previous_mode = AztecTableType.UPPER
         single_shift = False

aztec_tool/decoder.py

@@ -7,6 +7,7 @@
 from typing import List, Optional, Tuple, Union
 
 import numpy as np
+import numpy.typing as npt
 
 from .codewords import CodewordReader
 from .detection import BullseyeDetector
@@ -32,7 +33,7 @@ class AztecDecoder:
     :type image_path: Optional[Union[str, Path]]
     :param matrix: Binary matrix (0/1) of the Aztec symbol. If not provided, the
         *image_path* parameter must be used instead.
-    :type matrix: Optional[np.ndarray]
+    :type matrix: Optional[npt.NDArray[np.int_]]
     :param auto_orient: If *True*, the matrix is rotated automatically so that orientation
         patterns match the canonical position (black-white corner pattern), defaults to ``True``
     :type auto_orient: Optional[bool]
@@ -70,7 +71,7 @@ def __init__(
         self,
         image_path: Optional[Union[str, Path]] = None,
         *,
-        matrix: Optional[np.ndarray] = None,
+        matrix: Optional[npt.NDArray[np.int_]] = None,
         auto_orient: Optional[bool] = True,
         auto_correct: Optional[bool] = True,
         mode_auto_correct: Optional[bool] = True,
@@ -80,7 +81,7 @@ def __init__(
                 "either 'image_path' or 'matrix' must be provided"
             )
 
-        self._input_matrix: Optional[np.ndarray] = None
+        self._input_matrix: Optional[npt.NDArray[np.int_]] = None
         if matrix is not None:
             if not isinstance(matrix, np.ndarray) or matrix.ndim != 2:
                 raise InvalidParameterError(
@@ -100,7 +101,7 @@ def __init__(
         self._mode_auto_correct = mode_auto_correct
 
     @cached_property
-    def _raw_matrix(self) -> np.ndarray:
+    def _raw_matrix(self) -> npt.NDArray[np.int_]:
         if self._input_matrix is not None:
             return self._input_matrix
         return AztecMatrix(str(self.image_path)).matrix
@@ -120,7 +121,7 @@ def aztec_type(self) -> AztecType:
         return self._bullseye.aztec_type
 
     @cached_property
-    def matrix(self) -> np.ndarray:
+    def matrix(self) -> npt.NDArray[np.int_]:
         """Final, possibly rotated, binary matrix (0/1) of the symbol."""
         if not self._auto_orient:
             return self._raw_matrix
@@ -151,12 +152,12 @@ def _codewords(self) -> CodewordReader:
         )
 
     @cached_property
-    def bitmap(self) -> np.ndarray:
+    def bitmap(self) -> npt.NDArray[np.int_]:
         """Raw bit-stream extracted from the data spiral (before ECC)."""
         return self._codewords.bitmap
 
     @cached_property
-    def corrected_bits(self) -> List[int]:
+    def corrected_bits(self) -> npt.NDArray[np.int_]:
         """Bit-stream after Reed-Solomon correction and bit-stuff removal."""
         return self._codewords.corrected_bits
 

aztec_tool/detection.py

@@ -4,6 +4,7 @@
 from typing import Tuple, Union
 
 import numpy as np
+import numpy.typing as npt
 
 from .enums import AztecType
 from .exceptions import (
@@ -22,7 +23,7 @@ class BullseyeDetector:
     the detector expands outward ring-by-ring until the pattern breaks.
 
     :param matrix: Square binary matrix (0/1) representing the entire Aztec symbol.
-    :type matrix: numpy.ndarray
+    :type matrix: npt.NDArray[np.int_]
 
     :raises InvalidParameterError: *matrix* is not a square 2-D array of **odd** side length.
     :raises BullseyeDetectionError: The alternating ring pattern cannot be found (symbol damaged or
@@ -41,7 +42,7 @@ class BullseyeDetector:
         <AztecType.FULL: 1>
     """
 
-    def __init__(self, matrix: np.ndarray) -> None:
+    def __init__(self, matrix: npt.NDArray[np.int_]) -> None:
         if matrix.ndim != 2 or matrix.shape[0] != matrix.shape[1]:
             raise InvalidParameterError("matrix must be a square 2-D array")
         if matrix.shape[0] % 2 == 0:

aztec_tool/matrix.py

@@ -8,6 +8,8 @@
 
 import cv2
 import numpy as np
+import numpy.typing as npt
+from cv2.typing import MatLike
 
 from .exceptions import InvalidParameterError, UnsupportedSymbolError
 
@@ -46,7 +48,7 @@ def _detect_rois(
         min_area_ratio: float = 0.005,
         ar_tol: float = 0.15,
         density_tol: float = 0.15,
-    ) -> List[Tuple[np.ndarray, Tuple[int, int, int, int]]]:
+    ) -> List[Tuple[MatLike, Tuple[int, int, int, int]]]:
         """Detect all candidate Aztec codes in the image and return the crops.
 
         :param min_area_ratio: Minimum area of the detected region as a fraction of the image area, defaults to 0.005
@@ -60,7 +62,7 @@ def _detect_rois(
         :rtype: List[Tuple[crop_BGR, (x, y, w, h)]]
         """
 
-        img = cv2.imread(self.image_path)
+        img = cv2.imread(str(self.image_path))
         h, w = img.shape[:2]
 
         gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
@@ -74,7 +76,7 @@ def _detect_rois(
         n_labels, _, stats, _ = cv2.connectedComponentsWithStats(inv, connectivity=8)
 
         img_area = h * w
-        rois = []  # results
+        rois: List[Tuple[MatLike, Tuple[int, int, int, int]]] = []  # results
 
         for i in range(1, n_labels):  # 0 = background, we start from 1
             x, y, ww, hh, area = stats[i]
@@ -101,11 +103,11 @@ def _detect_rois(
         print(len(rois))
         return rois
 
-    def _estimate_n(self, binary: np.ndarray) -> int:
+    def _estimate_n(self, binary: MatLike) -> int:
         h, w = binary.shape
         row = (binary[h // 2, :] < 128).astype(int)
 
-        runs = []
+        runs: List[int] = []
         current = row[0]
         length = 1
         for pix in row[1:]:
@@ -127,7 +129,7 @@ def _estimate_n(self, binary: np.ndarray) -> int:
             raise UnsupportedSymbolError(f"unsupported Aztec side length: {n}")
         return n
 
-    def _matrix_from_crop(self, crop: np.ndarray) -> np.ndarray:
+    def _matrix_from_crop(self, crop: MatLike) -> npt.NDArray[np.int_]:
         """Convert a *single* square crop to a binary module matrix."""
         gray = cv2.cvtColor(crop, cv2.COLOR_BGR2GRAY)
         _, binary = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
@@ -152,18 +154,16 @@ def _matrix_from_crop(self, crop: np.ndarray) -> np.ndarray:
                 matrix[y, x] = 1 if binary[cy, cx] < 128 else 0
         return matrix
 
-    def _extract_matrix(self) -> List[np.ndarray]:
+    def _extract_matrix(self) -> List[npt.NDArray[np.int_]]:
         rois = self._detect_rois() if self._multiple else []
         if not rois:  # No Aztec code croped, try to read the whole image
             img = cv2.imread(str(self.image_path))
-            if img is None:
-                raise InvalidParameterError(f"cannot read image: {self.image_path}")
             try:
                 return [self._matrix_from_crop(img)]
             except (InvalidParameterError, UnsupportedSymbolError):
                 return []  # no Aztec code found
 
-        matrices = []
+        matrices: List[npt.NDArray[np.int_]] = []
         for crop, _ in rois:
             try:
                 matrices.append(self._matrix_from_crop(crop))
@@ -174,15 +174,15 @@ def _extract_matrix(self) -> List[np.ndarray]:
         return matrices
 
     @cached_property
-    def matrices(self) -> List[np.ndarray]:
+    def matrices(self) -> List[npt.NDArray[np.int_]]:
         """List of module matrices detected in the image."""
         matrices = self._extract_matrix()
         if not matrices:
             raise InvalidParameterError("no Aztec matrix detected in the image")
         return matrices
 
     @cached_property
-    def matrix(self) -> np.ndarray:
+    def matrix(self) -> npt.NDArray[np.int_]:
         """The binary module matrix (0 = white, 1 = black), shape (N, N). Lazy property."""
         if not self.matrices:
             raise InvalidParameterError("no Aztec matrix detected in the image")