picx-image-optimizer 0.1.0__py3-none-any.whl

picx/__init__.py

@@ -0,0 +1,8 @@
+"""Public Python API for picx."""
+
+from picx.api import optimize_dir, optimize_image
+from picx.help import examples, help
+from picx.models import OptimizeResult
+from picx.tile import tile_image
+
+__all__ = ["OptimizeResult", "examples", "help", "optimize_dir", "optimize_image", "tile_image"]

picx/__main__.py

@@ -0,0 +1,4 @@
+from picx.cli import app
+
+if __name__ == "__main__":
+    app()

picx/api.py

@@ -0,0 +1,177 @@
+from dataclasses import replace
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import List, Optional, Union
+
+from picx.backends.resolver import optimize_with_backend
+from picx.formats import INPUT_FORMATS, normalize_format, output_extension, source_format
+from picx.models import BackendName, OptimizeOptions, OptimizeResult
+from picx.presets import apply_preset
+
+
+def optimize_image(
+    source: Union[str, Path],
+    output: Optional[Union[str, Path]] = None,
+    format: Optional[str] = None,
+    quality: int = 82,
+    max_width: Optional[int] = None,
+    max_height: Optional[int] = None,
+    strip_meta: bool = True,
+    target_size: Optional[int] = None,
+    preset: Optional[str] = None,
+    backend: BackendName = "auto",
+    allow_large: bool = False,
+    max_pixels: Optional[int] = None,
+) -> OptimizeResult:
+    source_path = Path(source)
+    output_path = _resolve_output_path(source_path, output, format)
+
+    if not source_path.exists():
+        return _skipped(source_path, output_path, f"Input does not exist: {source_path}")
+    if not source_path.is_file():
+        return _skipped(source_path, output_path, f"Input is not a file: {source_path}")
+
+    try:
+        input_format = source_format(source_path)
+        requested_format = normalize_format(format)
+        options = OptimizeOptions(
+            output_format=requested_format,
+            quality=_validate_quality(quality),
+            max_width=_validate_dimension(max_width, "max_width"),
+            max_height=_validate_dimension(max_height, "max_height"),
+            strip_meta=strip_meta,
+            target_size=_validate_target_size(target_size),
+            backend=_validate_backend(backend),
+            allow_large=allow_large,
+            max_pixels=_validate_target_size(max_pixels),
+        )
+        preset_options = apply_preset(options, preset)
+        resolved_options = (
+            preset_options
+            if preset_options.output_format is not None
+            else replace(preset_options, output_format=input_format)
+        )
+        resolved_output = _resolve_output_path(source_path, output, resolved_options.output_format)
+        return optimize_with_backend(source_path, resolved_output, resolved_options)
+    except ValueError as exc:
+        return _skipped(source_path, output_path, str(exc))
+
+
+def optimize_dir(
+    source_dir: Union[str, Path],
+    out: Union[str, Path],
+    format: Optional[str] = None,
+    quality: int = 82,
+    max_width: Optional[int] = None,
+    max_height: Optional[int] = None,
+    strip_meta: bool = True,
+    target_size: Optional[int] = None,
+    recursive: bool = True,
+    preset: Optional[str] = None,
+    backend: BackendName = "auto",
+    allow_large: bool = False,
+    max_pixels: Optional[int] = None,
+    jobs: int = 1,
+) -> List[OptimizeResult]:
+    root = Path(source_dir)
+    output_root = Path(out)
+    if not root.exists() or not root.is_dir():
+        return [_skipped(root, output_root, f"Input directory does not exist: {root}")]
+
+    images = _iter_images(root, recursive)
+    _validate_jobs(jobs)
+
+    def optimize_one(image: Path) -> OptimizeResult:
+        return optimize_image(
+            image,
+            output=_dir_output_dir(root, output_root, image),
+            format=format,
+            quality=quality,
+            max_width=max_width,
+            max_height=max_height,
+            strip_meta=strip_meta,
+            target_size=target_size,
+            preset=preset,
+            backend=backend,
+            allow_large=allow_large,
+            max_pixels=max_pixels,
+        )
+
+    if jobs == 1:
+        return [optimize_one(image) for image in images]
+    with ThreadPoolExecutor(max_workers=jobs) as executor:
+        return list(executor.map(optimize_one, images))
+
+
+def _iter_images(root: Path, recursive: bool) -> List[Path]:
+    pattern = "**/*" if recursive else "*"
+    return sorted(
+        path for path in root.glob(pattern) if path.is_file() and path.suffix.lower().lstrip(".") in INPUT_FORMATS
+    )
+
+
+def _dir_output_dir(root: Path, output_root: Path, image: Path) -> Path:
+    relative_parent = image.relative_to(root).parent
+    return output_root / relative_parent
+
+
+def _resolve_output_path(
+    source: Path,
+    output: Optional[Union[str, Path]],
+    format_name: Optional[str],
+) -> Path:
+    output_format = normalize_format(format_name) if format_name else None
+    extension = output_extension(output_format) if output_format else source.suffix
+
+    if output is None:
+        return source.with_name(f"{source.stem}.optimized{extension}")
+
+    output_path = Path(output)
+    if output_path.exists() and output_path.is_dir():
+        return output_path / source.with_suffix(extension).name
+    if output_path.suffix:
+        return output_path
+    return output_path / source.with_suffix(extension).name
+
+
+def _validate_quality(value: int) -> int:
+    if value < 1 or value > 100:
+        raise ValueError("quality must be between 1 and 100")
+    return value
+
+
+def _validate_dimension(value: Optional[int], name: str) -> Optional[int]:
+    if value is not None and value <= 0:
+        raise ValueError(f"{name} must be greater than 0")
+    return value
+
+
+def _validate_target_size(value: Optional[int]) -> Optional[int]:
+    if value is not None and value <= 0:
+        raise ValueError("size values must be greater than 0")
+    return value
+
+
+def _validate_backend(value: BackendName) -> BackendName:
+    if value not in {"auto", "pillow", "pyvips"}:
+        raise ValueError("backend must be one of: auto, pillow, pyvips")
+    return value
+
+
+def _validate_jobs(value: int) -> int:
+    if value < 1:
+        raise ValueError("jobs must be greater than 0")
+    return value
+
+
+def _skipped(source: Path, output: Path, error: str) -> OptimizeResult:
+    original_size = source.stat().st_size if source.exists() and source.is_file() else 0
+    return OptimizeResult(
+        source_path=source,
+        output_path=output,
+        original_size=original_size,
+        output_size=0,
+        savings_ratio=0.0,
+        skipped=True,
+        error=error,
+    )

