thesportsdb_client

24class AsyncSportsDB:
25    """The asynchronous TheSportsDB client.
26
27    .. code-block:: python
28
29        async with AsyncSportsDB() as db:                    # free key 123: v1 only
30            arsenal = await db.v1.lookup.team(133604)
31        async with AsyncSportsDB(api_key=key) as db:         # premium: v1 and v2
32            tv = await db.v2.tv.country("Canada")
33
34    One client is safe to share across tasks; its rate limiter, cache and de-duplication cover
35    every call made through it. Create one per key and reuse it.
36    """
37
38    def __init__(
39        self,
40        api_key: str = FREE_API_KEY,
41        *,
42        transport: AsyncTransport | None = None,
43        requests_per_minute: int | None = None,
44        max_retries: int = 2,
45        retry_backoff: float = 0.5,
46        retry_on_rate_limit: bool = True,
47        rate_limit_wait: float = 60.0,
48        cache: ResponseCache | None = None,
49        cache_policy: CachePolicy | None = None,
50        timeout: float = 30.0,
51        deduplicate_requests: bool = True,
52        request_listener: Callable[[RequestEvent], None] | None = None,
53        base_url: str = "https://www.thesportsdb.com",
54        user_agent: str = "thesportsdb-client-python",
55    ) -> None:
56        options: dict[str, Any] = dict(
57            api_key=api_key, requests_per_minute=requests_per_minute, max_retries=max_retries,
58            retry_backoff=retry_backoff, retry_on_rate_limit=retry_on_rate_limit, rate_limit_wait=rate_limit_wait,
59            cache=cache, timeout=timeout, deduplicate_requests=deduplicate_requests,
60            request_listener=request_listener, base_url=base_url, user_agent=user_agent,
61        )
62        if cache_policy is not None:
63            options["cache_policy"] = cache_policy
64        self.config = Config(**options)
65        self._owns_transport = transport is None
66        self._transport = transport or HttpxAsyncTransport(timeout=timeout)
67        requester = AsyncRequester(self.config, self._transport)
68        self.v1 = AsyncV1Api(requester)
69        """The v1 API (free and premium keys)."""
70        self.v2 = AsyncV2Api(requester)
71        """The v2 API (premium keys only)."""
72        self.helpers = AsyncHelpers(self)
73        """Common tasks in one call, using v2 or v1 depending on the key."""
74
75    async def is_premium_key(self) -> bool:
76        """Whether v2 accepts the key. One call (v2 ``lookup/league/4328``) unless it's a free key."""
77        if self.config.is_free_key:
78            return False
79        try:
80            await self.v2.lookup.league(4328)
81            return True
82        except InvalidApiKeyError:
83            return False
84
85    async def aclose(self) -> None:
86        """Closes the HTTP connections the client opened (not a transport you passed in)."""
87        if self._owns_transport:
88            await self._transport.aclose()
89
90    async def __aenter__(self) -> AsyncSportsDB:
91        return self
92
93    async def __aexit__(
94        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
95    ) -> None:
96        await self.aclose()

