pixopt 1.0.5__py3-none-any.whl

pixopt/__init__.py

@@ -0,0 +1,19 @@
+"""pixopt - Fast Python image optimizer. Resize, compress, convert,
+and generate responsive assets."""
+
+from pixopt.models import OptimizationResult
+from pixopt.optimizer import (
+    change_extension,
+    convert_to_favicon,
+    optimize_directory,
+    optimize_image,
+)
+
+__version__ = "1.0.5"
+__all__ = [
+    "OptimizationResult",
+    "change_extension",
+    "convert_to_favicon",
+    "optimize_directory",
+    "optimize_image",
+]

pixopt/adaptive_quality.py

@@ -0,0 +1,103 @@
+"""Adaptive quality finder using binary search to hit a target file size."""
+
+from __future__ import annotations
+
+from io import BytesIO
+
+from PIL import Image
+
+from pixopt.image_ops import build_save_kwargs, convert_mode, resize_image
+
+
+def find_quality_for_target_size(
+    img: Image.Image,
+    pillow_fmt: str,
+    target_size: int,
+    *,
+    max_width: int | None = None,
+    max_height: int | None = None,
+    keep_aspect_ratio: bool = True,
+    strip_metadata: bool = True,
+    progressive: bool = True,
+    optimize: bool = True,
+    lossless: bool = False,
+    min_quality: int = 1,
+    max_quality: int = 100,
+    tolerance: float = 0.05,
+    max_iterations: int = 8,
+) -> int:
+    """Find the JPEG/WEBP quality that produces a file closest to target_size.
+
+    Uses binary search over quality (1-100) and measures the actual encoded
+    file size in memory. Returns the quality value that yields a size
+    closest to but not exceeding the target.
+
+    Args:
+        img: Open PIL Image.
+        pillow_fmt: Target Pillow format (JPEG or WEBP).
+        target_size: Target file size in bytes.
+        max_width: Maximum width in pixels, or None.
+        max_height: Maximum height in pixels, or None.
+        keep_aspect_ratio: Whether to keep the original aspect ratio.
+        strip_metadata: Whether to strip metadata before saving.
+        progressive: Whether to use progressive encoding.
+        optimize: Whether to optimize the output.
+        lossless: Whether to use lossless compression.
+        min_quality: Lowest quality to try.
+        max_quality: Highest quality to try.
+        tolerance: Fractional tolerance around target_size (e.g. 0.05 = 5%).
+        max_iterations: Maximum binary-search iterations.
+
+    Returns:
+        Quality integer (1-100).
+    """
+    if pillow_fmt not in ("JPEG", "WEBP"):
+        return 85
+
+    working = img.copy()
+    working = convert_mode(working, pillow_fmt)
+    working = resize_image(
+        working,
+        max_width=max_width,
+        max_height=max_height,
+        keep_aspect_ratio=keep_aspect_ratio,
+    )
+
+    low = min_quality
+    high = max_quality
+    best_quality = low
+    best_diff = float("inf")
+
+    for _ in range(max_iterations):
+        if low > high:
+            break
+        mid = (low + high) // 2
+
+        buf = BytesIO()
+        kwargs = build_save_kwargs(
+            pillow_fmt,
+            quality=mid,
+            progressive=progressive,
+            optimize=optimize,
+            strip_metadata=strip_metadata,
+            lossless=lossless,
+        )
+        working.save(buf, format=pillow_fmt, **kwargs)
+        size = buf.tell()
+
+        diff = abs(size - target_size)
+        if diff < best_diff:
+            best_diff = diff
+            best_quality = mid
+
+        # Within tolerance window?
+        if abs(size - target_size) <= target_size * tolerance:
+            best_quality = mid
+            break
+
+        if size > target_size:
+            high = mid - 1
+        else:
+            low = mid + 1
+
+    return best_quality

pixopt/cli/__init__.py

