_common.py

"""
Shared helpers for the demo scripts.

- Resolves the output directory next to the examples folder
- Builds a small sample PDF on demand for demos that need an input file
- Provides a consistent header banner so the console output is readable
"""

from __future__ import annotations

import os
import sys
from pathlib import Path

import exis_pdfeditor

# All demos write their output here. Created on first call.
OUTPUT_DIR = Path(__file__).parent / "output"
SAMPLES_DIR = Path(__file__).parent.parent / "samples"


def init_license() -> None:
    """Initialize the library trial / license once per process."""
    # No key -> 14-day trial. Set EXIS_PDF_LICENSE_KEY env var or pass a key
    # to initialize() if you have one.
    key = os.environ.get("EXIS_PDF_LICENSE_KEY")
    if key:
        exis_pdfeditor.initialize(key)
    else:
        exis_pdfeditor.initialize()


def ensure_output_dir() -> Path:
    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
    return OUTPUT_DIR


def header(title: str) -> None:
    bar = "=" * 70
    print()
    print(bar)
    print(f"  {title}")
    print(bar)


def info(message: str) -> None:
    print(f"  [INFO] {message}")


def success(message: str) -> None:
    print(f"  [ OK ] {message}")


def warn(message: str) -> None:
    print(f"  [WARN] {message}")


def error(message: str) -> None:
    print(f"  [FAIL] {message}", file=sys.stderr)


def get_sample_pdf() -> Path:
    """
    Return the path to a sample PDF that all demos can use as input.

    If samples/sample.pdf exists, use it. Otherwise look for any PDF in
    the samples folder. As a last resort, raise an informative error so the
    user knows to drop a PDF in.
    """
    ensure_output_dir()

    explicit = SAMPLES_DIR / "sample.pdf"
    if explicit.exists():
        return explicit

    if SAMPLES_DIR.exists():
        any_pdf = next((p for p in SAMPLES_DIR.glob("*.pdf")), None)
        if any_pdf is not None:
            return any_pdf

    raise FileNotFoundError(
        f"No sample PDF found.\n\n"
        f"Drop a PDF named 'sample.pdf' (or any .pdf file) into:\n"
        f"  {SAMPLES_DIR}\n\n"
        f"Then re-run this demo. Several free sample PDFs are available online,\n"
        f"or you can use any PDF file you have on hand."
    )