tvdb_api_client 0.8.0__py3-none-any.whl

tvdb_api_client/__init__.py

@@ -0,0 +1,3 @@
+from tvdb_api_client.client import TheTVDBClient
+
+__all__ = ["TheTVDBClient"]

tvdb_api_client/__version__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("tvdb_api_client")

tvdb_api_client/client.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import json
+from base64 import urlsafe_b64decode
+from http import HTTPStatus
+from typing import TYPE_CHECKING, cast
+
+import requests
+from dj_settings import get_setting
+from pyutilkit.date_utils import now
+
+from tvdb_api_client.constants import BASE_API_URL
+from tvdb_api_client.models import Episode, Series
+
+if TYPE_CHECKING:
+    from tvdb_api_client.lib.type_defs import (
+        AbstractCache,
+        CleanedEpisodeData,
+        FullEpisodeRawData,
+        SeriesRawData,
+    )
+
+
+class _Cache(dict):  # type: ignore[type-arg]
+    def set(self, key: str, value: object) -> None:
+        self[key] = value
+
+
+class TheTVDBClient:
+    __slots__ = ("_auth_data", "_cache")
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        cache: AbstractCache | None = None,
+        pin: str | None = None,
+    ) -> None:
+        self._cache = cache or _Cache()
+        self._auth_data = self._get_auth_data(api_key, pin)
+
+    @staticmethod
+    def _get_auth_data(
+        api_key: str | None = None, pin: str | None = None
+    ) -> dict[str, str]:
+        filename = "the_tvdb.yaml"
+        sections = ["client"]
+
+        if api_key is None:
+            api_key = get_setting(
+                "api_key",
+                filename=filename,
+                sections=sections,
+                use_env="TVDB_API_KEY_V4",
+            )
+        if api_key is None:
+            msg = "API Key is required."  # type: ignore[unreachable]
+            raise ValueError(msg)
+        output = {"apikey": api_key}
+
+        if pin is None:
+            pin = get_setting(
+                "pin", filename=filename, sections=sections, use_env="TVDB_PIN_V4"
+            )
+        if pin is not None:
+            output["pin"] = pin
+
+        return output
+
+    @staticmethod
+    def _get_expiry(token: str | None) -> int:
+        if token is None:
+            return 0
+
+        _, payload, *_ = token.split(".")
+        padding = "=" * (4 - len(payload) % 4)
+        data = json.loads(urlsafe_b64decode(payload + padding).decode())
+        return cast("int", data["exp"])
+
+    def _generate_token(self) -> str:
+        login_endpoint = "login"
+        url = BASE_API_URL.join(login_endpoint)
+        headers = {"Content-Type": "application/json", "accept": "application/json"}
+        response = requests.post(
+            url.string,
+            headers=headers,
+            data=json.dumps(self._auth_data),
+            timeout=(60, 120),
+        )
+        if response.status_code == HTTPStatus.UNAUTHORIZED:
+            msg = "Invalid credentials."
+            raise ConnectionRefusedError(msg)
+
+        if response.status_code != HTTPStatus.OK:
+            msg = "Unexpected Response."
+            raise ConnectionError(msg)
+
+        return cast("str", response.json()["data"]["token"])
+
+    def get(self, path: str) -> dict[str, object]:
+        url = BASE_API_URL.join(path)
+        cache_token_key = "tvdb_v4_token"  # noqa: S105
+        token = cast("str | None", self._cache.get(cache_token_key))
+        if self._get_expiry(token) < now().timestamp() + 60:
+            token = self._generate_token()
+            self._cache.set(cache_token_key, token)
+
+        headers = {"accept": "application/json", "Authorization": f"Bearer {token}"}
+        response = requests.get(url.string, headers=headers, timeout=(60, 120))
+
+        if response.status_code == HTTPStatus.OK:
+            return cast("dict[str, object]", response.json())
+
+        if response.status_code in {HTTPStatus.BAD_REQUEST, HTTPStatus.NOT_FOUND}:
+            msg = "There are no data for this term."
+            raise LookupError(msg)
+
+        if response.status_code == HTTPStatus.UNAUTHORIZED:
+            msg = "Invalid credentials."
+            raise ConnectionRefusedError(msg)
+
+        msg = "Unexpected Response."
+        raise ConnectionError(msg)
+
+    def get_raw_series_by_id(
+        self, tvdb_id: int, *, refresh_cache: bool = False
+    ) -> SeriesRawData:
+        """Get the series info by its tvdb ib as returned by the TVDB."""
+        key = f"get_series_by_id::tvdb_id:{tvdb_id}"
+        data = cast("SeriesRawData | None", self._cache.get(key))
+        if data is None or refresh_cache:
+            path = f"series/{tvdb_id}"
+            data = cast("SeriesRawData", self.get(path)["data"])
+            self._cache.set(key, data)
+        return data
+
+    def get_series_by_id(self, tvdb_id: int, *, refresh_cache: bool = False) -> Series:
+        raw_data = self.get_raw_series_by_id(tvdb_id, refresh_cache=refresh_cache)
+        return Series.from_raw_data(raw_data)
+
+    def get_raw_episodes_by_series(
+        self,
+        tvdb_id: int,
+        season_type: str = "default",
+        page: int = 0,
+        *,
+        refresh_cache: bool = False,
+    ) -> CleanedEpisodeData:
+        """Get all the episodes for a TV series as returned by the TVDB."""
+        key = f"get_episodes_by_series::tvdb_id:{tvdb_id}:{page}"
+        data = cast("CleanedEpisodeData | None", self._cache.get(key))
+        if data is None or refresh_cache:
+            path = f"series/{tvdb_id}/episodes/{season_type}?page={page}"
+            all_data = cast("FullEpisodeRawData", self.get(path))
+            episodes = all_data["data"]["episodes"]
+            data = {
+                "episodes": episodes,
+                "has_next_page": all_data["links"]["next"] is not None,
+            }
+            self._cache.set(key, data)
+        # Redundant cast to satisfy mypy & ty compatibility
+        return cast("CleanedEpisodeData", data)  # type: ignore[redundant-cast]
+
+    def get_episodes_by_series(
+        self, tvdb_id: int, season_type: str = "default", *, refresh_cache: bool = False
+    ) -> list[Episode]:
+        """Get all the episodes for a TV series."""
+        next_page = True
+        page = 0
+        data = []
+        while next_page:
+            raw_data = self.get_raw_episodes_by_series(
+                tvdb_id, season_type, refresh_cache=refresh_cache, page=page
+            )
+            data.extend(raw_data["episodes"])
+            next_page = raw_data["has_next_page"]
+            page += 1
+        return [Episode.from_raw_data(episode_info) for episode_info in data]

