Gestire il formato WebP in Python

In questo articolo costruiremo un piccolo toolkit completo: un parser dell'intestazione in Python puro per validare i file senza decodificarli, la conversione da JPEG e PNG con un controllo consapevole dei parametri dell'encoder, la gestione della trasparenza, delle animazioni e dei metadati, una pipeline di caricamento sicura, un endpoint Flask che negozia il formato con il browser e uno script di conversione in parallelo per gli archivi esistenti.

Python di Gabriele Romanato

WebP, il formato immagine sviluppato da Google a partire dal codec video VP8, è ormai uno standard di fatto per il web: lo leggono tutti i browser moderni, supporta la compressione con e senza perdita, la trasparenza e le animazioni, e a parità di qualità produce file più leggeri di JPEG, PNG e GIF. In Python la libreria di riferimento per lavorarci è Pillow, il fork attivamente mantenuto della storica PIL, che include il supporto a WebP nelle wheel ufficiali per tutte le piattaforme principali.

In questo articolo costruiremo un piccolo toolkit completo: un parser dell'intestazione in Python puro per validare i file senza decodificarli, la conversione da JPEG e PNG con un controllo consapevole dei parametri dell'encoder, la gestione della trasparenza, delle animazioni e dei metadati, una pipeline di caricamento sicura, un endpoint Flask che negozia il formato con il browser e uno script di conversione in parallelo per gli archivi esistenti.

La struttura di un file WebP

Un file WebP è un contenitore RIFF. I primi dodici byte contengono la stringa RIFF, la dimensione del resto del file come intero a 32 bit little-endian e la stringa WEBP. Seguono i chunk, blocchi formati da un identificatore di quattro caratteri, una dimensione a 32 bit e un contenuto di lunghezza pari. Il primo chunk rivela la variante del file:

  • VP8 , con uno spazio finale: immagine con perdita senza trasparenza. Le dimensioni sono due interi a 14 bit che seguono l'intestazione del fotogramma e il codice di sincronizzazione 9d 01 2a.
  • VP8L: immagine senza perdita. Dopo il byte di firma 0x2f, 28 bit contengono larghezza e altezza meno uno, e un bit successivo segnala l'uso dell'alfa.
  • VP8X: formato esteso. Un byte di flag indica la presenza di profilo ICC, alfa, EXIF, XMP e animazione; seguono le dimensioni della tela su 24 bit, memorizzate meno uno. I dati dell'immagine si trovano nei chunk successivi.

Leggere l'intestazione senza decodificare

Conoscere la struttura permette di scrivere un ispettore che legge solo i primi 30 byte. Lo useremo per validare i caricamenti, per conoscere le dimensioni senza allocare memoria per i pixel e per distinguere un WebP animato da uno statico prima ancora di aprirlo con Pillow.

# webp_info.py
from __future__ import annotations

import struct
from dataclasses import dataclass
from pathlib import Path
from typing import BinaryIO

FLAG_ICC = 0x20
FLAG_ALPHA = 0x10
FLAG_EXIF = 0x08
FLAG_XMP = 0x04
FLAG_ANIMATION = 0x02


@dataclass(frozen=True, slots=True)
class WebpInfo:
    format: str
    width: int
    height: int
    alpha: bool = False
    animated: bool = False
    icc: bool = False
    exif: bool = False
    xmp: bool = False


