"""Guarda una PIL Image como PNG con metadata embebida en chunks tEXt."""

from __future__ import annotations

import os


def image_save_png(img: "PIL.Image.Image", path: str, metadata: dict | None = None) -> str:
    """Guarda una PIL Image como PNG en la ruta indicada.

    Embebe metadata arbitraria en chunks tEXt del PNG (clave/valor string).
    Util para registrar prompt, seed, steps, sampler, model dentro del archivo
    para reproducibilidad.

    Crea el directorio padre si no existe.

    Args:
        img: imagen PIL a guardar.
        path: ruta de destino (absoluta o relativa). Debe terminar en .png.
        metadata: dict opcional de pares {clave: valor} a embeber en el PNG.
                  Los valores se convierten a str automaticamente.

    Returns:
        Ruta absoluta del archivo PNG escrito.

    Raises:
        ImportError: si Pillow no esta instalado.
        OSError: si no se puede escribir en la ruta indicada.
    """
    try:
        from PIL import PngImagePlugin
    except ImportError as exc:
        raise ImportError(
            "Pillow no esta instalado. Instalar con: pip install Pillow"
        ) from exc

    abs_path = os.path.abspath(path)
    parent = os.path.dirname(abs_path)
    if parent:
        os.makedirs(parent, exist_ok=True)

    png_info = PngImagePlugin.PngInfo()
    if metadata:
        for key, value in metadata.items():
            png_info.add_text(str(key), str(value))

    img.save(abs_path, format="PNG", pnginfo=png_info)
    return abs_path