Transformers¶

def drawio_export(source: Path | str, output_dir: Path, **options: Any) -> Path:
    """Export a draw.io diagram in the ``format`` asked of it (``pdf`` by default)."""
    return registry.convert("drawio", source, output_dir=output_dir, **options)

def fetch_image(url: str, output_dir: Path, **options: Any) -> Path:
    """Fetch a remote image and normalise it to PDF."""
    return registry.convert("fetch-image", url, output_dir=output_dir, **options)

def has_converter(name: str) -> bool:
    """Return True when a converter strategy is currently registered."""
    return registry.is_registered(name)

def image2pdf(source: Path | str, output_dir: Path, **options: Any) -> Path:
    """Convert bitmap images to PDF."""
    return registry.convert("image", source, output_dir=output_dir, **options)

def mermaid2pdf(source: Path | str, output_dir: Path, **options: Any) -> Path:
    """Convert Mermaid diagrams to PDF."""
    return registry.convert("mermaid", source, output_dir=output_dir, **options)

def register_converter(name: str, strategy: ConverterStrategy) -> None:
    """Expose a helper to register external strategies."""
    registry.register(name, strategy)

def svg2pdf(source: Path | str, output_dir: Path, **options: Any) -> Path:
    """Convert SVG assets to PDF."""
    return registry.convert("svg", source, output_dir=output_dir, **options)

def exponential_backoff(
    base_delay: float = 0.5, factor: float = 2.0, max_delay: float = 5.0
) -> Callable[[int], float]:
    """Return a simple exponential backoff policy."""

    def policy(attempt: int) -> float:
        delay = base_delay * (factor ** (attempt - 1))
        return min(delay, max_delay)

    return policy

def drawio_format(value: Any) -> str:
    """The export format of a draw.io conversion, ``pdf`` when it is unnamed."""
    fmt = str(value or "pdf").strip().lower()
    return fmt if fmt in DRAWIO_FORMATS else "pdf"

def drawio_suffix(value: Any) -> str:
    """The suffix a draw.io export lands under: its format, and nothing else."""
    return f".{drawio_format(value)}"

def option_flag(value: Any, *, default: bool = False) -> bool:
    """Read a boolean option that may reach us as a string from a document attribute."""
    resolved = coerce_bool(value)
    return default if resolved is None else resolved

def normalise_pdf_version(pdf_path: Path, *, target_version: str = "1.5") -> None:
    """Re-write a PDF so its header advertises the requested version."""
    try:
        import pypdf  # type: ignore[import]
    except ImportError as exc:  # pragma: no cover - optional dependency
        msg = "pypdf is required to normalise PDF artefacts."
        raise TransformerExecutionError(msg) from exc

    try:
        reader = pypdf.PdfReader(str(pdf_path))
    except Exception as exc:  # pragma: no cover - defensive
        msg = f"Failed to read generated PDF '{pdf_path}': {exc}"
        raise TransformerExecutionError(msg) from exc

    # Skip rewriting when already on the desired version.
    header = getattr(reader, "pdf_header", b"")
    if isinstance(header, bytes):
        header_text = header.decode("latin-1", "ignore")
        if header_text.startswith("%PDF-"):
            current_version = header_text[5:].strip()
            if current_version == target_version:
                return

    writer = pypdf.PdfWriter()
    for page in reader.pages:
        writer.add_page(page)
    writer.pdf_header = f"%PDF-{target_version}\n"

    metadata = reader.metadata or {}
    filtered_metadata = {k: v for k, v in metadata.items() if isinstance(v, str)}
    if filtered_metadata:
        writer.add_metadata(filtered_metadata)

    tmp_path = pdf_path.with_suffix(pdf_path.suffix + ".tmp")
    try:
        with tmp_path.open("wb") as handle:
            writer.write(handle)
    except Exception as exc:  # pragma: no cover - defensive
        msg = f"Failed to rewrite PDF '{pdf_path}' to version {target_version}: {exc}"
        raise TransformerExecutionError(msg) from exc

    tmp_path.replace(pdf_path)

def points_to_mm(points: float) -> float:
    """Convert PDF points to millimetres."""
    return points * 25.4 / 72