zimscraperlib.image

Modules:

• conversion –
• illustration –
• optimization –

  An image optimization module to optimize the following image formats:

• presets –
• probing –
• transformation –
• utils –

Functions:

• convert_image –

  convert an image file from one format to another

• is_valid_image –

  whether image is a valid imformat (PNG) image, optionnaly of requested size

• optimize_image –

  Optimize image, automatically selecting correct optimizer

• resize_image –

  resize an image to requested dimensions

convert_image

convert_image(
    src: Path | BytesIO,
    dst: Path | BytesIO,
    **params: str | None,
) -> None

convert an image file from one format to another params: Image.save() parameters. Depends on dest format. params can include the following keys: - fmt: specify the dest format (otherwise guessed from extension) ex: JPEG, PNG, BMP (and other PIL formats) - colorspace: convert to this colorspace. Otherwise not converted unless target format has no halpha channel while source had. In this case converted to RGB. ex: RGB, ARGB, CMYK (and other PIL colorspaces)

Source code in src/zimscraperlib/image/conversion.py

def convert_image(
    src: pathlib.Path | io.BytesIO,
    dst: pathlib.Path | io.BytesIO,
    **params: str | None,
) -> None:
    """convert an image file from one format to another
    params: Image.save() parameters. Depends on dest format.
    params can include the following keys:
     - fmt: specify the dest format (otherwise guessed from extension)
            ex: JPEG, PNG, BMP (and other PIL formats)
     - colorspace: convert to this colorspace. Otherwise not converted unless
     target format has no halpha channel while source had. In this case converted
     to RGB. ex: RGB, ARGB, CMYK (and other PIL colorspaces)"""

    colorspace = params.get("colorspace")  # requested colorspace
    fmt = (
        str(params.pop("fmt")).upper() if params.get("fmt") else None
    )  # requested format
    if not fmt:
        fmt = format_for(dst)
    if not fmt:
        raise ValueError("Impossible to guess destination image format")
    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)

is_valid_image

is_valid_image(
    image: Path | bytes | BytesIO,
    imformat: str,
    size: tuple[int, int] | None = None,
) -> bool

whether image is a valid imformat (PNG) image, optionnaly of requested size

Source code in src/zimscraperlib/image/probing.py

def is_valid_image(
    image: pathlib.Path | bytes | io.BytesIO,
    imformat: str,
    size: tuple[int, int] | None = None,
) -> bool:
    """whether image is a valid imformat (PNG) image, optionnaly of requested size"""
    if isinstance(image, bytes):
        image = io.BytesIO(image)
    try:
        img = PIL.Image.open(image)
        if img.format != imformat:
            return False
        if size and img.size != size:
            return False
    except Exception:
        return False
    return True

optimize_image

optimize_image(
    src: Path | BytesIO | bytes,
    dst: Path | BytesIO,
    options: OptimizeOptions | None = None,
    *,
    dst_format: str | None = None,
    delete_src: bool = False,
    convert: bool | str = False,
) -> Path | BytesIO

Optimize image, automatically selecting correct optimizer

Parameters:

• dst_format (str | None, default: None ) –

  format of the destination image, required when dst is io.BytesIO.

• delete_src (bool, default: False ) –

  whether to remove src file upon success (boolean) values: True | False

• convert (bool | str, default: False ) –

  will be deprecated in scraperlib 6, use dst_format instead. values: False: don't convert True: convert to format implied by dst suffix str: convert to the specified format

Source code in src/zimscraperlib/image/optimization.py