def read_webp_info(data: bytes) -> WebpInfo | None:
    """Restituisce le informazioni dell'intestazione o None se i dati non sono WebP."""
    if len(data) < 30 or data[0:4] != b"RIFF" or data[8:12] != b"WEBP":
        return None

    fourcc = data[12:16]

    if fourcc == b"VP8 ":
        # Codice di sincronizzazione del fotogramma chiave
        if data[23:26] != b"\x9d\x01\x2a":
            return None
        width, height = struct.unpack_from("<HH", data, 26)
        return WebpInfo("lossy", width & 0x3FFF, height & 0x3FFF)

    if fourcc == b"VP8L":
        if data[20] != 0x2F:
            return None
        (bits,) = struct.unpack_from("<I", data, 21)
        return WebpInfo(
            "lossless",
            (bits & 0x3FFF) + 1,
            ((bits >> 14) & 0x3FFF) + 1,
            alpha=bool((bits >> 28) & 0x1),
        )

    if fourcc == b"VP8X":
        flags = data[20]
        width = int.from_bytes(data[24:27], "little") + 1
        height = int.from_bytes(data[27:30], "little") + 1
        return WebpInfo(
            "extended",
            width,
            height,
            alpha=bool(flags & FLAG_ALPHA),
            animated=bool(flags & FLAG_ANIMATION),
            icc=bool(flags & FLAG_ICC),
            exif=bool(flags & FLAG_EXIF),
            xmp=bool(flags & FLAG_XMP),
        )

    return None


def inspect(source: str | Path | BinaryIO) -> WebpInfo | None:
    # Legge solo l'inizio del file, qualunque sia la sua dimensione
    if isinstance(source, (str, Path)):
        with open(source, "rb") as handle:
            return read_webp_info(handle.read(64))
    position = source.tell()
    try:
        return read_webp_info(source.read(64))
    finally:
        source.seek(position)

Il modulo struct si occupa degli interi little-endian a 16 e 32 bit, mentre per i valori a 24 bit del formato esteso è più comodo int.from_bytes. La funzione inspect accetta sia un percorso sia un file già aperto, e in quel caso riporta il cursore nella posizione originale: è un dettaglio che evita errori subdoli quando lo stesso oggetto viene poi passato a Pillow.

Installare Pillow e verificare il supporto

Le wheel di Pillow pubblicate su PyPI includono libwebp, quindi su Linux, macOS e Windows basta un normale pip install. Se si compila Pillow dai sorgenti, invece, bisogna avere installati gli header di libwebp, altrimenti il supporto viene escluso in silenzio.

python -m venv .venv
source .venv/bin/activate
pip install Pillow
python -c "from PIL import features; print(features.check('webp'), features.version('webp'))"

L'ultimo comando stampa la disponibilità del codec e la versione di libwebp in uso. È un'informazione da registrare nei log di avvio: nel settembre 2023 la vulnerabilità CVE-2023-4863, un heap overflow nella decodifica senza perdita sfruttato attivamente, ha reso necessari aggiornamenti urgenti in browser e librerie, Pillow compreso. Tenere Pillow aggiornato è la contromisura principale, perché porta con sé una libwebp recente.

La prima conversione

Con Pillow si apre l'immagine, la si porta in una modalità colore che WebP sa codificare e la si salva indicando il formato. Il punto che spesso si trascura è proprio la modalità: WebP lavora in RGB o RGBA, mentre un JPEG può essere in CMYK, un PNG in scala di grigi o a tavolozza, una TIFF a 16 bit per canale.

# convert.py
from pathlib import Path

from PIL import Image, ImageOps


def normalize_mode(image: Image.Image) -> Image.Image:
    """Porta l'immagine in RGB o RGBA conservando l'eventuale trasparenza."""
    if image.mode in ("RGB", "RGBA"):
        return image
    has_alpha = image.mode in ("LA", "PA") or (
        image.mode == "P" and "transparency" in image.info
    )
    return image.convert("RGBA" if has_alpha else "RGB")


def to_webp(source: Path, target: Path, quality: int = 80, method: int = 4) -> int:
    with Image.open(source) as image:
        # Applica la rotazione indicata nel tag EXIF Orientation
        image = ImageOps.exif_transpose(image)
        image = normalize_mode(image)
        image.save(target, "WEBP", quality=quality, method=method)
    return target.stat().st_size


if __name__ == "__main__":
    size = to_webp(Path("foto.jpg"), Path("foto.webp"))
    print(f"Scritti {size} byte")