@@ -0,0 +1,17 @@
+"""CLI package entry-point."""
+
+from __future__ import annotations
+
+from pixopt.cli.app import app
+from pixopt.cli.commands import (
+    batch,  # noqa: F401
+    compare,  # noqa: F401
+    convert,  # noqa: F401
+    favicon,  # noqa: F401
+    info,  # noqa: F401
+    optimize,  # noqa: F401
+    placeholder,  # noqa: F401
+    srcset,  # noqa: F401
+)
+
+__all__ = ["app"]

pixopt/cli/app.py

@@ -0,0 +1,14 @@
+"""Typer application and Rich console instances."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(
+    name="pixopt",
+    help="Optimize images for web and storage.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+console = Console()

pixopt/cli/commands/__init__.py

@@ -0,0 +1,14 @@
+"""Import all CLI commands so they register with Typer."""
+
+from __future__ import annotations
+
+from pixopt.cli.commands.batch import batch
+from pixopt.cli.commands.compare import compare
+from pixopt.cli.commands.convert import convert
+from pixopt.cli.commands.favicon import favicon
+from pixopt.cli.commands.info import info
+from pixopt.cli.commands.optimize import optimize
+from pixopt.cli.commands.placeholder import placeholder
+from pixopt.cli.commands.srcset import srcset
+
+__all__ = ["optimize", "batch", "convert", "favicon", "info", "compare", "srcset", "placeholder"]

pixopt/cli/commands/batch.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.progress import BarColumn, Progress, SpinnerColumn, TaskProgressColumn, TextColumn
+
+from pixopt.cli.app import app, console
+from pixopt.cli.options import (
+    BackupOption,
+    FormatChoices,
+    HeightOption,
+    LosslessOption,
+    MinSizeOption,
+    OptimizeOption,
+    ProgressiveOption,
+    QualityOption,
+    StripOption,
+    WidthOption,
+)
+from pixopt.cli.output import _print_summary
+from pixopt.models import OutputFormat
+from pixopt.optimizer import optimize_image
+
+
+@app.command()
+def batch(
+    sources: Annotated[
+        list[Path],
+        typer.Argument(
+            help="Source image files.",
+            exists=True,
+            resolve_path=True,
+        ),
+    ],
+    output_dir: Annotated[
+        Path,
+        typer.Option(
+            "--output-dir",
+            "-o",
+            help="Output directory for all processed images.",
+        ),
+    ] = Path("./optimized"),
+    width: WidthOption = None,
+    height: HeightOption = None,
+    quality: QualityOption = 85,
+    fmt: FormatChoices = OutputFormat.AUTO,
+    strip: StripOption = True,
+    progressive: ProgressiveOption = True,
+    optimize_flag: OptimizeOption = True,
+    lossless: LosslessOption = False,
+    backup: BackupOption = None,
+    min_size: MinSizeOption = None,
+) -> None:
+    """Optimize multiple image files at once."""
+    output_dir = output_dir.resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    min_bytes = min_size * 1024 if min_size is not None else None
+
+    results: list[object] = []
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TaskProgressColumn(),
+        console=console,
+    ) as progress:
+        task = progress.add_task("Optimizing images...", total=len(sources))
+        for src in sources:
+            out = output_dir / src.name
+            result = optimize_image(
+                src,
+                out,
+                max_width=width,
+                max_height=height,
+                quality=quality,
+                strip_metadata=strip,
+                output_format=fmt,
+                progressive=progressive,
+                optimize=optimize_flag,
+                lossless=lossless,
+                backup_dir=backup,
+                min_size_bytes=min_bytes,
+            )
+            results.append(result)
+            progress.advance(task)
+
+    _print_summary(results)  # type: ignore[arg-type]

pixopt/cli/commands/compare.py

@@ -0,0 +1,94 @@
+"""compare command — generate an interactive HTML before/after slider."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from pixopt.cli.app import app, console
+from pixopt.cli.options import (
+    FormatChoices,
+    HeightOption,
+    LosslessOption,
+    OptimizeOption,
+    ProgressiveOption,
+    QualityOption,
+    StripOption,
+    WidthOption,
+)
+from pixopt.html_comparison import generate_comparison_html
+from pixopt.models import OutputFormat
+from pixopt.optimizer import optimize_image
+
+
+@app.command()
+def compare(
+    source: Annotated[
+        Path,
+        typer.Argument(
+            help="Source image file.",
+            exists=True,
+            resolve_path=True,
+        ),
+    ],
+    output_html: Annotated[
+        Path,
+        typer.Argument(
+            help="Output HTML comparison file.",
+            exists=False,
+        ),
+    ] = Path("comparison.html"),
+    width: WidthOption = None,
+    height: HeightOption = None,
+    quality: QualityOption = 85,
+    fmt: FormatChoices = OutputFormat.AUTO,
+    strip: StripOption = True,
+    progressive: ProgressiveOption = True,
+    optimize_flag: OptimizeOption = True,
+    lossless: LosslessOption = False,
+    open_browser: Annotated[
+        bool,
+        typer.Option(
+            "--open/--no-open",
+            help="Open the generated HTML in the default browser.",
+        ),
+    ] = False,
+) -> None:
+    """Optimize an image and generate an interactive before/after comparison HTML."""
+    import tempfile
+    import webbrowser
+
+    output_html = output_html.resolve()
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_path = Path(tmp)
+        optimized = tmp_path / f"opt{source.suffix}"
+        result = optimize_image(
+            source,
+            optimized,
+            max_width=width,
+            max_height=height,
+            quality=quality,
+            strip_metadata=strip,
+            output_format=fmt,
+            progressive=progressive,
+            optimize=optimize_flag,
+            lossless=lossless,
+        )
+
+        if not result.success:
+            console.print(f"[bold red]Optimization failed:[/bold red] {result.error}")
+            raise typer.Exit(1)
+
+        generate_comparison_html(
+            before_path=source,
+            after_path=optimized,
+            output_html=output_html,
+            title=f"Comparison — {source.name}",
+        )
+
+    console.print(f"[bold green]Comparison saved to[/bold green] {output_html}")
+    if open_browser:
+        webbrowser.open(f"file://{output_html}")