picx/backends/__init__.py

@@ -0,0 +1,6 @@
+"""Image processing backends."""
+
+from picx.backends.base import ImageBackend
+from picx.backends.pillow import PillowBackend
+
+__all__ = ["ImageBackend", "PillowBackend"]

picx/backends/base.py

@@ -0,0 +1,11 @@
+from pathlib import Path
+from typing import Protocol
+
+from picx.models import OptimizeOptions, OptimizeResult
+
+
+class ImageBackend(Protocol):
+    """Backend contract reserved for future engines such as pyvips."""
+
+    def optimize(self, source: Path, output: Path, options: OptimizeOptions) -> OptimizeResult:
+        """Optimize a single image."""

picx/backends/pillow.py

@@ -0,0 +1,177 @@
+from io import BytesIO
+from pathlib import Path
+from typing import Dict, Iterator, Optional
+
+from PIL import Image, ImageOps, UnidentifiedImageError
+from contextlib import contextmanager
+
+from picx.errors import large_image_guidance, webp_dimension_guidance
+from picx.formats import PIL_FORMATS
+from picx.models import OptimizeOptions, OptimizeResult
+
+MIN_QUALITY = 1
+DEFAULT_MAX_PIXELS = Image.MAX_IMAGE_PIXELS
+
+
+class PillowBackend:
+    """Default image optimization backend using Pillow."""
+
+    def optimize(self, source: Path, output: Path, options: OptimizeOptions) -> OptimizeResult:
+        original_size = source.stat().st_size
+        try:
+            with _pixel_limit(options):
+                with Image.open(source) as image:
+                    large_result = self._large_image_result(source, output, image, options)
+                    if large_result is not None:
+                        return large_result
+                    prepared = self._prepare_image(image, options)
+                    output.parent.mkdir(parents=True, exist_ok=True)
+                    output_format = options.output_format or source.suffix.lower().lstrip(".")
+                    data = self._encode(prepared, output_format, options)
+                    output.write_bytes(data)
+                    output_size = output.stat().st_size
+                    return OptimizeResult(
+                        source_path=source,
+                        output_path=output,
+                        original_size=original_size,
+                        output_size=output_size,
+                        savings_ratio=self._savings_ratio(original_size, output_size),
+                        backend="pillow",
+                        format=output_format,
+                        width=prepared.width,
+                        height=prepared.height,
+                    )
+        except Image.DecompressionBombError as exc:
+            return OptimizeResult(
+                source_path=source,
+                output_path=output,
+                original_size=original_size,
+                output_size=0,
+                savings_ratio=0.0,
+                skipped=True,
+                error=f"{exc} {large_image_guidance(0, options.max_pixels or DEFAULT_MAX_PIXELS)}",
+                backend="pillow",
+            )
+        except (OSError, ValueError, UnidentifiedImageError) as exc:
+            return OptimizeResult(
+                source_path=source,
+                output_path=output,
+                original_size=original_size,
+                output_size=0,
+                savings_ratio=0.0,
+                skipped=True,
+                error=str(exc),
+                backend="pillow",
+            )
+
+    def _large_image_result(
+        self,
+        source: Path,
+        output: Path,
+        image: Image.Image,
+        options: OptimizeOptions,
+    ) -> Optional[OptimizeResult]:
+        if options.allow_large:
+            return None
+        max_pixels = options.max_pixels if options.max_pixels is not None else DEFAULT_MAX_PIXELS
+        pixels = image.width * image.height
+        if max_pixels is not None and pixels > max_pixels:
+            return OptimizeResult(
+                source_path=source,
+                output_path=output,
+                original_size=source.stat().st_size,
+                output_size=0,
+                savings_ratio=0.0,
+                skipped=True,
+                error=large_image_guidance(pixels, max_pixels),
+                backend="pillow",
+            )
+        return None
+
+    def _prepare_image(self, image: Image.Image, options: OptimizeOptions) -> Image.Image:
+        transposed = ImageOps.exif_transpose(image)
+        resized = self._resize(transposed, options)
+        return self._strip_metadata(resized) if options.strip_meta else resized.copy()
+
+    def _resize(self, image: Image.Image, options: OptimizeOptions) -> Image.Image:
+        if options.max_width is None and options.max_height is None:
+            return image.copy()
+        max_width = options.max_width or image.width
+        max_height = options.max_height or image.height
+        return ImageOps.contain(image, (max_width, max_height))
+
+    def _strip_metadata(self, image: Image.Image) -> Image.Image:
+        copied = image.copy()
+        copied.info.clear()
+        return copied
+
+    def _encode(self, image: Image.Image, output_format: str, options: OptimizeOptions) -> bytes:
+        if options.target_size is None:
+            return self._save(image, output_format, options.quality)
+        return self._encode_target_size(image, output_format, options)
+
+    def _encode_target_size(
+        self,
+        image: Image.Image,
+        output_format: str,
+        options: OptimizeOptions,
+    ) -> bytes:
+        low = MIN_QUALITY
+        high = max(MIN_QUALITY, min(100, options.quality))
+        best: Optional[bytes] = None
+        smallest = self._save(image, output_format, MIN_QUALITY)
+
+        while low <= high:
+            quality = (low + high) // 2
+            data = self._save(image, output_format, quality)
+            if len(data) <= options.target_size:
+                best = data
+                low = quality + 1
+            else:
+                high = quality - 1
+
+        return best if best is not None else smallest
+
+    def _save(self, image: Image.Image, output_format: str, quality: int) -> bytes:
+        if output_format == "webp" and (image.width > 16383 or image.height > 16383):
+            raise ValueError(webp_dimension_guidance(image.width, image.height))
+        buffer = BytesIO()
+        pil_format = PIL_FORMATS[output_format]
+        prepared = self._convert_for_format(image, output_format)
+        save_options = self._save_options(output_format, quality)
+        prepared.save(buffer, format=pil_format, **save_options)
+        return buffer.getvalue()
+
+    def _convert_for_format(self, image: Image.Image, output_format: str) -> Image.Image:
+        if output_format in {"jpg", "jpeg"} and image.mode not in {"RGB", "L"}:
+            return image.convert("RGB")
+        return image
+
+    def _save_options(self, output_format: str, quality: int) -> Dict[str, object]:
+        normalized_quality = max(MIN_QUALITY, min(100, quality))
+        if output_format in {"jpg", "jpeg"}:
+            return {"quality": normalized_quality, "optimize": True, "progressive": True}
+        if output_format == "png":
+            return {"optimize": True}
+        if output_format == "webp":
+            return {"quality": normalized_quality, "method": 6}
+        if output_format == "avif":
+            return {"quality": normalized_quality}
+        if output_format in {"tif", "tiff"}:
+            return {"compression": "tiff_lzw"}
+        return {}
+
+    def _savings_ratio(self, original_size: int, output_size: int) -> float:
+        if original_size <= 0:
+            return 0.0
+        return max(0.0, (original_size - output_size) / original_size)
+
+
+@contextmanager
+def _pixel_limit(options: OptimizeOptions) -> Iterator[None]:
+    previous = Image.MAX_IMAGE_PIXELS
+    Image.MAX_IMAGE_PIXELS = None
+    try:
+        yield
+    finally:
+        Image.MAX_IMAGE_PIXELS = previous

