"""Protocole pour les fournisseurs d'agenda théorique.

Ce module définit :class:`TheoreticalAgendaProvider`, le contrat que
tous les fournisseurs d'agenda théorique doivent respecter pour exposer
les cours théoriques (emploi du temps attendu) par date ou plage de
dates.
"""

from __future__ import annotations

from datetime import date
from typing import Protocol, runtime_checkable

from pronote_sync.models.agenda import TheoreticalLesson


@runtime_checkable
class TheoreticalAgendaProvider(Protocol):
    """Protocole pour un fournisseur d'agenda théorique.

    Un fournisseur d'agenda théorique expose les cours théoriques
    (emploi du temps attendu) pour une date ou une plage de dates.
    L'implémentation encapsule la logique de filtrage par parité de
    semaine et par vacances scolaires.
    """

    def get_lessons(self, target_date: date) -> list[TheoreticalLesson]:
        """Retourne les cours théoriques applicables à la date donnée.

        :param target_date: Date cible.
        :return: Liste des cours théoriques triée par identifiant.
        :rtype: list[TheoreticalLesson]
        """
        ...

    def get_lessons_for_range(self, start_date: date, end_date: date) -> list[TheoreticalLesson]:
        """Retourne les cours théoriques pour une plage de dates (inclusives).

        :param start_date: Date de début (inclusive).
        :param end_date: Date de fin (inclusive).
        :return: Liste des cours théoriques triée par identifiant.
        :rtype: list[TheoreticalLesson]
        """
        ...