"""Résultat de la récupération du flux RSS du blog du collège.

Ce module définit :class:`BlogRSSFetchResult`, le type de retour figé du
client RSS du blog (:mod:`pronote_sync.sources.blog`).
"""

from __future__ import annotations

from pydantic import BaseModel, ConfigDict, Field

from pronote_sync.models.blog import BlogArticle


class BlogRSSFetchResult(BaseModel):
    """Résultat d'une récupération du flux RSS du blog du collège.

    Modèle figé (``frozen``) : les instances sont immuables après création.
    Il regroupe les nouveaux articles, triés par date de publication
    décroissante puis par identifiant croissant, ainsi que les en-têtes
    HTTP utiles aux requêtes conditionnelles (``ETag`` et
    ``Last-Modified``).

    :param articles: Nouveaux articles absents de ``known_guids``, triés
        par date de publication décroissante puis par identifiant
        croissant. Vide par défaut.
    :param etag: Valeur de l'en-tête ``ETag`` de la réponse RSS, si elle
        est disponible. ``None`` par défaut.
    :param last_modified: Valeur de l'en-tête ``Last-Modified`` de la
        réponse RSS, si elle est disponible. ``None`` par défaut.
    :param not_modified: Vaut ``True`` si le serveur a répondu avec le
        statut ``304 Not Modified``, ``False`` sinon.
    :param error: Message d'erreur expurgé si la récupération a échoué,
        ``None`` sinon.
    """

    model_config = ConfigDict(frozen=True)

    articles: tuple[BlogArticle, ...] = Field(
        default=(),
        description=(
            "Nouveaux articles absents de known_guids, triés par date de "
            "publication décroissante puis par identifiant croissant"
        ),
    )
    etag: str | None = Field(
        default=None,
        description="Valeur de l'en-tête ETag de la réponse RSS, si disponible",
    )
    last_modified: str | None = Field(
        default=None,
        description="Valeur de l'en-tête Last-Modified de la réponse RSS, si disponible",
    )
    not_modified: bool = Field(
        default=False,
        description="Vaut True si le serveur a répondu 304 Not Modified",
    )
    error: str | None = Field(
        default=None,
        description=("Message d'erreur expurgé si la récupération a échoué, None sinon"),
    )