picx/backends/pyvips.py

@@ -0,0 +1,110 @@
+from pathlib import Path
+from typing import Dict, Optional
+
+from picx.formats import output_extension, source_format
+from picx.errors import webp_dimension_guidance
+from picx.models import OptimizeOptions, OptimizeResult
+
+MIN_QUALITY = 1
+
+
+class PyvipsBackend:
+    """Optional backend for large images using pyvips/libvips."""
+
+    def __init__(self) -> None:
+        import pyvips  # type: ignore[import-not-found]
+
+        self._pyvips = pyvips
+
+    def optimize(self, source: Path, output: Path, options: OptimizeOptions) -> OptimizeResult:
+        original_size = source.stat().st_size
+        try:
+            image = self._load(source)
+            resized = self._resize(image, options)
+            output_format = options.output_format or source_format(source)
+            output.parent.mkdir(parents=True, exist_ok=True)
+            data = self._encode(resized, output_format, options)
+            output.write_bytes(data)
+            output_size = output.stat().st_size
+            return OptimizeResult(
+                source_path=source,
+                output_path=output,
+                original_size=original_size,
+                output_size=output_size,
+                savings_ratio=self._savings_ratio(original_size, output_size),
+                backend="pyvips",
+                format=output_format,
+                width=resized.width,
+                height=resized.height,
+            )
+        except Exception as exc:
+            return OptimizeResult(
+                source_path=source,
+                output_path=output,
+                original_size=original_size,
+                output_size=0,
+                savings_ratio=0.0,
+                skipped=True,
+                error=str(exc),
+                backend="pyvips",
+            )
+
+    def _load(self, source: Path):
+        return self._pyvips.Image.new_from_file(str(source), access="sequential")
+
+    def _resize(self, image, options: OptimizeOptions):
+        if options.max_width is None and options.max_height is None:
+            return image
+        max_width = options.max_width or image.width
+        max_height = options.max_height or image.height
+        scale = min(max_width / image.width, max_height / image.height, 1.0)
+        if scale >= 1.0:
+            return image
+        return image.resize(scale)
+
+    def _encode(self, image, output_format: str, options: OptimizeOptions) -> bytes:
+        if options.target_size is None:
+            return self._write(image, output_format, options.quality, options.strip_meta)
+        return self._encode_target_size(image, output_format, options)
+
+    def _encode_target_size(self, image, output_format: str, options: OptimizeOptions) -> bytes:
+        low = MIN_QUALITY
+        high = max(MIN_QUALITY, min(100, options.quality))
+        best: Optional[bytes] = None
+        smallest = self._write(image, output_format, MIN_QUALITY, options.strip_meta)
+
+        while low <= high:
+            quality = (low + high) // 2
+            data = self._write(image, output_format, quality, options.strip_meta)
+            if len(data) <= options.target_size:
+                best = data
+                low = quality + 1
+            else:
+                high = quality - 1
+
+        return best if best is not None else smallest
+
+    def _write(self, image, output_format: str, quality: int, strip_meta: bool) -> bytes:
+        if output_format == "webp" and (image.width > 16383 or image.height > 16383):
+            raise ValueError(webp_dimension_guidance(image.width, image.height))
+        extension = output_extension(output_format)
+        options = self._write_options(output_format, quality, strip_meta)
+        if output_format in {"jpg", "jpeg"} and image.hasalpha():
+            image = image.flatten(background=[255, 255, 255])
+        return image.write_to_buffer(extension, **options)
+
+    def _write_options(self, output_format: str, quality: int, strip_meta: bool) -> Dict[str, object]:
+        normalized_quality = max(MIN_QUALITY, min(100, quality))
+        strip_options: Dict[str, object] = {"strip": True} if strip_meta else {}
+        if output_format in {"jpg", "jpeg", "webp", "avif"}:
+            return {"Q": normalized_quality, **strip_options}
+        if output_format == "png":
+            return {"compression": 9, **strip_options}
+        if output_format in {"tif", "tiff"}:
+            return {"compression": "lzw", **strip_options}
+        return strip_options
+
+    def _savings_ratio(self, original_size: int, output_size: int) -> float:
+        if original_size <= 0:
+            return 0.0
+        return max(0.0, (original_size - output_size) / original_size)

