"""Restorer interface — "un-censor" detected regions of an image.

A Restorer takes an image plus the detected censored regions and returns a new
image with those regions reconstructed/filled. This mirrors the ``Detector``
abstraction so different engines (classic inpaint now; a generative model like
DeepMosaics / LADA later) plug in behind the same interface.
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from collections.abc import Callable

import numpy as np

from ..detection.types import Detection

# Optional cooperative-cancel hook: returns True to abort. Engines that loop or
# drive a subprocess should poll it; instant engines may ignore it.
CancelCheck = Callable[[], bool]


class Cancelled(Exception):
    """Raised by a Restorer when ``should_cancel`` asked it to stop."""


class Restorer(ABC):
    @property
    def name(self) -> str:
        return type(self).__name__

    @abstractmethod
    def restore(
        self,
        image: np.ndarray,
        detections: list[Detection],
        should_cancel: CancelCheck | None = None,
    ) -> np.ndarray:
        """Return a copy of ``image`` with the detected regions reconstructed.

        ``should_cancel`` (if given) is polled periodically; when it returns
        True the engine should abort and raise :class:`Cancelled`.
        """
        raise NotImplementedError