From 1893e14d1021c56047b597ad333f46d855fa51be Mon Sep 17 00:00:00 2001
From: benoit74 <benoit74@users.noreply.github.com>
Date: Tue, 2 Dec 2025 13:39:03 +0000
Subject: [PATCH] Add proper typing @overload to  methods

---
 CHANGELOG.md                            |  4 +++
 src/zimscraperlib/image/optimization.py | 37 +++++++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 87cab73..d5fac8f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Add proper typing @overload to `zimscraperlib.image.optimize_xxx` methods (#273)
+
 ## [5.3.0] - 2025-11-14
 
 ### Changed
diff --git a/src/zimscraperlib/image/optimization.py b/src/zimscraperlib/image/optimization.py
index f37d21c..6a57936 100644
--- a/src/zimscraperlib/image/optimization.py
+++ b/src/zimscraperlib/image/optimization.py
@@ -23,6 +23,7 @@
 import pathlib
 import subprocess
 from dataclasses import dataclass
+from typing import overload
 
 import piexif  # pyright: ignore[reportMissingTypeStubs]
 from optimize_images.img_aux_processing import (  # pyright: ignore[reportMissingTypeStubs]
@@ -78,6 +79,18 @@ class OptimizePngOptions:
     remove_transparency: bool | None = False
 
 
+@overload
+def optimize_png(
+    src: pathlib.Path | io.BytesIO,
+    dst: io.BytesIO | None = None,
+    options: OptimizePngOptions | None = None,
+) -> io.BytesIO: ...
+@overload
+def optimize_png(
+    src: pathlib.Path | io.BytesIO,
+    dst: pathlib.Path,
+    options: OptimizePngOptions | None = None,
+) -> pathlib.Path: ...
 def optimize_png(
     src: pathlib.Path | io.BytesIO,
     dst: pathlib.Path | io.BytesIO | None = None,
@@ -128,6 +141,18 @@ class OptimizeJpgOptions:
     keep_exif: bool | None = True
 
 
+@overload
+def optimize_jpeg(
+    src: pathlib.Path | io.BytesIO,
+    dst: io.BytesIO | None = None,
+    options: OptimizeJpgOptions | None = None,
+) -> io.BytesIO: ...
+@overload
+def optimize_jpeg(
+    src: pathlib.Path | io.BytesIO,
+    dst: pathlib.Path,
+    options: OptimizeJpgOptions | None = None,
+) -> pathlib.Path: ...
 def optimize_jpeg(
     src: pathlib.Path | io.BytesIO,
     dst: pathlib.Path | io.BytesIO | None = None,
@@ -218,6 +243,18 @@ class OptimizeWebpOptions:
     lossless: bool | None = False
 
 
+@overload
+def optimize_webp(
+    src: pathlib.Path | io.BytesIO,
+    dst: io.BytesIO | None = None,
+    options: OptimizeWebpOptions | None = None,
+) -> io.BytesIO: ...
+@overload
+def optimize_webp(
+    src: pathlib.Path | io.BytesIO,
+    dst: pathlib.Path,
+    options: OptimizeWebpOptions | None = None,
+) -> pathlib.Path: ...
 def optimize_webp(
     src: pathlib.Path | io.BytesIO,
     dst: pathlib.Path | io.BytesIO | None = None,