tvdb_api_client/constants.py

@@ -0,0 +1,5 @@
+from pathurl import URL
+
+BASE_API_URL = URL("https://api4.thetvdb.com/v4/")
+DATE_FORMAT = "%Y-%m-%d"
+DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S"

tvdb_api_client/lib/type_defs.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, TypedDict
+
+
+class AbstractCache(Protocol):
+    def set(self, key: str, value: object) -> None: ...
+    def get(self, key: str) -> Any: ...  # type: ignore[explicit-any]  # noqa: ANN401
+
+
+class AliasRawData(TypedDict):
+    language: str
+    name: str
+
+
+class StatusRawData(TypedDict):
+    id: int
+    name: str
+    recordType: str
+    keepUpdated: bool
+
+
+class SeriesRawData(TypedDict):
+    id: int
+    name: str
+    slug: str
+    image: str | None
+    nameTranslations: list[str]
+    overviewTranslations: list[str]
+    aliases: list[AliasRawData]
+    firstAired: str
+    lastAired: str
+    nextAired: str
+    score: float
+    status: StatusRawData
+    originalCountry: str
+    originalLanguage: str
+    defaultSeasonType: int
+    isOrderRandomized: bool
+    lastUpdated: str
+    averageRuntime: int
+    overview: str
+    episodes: EpisodeRawData | None
+    year: str
+
+
+class EpisodeRawData(TypedDict):
+    id: int
+    seriesId: int
+    name: str
+    aired: str
+    runtime: int
+    nameTranslations: list[str]
+    overview: str
+    overviewTranslations: list[str]
+    image: str
+    imageType: int
+    isMovie: int
+    number: int
+    seasonNumber: int
+    lastUpdated: str
+    finaleType: str
+    seasons: int | None
+    absoluteNumber: int
+    year: str
+
+
+class LinksRawData(TypedDict):
+    next: str | None
+    prev: str | None
+
+
+class _FullRawData(TypedDict):
+    series: SeriesRawData
+    episodes: list[EpisodeRawData]
+
+
+class CleanedEpisodeData(TypedDict):
+    episodes: list[EpisodeRawData]
+    has_next_page: bool
+
+
+class FullEpisodeRawData(TypedDict):
+    data: _FullRawData
+    links: LinksRawData