I parametri principali accettati da save() per il formato WebP sono questi:

  • quality (da 0 a 100, predefinito 80): nella modalità con perdita controlla la qualità visiva; in quella senza perdita indica quanto impegno dedicare alla compressione.
  • method (da 0 a 6, predefinito 4): il compromesso tra velocità di codifica e dimensione del file, come l'opzione -m di cwebp.
  • lossless: attiva la compressione senza perdita.
  • alpha_quality (da 0 a 100, predefinito 100): la qualità del canale alfa nella modalità con perdita.
  • exact: conserva i valori RGB dei pixel completamente trasparenti, che altrimenti l'encoder è libero di modificare.
  • icc_profile, exif e xmp: i metadati da incorporare nel file.

Misurare invece di indovinare

La scelta della qualità è un compromesso che conviene prendere sui dati. Lo script seguente codifica la stessa immagine in memoria con diversi profili e riporta peso e tempo di ciascuno, senza scrivere nulla su disco grazie a io.BytesIO.

# compare.py
import io
import sys
import time
from pathlib import Path

from PIL import Image, ImageOps

from convert import normalize_mode

PROFILES = {
    "jpeg-q85": ("JPEG", {"quality": 85, "optimize": True}),
    "webp-q60": ("WEBP", {"quality": 60}),
    "webp-q75": ("WEBP", {"quality": 75}),
    "webp-q82": ("WEBP", {"quality": 82}),
    "webp-q82-m6": ("WEBP", {"quality": 82, "method": 6}),
    "webp-lossless": ("WEBP", {"lossless": True}),
}


def compare(path: Path) -> None:
    original = path.stat().st_size
    with Image.open(path) as source:
        image = normalize_mode(ImageOps.exif_transpose(source))
        image.load()

    print(f"{'profilo':<16}{'KB':>8}{'rapporto':>10}{'ms':>8}")
    for name, (fmt, options) in PROFILES.items():
        buffer = io.BytesIO()
        started = time.perf_counter()
        image.save(buffer, fmt, **options)
        elapsed = (time.perf_counter() - started) * 1000
        size = buffer.tell()
        print(f"{name:<16}{size // 1024:>8}{size / original:>10.0%}{elapsed:>8.0f}")


if __name__ == "__main__":
    compare(Path(sys.argv[1] if len(sys.argv) > 1 else "foto.jpg"))

Su una fotografia i valori tra 75 e 82 danno di solito file molto più leggeri di un JPEG con qualità 85, mentre method=6 guadagna ancora qualche punto percentuale a fronte di un tempo di codifica sensibilmente maggiore. La compressione senza perdita, applicata a una foto, produce invece file più pesanti del JPEG di partenza: preserva fedelmente anche il rumore del sensore e gli artefatti della compressione precedente. È lo strumento giusto per altre immagini, come vedremo.

Trasparenza, grafiche e near-lossless

WebP permette una combinazione impossibile con i formati tradizionali: trasparenza e compressione con perdita nello stesso file. Una foto di prodotto scontornata, che in PNG pesa centinaia di kilobyte, in WebP con perdita ne pesa una frazione. Per loghi, icone, schermate e grafiche a colori piatti, invece, la modalità senza perdita è quasi sempre la scelta migliore, perché la compressione con perdita sporca i bordi netti.

# graphics.py
from pathlib import Path

from PIL import Image

from convert import normalize_mode


def is_flat_graphic(image: Image.Image, max_colors: int = 256) -> bool:
    # getcolors restituisce None se i colori distinti superano la soglia
    return image.mode == "P" or image.getcolors(max_colors) is not None


def encode_graphic(source: Path, target: Path) -> None:
    with Image.open(source) as original:
        flat = is_flat_graphic(original)
        image = normalize_mode(original)
        if flat:
            image.save(target, "WEBP", lossless=True, quality=100, method=6)
        elif image.mode == "RGBA":
            image.save(target, "WEBP", quality=82, alpha_quality=90, method=5)
        else:
            image.save(target, "WEBP", quality=80)


def save_exact(image: Image.Image, target: Path) -> None:
    # Utile per texture o maschere in cui i pixel trasparenti contengono dati
    image.save(target, "WEBP", lossless=True, exact=True)

