"""Spiel-Bewertungs-Utility für brettspiel-news.de."""

MAX_BEWERTUNG = 10
MIN_BEWERTUNG = 1


def validate_rating(wert: int) -> bool:
    """Validiert eine Spielbewertung.

    Prüft, ob die Bewertung im zulässigen Bereich von 1 bis MAX_BEWERTUNG liegt.

    Args:
        wert: Die zu prüfende Bewertung als Ganzzahl.

    Returns:
        True, wenn die Bewertung gültig ist.

    Raises:
        ValueError: Wenn die Bewertung außerhalb von 1 bis 10 liegt.
    """
    if wert < MIN_BEWERTUNG or wert > MAX_BEWERTUNG:
        raise ValueError(
            f"Bewertung {wert} ungültig. Gültiger Bereich: {MIN_BEWERTUNG}–{MAX_BEWERTUNG}"
        )
    return True


def berechne_durchschnitt(bewertungen: list[int]) -> float | None:
    """Berechnet den Durchschnitt einer Liste von Bewertungen.

    Validiert jede Bewertung vor der Berechnung. Gibt None zurück,
    wenn die Liste leer ist.

    Args:
        bewertungen: Liste von Bewertungen als Ganzzahlen.

    Returns:
        Der Durchschnitt als Float, oder None bei leerer Liste.
    """
    if not bewertungen:
        return None

    for wert in bewertungen:
        validate_rating(wert)

    return sum(bewertungen) / len(bewertungen)