tvdb_api_client/models.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from pathurl import URL
+
+from tvdb_api_client.utils import get_tvdb_date, get_tvdb_datetime
+
+if TYPE_CHECKING:
+    from datetime import date, datetime
+
+    from tvdb_api_client.lib.type_defs import (
+        AliasRawData,
+        EpisodeRawData,
+        SeriesRawData,
+        StatusRawData,
+    )
+
+
+@dataclass
+class Alias:
+    language: str
+    name: str
+
+    @classmethod
+    def from_raw_data(cls, raw_data: AliasRawData) -> Alias:
+        return cls(language=raw_data["language"], name=raw_data["name"])
+
+
+@dataclass
+class Status:
+    id: int
+    name: str
+    record_type: str
+    keep_updated: bool
+
+    @classmethod
+    def from_raw_data(cls, raw_data: StatusRawData) -> Status:
+        return cls(
+            id=raw_data["id"],
+            name=raw_data["name"],
+            record_type=raw_data["recordType"],
+            keep_updated=raw_data["keepUpdated"],
+        )
+
+
+@dataclass
+class Series:
+    id: int
+    name: str
+    slug: str
+    image: URL | None
+    name_translations: list[str]
+    overview_translations: list[str]
+    aliases: list[Alias]
+    first_aired: date | None
+    last_aired: date | None
+    next_aired: date | None
+    score: float
+    status: Status
+    original_country: str
+    original_language: str
+    default_season_type: int
+    is_order_randomized: bool
+    last_updated: datetime | None
+    average_runtime: int
+    overview: str
+
+    @classmethod
+    def from_raw_data(cls, raw_data: SeriesRawData) -> Series:
+        image_url = raw_data["image"]
+        return cls(
+            id=raw_data["id"],
+            name=raw_data["name"],
+            slug=raw_data["slug"],
+            image=URL(image_url) if image_url else None,
+            name_translations=raw_data["nameTranslations"],
+            overview_translations=raw_data["overviewTranslations"],
+            aliases=[Alias.from_raw_data(alias) for alias in raw_data["aliases"]],
+            first_aired=get_tvdb_date(raw_data["firstAired"]),
+            last_aired=get_tvdb_date(raw_data["lastAired"]),
+            next_aired=get_tvdb_date(raw_data["nextAired"]),
+            score=raw_data["score"],
+            status=Status.from_raw_data(raw_data["status"]),
+            original_country=raw_data["originalCountry"],
+            original_language=raw_data["originalLanguage"],
+            default_season_type=raw_data["defaultSeasonType"],
+            is_order_randomized=raw_data["isOrderRandomized"],
+            last_updated=get_tvdb_datetime(raw_data["lastUpdated"]),
+            average_runtime=raw_data["averageRuntime"],
+            overview=raw_data["overview"],
+        )
+
+
+@dataclass
+class Episode:
+    id: int
+    series_id: int
+    name: str
+    aired: date | None
+    runtime: int
+    name_translations: list[str]
+    overview: str
+    overview_translations: list[str]
+    image: URL | None
+    image_type: int
+    is_movie: int
+    number: int
+    season_number: int
+    last_updated: datetime | None
+    finale_type: str
+
+    @classmethod
+    def from_raw_data(cls, raw_data: EpisodeRawData) -> Episode:
+        image_url = raw_data["image"]
+        return cls(
+            id=raw_data["id"],
+            series_id=raw_data["seriesId"],
+            name=raw_data["name"],
+            aired=get_tvdb_date(raw_data["aired"]),
+            runtime=raw_data["runtime"],
+            name_translations=raw_data["nameTranslations"],
+            overview=raw_data["overview"],
+            overview_translations=raw_data["overviewTranslations"],
+            image=URL(image_url) if image_url else None,
+            image_type=raw_data["imageType"],
+            is_movie=raw_data["isMovie"],
+            number=raw_data["number"],
+            season_number=raw_data["seasonNumber"],
+            last_updated=get_tvdb_datetime(raw_data["lastUpdated"]),
+            finale_type=raw_data["finaleType"],
+        )