Il controllo con getcolors() è un'euristica semplice ed efficace: un'immagine con meno di 256 colori distinti è quasi certamente una grafica. Con lossless=True il parametro quality non degrada nulla, ma indica all'encoder quanto lavorare per ridurre il peso: quality=100 e method=6 producono il file più piccolo possibile. Pillow non espone direttamente la modalità near-lossless di libwebp; se serve, l'alternativa è invocare cwebp -near_lossless da un processo esterno.

Varianti per srcset

Un CMS o un'applicazione che pubblica immagini deve quasi sempre produrre più larghezze della stessa immagine, da usare con l'attributo srcset. Conviene aprire e orientare la sorgente una sola volta, poi generare le varianti da quella copia in memoria.

# variants.py
from dataclasses import dataclass
from pathlib import Path

from PIL import Image, ImageOps

from convert import normalize_mode

WIDTHS = (320, 640, 960, 1280, 1920)


@dataclass(frozen=True, slots=True)
class Variant:
    width: int
    height: int
    path: Path


def create_variants(source: Path, output_dir: Path) -> list[Variant]:
    output_dir.mkdir(parents=True, exist_ok=True)
    with Image.open(source) as original:
        image = normalize_mode(ImageOps.exif_transpose(original))
        icc_profile = original.info.get("icc_profile")

    variants = []
    for width in WIDTHS:
        # Non si generano varianti più grandi dell'originale
        if width > image.width:
            break
        height = round(image.height * width / image.width)
        resized = image.resize((width, height), Image.Resampling.LANCZOS)
        path = output_dir / f"{source.stem}-{width}.webp"
        resized.save(
            path,
            "WEBP",
            quality=75 if width <= 640 else 80,
            method=5,
            icc_profile=icc_profile,
        )
        variants.append(Variant(width, height, path))
    return variants


def srcset(variants: list[Variant], public_path: str) -> str:
    return ", ".join(f"{public_path}/{v.path.name} {v.width}w" for v in variants)

Il filtro LANCZOS è il più accurato tra quelli di Pillow per la riduzione di scala. Si noti che il profilo ICC viene letto dall'immagine originale e passato esplicitamente a save(): le operazioni di ridimensionamento e conversione creano nuove immagini e non sempre si portano dietro il dizionario info. Il risultato si usa nel markup in questo modo:

<img src="/media/foto-1280.webp"
     srcset="/media/foto-320.webp 320w, /media/foto-640.webp 640w, /media/foto-1280.webp 1280w"
     sizes="(max-width: 700px) 100vw, 700px"
     width="1280" height="853" alt="Descrizione della foto" loading="lazy">

Metadati e privacy

Le foto scattate con uno smartphone contengono nei dati EXIF la posizione GPS, il modello del dispositivo e la data dello scatto. Pubblicarle così come sono significa diffondere informazioni che l'utente probabilmente non vuole condividere. Pillow, quando salva in WebP, non copia i metadati a meno che non li si passi esplicitamente: questo ci permette di decidere con precisione cosa conservare. Una strategia equilibrata è mantenere il profilo colore, che influisce sulla resa, e un EXIF ripulito.

# metadata.py
from pathlib import Path

from PIL import ExifTags, Image, ImageOps

from convert import normalize_mode

# Tag da eliminare prima della pubblicazione
PRIVATE_TAGS = (
    ExifTags.Base.Make,
    ExifTags.Base.Model,
    ExifTags.Base.BodySerialNumber,
    ExifTags.Base.LensSerialNumber,
)


def clean_exif(image: Image.Image) -> bytes:
    exif = image.getexif()
    # Il blocco GPS è una sotto-directory raggiungibile tramite un puntatore
    exif.pop(ExifTags.IFD.GPSInfo, None)
    for tag in PRIVATE_TAGS:
        exif.pop(tag, None)
    # I pixel sono già stati ruotati da exif_transpose: nessuna rotazione residua
    exif[ExifTags.Base.Orientation] = 1
    return exif.tobytes()


