#!/usr/bin/env python3
"""Gemeinsame Schnittstelle fuer Kodi-Plugins."""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any, Dict, List, Optional, Set, Tuple


class BasisPlugin(ABC):
    """Abstrakte Basisklasse fuer alle Integrationen."""

    name: str
    version: str = "0.0.0"
    prefer_source_metadata: bool = False

    @abstractmethod
    async def search_titles(self, query: str) -> List[str]:
        """Liefert eine Liste aller Treffer fuer die Suche."""

    @abstractmethod
    def seasons_for(self, title: str) -> List[str]:
        """Liefert alle Staffeln zu einem Titel."""

    @abstractmethod
    def episodes_for(self, title: str, season: str) -> List[str]:
        """Liefert alle Folgen zu einer Staffel."""

    def stream_link_for(self, title: str, season: str, episode: str) -> Optional[str]:
        """Optional: Liefert den Stream-Link fuer eine konkrete Folge."""
        return None

    def metadata_for(self, title: str) -> Tuple[Dict[str, str], Dict[str, str], Optional[List[Any]]]:
        """Optional: Liefert Info-Labels, Art und Cast fuer einen Titel."""
        return {}, {}, None

    def resolve_stream_link(self, link: str) -> Optional[str]:
        """Optional: Folgt einem Stream-Link und liefert die finale URL."""
        return None

    def genres(self) -> List[str]:
        """Optional: Liefert eine Liste an Genres (falls verfügbar)."""
        return []

    def titles_for_genre(self, genre: str) -> List[str]:
        """Optional: Liefert alle Serientitel zu einem Genre."""
        return []

    def capabilities(self) -> Set[str]:
        """Optional: Liefert eine Menge an Features/Capabilities dieses Plugins.

        Beispiele:
        - `popular_series`: Plugin kann eine Liste beliebter Serien liefern.
        """

        return set()

    def popular_series(self) -> List[str]:
        """Optional: Liefert eine Liste beliebter Serien (als Titel-Strings)."""

        return []