def optimize_image(
    src: pathlib.Path | io.BytesIO | bytes,
    dst: pathlib.Path | io.BytesIO,
    options: OptimizeOptions | None = None,
    *,
    dst_format: str | None = None,
    delete_src: bool = False,
    convert: bool | str = False,
) -> pathlib.Path | io.BytesIO:
    """Optimize image, automatically selecting correct optimizer

    Arguments:
        dst_format: format of the destination image,
            required when dst is io.BytesIO.
        delete_src: whether to remove src file upon success (boolean)
            values: True | False
        convert: will be deprecated in scraperlib 6, use dst_format instead.
            values: False: don't convert
                    True: convert to format implied by dst suffix
                    str: convert to the specified format"""

    if convert is not False:
        warnings.warn(
            "The 'convert' param is deprecated and will be removed in scraperlib 6."
            "Use 'dst_format' parameter instead.",
            DeprecationWarning,
            stacklevel=2,
        )

        if isinstance(convert, str):
            dst_format = convert

    if options is None:
        options = OptimizeOptions.of()

    if isinstance(src, bytes):
        src = io.BytesIO(src)

    if delete_src and isinstance(src, io.BytesIO):
        raise ValueError("delete_src is not applicable when src is io.BytesIO or bytes")

    if isinstance(dst, pathlib.Path):
        dst_format = dst_format or format_for(dst)
        if dst_format is None:
            raise ValueError("Impossible to guess format from dst image")
    elif dst_format is None:
        raise ValueError("dst_format is required when dst is io.BytesIO")
    dst_format = dst_format.lower()

    if dst_format in ("jpg", "jpeg"):
        optimize_jpeg(src=src, dst=dst, options=options.jpg)
    elif dst_format == "gif":
        optimize_gif(src=src, dst=dst, options=options.gif)
    elif dst_format == "png":
        optimize_png(src=src, dst=dst, options=options.png)
    elif dst_format == "webp":
        optimize_webp(src=src, dst=dst, options=options.webp)
    else:
        raise NotImplementedError(
            f"Image format '{dst_format}' cannot yet be optimized"
        )

    if (
        delete_src
        and isinstance(src, pathlib.Path)
        and src.exists()
        and isinstance(dst, pathlib.Path)
        and dst.exists()
        and not src.samefile(dst)
    ):
        src.unlink()

    return dst

resize_image

resize_image(
    src: Path | BytesIO,
    width: int,
    height: int | None = None,
    dst: Path | BytesIO | None = None,
    method: str | None = "width",
    *,
    allow_upscaling: bool | None = True,
    **params: str,
) -> None

resize an image to requested dimensions

methods: width, height, cover, thumbnail allow upscaling: upscale image first, preserving aspect ratio if required

Source code in src/zimscraperlib/image/transformation.py

def resize_image(
    src: pathlib.Path | io.BytesIO,
    width: int,
    height: int | None = None,
    dst: pathlib.Path | io.BytesIO | None = None,
    method: str | None = "width",
    *,
    allow_upscaling: bool | None = True,
    **params: str,
) -> None:
    """resize an image to requested dimensions

    methods: width, height, cover, thumbnail
    allow upscaling: upscale image first, preserving aspect ratio if required"""
    with pilopen(src) as image:
        # preserve image format as resize() does not transmit it into new object
        image_format = image.format
        image_mode = image.mode

        # upscale if required preserving the aspect ratio
        if allow_upscaling:
            height_width_ratio = float(image.size[1]) / float(image.size[0])
            if image.size[0] < width:
                image = image.resize(  # noqa: PLW2901 # pyright: ignore[reportUnknownMemberType]
                    (width, int(width * height_width_ratio))
                )
            if height and image.size[1] < height:
                image = image.resize(  # noqa: PLW2901 # pyright: ignore[reportUnknownMemberType]
                    (int(height / height_width_ratio), height)
                )

        # resize using the requested method
        if method == "width":
            resized = resizeimage.resize(  # pyright: ignore[reportUnknownMemberType]
                method, image, width
            )
        elif method == "height":
            resized = resizeimage.resize(  # pyright: ignore[reportUnknownMemberType]
                method, image, height
            )
        else:
            resized = resizeimage.resize(  # pyright: ignore[reportUnknownMemberType]
                method, image, [width, height]
            )

    # remove alpha layer if not supported and added during resizing
    if resized.mode == "RGBA" and image_format in ALPHA_NOT_SUPPORTED:
        resized = resized.convert(image_mode)

    # reset src if it's a byte stream and should be resized in-place
    if dst is None and isinstance(src, io.BytesIO):
        src.seek(0)

    if image_format is None:  # pragma: no cover
        raise ValueError("Impossible to guess format from src image")

    save_image(
        resized,
        dst if dst is not None else src,
        image_format,
        **params,
    )