def publish(source: Path, target: Path, quality: int = 80) -> None:
    with Image.open(source) as original:
        icc_profile = original.info.get("icc_profile")
        image = ImageOps.exif_transpose(original)
        exif = clean_exif(image)
        normalize_mode(image).save(
            target, "WEBP", quality=quality, icc_profile=icc_profile, exif=exif
        )


def describe(path: Path) -> dict:
    with Image.open(path) as image:
        exif = image.getexif()
        return {
            "format": image.format,
            "size": image.size,
            "mode": image.mode,
            "frames": getattr(image, "n_frames", 1),
            "icc": "icc_profile" in image.info,
            "orientation": exif.get(ExifTags.Base.Orientation),
            "gps": ExifTags.IFD.GPSInfo in exif,
            "camera": exif.get(ExifTags.Base.Model),
        }

Due dettagli meritano attenzione. Il primo è l'ordine delle operazioni: exif_transpose ruota i pixel in base al tag Orientation e restituisce un'immagine il cui EXIF non contiene più quel tag; per questo clean_exif va chiamata sull'immagine già ruotata e non sull'originale, altrimenti i visualizzatori ruoterebbero la foto una seconda volta. Impostare esplicitamente il tag a 1, il valore che indica nessuna rotazione, rende la scelta evidente anche a chi legge il file. Il secondo è che il blocco GPS non è un tag come gli altri, ma un puntatore a una sotto-directory: rimuovendo il puntatore l'intero blocco sparisce dal file risultante.

Animazioni

Pillow legge e scrive WebP animati con la stessa interfaccia usata per le GIF. In lettura, l'immagine espone n_frames e is_animated, e il metodo seek() permette di spostarsi tra i fotogrammi; la durata di ciascuno si trova in info["duration"]. In scrittura si usa save_all=True con l'elenco dei fotogrammi aggiuntivi.

# animation.py
from pathlib import Path

from PIL import Image, ImageSequence


def read_frames(source: Path) -> tuple[list[Image.Image], list[int], int]:
    frames, durations = [], []
    with Image.open(source) as image:
        loop = image.info.get("loop", 0)
        for frame in ImageSequence.Iterator(image):
            # Ogni fotogramma va copiato: l'iteratore riusa lo stesso oggetto
            frames.append(frame.convert("RGBA"))
            durations.append(frame.info.get("duration", 100))
    return frames, durations, loop


def gif_to_webp(source: Path, target: Path, lossless: bool = False) -> int:
    frames, durations, loop = read_frames(source)
    frames[0].save(
        target,
        "WEBP",
        save_all=True,
        append_images=frames[1:],
        duration=durations,
        loop=loop,
        lossless=lossless,
        quality=75,
        method=4,
        # Cerca la codifica più compatta, a costo di un tempo maggiore
        minimize_size=True,
        # Permette di mescolare fotogrammi con e senza perdita
        allow_mixed=not lossless,
    )
    return target.stat().st_size


def resize_animation(source: Path, target: Path, width: int) -> None:
    frames, durations, loop = read_frames(source)
    height = round(frames[0].height * width / frames[0].width)
    resized = [frame.resize((width, height), Image.Resampling.LANCZOS) for frame in frames]
    resized[0].save(
        target, "WEBP", save_all=True, append_images=resized[1:],
        duration=durations, loop=loop, quality=70,
    )


def poster(source: Path, target: Path) -> None:
    # Il primo fotogramma come anteprima statica
    with Image.open(source) as image:
        image.seek(0)
        image.convert("RGBA").save(target, "WEBP", quality=80)

Il risparmio rispetto alle GIF è spesso del 50-70%, e il risultato non è limitato a 256 colori per fotogramma né alla trasparenza a un bit. Il parametro allow_mixed lascia all'encoder la libertà di codificare alcuni fotogrammi senza perdita, cosa che giova molto alle animazioni fatte di grafiche piatte. Va tenuto presente che read_frames carica tutti i fotogrammi in memoria: per animazioni lunghe e grandi conviene impostare un limite sul numero di fotogrammi accettati.

