docs: adding docstrings and type annotations

Author: mdevolde

README.md

@@ -3,7 +3,7 @@
 [![Test with PyTest](https://github.com/mdevolde/aztec_tool/workflows/Test%20with%20PyTest/badge.svg)](https://github.com/mdevolde/aztec_tool/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-*A fast, pure‑Python Aztec Code reader with auto‑orientation and Reed–Solomon correction.*
+*A fast, pure‑Python Aztec Code reader with auto‑orientation and Reed-Solomon correction.*
 
 -------------
 ## Table of content

TODO.md

@@ -2,5 +2,4 @@
 - Allow to decode Aztec barcodes from other sources than images
 - Auto cropping Aztec barcodes from images
 - Add a `CONTRIBUTING.md`
-- Adding better type annotations
-- Adding docstrings
+- Allow to decode Aztec barcodes from PNG "without white" images

aztec_tool/__init__.py

@@ -2,7 +2,7 @@
 import toml
 from importlib.metadata import PackageNotFoundError
 from pathlib import Path
-from typing import Any
+from typing import Any, Union, Optional
 
 from .decoder import AztecDecoder
 from .exceptions import (
@@ -52,13 +52,50 @@
 
 
 def decode(
-    image_path: str | Path,
+    image_path: Union[str, Path],
     *,
-    auto_orient: bool = True,
-    auto_correct: bool = True,
-    mode_auto_correct: bool = True,
+    auto_orient: Optional[bool] = True,
+    auto_correct: Optional[bool] = True,
+    mode_auto_correct: Optional[bool] = True,
     **kwargs: Any,
 ) -> str:
+    """Decode an Aztec Code image in **one line**.
+
+    This convenience wrapper instantiates :class:`~aztec_tool.decoder.AztecDecoder`
+    and returns its :pyattr:`~aztec_tool.decoder.AztecDecoder.message`
+    property.  All keyword arguments are forwarded unchanged.
+
+    Parameters
+    ----------
+    image_path : Union[str, pathlib.Path]
+        Path to the cropped image containing the Aztec symbol.
+    auto_orient : Optional[bool], default ``True``
+        Auto-rotate the matrix to the canonical orientation.
+    auto_correct : Optional[bool], default ``True``
+        Apply Reed-Solomon correction on the *data* code-words.
+    mode_auto_correct : Optional[bool], default ``True``
+        Apply Reed-Solomon correction on the *mode* message.
+    **kwargs
+        Reserved for future options, currently ignored.
+
+    Returns
+    -------
+    str
+        The decoded user message.
+
+    Raises
+    ------
+    InvalidParameterError
+        The image path is invalid or the file cannot be opened.
+    BullseyeDetectionError, OrientationError, ReedSolomonError, …
+        Any exception propagated by the underlying decoder phases.
+
+    Examples
+    --------
+    >>> from aztec_tool import decode
+    >>> decode("ticket.png")
+    'EVENT: Concert\\nROW 12 SEAT 34'
+    """
     return AztecDecoder(
         image_path,
         auto_orient=auto_orient,

aztec_tool/codewords.py

@@ -2,6 +2,7 @@
 from functools import cached_property
 import numpy as np
 import reedsolo
+from typing import List, Optional
 
 from .tables import TableManager
 from .enums import ReadingDirection, AztecTableType, AztecType
@@ -18,6 +19,45 @@
 
 
 class CodewordReader:
+    """Read the data spiral, apply Reed-Solomon correction and decode code-words.
+
+    Parameters
+    ----------
+    matrix : numpy.ndarray
+        Square binary matrix (0/1) representing the Aztec symbol.
+    layers : int
+        Number of data layers (excluding the bull's-eye).
+    data_words : int
+        Expected count of data code-words (script does *not* include ECC words).
+    aztec_type : AztecType
+        ``AztecType.COMPACT`` or ``AztecType.FULL`` according to the spec.
+    auto_correct : Optional[bool], default ``True``
+        If *True*, a Reed-Solomon pass is executed before high-level decoding.
+
+    Attributes
+    ----------
+    bitmap : numpy.ndarray
+        Raw bit-stream extracted from the symbol (before ECC correction).
+    corrected_bits : List[int]
+        Bit-stream after Reed-Solomon decoding and bit-stuff removal.
+    decoded_string : str
+        Final user message built with the Aztec shift/latch tables.
+
+    Raises
+    ------
+    InvalidParameterError
+        One of the constructor arguments is incoherent (e.g. *layers* < 1).
+    BitReadError
+        Data spiral extraction failed (index out of matrix or empty result).
+    ReedSolomonError
+        The Reed-Solomon decoder could not correct the symbol.
+    BitStuffingError
+        Stuffed/padding bits do not follow the spec rules.
+    SymbolDecodeError
+        An index maps to no entry in the current character table.
+    StreamTerminationError
+        Premature end of bit-stream (e.g. incomplete Byte-shift segment).
+    """
 
     PRIM_POLY = {
         6: 0x43,  # x^6 + x^5 + 1
@@ -32,8 +72,8 @@ def __init__(
         layers: int,
         data_words: int,
         aztec_type: AztecType,
-        auto_correct: bool = True,
-    ):
+        auto_correct: Optional[bool] = True,
+    ) -> None:
         if layers < 1:
             raise InvalidParameterError("layers must be ≥ 1")
         if matrix.ndim != 2 or matrix.shape[0] != matrix.shape[1]:
@@ -49,7 +89,7 @@ def __init__(
         self.aztec_type = aztec_type
         self.auto_correct = auto_correct
 
-    def _is_reference(self, r, c):
+    def _is_reference(self, r: int, c: int) -> bool:
         centre = self.matrix.shape[0] // 2
         return (r - centre) % 16 == 0 or (c - centre) % 16 == 0
 
@@ -153,7 +193,7 @@ def _read_bits(self) -> np.ndarray:
     def bitmap(self) -> np.ndarray:
         return self._read_bits()
 
-    def _correct(self) -> list:
+    def _correct(self) -> List[int]:
         if self.layers <= 2:
             cw_size = 6
         elif self.layers <= 8:
@@ -200,18 +240,20 @@ def _correct(self) -> list:
         return corrected_bits
 
     @cached_property
-    def corrected_bits(self) -> list[int]:
+    def corrected_bits(self) -> List[int]:
         return self._correct()
 
     @classmethod
-    def _bits_to_int(cls, bits) -> int:
+    def _bits_to_int(cls, bits: List[int]) -> int:
         return int("".join(str(b) for b in bits), 2)
 
     @classmethod
-    def _bits_to_bytes(cls, bits) -> bytes:
+    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, cw_size, data_words):
+    def _remove_stuff_bits(
+        self, bits: List[int], cw_size: int, data_words: int
+    ) -> List[int]:
         cleaned = []
         i = 0
         words_seen = 0

aztec_tool/decoder.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 from functools import cached_property
 from pathlib import Path
+from typing import Union, Optional, Tuple, List, Dict
+import numpy as np
 
 from .matrix import AztecMatrix
 from .detection import BullseyeDetector
@@ -14,13 +16,74 @@
 
 
 class AztecDecoder:
+    """High-level façade that decodes an Aztec symbol from an image in **one line**.
+
+        This class orchestrates all lower-level components:
+        :class:`AztecMatrix`, :class:`BullseyeDetector`,
+        :class:`OrientationManager`, :class:`ModeReader` and
+        :class:`CodewordReader`.
+
+        Parameters
+        ----------
+        image_path : Union[str, Path]
+            Path to the image file **already cropped** to the Aztec symbol.
+        auto_orient : Optional[bool], default ``True``
+            If *True*, the matrix is rotated automatically so that orientation
+            patterns match the canonical position (black-white corner pattern).
+        auto_correct :  Optional[bool], default ``True``
+            Apply Reed-Solomon correction on the *data* code-words before
+            high-level decoding.  Disable it for debugging corrupted symbols.
+        mode_auto_correct :  Optional[bool], default ``True``
+            Apply Reed-Solomon correction on the *mode message* (layers, data
+            words, ecc bits).
+
+        Attributes
+        ----------
+        matrix : numpy.ndarray
+            Final, possibly rotated, binary matrix (0/1) of the symbol.
+        aztec_type : AztecType
+            ``COMPACT`` or ``FULL`` deduced from the bull's-eye.
+        bullseye_bounds : Tuple[int, int, int, int]
+            Coordinates of the bull's-eye corners.
+        mode_info : Dict[str, Union[int, List[int]]]
+            Parsed mode fields - keys ``layers``, ``data_words``, ``ecc_bits``.
+        bitmap : numpy.ndarray
+            Raw bit-stream extracted from the data spiral (before ECC).
+        corrected_bits : List[int]
+            Bit-stream after Reed-Solomon correction and bit-stuff removal.
+        message : str
+            Decoded user message (lazy property, evaluated once).
+
+        Raises
+        ------
+        InvalidParameterError
+            *image_path* does not point to an existing file.
+        BullseyeDetectionError, OrientationError, BitReadError, etc.
+            Any lower-level exception is propagated so the caller can catch
+            precisely the failing phase.
+
+        Examples
+        --------
+        >>> from aztec_tool import AztecDecoder
+        >>> dec = AztecDecoder("ticket.png")
+        >>> dec.message  # same as dec.decode()
+        'EVENT: Concert
+    ROW 12 SEAT 34'
+
+        A one-liner helper is also available:
+
+        >>> from aztec_tool import decode
+        >>> decode("hello.png")
+        'Hello, world!'
+    """
+
     def __init__(
         self,
-        image_path: str | Path,
+        image_path: Union[str, Path],
         *,
-        auto_orient: bool = True,
-        auto_correct: bool = True,
-        mode_auto_correct: bool = True,
+        auto_orient: Optional[bool] = True,
+        auto_correct: Optional[bool] = True,
+        mode_auto_correct: Optional[bool] = True,
     ) -> None:
         self.image_path = Path(image_path)
         if not self.image_path.exists():
@@ -32,42 +95,42 @@ def __init__(
         self._mode_auto_correct = mode_auto_correct
 
     @cached_property
-    def _raw_matrix(self):
+    def _raw_matrix(self) -> np.ndarray:
         return AztecMatrix(str(self.image_path)).matrix
 
     @cached_property
     def _bullseye(self) -> BullseyeDetector:
         return BullseyeDetector(self._raw_matrix)
 
     @cached_property
-    def bullseye_bounds(self):
+    def bullseye_bounds(self) -> Tuple[int, int, int, int]:
         return self._bullseye.bounds
 
     @cached_property
     def aztec_type(self) -> AztecType:
         return self._bullseye.aztec_type
 
     @cached_property
-    def matrix(self):
+    def matrix(self) -> np.ndarray:
         if not self._auto_orient:
             return self._raw_matrix
         return OrientationManager(
             self._raw_matrix, self.bullseye_bounds
         ).rotate_if_needed()
 
     @cached_property
-    def _mode(self):
+    def _mode(self) -> ModeReader:
         bullseye = BullseyeDetector(self.matrix)
         return ModeReader(
             self.matrix, bullseye.bounds, bullseye.aztec_type, self._mode_auto_correct
         )
 
     @cached_property
-    def mode_info(self):
+    def mode_info(self) -> Dict[str, Union[int, List[int]]]:
         return self._mode.mode_fields
 
     @cached_property
-    def _codewords(self):
+    def _codewords(self) -> CodewordReader:
         return CodewordReader(
             self.matrix,
             self.mode_info["layers"],
@@ -77,16 +140,17 @@ def _codewords(self):
         )
 
     @cached_property
-    def bitmap(self):
+    def bitmap(self) -> np.ndarray:
         return self._codewords.bitmap
 
     @cached_property
-    def corrected_bits(self):
+    def corrected_bits(self) -> List[int]:
         return self._codewords.corrected_bits
 
     @cached_property
     def message(self) -> str:
         return self._codewords.decoded_string
 
     def decode(self) -> str:
+        """Return the decoded user message (alias of :pyattr:`message`)."""
         return self.message