pixopt/cli/commands/convert.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from pixopt.cli.app import app, console
+from pixopt.cli.options import (
+    BackupOption,
+    FormatChoices,
+    HeightOption,
+    LosslessOption,
+    MinSizeOption,
+    OptimizeOption,
+    OverwriteOption,
+    ProgressiveOption,
+    QualityOption,
+    RecursiveOption,
+    StripOption,
+    WidthOption,
+)
+from pixopt.cli.output import _print_result, _print_summary
+from pixopt.models import OutputFormat
+from pixopt.optimizer import change_extension, optimize_directory
+from pixopt.smart_format import detect_optimal_format
+
+
+@app.command()
+def convert(
+    source: Annotated[
+        Path,
+        typer.Argument(
+            help="Source image file or directory.",
+            exists=True,
+            resolve_path=True,
+        ),
+    ],
+    output: Annotated[
+        Path | None,
+        typer.Argument(
+            help="Output path (file or directory).",
+            exists=False,
+        ),
+    ] = None,
+    width: WidthOption = None,
+    height: HeightOption = None,
+    quality: QualityOption = 85,
+    fmt: FormatChoices = OutputFormat.AUTO,
+    strip: StripOption = True,
+    progressive: ProgressiveOption = True,
+    optimize_flag: OptimizeOption = True,
+    recursive: RecursiveOption = False,
+    overwrite: OverwriteOption = False,
+    lossless: LosslessOption = False,
+    backup: BackupOption = None,
+    min_size: MinSizeOption = None,
+    smart_format: Annotated[
+        bool,
+        typer.Option(
+            "--smart-format",
+            help="Auto-detect the most efficient output format.",
+        ),
+    ] = False,
+) -> None:
+    """Convert image(s) to a different format or extension."""
+    resolved_fmt = fmt
+    if smart_format and not source.is_dir():
+        detected = detect_optimal_format(source)
+        resolved_fmt = detected
+        console.print(f"[dim]Smart format detected: {detected.value}[/dim]")
+
+    min_bytes = min_size * 1024 if min_size is not None else None
+
+    if source.is_dir():
+        if output is not None:
+            output = output.resolve()
+        results = optimize_directory(
+            source,
+            output,
+            recursive=recursive,
+            max_width=width,
+            max_height=height,
+            quality=quality,
+            strip_metadata=strip,
+            output_format=resolved_fmt,
+            progressive=progressive,
+            optimize=optimize_flag,
+            lossless=lossless,
+            backup_dir=backup,
+            min_size_bytes=min_bytes,
+        )
+        _print_summary(results)
+    else:
+        result = change_extension(
+            source,
+            output,
+            max_width=width,
+            max_height=height,
+            quality=quality,
+            strip_metadata=strip,
+            output_format=resolved_fmt,
+            progressive=progressive,
+            optimize=optimize_flag,
+            overwrite=overwrite,
+            lossless=lossless,
+            backup_dir=backup,
+            min_size_bytes=min_bytes,
+        )
+        _print_result(result)