Caricamenti sicuri

Un'immagine caricata da un utente è un input non fidato, e i decoder di immagini sono un bersaglio storico. Pillow offre una protezione integrata contro le decompression bomb, file minuscoli che dichiarano dimensioni enormi: Image.MAX_IMAGE_PIXELS vale circa 89 milioni di pixel, oltre i quali viene emesso un avviso, e oltre il doppio viene sollevata DecompressionBombError. Per un servizio di caricamento conviene un limite più basso e un controllo esplicito, approfittando del fatto che Image.open() è pigro e legge solo l'intestazione.

# upload.py
import io

from PIL import Image, ImageOps, UnidentifiedImageError

from convert import normalize_mode
from metadata import clean_exif

MAX_BYTES = 15 * 1024 * 1024
MAX_PIXELS = 40_000_000
MAX_FRAMES = 300
ALLOWED_FORMATS = ["JPEG", "PNG", "WEBP", "GIF"]
MAX_SIDE = 2560

Image.MAX_IMAGE_PIXELS = MAX_PIXELS


class UploadError(ValueError):
    pass


def process_upload(data: bytes) -> bytes:
    if len(data) > MAX_BYTES:
        raise UploadError("File troppo grande")

    try:
        # formats limita i decoder che Pillow proverà a usare
        image = Image.open(io.BytesIO(data), formats=ALLOWED_FORMATS)
    except (UnidentifiedImageError, Image.DecompressionBombError) as error:
        raise UploadError("Immagine non valida") from error

    with image:
        # Fin qui è stata letta solo l'intestazione: si controlla prima di decodificare
        width, height = image.size
        if width * height > MAX_PIXELS:
            raise UploadError("Dimensioni eccessive")
        if getattr(image, "n_frames", 1) > MAX_FRAMES:
            raise UploadError("Troppi fotogrammi")

        try:
            # verify() su una copia individua i file troncati o corrotti
            with Image.open(io.BytesIO(data)) as probe:
                probe.verify()
            icc_profile = image.info.get("icc_profile")
            image = ImageOps.exif_transpose(image)
            image.thumbnail((MAX_SIDE, MAX_SIDE), Image.Resampling.LANCZOS)
        except (OSError, SyntaxError) as error:
            raise UploadError("Immagine danneggiata") from error

        output = io.BytesIO()
        normalize_mode(image).save(
            output, "WEBP", quality=82, icc_profile=icc_profile, exif=clean_exif(image)
        )
        return output.getvalue()

L'argomento formats di Image.open() è una difesa spesso ignorata: Pillow supporta decine di formati, alcuni poco usati e meno collaudati, e restringere l'elenco a quelli che ci interessano riduce la superficie di attacco. Il metodo thumbnail() ridimensiona sul posto mantenendo le proporzioni e senza mai ingrandire, quindi è perfetto per imporre un lato massimo. Nota: questa funzione riduce le animazioni al primo fotogramma; per conservarle si combina con il codice della sezione precedente.

Negoziazione del formato con Flask

Se gli originali restano in JPEG o PNG, il server può decidere a ogni richiesta se servire WebP in base all'intestazione Accept inviata dal browser. Flask espone l'intestazione già analizzata in request.accept_mimetypes, con il fattore di qualità di ciascun tipo. La risposta deve sempre includere Vary: Accept, altrimenti una cache intermedia potrebbe servire a tutti la prima variante memorizzata.

# app.py
import os
import threading
from pathlib import Path

from flask import Flask, abort, request, send_file
from PIL import Image, ImageOps
from werkzeug.security import safe_join

from convert import normalize_mode

MEDIA_DIR = Path("media").resolve()
CACHE_DIR = Path("cache").resolve()
SOURCE_TYPES = {".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png"}

app = Flask(__name__)
locks: dict[Path, threading.Lock] = {}
locks_guard = threading.Lock()