25class SportsDB:
26    """The blocking TheSportsDB client.
27
28    .. code-block:: python
29
30        with SportsDB() as db:                    # free key 123: v1 only
31            arsenal = db.v1.lookup.team(133604)
32        with SportsDB(api_key=key) as db:         # premium: v1 and v2
33            tv = db.v2.tv.country("Canada")
34
35    One client is safe to share across tasks; its rate limiter, cache and de-duplication cover
36    every call made through it. Create one per key and reuse it.
37    """
38
39    def __init__(
40        self,
41        api_key: str = FREE_API_KEY,
42        *,
43        transport: Transport | None = None,
44        requests_per_minute: int | None = None,
45        max_retries: int = 2,
46        retry_backoff: float = 0.5,
47        retry_on_rate_limit: bool = True,
48        rate_limit_wait: float = 60.0,
49        cache: ResponseCache | None = None,
50        cache_policy: CachePolicy | None = None,
51        timeout: float = 30.0,
52        deduplicate_requests: bool = True,
53        request_listener: Callable[[RequestEvent], None] | None = None,
54        base_url: str = "https://www.thesportsdb.com",
55        user_agent: str = "thesportsdb-client-python",
56    ) -> None:
57        options: dict[str, Any] = dict(
58            api_key=api_key, requests_per_minute=requests_per_minute, max_retries=max_retries,
59            retry_backoff=retry_backoff, retry_on_rate_limit=retry_on_rate_limit, rate_limit_wait=rate_limit_wait,
60            cache=cache, timeout=timeout, deduplicate_requests=deduplicate_requests,
61            request_listener=request_listener, base_url=base_url, user_agent=user_agent,
62        )
63        if cache_policy is not None:
64            options["cache_policy"] = cache_policy
65        self.config = Config(**options)
66        self._owns_transport = transport is None
67        self._transport = transport or HttpxTransport(timeout=timeout)
68        requester = Requester(self.config, self._transport)
69        self.v1 = V1Api(requester)
70        """The v1 API (free and premium keys)."""
71        self.v2 = V2Api(requester)
72        """The v2 API (premium keys only)."""
73        self.helpers = Helpers(self)
74        """Common tasks in one call, using v2 or v1 depending on the key."""
75
76    def is_premium_key(self) -> bool:
77        """Whether v2 accepts the key. One call (v2 ``lookup/league/4328``) unless it's a free key."""
78        if self.config.is_free_key:
79            return False
80        try:
81            self.v2.lookup.league(4328)
82            return True
83        except InvalidApiKeyError:
84            return False
85
86    def close(self) -> None:
87        """Closes the HTTP connections the client opened (not a transport you passed in)."""
88        if self._owns_transport:
89            self._transport.close()
90
91    def __enter__(self) -> SportsDB:
92        return self
93
94    def __exit__(
95        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
96    ) -> None:
97        self.close()

19@dataclass(frozen=True, kw_only=True)
20class Config:
21    api_key: str = FREE_API_KEY
22    requests_per_minute: int | None = None
23    """Client-side limit shared by v1 and v2. None: 30 for a free key, 100 otherwise. 0 turns it off."""
24    max_retries: int = 2
25    """Retries for network errors and HTTP 5xx, with exponential backoff."""
26    retry_backoff: float = 0.5
27    """First backoff, in seconds; doubles on every retry."""
28    retry_on_rate_limit: bool = True
29    """On HTTP 429, wait (Retry-After, or rate_limit_wait) and retry once."""
30    rate_limit_wait: float = 60.0
31    cache: ResponseCache | None = None
32    cache_policy: CachePolicy = field(default_factory=CachePolicy)
33    timeout: float = 30.0
34    """Seconds before a request gives up (connect and read)."""
35    deduplicate_requests: bool = True
36    """Identical calls made at the same time share one HTTP request."""
37    request_listener: Callable[[RequestEvent], None] | None = None
38    """Called once per call, after it finishes. Exceptions it raises are ignored."""
39    base_url: str = "https://www.thesportsdb.com"
40    user_agent: str = "thesportsdb-client-python"
41
42    @property
43    def is_free_key(self) -> bool:
44        return self.api_key in FREE_API_KEYS
45
46    @property
47    def effective_requests_per_minute(self) -> int:
48        if self.requests_per_minute is not None:
49            return self.requests_per_minute
50        return 30 if self.is_free_key else 100

26class AsyncTransport(Protocol):
27    """Performs GET requests. Raise ``OSError`` (e.g. ``ConnectionError``) for network failures;
28    return every HTTP status, including 4xx and 5xx, as a ``Response``."""
29
30    async def get(self, url: str, headers: Mapping[str, str]) -> Response: ...
31
32    async def aclose(self) -> None: ...