pixopt/cli/commands/favicon.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from pixopt.cli.app import app
+from pixopt.cli.output import _print_result
+from pixopt.optimizer import convert_to_favicon
+
+
+@app.command()
+def favicon(
+    source: Annotated[
+        Path,
+        typer.Argument(
+            help="Source image file.",
+            exists=True,
+            resolve_path=True,
+        ),
+    ],
+    output: Annotated[
+        Path | None,
+        typer.Argument(
+            help="Output .ico path. Defaults to source name with .ico.",
+            exists=False,
+        ),
+    ] = None,
+    sizes: Annotated[
+        list[int] | None,
+        typer.Option(
+            "--size",
+            help="Square sizes to include in the ICO.",
+        ),
+    ] = None,
+    keep_transparency: Annotated[
+        bool,
+        typer.Option(
+            "--keep-transparency/--fill-background",
+            help="Preserve alpha channel or fill with background color.",
+        ),
+    ] = True,
+) -> None:
+    """Convert an image to a multi-resolution favicon (.ico)."""
+    result = convert_to_favicon(
+        source,
+        output,
+        sizes=sizes if sizes is not None else [16, 32, 48, 64, 128, 256],
+        keep_transparency=keep_transparency,
+    )
+    _print_result(result)

pixopt/cli/commands/info.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from PIL import Image
+from PIL.ExifTags import Base
+
+from pixopt.cli.app import app, console
+from pixopt.cli.output import _human_size
+
+
+@app.command()
+def info(
+    source: Annotated[
+        Path,
+        typer.Argument(
+            help="Image file to inspect.",
+            exists=True,
+            resolve_path=True,
+        ),
+    ],
+) -> None:
+    """Show image metadata and properties without optimizing."""
+    with Image.open(source) as img:
+        console.print(f"[bold cyan]File:[/bold cyan]       {source}")
+        console.print(f"[bold cyan]Size:[/bold cyan]       {img.size[0]}x{img.size[1]} px")
+        console.print(f"[bold cyan]Mode:[/bold cyan]       {img.mode}")
+        console.print(f"[bold cyan]Format:[/bold cyan]     {img.format}")
+        console.print(f"[bold cyan]File size:[/bold cyan]  {_human_size(source.stat().st_size)}")
+
+        if img.format == "JPEG":
+            prog = "Yes" if img.info.get("progressive") else "No"
+            console.print(f"[bold cyan]Progressive:[/bold cyan] {prog}")
+
+        exif = img.getexif()
+        if exif:
+            console.print("\n[bold yellow]EXIF Metadata:[/bold yellow]")
+            for tag_id, value in exif.items():
+                tag = Base(tag_id).name if tag_id in {t.value for t in Base} else f"Tag {tag_id}"
+                console.print(f"  {tag}: {value}")
+        else:
+            console.print("\n[bold yellow]EXIF Metadata:[/bold yellow] None")