def prefers_webp() -> bool:
    accepted = request.accept_mimetypes
    # Il quality di image/webp deve essere positivo e non inferiore al formato originale
    return accepted["image/webp"] > 0 and accepted["image/webp"] >= accepted["image/jpeg"]


def ensure_webp(source: Path, relative: str) -> Path:
    target = CACHE_DIR / Path(relative).with_suffix(".webp")
    if target.exists() and target.stat().st_mtime >= source.stat().st_mtime:
        return target
    with locks_guard:
        lock = locks.setdefault(target, threading.Lock())
    # Un solo thread converte un dato file, gli altri attendono il risultato
    with lock:
        if target.exists() and target.stat().st_mtime >= source.stat().st_mtime:
            return target
        target.parent.mkdir(parents=True, exist_ok=True)
        temporary = target.with_suffix(f".{os.getpid()}.tmp")
        with Image.open(source) as image:
            icc_profile = image.info.get("icc_profile")
            image = normalize_mode(ImageOps.exif_transpose(image))
            image.save(temporary, "WEBP", quality=80, icc_profile=icc_profile)
        # La rinomina è atomica: nessun client legge un file scritto a metà
        temporary.replace(target)
    return target


@app.get("/media/<path:relative>")
def media(relative: str):
    joined = safe_join(str(MEDIA_DIR), relative)
    if joined is None:
        abort(404)
    source = Path(joined)
    mimetype = SOURCE_TYPES.get(source.suffix.lower())
    if mimetype is None or not source.is_file():
        abort(404)

    if prefers_webp():
        response = send_file(ensure_webp(source, relative), mimetype="image/webp")
    else:
        response = send_file(source, mimetype=mimetype)

    response.vary.add("Accept")
    response.cache_control.public = True
    response.cache_control.max_age = 86400
    return response

La funzione safe_join di Werkzeug impedisce i percorsi che tentano di uscire dalla cartella delle immagini, come ../../etc/passwd. Il confronto tra le date di modifica rigenera la versione in cache se l'originale viene sostituito, e il lucchetto per file evita che più richieste simultanee sulla stessa immagine avviino conversioni duplicate. In produzione, con più processi gestiti da Gunicorn, la rinomina atomica garantisce comunque che il file servito sia sempre completo.

Conversione di un archivio in parallelo

La codifica WebP è un'operazione dominata dalla CPU. Pillow rilascia il GIL durante buona parte del lavoro dei codec, ma per sfruttare davvero tutti i core su migliaia di file la soluzione più semplice e prevedibile è un pool di processi. Ogni processo lavora su un file alla volta, quindi la memoria occupata resta proporzionale al numero di worker e non al numero di immagini.

# batch.py
import sys
from concurrent.futures import ProcessPoolExecutor, as_completed
from pathlib import Path

from PIL import Image, ImageOps

from animation import gif_to_webp
from convert import normalize_mode

EXTENSIONS = {".jpg", ".jpeg", ".png", ".gif"}


def convert_one(source: Path, target: Path) -> tuple[Path, int, int]:
    target.parent.mkdir(parents=True, exist_ok=True)
    before = source.stat().st_size
    if source.suffix.lower() == ".gif":
        after = gif_to_webp(source, target)
    else:
        with Image.open(source) as image:
            icc_profile = image.info.get("icc_profile")
            normalize_mode(ImageOps.exif_transpose(image)).save(
                target, "WEBP", quality=80, method=5, icc_profile=icc_profile
            )
        after = target.stat().st_size
    return source, before, after


def convert_tree(source_dir: Path, target_dir: Path, workers: int | None = None) -> None:
    jobs = [
        (path, (target_dir / path.relative_to(source_dir)).with_suffix(".webp"))
        for path in source_dir.rglob("*")
        if path.suffix.lower() in EXTENSIONS and path.is_file()
    ]
    saved = failed = 0
    with ProcessPoolExecutor(max_workers=workers) as pool:
        futures = {pool.submit(convert_one, source, target): source for source, target in jobs}
        for future in as_completed(futures):
            try:
                source, before, after = future.result()
                saved += before - after
                print(f"{source}: {before // 1024} KB -> {after // 1024} KB")
            except Exception as error:
                failed += 1
                print(f"Errore su {futures[future]}: {error}", file=sys.stderr)
    print(f"Convertiti {len(jobs) - failed} file, falliti {failed}, risparmiati {saved // 1024} KB")