27class Transport(Protocol):
28    """Performs GET requests. Raise ``OSError`` (e.g. ``ConnectionError``) for network failures;
29    return every HTTP status, including 4xx and 5xx, as a ``Response``."""
30
31    def get(self, url: str, headers: Mapping[str, str]) -> Response: ...
32
33    def close(self) -> None: ...

35class HttpxAsyncTransport:
36    """The default transport, on httpx. Pass your own ``httpx.AsyncClient`` to share connections."""
37
38    def __init__(self, client: httpx.AsyncClient | None = None, timeout: float = 30.0) -> None:
39        self._owned = client is None
40        self._client = client or httpx.AsyncClient(timeout=timeout)
41
42    async def get(self, url: str, headers: Mapping[str, str]) -> Response:
43        try:
44            r = await self._client.get(url, headers=dict(headers))
45        except httpx.TransportError as e:
46            raise ConnectionError(str(e) or type(e).__name__) from e
47        return Response(r.status_code, r.text, dict(r.headers))
48
49    async def aclose(self) -> None:
50        if self._owned:
51            await self._client.aclose()

36class HttpxTransport:
37    """The default transport, on httpx. Pass your own ``httpx.Client`` to share connections."""
38
39    def __init__(self, client: httpx.Client | None = None, timeout: float = 30.0) -> None:
40        self._owned = client is None
41        self._client = client or httpx.Client(timeout=timeout)
42
43    def get(self, url: str, headers: Mapping[str, str]) -> Response:
44        try:
45            r = self._client.get(url, headers=dict(headers))
46        except httpx.TransportError as e:
47            raise ConnectionError(str(e) or type(e).__name__) from e
48        return Response(r.status_code, r.text, dict(r.headers))
49
50    def close(self) -> None:
51        if self._owned:
52            self._client.close()

16@dataclass(frozen=True)
17class Response:
18    status: int
19    body: str
20    headers: Mapping[str, str] = field(default_factory=dict)
21
22    def header(self, name: str) -> str | None:
23        return next((v for k, v in self.headers.items() if k.lower() == name.lower()), None)

24@dataclass(frozen=True)
25class CachePolicy:
26    """Time-to-live in seconds for each Freshness. Zero or less means don't cache."""
27
28    static: float = 7 * 24 * 3600
29    slow: float = 24 * 3600
30    medium: float = 3600
31    live: float = 0
32
33    def ttl(self, freshness: Freshness) -> float:
34        return {Freshness.STATIC: self.static, Freshness.SLOW: self.slow,
35                Freshness.MEDIUM: self.medium, Freshness.LIVE: self.live}[freshness]

15class Freshness(Enum):
16    """How quickly an endpoint's data changes. Every endpoint is tagged with one."""
17
18    STATIC = "static"  # sports, countries, the league list
19    SLOW = "slow"  # teams, players, venues, seasons
20    MEDIUM = "medium"  # schedules, standings, TV listings, highlights
21    LIVE = "live"  # live scores

46class InMemoryResponseCache:
47    """A bounded, thread-safe, in-memory LRU cache with per-entry expiry."""
48
49    def __init__(self, max_entries: int = 1000, clock: Callable[[], float] = time.monotonic) -> None:
50        self._max = max_entries
51        self._clock = clock
52        self._lock = threading.Lock()
53        self._entries: OrderedDict[str, tuple[str, float]] = OrderedDict()
54
55    def get(self, key: str) -> str | None:
56        with self._lock:
57            entry = self._entries.get(key)
58            if entry is None:
59                return None
60            body, expires = entry
61            if expires <= self._clock():
62                del self._entries[key]
63                return None
64            self._entries.move_to_end(key)
65            return body
66
67    def put(self, key: str, body: str, ttl: float) -> None:
68        if ttl <= 0:
69            return
70        with self._lock:
71            self._entries[key] = (body, self._clock() + ttl)
72            self._entries.move_to_end(key)
73            while len(self._entries) > self._max:
74                self._entries.popitem(last=False)
75
76    def clear(self) -> None:
77        with self._lock:
78            self._entries.clear()
79
80    def __len__(self) -> int:
81        with self._lock:
82            return len(self._entries)