picx/backends/resolver.py

@@ -0,0 +1,73 @@
+from pathlib import Path
+from typing import Optional
+
+from picx.backends.base import ImageBackend
+from picx.backends.pillow import PillowBackend
+from picx.errors import pyvips_missing_guidance
+from picx.models import OptimizeOptions, OptimizeResult
+
+
+def optimize_with_backend(source: Path, output: Path, options: OptimizeOptions) -> OptimizeResult:
+    if options.backend == "pillow":
+        return PillowBackend().optimize(source, output, options)
+    if options.backend == "pyvips":
+        return _pyvips_or_error().optimize(source, output, options)
+
+    pillow_result = PillowBackend().optimize(source, output, options)
+    if not _should_retry_with_pyvips(pillow_result):
+        return pillow_result
+
+    pyvips_backend = _optional_pyvips()
+    if pyvips_backend is None:
+        error = f"{pillow_result.error} {pyvips_missing_guidance()}"
+        return OptimizeResult(
+            source_path=source,
+            output_path=output,
+            original_size=pillow_result.original_size,
+            output_size=0,
+            savings_ratio=0.0,
+            skipped=True,
+            error=error,
+            backend="auto",
+        )
+    return pyvips_backend.optimize(source, output, options)
+
+
+def _should_retry_with_pyvips(result: OptimizeResult) -> bool:
+    return bool(result.error and "exceeding the configured limit" in result.error)
+
+
+def _optional_pyvips() -> Optional[ImageBackend]:
+    try:
+        from picx.backends.pyvips import PyvipsBackend
+
+        return PyvipsBackend()
+    except Exception:
+        return None
+
+
+def _pyvips_or_error() -> ImageBackend:
+    try:
+        from picx.backends.pyvips import PyvipsBackend
+
+        return PyvipsBackend()
+    except Exception as exc:
+        return MissingPyvipsBackend(str(exc))
+
+
+class MissingPyvipsBackend:
+    def __init__(self, detail: str) -> None:
+        self._detail = detail
+
+    def optimize(self, source: Path, output: Path, options: OptimizeOptions) -> OptimizeResult:
+        original_size = source.stat().st_size if source.exists() and source.is_file() else 0
+        return OptimizeResult(
+            source_path=source,
+            output_path=output,
+            original_size=original_size,
+            output_size=0,
+            savings_ratio=0.0,
+            skipped=True,
+            error=pyvips_missing_guidance(self._detail),
+            backend="pyvips",
+        )