if __name__ == "__main__":
    convert_tree(Path(sys.argv[1]), Path(sys.argv[2]))

Il blocco if __name__ == "__main__" non è un vezzo: su macOS e Windows, dove i processi figli vengono avviati con il metodo spawn, ogni worker reimporta il modulo principale, e senza quella guardia rilancerebbe a sua volta la conversione. Un errore su un singolo file viene registrato senza interrompere il lavoro sugli altri.

Test con pytest

Il parser dell'intestazione e la pulizia dei metadati sono le parti in cui un errore passa più facilmente inosservato. I test seguenti generano immagini sintetiche in memoria con Pillow e verificano il comportamento di entrambi.

# test_webp.py
import io

import pytest
from PIL import ExifTags, Image

from metadata import clean_exif
from upload import UploadError, process_upload
from webp_info import read_webp_info


def encode(mode: str, **options) -> bytes:
    image = Image.new(mode, (123, 45), (200, 30, 60, 128)[: len(mode)])
    buffer = io.BytesIO()
    image.save(buffer, "WEBP", **options)
    return buffer.getvalue()


def test_lossy():
    info = read_webp_info(encode("RGB", quality=80))
    assert (info.format, info.width, info.height, info.alpha) == ("lossy", 123, 45, False)


def test_lossless_with_alpha():
    info = read_webp_info(encode("RGBA", lossless=True))
    assert (info.format, info.alpha, info.width) == ("lossless", True, 123)


def test_lossy_with_alpha_uses_extended_format():
    info = read_webp_info(encode("RGBA", quality=80))
    assert (info.format, info.alpha, info.height) == ("extended", True, 45)


def test_animation_flag():
    frames = [Image.new("RGB", (40, 30), color) for color in ("red", "green", "blue")]
    buffer = io.BytesIO()
    frames[0].save(buffer, "WEBP", save_all=True, append_images=frames[1:], duration=100)
    assert read_webp_info(buffer.getvalue()).animated


def test_not_webp():
    assert read_webp_info(b"RIFF" + b"\x00" * 40) is None


def test_clean_exif_removes_gps_and_camera():
    # Si costruisce un JPEG reale con modello della fotocamera e coordinate GPS
    exif = Image.Exif()
    exif[ExifTags.Base.Model] = "Phone"
    exif.get_ifd(ExifTags.IFD.GPSInfo)[ExifTags.GPS.GPSLatitudeRef] = "N"
    buffer = io.BytesIO()
    Image.new("RGB", (10, 10)).save(buffer, "JPEG", exif=exif.tobytes())

    with Image.open(buffer) as image:
        assert ExifTags.IFD.GPSInfo in image.getexif()
        cleaned = Image.Exif()
        cleaned.load(clean_exif(image))
    assert ExifTags.Base.Model not in cleaned
    assert ExifTags.IFD.GPSInfo not in cleaned


def test_upload_rejects_garbage():
    with pytest.raises(UploadError):
        process_upload(b"non sono un'immagine")

Conclusioni

Con Pillow la gestione di WebP in Python è alla portata di poche righe, ma le righe che fanno la differenza sono quelle intorno alla chiamata a save(): normalizzare la modalità colore, applicare l'orientamento EXIF, decidere quali metadati conservare, scegliere tra compressione con e senza perdita in base al contenuto, misurare la qualità invece di fissarla a caso. Sul fronte della sicurezza, limitare pixel, fotogrammi e decoder ammessi e mantenere aggiornata la libreria sono pratiche che costano poco e proteggono molto. Il parser dell'intestazione, infine, resta uno strumento prezioso: in trenta byte dice quasi tutto di un file WebP, senza dover decodificare un solo pixel.