38class ResponseCache(Protocol):
39    """Stores raw response bodies. Keys never contain an API key. Implement it for Redis, disk, etc."""
40
41    def get(self, key: str) -> str | None: ...
42
43    def put(self, key: str, body: str, ttl: float) -> None: ...

 9@dataclass(frozen=True)
10class RequestEvent:
11    """One finished API call, passed to ``request_listener``."""
12
13    url: str
14    """The URL with any v1 key replaced by ``***``. Safe to log."""
15    status: int | None
16    """The last HTTP status; None if no response arrived or the result came from the cache."""
17    attempts: int
18    """HTTP requests made, counting retries; 0 when served by the cache or another caller's request."""
19    from_cache: bool
20    shared: bool
21    """True when an identical call already in flight supplied the result."""
22    duration: float
23    """Seconds for the whole call, including rate-limit waits and retries."""
24    error: BaseException | None

11class SportsDBError(Exception):
12    """Base class for every error this library raises."""

15class InvalidApiKeyError(SportsDBError):
16    """The API rejected the key (HTTP 400 ``Invalid Premium API key``). Only ``123``, ``3`` and paid keys work."""

19class PremiumRequiredError(SportsDBError):
20    """A v2 endpoint was called with a free key. v2 accepts premium keys only. Raised before any request."""

23class RateLimitError(SportsDBError):
24    """HTTP 429 after the retry was used up or disabled. ``retry_after`` is the server's wait in seconds, if given."""
25
26    def __init__(self, message: str, retry_after: float | None) -> None:
27        super().__init__(message)
28        self.retry_after = retry_after

31class HTTPStatusError(SportsDBError):
32    """Any other non-2xx HTTP response, after retries for 5xx."""
33
34    def __init__(self, message: str, status: int, body_snippet: str) -> None:
35        super().__init__(message)
36        self.status = status
37        self.body_snippet = body_snippet

40class ResponseParseError(SportsDBError):
41    """The body was not a TheSportsDB envelope (e.g. an HTML error page)."""

44class ApiMessageError(SportsDBError):
45    """The API answered with a message instead of data.
46
47    Either an unrecognised ``{"Message": ...}`` body, or a rejected parameter, which v1
48    reports as text where the records belong: ``{"seasons": "Invalid League ID passed"}``.
49    """
50
51    def __init__(self, message: str, api_message: str) -> None:
52        super().__init__(message)
53        self.api_message = api_message

56class NetworkError(SportsDBError):
57    """No HTTP response arrived (DNS, connection, timeout), after retries."""

30@dataclass(frozen=True, kw_only=True, eq=False, repr=False)
31class ApiRecord:
32    """Base class of every record ([Team], [Event], ...)."""
33
34    raw: Mapping[str, str | None] = field(default_factory=lambda: MappingProxyType({}))
35    """Every field as the API sent it (blank strings as None). Use it for unmodelled fields: ``team.raw["strKeywords"]``."""
36
37    _summary: ClassVar[tuple[str, ...]] = ()
38
39    def __eq__(self, other: object) -> bool:
40        return type(self) is type(other) and isinstance(other, ApiRecord) and dict(self.raw) == dict(other.raw)
41
42    def __hash__(self) -> int:
43        return hash((type(self), frozenset(self.raw.items())))
44
45    def __repr__(self) -> str:
46        parts = ", ".join(f"{name}={getattr(self, name)!r}" for name in self._summary)
47        return f"{type(self).__name__}({parts})"
48
49    @classmethod
50    def _from(cls: type[R], raw: Mapping[str, str | None]) -> R:
51        values = cls._read(Rec(raw))
52        return cls(raw=MappingProxyType(dict(raw)), **values)
53
54    @classmethod
55    def _read(cls, r: Rec) -> dict[str, Any]:
56        raise NotImplementedError