Rename zimscraperlib.image.convertion to zimscraperlib.image.conversion to fix typo and fix type hints

Author: benoit74

Diff for: CHANGELOG.md

@@ -15,6 +15,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Automatically index PDF documents content #167
 - Automatically set proper title on PDF documents #168
 
+## Changed
+- **BREAKING** Renamed `zimscraperlib.image.convertion` to `zimscraperlib.image.conversion` to fix typo
+- **BREAKING** Many changes in type hints to match the real underlying code
+- **BREAKING** Force all boolean arguments to be keyword-only in function calls for clarity / disambiguation (see ruff rule FBT002)
+- Prefer to use `IO[bytes]` to `io.BytesIO` when possible since it is more generic
+
 ### Fixed
 
 - Metadata length validation is buggy for unicode strings #158

Diff for: src/zimscraperlib/image/__init__.py

@@ -3,7 +3,7 @@
 # vim: ai ts=4 sts=4 et sw=4 nu
 
 # flake8: noqa
-from .convertion import convert_image
+from .conversion import convert_image
 from .optimization import optimize_image
 from .probing import is_valid_image
 from .transformation import resize_image

Diff for: src/zimscraperlib/image/convertion.py renamed to src/zimscraperlib/image/conversion.py

@@ -3,10 +3,10 @@
 
 from __future__ import annotations
 
-import io
 import pathlib
+from typing import IO
 
-import PIL
+from PIL.Image import open as pilopen
 
 from zimscraperlib.constants import ALPHA_NOT_SUPPORTED
 from zimscraperlib.image.probing import format_for
@@ -15,8 +15,8 @@
 
 
 def convert_image(
-    src: pathlib.Path | io.BytesIO,
-    dst: pathlib.Path | io.BytesIO,
+    src: pathlib.Path | IO[bytes],
+    dst: pathlib.Path | IO[bytes],
     **params: str,
 ) -> None:
     """convert an image file from one format to another
@@ -29,12 +29,10 @@ def convert_image(
      to RGB. ex: RGB, ARGB, CMYK (and other PIL colorspaces)"""
 
     colorspace = params.get("colorspace")  # requested colorspace
-    fmt = (
-        params.pop("fmt").upper() if "fmt" in params else None  # pyright: ignore
-    )  # requested format
+    fmt = params.pop("fmt").upper() if "fmt" in params else None  # requested format
     if not fmt:
         fmt = format_for(dst)
-    with PIL.Image.open(src) as image:  # pyright: ignore
+    with pilopen(src) as image:
         if image.mode == "RGBA" and fmt in ALPHA_NOT_SUPPORTED or colorspace:
             image = image.convert(colorspace or "RGB")  # noqa: PLW2901
         save_image(image, dst, fmt, **params)
@@ -45,13 +43,13 @@ def create_favicon(src: pathlib.Path, dst: pathlib.Path) -> None:
     if dst.suffix != ".ico":
         raise ValueError("favicon extension must be ICO")
 
-    img = PIL.Image.open(src)  # pyright: ignore
+    img = pilopen(src)
     w, h = img.size
     # resize image to square first
     if w != h:
         size = min([w, h])
         resized = dst.parent.joinpath(f"{src.stem}.tmp.{src.suffix}")
         resize_image(src, size, size, resized, "contain")
-        img = PIL.Image.open(resized)  # pyright: ignore
+        img = pilopen(resized)
     # now convert to ICO
     save_image(img, dst, "ICO")

Diff for: src/zimscraperlib/image/optimization.py

@@ -35,7 +35,7 @@
 from optimize_images.img_dynamic_quality import jpeg_dynamic_quality
 from PIL import Image
 
-from zimscraperlib.image.convertion import convert_image
+from zimscraperlib.image.conversion import convert_image
 from zimscraperlib.image.probing import format_for
 from zimscraperlib.image.utils import save_image
 

Diff for: src/zimscraperlib/image/utils.py

@@ -2,19 +2,20 @@
 # vim: ai ts=4 sts=4 et sw=4 nu
 from __future__ import annotations
 
-import io
 import pathlib
+from typing import IO
 
-from PIL import Image
+from PIL.Image import Image
+from PIL.ImageFile import ImageFile
 
 
 def save_image(
-    src: Image,  # pyright: ignore
-    dst: pathlib.Path | io.BytesIO,
-    fmt: str | None = None,
+    src: Image | ImageFile,
+    dst: pathlib.Path | IO[bytes],
+    fmt: str,
     **params: str,
 ) -> None:
     """PIL.Image.save() wrapper setting default parameters"""
-    args = {"JPEG": {"quality": 100}, "PNG": {}}.get(fmt, {})  # pyright: ignore
+    args = {"JPEG": {"quality": 100}, "PNG": {}}.get(fmt, {})
     args.update(params or {})
-    src.save(dst, fmt, **args)  # pyright: ignore
+    src.save(dst, fmt, **args)

Diff for: tests/image/test_image.py

@@ -15,7 +15,7 @@
 from resizeimage.imageexceptions import ImageSizeError
 
 from zimscraperlib.image import presets
-from zimscraperlib.image.convertion import convert_image, create_favicon
+from zimscraperlib.image.conversion import convert_image, create_favicon
 from zimscraperlib.image.optimization import (
     ensure_matches,
     optimize_gif,