"""Hiérarchie d'erreurs transversale du projet pronote-sync."""

from __future__ import annotations


class PronoteSyncError(Exception):
    """Erreur de base pour toutes les exceptions du projet pronote-sync.

    Toutes les exceptions métier héritent de cette classe pour permettre
    une interception unifiée des erreurs applicatives.
    """

    def __init__(self, message: str) -> None:
        """Initialise l'erreur avec un message descriptif.

        :param message: Message décrivant la cause de l'erreur.
        """
        super().__init__(message)


class PipelineCriticalError(PronoteSyncError):
    """Erreur critique du pipeline, levée quand aucune récupération n'est possible.

    Par exemple : échec simultané des sources iCal et pronotepy,
    rendant impossible toute synchronisation.
    """

    def __init__(self, message: str) -> None:
        """Initialise l'erreur critique avec un message descriptif.

        :param message: Message décrivant la cause de l'erreur critique.
        """
        super().__init__(message)


class PipelineWarning(PronoteSyncError):
    """Avertissement non bloquant pour une erreur récupérable du pipeline.

    Contrairement à :class:`PipelineCriticalError`, cet avertissement signale
    un problème récupérable : le pipeline peut poursuivre son exécution en
    mode dégradé.

    Il hérite volontairement de :class:`PronoteSyncError` (et non de la classe
    native :class:`Warning`) afin de rester dans la hiérarchie canonique des
    erreurs du projet.

    :ivar recoverable: Indique que l'erreur est récupérable (toujours ``True``).
    :ivar step: Étape du pipeline ayant produit l'avertissement.
    """

    def __init__(self, message: str, step: str | None = None) -> None:
        """Initialise l'avertissement avec un message descriptif.

        :param message: Message décrivant la cause de l'avertissement.
        :param step: Étape du pipeline ayant produit l'avertissement.
        """
        super().__init__(message)
        self.recoverable = True
        self.step = step