tvdb_api_client/utils.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+
+from pyutilkit.date_utils import add_timezone
+
+from tvdb_api_client.constants import DATE_FORMAT, DATETIME_FORMAT
+
+
+def get_tvdb_date(date_string: str) -> date | None:
+    if not date_string:
+        return None
+
+    naive_datetime = datetime.strptime(date_string, DATE_FORMAT)  # noqa: DTZ007
+    return add_timezone(naive_datetime).date()
+
+
+def get_tvdb_datetime(datetime_string: str) -> datetime | None:
+    if not datetime_string:
+        return None
+
+    naive_datetime = datetime.strptime(datetime_string, DATETIME_FORMAT)  # noqa: DTZ007
+    return add_timezone(naive_datetime)

tvdb_api_client-0.8.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.3
+Name: tvdb_api_client
+Version: 0.8.0
+Summary: A python client for TVDB rest API
+Keywords: tvdb,imdb,tv series
+Author: Stephanos Kuma
+Author-email: Stephanos Kuma <stephanos@kuma.ai>
+License: BSD-3-Clause
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Intended Audience :: Developers
+Requires-Dist: dj-settings~=8.0
+Requires-Dist: pathurl~=0.8
+Requires-Dist: pyutilkit~=0.11
+Requires-Dist: requests>=2.34.2,<3.0
+Requires-Python: >=3.10
+Project-URL: homepage, https://tvdb-api-client.readthedocs.io/en/stable/
+Project-URL: repository, https://github.com/spapanik/tvdb_api_client
+Project-URL: documentation, https://tvdb-api-client.readthedocs.io/en/stable/
+Description-Content-Type: text/markdown
+
+# tvdb_api_client: an unofficial API for the TVDB
+
+[![build][build_badge]][build_url]
+[![lint][lint_badge]][lint_url]
+[![tests][tests_badge]][tests_url]
+[![license][licence_badge]][licence_url]
+[![codecov][codecov_badge]][codecov_url]
+[![readthedocs][readthedocs_badge]][readthedocs_url]
+[![pypi][pypi_badge]][pypi_url]
+[![downloads][pepy_badge]][pepy_url]
+[![build automation: yam][yam_badge]][yam_url]
+[![Lint: ruff][ruff_badge]][ruff_url]
+
+`tvdb_api_client` is an unofficial API for the TVDB.
+
+## In a nutshell
+
+### Installation
+
+[uv] is an extremely fast Python package installer.
+You can use it to install `tvdb_api_client` and try it out:
+
+```console
+$ uv pip install tvdb_api_client
+```
+
+### Usage
+
+Initialise the client and fetch data:
+
+```python
+from tvdb_api_client import TheTVDBClient
+
+client = TheTVDBClient(api_key="your-api-key")
+
+# Get a TV series by its TVDB id
+series = client.get_series_by_id(81189)  # Breaking Bad
+
+# Get all episodes for a TV series
+episodes = client.get_episodes_by_series(81189)
+```
+
+Once the client has been initialised, you can use it to:
+
+- get a TV series by its TVDB id
+- get all episodes for a TV series by its TVDB id
+- access raw API responses for custom processing
+
+## Links
+
+- [Documentation]
+- [Changelog]
+
+[build_badge]: https://github.com/spapanik/tvdb_api_client/actions/workflows/build.yml/badge.svg
+[build_url]: https://github.com/spapanik/tvdb_api_client/actions/workflows/build.yml
+[lint_badge]: https://github.com/spapanik/tvdb_api_client/actions/workflows/lint.yml/badge.svg
+[lint_url]: https://github.com/spapanik/tvdb_api_client/actions/workflows/lint.yml
+[tests_badge]: https://github.com/spapanik/tvdb_api_client/actions/workflows/tests.yml/badge.svg
+[tests_url]: https://github.com/spapanik/tvdb_api_client/actions/workflows/tests.yml
+[licence_badge]: https://img.shields.io/pypi/l/tvdb-api-client
+[licence_url]: https://tvdb-api-client.readthedocs.io/en/stable/LICENSE/
+[codecov_badge]: https://codecov.io/github/spapanik/tvdb-api-client/graph/badge.svg?token=Q20F84BW72
+[codecov_url]: https://codecov.io/github/spapanik/tvdb-api-client
+[readthedocs_badge]: https://readthedocs.org/projects/tvdb-api-client/badge/?version=latest
+[readthedocs_url]: https://tvdb-api-client.readthedocs.io/en/latest/
+[pypi_badge]: https://img.shields.io/pypi/v/tvdb-api-client
+[pypi_url]: https://pypi.org/project/tvdb-api-client
+[pepy_badge]: https://pepy.tech/badge/tvdb-api-client
+[pepy_url]: https://pepy.tech/project/tvdb-api-client
+[yam_badge]: https://img.shields.io/badge/build%20automation-yamk-success
+[yam_url]: https://github.com/spapanik/yamk
+[ruff_badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json
+[ruff_url]: https://github.com/charliermarsh/ruff
+[uv]: https://github.com/astral-sh/uv
+[Documentation]: https://tvdb-api-client.readthedocs.io/en/stable/
+[Changelog]: https://tvdb-api-client.readthedocs.io/en/stable/CHANGELOG/

tvdb_api_client-0.8.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+tvdb_api_client/__init__.py,sha256=DQIblb3gZlfWeia4EGO0RsiNQT4lj6CHRdZlFWS_7oc,78
+tvdb_api_client/__version__.py,sha256=P2pH0fxf71o-XEB1g9i3zVGtCdoGTdGf74OSPWyI2S4,81
+tvdb_api_client/client.py,sha256=c_UBRyiI6qDD90F3YabVZTwnexq2cMKK-ZYtTaULltQ,6201
+tvdb_api_client/constants.py,sha256=XgutJ_iA9uAyju6gUU2kFDYuEQsM1IQLndv5qhcUsbk,139
+tvdb_api_client/lib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tvdb_api_client/lib/type_defs.py,sha256=L4bYpkzRdS91o7FypiWKPXHz2LcKmp66Rx-PVNFisGU,1680
+tvdb_api_client/models.py,sha256=SQf6AiXYUf7Q7krEX0a1Z-boN2GEukgSYgNSE8fH4Dw,3924
+tvdb_api_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tvdb_api_client/utils.py,sha256=I2epHrpWnZK-v2SmYHzHSkk_Zxn2GRC4EcaEaJ8Van8,658
+tvdb_api_client-0.8.0.dist-info/WHEEL,sha256=V5-3dKee3Zs8C4JP6swr6zdqriLsOpItBEQxe6_oWpY,81
+tvdb_api_client-0.8.0.dist-info/METADATA,sha256=1Hj_9z8cKZ-zTtQQmBbkyceT-M4qiAC3-LysmbSN_MM,3789
+tvdb_api_client-0.8.0.dist-info/RECORD,,

tvdb_api_client-0.8.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.18
+Root-Is-Purelib: true
+Tag: py3-none-any