Merge 64e448f into 9d2f5ca

trakt/api.py

@@ -12,6 +12,7 @@
     CheckinI,
     CommentsI,
     CountriesI,
+    EpisodesI,
     GenresI,
     LanguagesI,
     ListsI,
@@ -21,6 +22,7 @@
     RecommendationsI,
     ScrobbleI,
     SearchI,
+    SeasonsI,
     ShowsI,
 )
 
@@ -51,6 +53,8 @@ def __init__(
         search_interface: Optional[Type[SearchI]] = None,
         recommendations_interface: Optional[Type[RecommendationsI]] = None,
         scrobble_interface: Optional[Type[ScrobbleI]] = None,
+        seasons_interface: Optional[Type[SeasonsI]] = None,
+        episodes_interface: Optional[Type[EpisodesI]] = None,
         user: Optional[TraktCredentials] = None,
         auto_refresh_token: bool = False,
         **config: str
@@ -90,6 +94,8 @@ def __init__(
             self, Executor
         )
         self.scrobble = (scrobble_interface or ScrobbleI)(self, Executor)
+        self.seasons = (seasons_interface or SeasonsI)(self, Executor)
+        self.episodes = (episodes_interface or EpisodesI)(self, Executor)
 
     def request(self, params: Union[str, List[str]], **kwargs: Any) -> Any:
         if isinstance(params, str):

trakt/core/models.py

@@ -136,8 +136,20 @@ class Person(AbstractBaseModel):
 
 @dataclass
 class Season(AbstractBaseModel):
+    number: int
     ids: Dict[str, MediaForeignIDType]
 
+    rating: Optional[int] = None
+    votes: Optional[int] = None
+    episode_count: Optional[int] = None
+    aired_episodes: Optional[int] = None
+    title: Optional[str] = None
+    overview: Optional[str] = None
+    first_aired: Optional[datetime] = None
+    network: Optional[str] = None
+
+    episodes: Optional[List[Episode]] = None
+
 
 @dataclass
 class Comment:

trakt/core/paths/__init__.py

@@ -2,6 +2,7 @@
 from trakt.core.paths.endpoint_mappings.calendars import CalendarsI
 from trakt.core.paths.endpoint_mappings.checkin import CheckinI
 from trakt.core.paths.endpoint_mappings.comments import CommentsI
+from trakt.core.paths.endpoint_mappings.episodes import EpisodesI
 from trakt.core.paths.endpoint_mappings.misc_mappings import (
     CertificationsI,
     CountriesI,
@@ -17,3 +18,4 @@
 from trakt.core.paths.endpoint_mappings.recommendations import RecommendationsI
 from trakt.core.paths.endpoint_mappings.scrobble import ScrobbleI
 from trakt.core.paths.endpoint_mappings.search import SearchI
+from trakt.core.paths.endpoint_mappings.seasons import SeasonsI

trakt/core/paths/endpoint_mappings/episodes.py

@@ -0,0 +1,195 @@
+from typing import Iterable, List, Union
+
+from trakt.core.models import Comment, Episode, Season
+from trakt.core.paths.endpoint_mappings.movies import (
+    COMMENT_SORT_VALUES,
+    LIST_SORT_VALUES,
+    LIST_TYPE_VALUES,
+)
+from trakt.core.paths.path import Path
+from trakt.core.paths.response_structs import (
+    EpisodeTranslation,
+    RatingsSummary,
+    SeasoneEpisodeStats,
+    Show,
+    TraktList,
+    User,
+)
+from trakt.core.paths.suite_interface import SuiteInterface
+from trakt.core.paths.validators import PerArgValidator
+
+ID_VALIDATOR = PerArgValidator("id", lambda i: isinstance(i, (int, str)))
+SEASON_ID_VALIDATOR = PerArgValidator("season", lambda i: isinstance(i, int))
+EPISODE_ID_VALIDATOR = PerArgValidator("season", lambda i: isinstance(i, int))
+
+
+class EpisodesI(SuiteInterface):
+    name = "episodes"
+
+    paths = {
+        "get_episode": Path(
+            "shows/!id/seasons/!season/episodes/!episode",
+            Episode,
+            extended=["full"],
+            validators=[ID_VALIDATOR, SEASON_ID_VALIDATOR, EPISODE_ID_VALIDATOR],
+        ),
+        "get_translations": Path(
+            "shows/!id/seasons/!season/comments/episodes/!episode/translations/?language",
+            [EpisodeTranslation],
+            validators=[
+                ID_VALIDATOR,
+                SEASON_ID_VALIDATOR,
+                EPISODE_ID_VALIDATOR,
+                PerArgValidator("language", lambda s: isinstance(s, str)),
+            ],
+            pagination=True,
+        ),
+        "get_comments": Path(
+            "shows/!id/seasons/!season/comments/episodes/!episode/?sort",
+            [Comment],
+            validators=[
+                ID_VALIDATOR,
+                SEASON_ID_VALIDATOR,
+                EPISODE_ID_VALIDATOR,
+                PerArgValidator("sort", lambda s: s in COMMENT_SORT_VALUES),
+            ],
+            pagination=True,
+        ),
+        "get_lists": Path(
+            "shows/!id/seasons/!season/episodes/!episode/lists/?type/?sort",
+            [TraktList],
+            validators=[
+                ID_VALIDATOR,
+                SEASON_ID_VALIDATOR,
+                EPISODE_ID_VALIDATOR,
+                PerArgValidator("type", lambda t: t in LIST_TYPE_VALUES),
+                PerArgValidator("sort", lambda s: s in LIST_SORT_VALUES),
+            ],
+            pagination=True,
+        ),
+        "get_ratings": Path(
+            "shows/!id/seasons/!season/episodes/!episode/ratings",
+            RatingsSummary,
+            validators=[ID_VALIDATOR, SEASON_ID_VALIDATOR, EPISODE_ID_VALIDATOR],
+        ),
+        "get_stats": Path(
+            "shows/!id/seasons/!season/episodes/!episode/stats",
+            SeasoneEpisodeStats,
+            validators=[ID_VALIDATOR, SEASON_ID_VALIDATOR, EPISODE_ID_VALIDATOR],
+        ),
+        "get_users_watching": Path(
+            "shows/!id/seasons/!season/episodes/!episode/watching",
+            [User],
+            extended=["full"],
+            validators=[ID_VALIDATOR, SEASON_ID_VALIDATOR, EPISODE_ID_VALIDATOR],
+        ),
+    }
+
+    def get_season(
+        self,
+        *,
+        show: Union[Show, str, int],
+        season: Union[Season, str, int],
+        episode: Union[Episode, int, str],
+        **kwargs
+    ) -> Season:
+        id = self._generic_get_id(show)
+        season = self._generic_get_id(season)
+        episode = self._generic_get_id(episode)
+        return self.run("get_season", **kwargs, id=id, season=season, episode=episode)
+
+    def get_comments(
+        self,
+        *,
+        show: Union[Show, str, int],
+        season: Union[Season, str, int],
+        episode: Union[Episode, int, str],
+        sort: str = "newest",
+        **kwargs
+    ) -> Iterable[Comment]:
+        id = self._generic_get_id(show)
+        season = self._generic_get_id(season)
+        episode = self._generic_get_id(episode)
+        return self.run(
+            "get_comments", **kwargs, sort=sort, id=id, season=season, episode=episode
+        )
+
+    def get_translations(
+        self,
+        *,
+        show: Union[Show, str, int],
+        season: Union[Season, str, int],
+        episode: Union[Episode, int, str],
+        sort: str = "newest",
+        **kwargs
+    ) -> Iterable[Comment]:
+        id = self._generic_get_id(show)
+        season = self._generic_get_id(season)
+        episode = self._generic_get_id(episode)
+        return self.run(
+            "get_comments", **kwargs, sort=sort, id=id, season=season, episode=episode
+        )
+
+    def get_lists(
+        self,
+        *,
+        show: Union[Show, str, int],
+        season: Union[Season, str, int],
+        episode: Union[Episode, int, str],
+        type: str = "personal",
+        sort: str = "popular",
+        **kwargs
+    ) -> Iterable[TraktList]:
+        id = self._generic_get_id(show)
+        season = self._generic_get_id(season)
+        episode = self._generic_get_id(episode)
+        return self.run(
+            "get_lists",
+            **kwargs,
+            type=type,
+            sort=sort,
+            id=id,
+            season=season,
+            episode=episode
+        )
+
+    def get_ratings(
+        self,
+        *,
+        show: Union[Show, str, int],
+        season: Union[Season, str, int],
+        episode: Union[Episode, int, str],
+        **kwargs
+    ) -> RatingsSummary:
+        id = self._generic_get_id(show)
+        season = self._generic_get_id(season)
+        episode = self._generic_get_id(episode)
+        return self.run("get_ratings", **kwargs, id=id, season=season, episode=episode)
+
+    def get_stats(
+        self,
+        *,
+        show: Union[Show, str, int],
+        season: Union[Season, str, int],
+        episode: Union[Episode, int, str],
+        **kwargs
+    ) -> SeasoneEpisodeStats:
+        id = self._generic_get_id(show)
+        season = self._generic_get_id(season)
+        episode = self._generic_get_id(episode)
+        return self.run("get_stats", **kwargs, id=id, season=season, episode=episode)
+
+    def get_users_watching(
+        self,
+        *,
+        show: Union[Show, str, int],
+        season: Union[Season, str, int],
+        episode: Union[Episode, int, str],
+        **kwargs
+    ) -> List[User]:
+        id = self._generic_get_id(show)
+        season = self._generic_get_id(season)
+        episode = self._generic_get_id(episode)
+        return self.run(
+            "get_users_watching", **kwargs, id=id, season=season, episode=episode
+        )