qa: Add typing annotations and run mypy in "quality" CI job

Author: dbaty

Makefile

@@ -11,7 +11,8 @@ docs:
 quality:
 	black --check .
 	isort --check-only --diff .
-	pylint --reports=no --score=no setup.py src tests
+	mypy run.py src tests
+	pylint --reports=no --score=no setup.py run.py src tests
 	python setup.py check --strict --metadata --restructuredtext
 	check-manifest
 	python setup.py sdist >/dev/null 2>&1 && twine check dist/*

pyproject.toml

@@ -1,3 +1,14 @@
+[tool.mypy]
+show_error_codes = true
+strict = true
+strict_equality_for_none = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+# Don't force us to type test functions, it's boring and useless.
+disallow_untyped_defs = false
+
 
 [tool.pylint.MASTER]
 load-plugins = []

requirements-dev.txt

@@ -9,6 +9,7 @@ sphinx_rtd_theme
 # Tests and Quality
 black
 check-manifest
+mypy
 pylint
 pytest
 vulture

run.py

@@ -1,13 +1,12 @@
 #!/usr/bin/python
 import argparse
-import sys
 
 from PIL import Image
 
 import zbarlight
 
 
-def main():
+def main() -> None:
     parser = argparse.ArgumentParser()
     parser.add_argument("image", help="input image")
     args = parser.parse_args()

src/zbarlight/__init__.py

@@ -1,15 +1,12 @@
 import importlib.metadata
+import typing
 import warnings
 
 from PIL import Image
 
-from . import compat
+from ._zbarlight import Symbologies
+from ._zbarlight import zbar_code_scanner
 
-# FIXME: pylint is capable of reading .pyi stub files, which we'll
-# create when we set up a type checker. Remove the following pragmas
-# once it's done.
-from ._zbarlight import Symbologies  # pylint: disable=no-name-in-module
-from ._zbarlight import zbar_code_scanner  # pylint: disable=no-name-in-module
 
 __version__ = importlib.metadata.version("zbarlight")
 __ALL__ = [
@@ -29,7 +26,7 @@ class UnknownSymbologieError(Exception):
     pass
 
 
-def scan_codes(code_types, image):
+def scan_codes(code_types: str | list[str], image: Image.Image) -> list[bytes] | None:
     """
     Get *code_type* codes from a PIL Image.
 
@@ -69,9 +66,10 @@ def scan_codes(code_types, image):
             if code_type.upper() not in Symbologies
         ]
         raise UnknownSymbologieError("Unknown Symbologies: %s" % bad_code_types)
+    # mypy cannot narrow the type, despite our membership check above.
+    if not _has_only_integers(symbologies):
+        raise RuntimeError("should not happen")
 
-    if not compat.is_image(image):
-        raise RuntimeError("Bad or unknown image format")
     # Convert image to gray scale (8 bits per pixel).
     converted_image = image.convert("L")
     raw = converted_image.tobytes()
@@ -80,7 +78,9 @@ def scan_codes(code_types, image):
     return zbar_code_scanner(symbologies, raw, width, height)
 
 
-def copy_image_on_background(image, color=WHITE):
+def copy_image_on_background(
+    image: Image.Image, color: tuple[int, int, int] = WHITE
+) -> Image.Image:
     """
     Create a new image by copying the image on a *color* background.
 
@@ -95,3 +95,7 @@ def copy_image_on_background(image, color=WHITE):
     background = Image.new("RGB", image.size, color)
     background.paste(image, mask=image.split()[3])
     return background
+
+
+def _has_only_integers(values: list[int | None]) -> typing.TypeGuard[list[int]]:
+    return None not in values

src/zbarlight/_zbarlight.pyi

@@ -0,0 +1,13 @@
+import typing
+
+SymbologyValue: typing.TypeAlias = int
+SymbologiesType: typing.TypeAlias = dict[str, SymbologyValue]
+
+Symbologies: SymbologiesType
+
+def zbar_code_scanner(
+    symbologies: list[SymbologyValue],
+    raw: bytes,
+    width: int,
+    height: int,
+) -> list[bytes] | None: ...

src/zbarlight/compat.py

@@ -6,7 +6,7 @@
 import zbarlight
 
 
-def get_image(name, ext="png"):
+def get_image(name: str, ext: str = "png") -> Image.Image:
     directory = pathlib.Path(__file__).parent
     file_path = directory / "fixtures" / "{}.{}".format(name, ext)
     with open(str(file_path), "rb") as image_file:
@@ -69,6 +69,7 @@ def compute_parametrize_id(value):
 def test_scan_codes(image_name, symbologies, excepted_codes):
     image = get_image(image_name)
     detected_codes = zbarlight.scan_codes(symbologies, image)
+    assert detected_codes is not None
     assert sorted(detected_codes) == sorted(excepted_codes)