universal-game-api 0.1.0__py3-none-any.whl

gameapi/__init__.py

@@ -0,0 +1,48 @@
+"""Universal Game API — a unified, developer-friendly interface for public
+game data and statistics.
+
+Quick start:
+
+    >>> from gameapi import GameAPI
+    >>> api = GameAPI()
+    >>> player = api.player(game="chess_com", identifier="hikaru")
+    >>> print(player.name, player.stats)
+
+See the README for the full guide, supported games, and async usage.
+"""
+
+from .async_client import AsyncGameAPI
+from .client import GameAPI
+from .exceptions import (
+    APIUnavailableError,
+    AuthenticationError,
+    GameAPIError,
+    GameNotSupportedError,
+    InvalidResponseError,
+    PlayerNotFoundError,
+    RateLimitError,
+)
+from .games.registry import supported_games
+from .models import Leaderboard, LeaderboardEntry, Match, Player, PlayerStats, Rank
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "GameAPI",
+    "AsyncGameAPI",
+    "Player",
+    "PlayerStats",
+    "Rank",
+    "Match",
+    "Leaderboard",
+    "LeaderboardEntry",
+    "GameAPIError",
+    "GameNotSupportedError",
+    "PlayerNotFoundError",
+    "AuthenticationError",
+    "RateLimitError",
+    "APIUnavailableError",
+    "InvalidResponseError",
+    "supported_games",
+    "__version__",
+]

gameapi/_base.py

@@ -0,0 +1,59 @@
+"""Shared setup/resolution logic for GameAPI and AsyncGameAPI."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from .cache import MemoryCache
+from .exceptions import GameNotSupportedError
+from .games.base import GameIntegration
+from .games.registry import GAME_REGISTRY, supported_games
+from .http import HTTPClient
+
+_ENV_API_KEY = "GAMEAPI_API_KEY"
+
+
+class _BaseGameAPI:
+    """Common configuration and integration resolution for both clients."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        cache: bool = False,
+        cache_ttl: float = 60.0,
+        timeout: float = 10.0,
+        max_retries: int = 2,
+    ) -> None:
+        self.api_key = api_key or os.environ.get(_ENV_API_KEY)
+        self.cache_enabled = cache
+        self.cache_ttl = cache_ttl
+
+        self._http = HTTPClient(timeout=timeout, max_retries=max_retries)
+        self._cache = MemoryCache(default_ttl=cache_ttl) if cache else None
+        self._integrations: dict = {}
+
+    def _resolve(self, game: str) -> GameIntegration:
+        integration = self._integrations.get(game)
+        if integration is not None:
+            return integration
+
+        integration_cls = GAME_REGISTRY.get(game)
+        if integration_cls is None:
+            raise GameNotSupportedError(game, supported=supported_games())
+
+        integration = integration_cls(self._http, api_key=self.api_key, cache=self._cache)
+        self._integrations[game] = integration
+        return integration
+
+    def game_info(self, game: str) -> dict:
+        """Return metadata about a registered integration."""
+        integration_cls = GAME_REGISTRY.get(game)
+        if integration_cls is None:
+            raise GameNotSupportedError(game, supported=supported_games())
+        return {
+            "slug": integration_cls.slug,
+            "requires_api_key": integration_cls.requires_api_key,
+            "source_name": integration_cls.source_name,
+            "source_url": integration_cls.source_url,
+        }

gameapi/async_client.py

@@ -0,0 +1,40 @@
+"""The asynchronous public entry point for gameapi."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from ._base import _BaseGameAPI
+from .games.registry import supported_games
+from .models import Leaderboard, Match, Player
+
+
+class AsyncGameAPI(_BaseGameAPI):
+    """Asynchronous client for accessing unified public game data."""
+
+    async def player(self, game: str, identifier: str) -> Player:
+        return await self._resolve(game).get_player_async(identifier)
+
+    async def matches(self, game: str, identifier: str, limit: int = 20) -> List[Match]:
+        return await self._resolve(game).get_matches_async(identifier, limit=limit)
+
+    async def leaderboard(self, game: str, region: Optional[str] = None) -> Leaderboard:
+        return await self._resolve(game).get_leaderboard_async(region=region)
+
+    async def compare_players(self, game: str, identifiers: List[str]) -> List[Player]:
+        """Fetch multiple players concurrently."""
+        integration = self._resolve(game)
+        return [await integration.get_player_async(ident) for ident in identifiers]
+
+    async def aclose(self) -> None:
+        """Release the underlying HTTP connection pool."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncGameAPI":
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return f"AsyncGameAPI(games={supported_games()}, cache={self.cache_enabled})"

gameapi/cache/__init__.py

@@ -0,0 +1,5 @@
+"""Caching layer for gameapi."""
+
+from .memory import MemoryCache
+
+__all__ = ["MemoryCache"]

gameapi/cache/memory.py

@@ -0,0 +1,40 @@
+"""A minimal, dependency-free in-memory cache with per-entry TTL expiry."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional, Tuple
+
+
+class MemoryCache:
+    """A simple thread-unsafe, process-local TTL cache."""
+
+    def __init__(self, default_ttl: float = 60.0) -> None:
+        self.default_ttl = default_ttl
+        self._store: Dict[str, Tuple[float, Any]] = {}
+
+    def get(self, key: str) -> Optional[Any]:
+        """Return the cached value for ``key``, or ``None`` if missing/expired."""
+        entry = self._store.get(key)
+        if entry is None:
+            return None
+        expires_at, value = entry
+        if expires_at < time.monotonic():
+            del self._store[key]
+            return None
+        return value
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        """Store ``value`` under ``key`` for ``ttl`` seconds."""
+        effective_ttl = self.default_ttl if ttl is None else ttl
+        self._store[key] = (time.monotonic() + effective_ttl, value)
+
+    def clear(self) -> None:
+        """Remove all cached entries."""
+        self._store.clear()
+
+    def __contains__(self, key: str) -> bool:
+        return self.get(key) is not None
+
+    def __len__(self) -> int:
+        return len(self._store)

gameapi/client.py

@@ -0,0 +1,43 @@
+"""The synchronous public entry point for gameapi."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from ._base import _BaseGameAPI
+from .games.registry import supported_games
+from .models import Leaderboard, Match, Player
+
+
+class GameAPI(_BaseGameAPI):
+    """Synchronous client for accessing unified public game data."""
+
+    def player(self, game: str, identifier: str) -> Player:
+        """Fetch a unified player profile."""
+        return self._resolve(game).get_player(identifier)
+
+    def matches(self, game: str, identifier: str, limit: int = 20) -> List[Match]:
+        """Fetch a player's recent matches, most recent first."""
+        return self._resolve(game).get_matches(identifier, limit=limit)
+
+    def leaderboard(self, game: str, region: Optional[str] = None) -> Leaderboard:
+        """Fetch a game's leaderboard."""
+        return self._resolve(game).get_leaderboard(region=region)
+
+    def compare_players(self, game: str, identifiers: List[str]) -> List[Player]:
+        """Fetch multiple players at once (synchronous)."""
+        integration = self._resolve(game)
+        return [integration.get_player(ident) for ident in identifiers]
+
+    def close(self) -> None:
+        """Release the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> "GameAPI":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"GameAPI(games={supported_games()}, cache={self.cache_enabled})"

gameapi/exceptions.py

@@ -0,0 +1,95 @@
+"""Custom exception hierarchy for Universal Game API.
+
+All exceptions raised by the public API inherit from :class:`GameAPIError`,
+so callers can either catch broad failures or narrow in on a specific
+failure mode.
+
+Example
+-------
+>>> try:
+...     player = api.player("chess_com", "does-not-exist-hopefully")
+... except PlayerNotFoundError:
+...     print("Player doesn't exist.")
+... except GameAPIError as exc:
+...     print(f"Something else went wrong: {exc}")
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class GameAPIError(Exception):
+    """Base class for all errors raised by gameapi.
+
+    Attributes:
+        message: Human-readable description of the failure.
+    """
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(message)
+
+
+class GameNotSupportedError(GameAPIError):
+    """Raised when a requested game has no registered integration."""
+
+    def __init__(self, game: str, supported: Optional[list] = None) -> None:
+        self.game = game
+        self.supported = supported or []
+        supported_str = ", ".join(sorted(self.supported)) if self.supported else "none registered"
+        super().__init__(
+            f"Game '{game}' is not supported. Currently supported games: {supported_str}."
+        )
+
+
+class PlayerNotFoundError(GameAPIError):
+    """Raised when a game's API reports that a player/identifier does not exist."""
+
+    def __init__(self, game: str, identifier: str) -> None:
+        self.game = game
+        self.identifier = identifier
+        super().__init__(f"Player '{identifier}' was not found for game '{game}'.")
+
+
+class AuthenticationError(GameAPIError):
+    """Raised when a request fails due to missing or invalid credentials."""
+
+    def __init__(self, message: str = "Authentication failed. Check your API key.") -> None:
+        super().__init__(message)
+
+
+class RateLimitError(GameAPIError):
+    """Raised when the upstream API reports that a rate limit was exceeded.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying, if the upstream API
+            provided this information (via a ``Retry-After`` header). May be
+            ``None`` if the upstream response did not include it.
+    """
+
+    def __init__(
+        self, message: str = "Rate limit exceeded.", retry_after: Optional[float] = None
+    ) -> None:
+        self.retry_after = retry_after
+        super().__init__(message)
+
+    def __repr__(self) -> str:
+        return f"RateLimitError(retry_after={self.retry_after!r}, message={self.message!r})"
+
+
+class APIUnavailableError(GameAPIError):
+    """Raised when the upstream API is unreachable or returns a server error
+    after retries have been exhausted."""
+
+    def __init__(self, message: str = "The upstream API is currently unavailable.") -> None:
+        super().__init__(message)
+
+
+class InvalidResponseError(GameAPIError):
+    """Raised when the upstream API returns a response gameapi cannot parse."""
+
+    def __init__(
+        self, message: str = "Received an invalid or unparsable response from the API."
+    ) -> None:
+        super().__init__(message)

gameapi/games/__init__.py

@@ -0,0 +1,6 @@
+"""Game-specific integrations."""
+
+from .base import GameIntegration
+from .registry import GAME_REGISTRY, register_game, supported_games
+
+__all__ = ["GameIntegration", "GAME_REGISTRY", "register_game", "supported_games"]

gameapi/games/base.py

@@ -0,0 +1,60 @@
+"""Abstract base class every game integration must implement."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from ..cache import MemoryCache
+from ..http import HTTPClient
+from ..models import Leaderboard, Match, Player
+
+
+class GameIntegration(ABC):
+    """Base class for a single game's integration."""
+
+    slug: str
+    requires_api_key: bool = False
+    source_name: str = "unknown"
+    source_url: str = ""
+
+    def __init__(
+        self,
+        http: HTTPClient,
+        *,
+        api_key: Optional[str] = None,
+        cache: Optional[MemoryCache] = None,
+    ) -> None:
+        self.http = http
+        self.api_key = api_key
+        self.cache = cache
+
+    @abstractmethod
+    def get_player(self, identifier: str) -> Player:
+        """Fetch a player profile synchronously."""
+
+    @abstractmethod
+    async def get_player_async(self, identifier: str) -> Player:
+        """Fetch a player profile asynchronously."""
+
+    def get_matches(self, identifier: str, limit: int = 20) -> List[Match]:
+        raise NotImplementedError(f"'{self.slug}' does not support match history.")
+
+    async def get_matches_async(self, identifier: str, limit: int = 20) -> List[Match]:
+        raise NotImplementedError(f"'{self.slug}' does not support match history.")
+
+    def get_leaderboard(self, region: Optional[str] = None) -> Leaderboard:
+        raise NotImplementedError(f"'{self.slug}' does not support leaderboards.")
+
+    async def get_leaderboard_async(self, region: Optional[str] = None) -> Leaderboard:
+        raise NotImplementedError(f"'{self.slug}' does not support leaderboards.")
+
+    def _cache_get(self, key: str) -> Optional[object]:
+        if self.cache is None:
+            return None
+        return self.cache.get(f"{self.slug}:{key}")
+
+    def _cache_set(self, key: str, value: object, ttl: Optional[float] = None) -> None:
+        if self.cache is None:
+            return
+        self.cache.set(f"{self.slug}:{key}", value, ttl=ttl)

gameapi/games/chess_com/__init__.py

@@ -0,0 +1,5 @@
+"""Chess.com game integration."""
+
+from .client import ChessComIntegration
+
+__all__ = ["ChessComIntegration"]

gameapi/games/chess_com/client.py

@@ -0,0 +1,271 @@
+"""Chess.com game integration.
+
+Data source: the free, public Chess.com "Published-Data API"
+(https://www.chess.com/news/view/published-data-api). No API key is
+required. This integration is not affiliated with, endorsed by, or
+sponsored by Chess.com.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from ...exceptions import InvalidResponseError, PlayerNotFoundError
+from ...models import Leaderboard, LeaderboardEntry, Match, Player, PlayerStats, Rank
+from ..base import GameIntegration
+from . import endpoints
+from .models import ChessComMatchData, ChessComPlayerData, ChessComRatingSummary
+
+_USER_AGENT = "gameapi/0.2.0 (+https://github.com/F0xyN0xy/universal-game-api)"
+
+_TIME_CONTROL_KEYS = {
+    "chess_bullet": "bullet",
+    "chess_blitz": "blitz",
+    "chess_rapid": "rapid",
+    "chess_daily": "daily",
+}
+
+_PRIMARY_TIME_CONTROL = "chess_rapid"
+_DEFAULT_LEADERBOARD_CATEGORY = "live_blitz"
+
+
+class ChessComIntegration(GameIntegration):
+    """Game integration for Chess.com."""
+
+    slug = "chess_com"
+    requires_api_key = False
+    source_name = "Chess.com Published-Data API"
+    source_url = "https://www.chess.com/news/view/published-data-api"
+
+    def _headers(self) -> Dict[str, str]:
+        return {"User-Agent": _USER_AGENT, "Accept": "application/json"}
+
+    def get_player(self, identifier: str) -> Player:
+        cached = self._cache_get(f"player:{identifier}")
+        if cached is not None:
+            return cached  # type: ignore[return-value]
+
+        profile = self._fetch_profile(identifier)
+        stats = self._fetch_stats(identifier)
+        player = self._build_player(identifier, profile, stats)
+        self._cache_set(f"player:{identifier}", player, ttl=60)
+        return player
+
+    async def get_player_async(self, identifier: str) -> Player:
+        cached = self._cache_get(f"player:{identifier}")
+        if cached is not None:
+            return cached  # type: ignore[return-value]
+
+        profile = await self._fetch_profile_async(identifier)
+        stats = await self._fetch_stats_async(identifier)
+        player = self._build_player(identifier, profile, stats)
+        self._cache_set(f"player:{identifier}", player, ttl=60)
+        return player
+
+    def _fetch_profile(self, identifier: str) -> Dict[str, Any]:
+        try:
+            return self.http.request(
+                "GET", endpoints.player_profile_url(identifier), headers=self._headers()
+            )
+        except InvalidResponseError as exc:
+            raise PlayerNotFoundError(self.slug, identifier) from exc
+
+    async def _fetch_profile_async(self, identifier: str) -> Dict[str, Any]:
+        try:
+            return await self.http.request_async(
+                "GET", endpoints.player_profile_url(identifier), headers=self._headers()
+            )
+        except InvalidResponseError as exc:
+            raise PlayerNotFoundError(self.slug, identifier) from exc
+
+    def _fetch_stats(self, identifier: str) -> Dict[str, Any]:
+        try:
+            return self.http.request(
+                "GET", endpoints.player_stats_url(identifier), headers=self._headers()
+            )
+        except InvalidResponseError:
+            return {}
+
+    async def _fetch_stats_async(self, identifier: str) -> Dict[str, Any]:
+        try:
+            return await self.http.request_async(
+                "GET", endpoints.player_stats_url(identifier), headers=self._headers()
+            )
+        except InvalidResponseError:
+            return {}
+
+    def _build_player(
+        self, identifier: str, profile: Dict[str, Any], stats: Dict[str, Any]
+    ) -> Player:
+        ratings: Dict[str, ChessComRatingSummary] = {}
+        total_wins = total_losses = total_draws = 0
+        has_record = False
+
+        for stats_key, label in _TIME_CONTROL_KEYS.items():
+            block = stats.get(stats_key)
+            if not block:
+                continue
+            last = block.get("last", {})
+            record = block.get("record", {})
+            summary = ChessComRatingSummary(
+                rating=last.get("rating"),
+                wins=record.get("win"),
+                losses=record.get("loss"),
+                draws=record.get("draw"),
+            )
+            ratings[label] = summary
+            if record:
+                has_record = True
+                total_wins += record.get("win", 0) or 0
+                total_losses += record.get("loss", 0) or 0
+                total_draws += record.get("draw", 0) or 0
+
+        games_played = total_wins + total_losses + total_draws if has_record else None
+        win_rate = (total_wins / games_played) if games_played else None
+
+        player_stats = PlayerStats(
+            games_played=games_played,
+            wins=total_wins if has_record else None,
+            losses=total_losses if has_record else None,
+            draws=total_draws if has_record else None,
+            win_rate=win_rate,
+        )
+
+        primary = ratings.get(_TIME_CONTROL_KEYS[_PRIMARY_TIME_CONTROL])
+        rank = Rank(
+            tier=profile.get("title"),
+            rating=primary.rating if primary else None,
+            raw={"tactics": stats.get("tactics"), "puzzle_rush": stats.get("puzzle_rush")},
+        )
+
+        game_data = ChessComPlayerData(
+            title=profile.get("title"),
+            country=profile.get("country"),
+            followers=profile.get("followers"),
+            joined_timestamp=profile.get("joined"),
+            league=profile.get("league"),
+            ratings=ratings,
+            puzzle_rush_best=(stats.get("puzzle_rush", {}) or {})
+            .get("best", {})
+            .get("score"),
+        )
+
+        return Player(
+            name=profile.get("username", identifier),
+            game=self.slug,
+            identifier=identifier,
+            stats=player_stats,
+            rank=rank,
+            game_data=game_data,
+            avatar_url=profile.get("avatar"),
+        )
+
+    def get_matches(self, identifier: str, limit: int = 20) -> List[Match]:
+        archives = self._fetch_archives(identifier)
+        games: List[Dict[str, Any]] = []
+        for archive_url in reversed(archives):
+            if len(games) >= limit:
+                break
+            payload = self.http.request("GET", archive_url, headers=self._headers())
+            games.extend(payload.get("games", []))
+        return self._build_matches(identifier, games, limit)
+
+    async def get_matches_async(self, identifier: str, limit: int = 20) -> List[Match]:
+        archives = await self._fetch_archives_async(identifier)
+        games: List[Dict[str, Any]] = []
+        for archive_url in reversed(archives):
+            if len(games) >= limit:
+                break
+            payload = await self.http.request_async("GET", archive_url, headers=self._headers())
+            games.extend(payload.get("games", []))
+        return self._build_matches(identifier, games, limit)
+
+    def _fetch_archives(self, identifier: str) -> List[str]:
+        try:
+            payload = self.http.request(
+                "GET", endpoints.player_archives_url(identifier), headers=self._headers()
+            )
+        except InvalidResponseError as exc:
+            raise PlayerNotFoundError(self.slug, identifier) from exc
+        return payload.get("archives", [])
+
+    async def _fetch_archives_async(self, identifier: str) -> List[str]:
+        try:
+            payload = await self.http.request_async(
+                "GET", endpoints.player_archives_url(identifier), headers=self._headers()
+            )
+        except InvalidResponseError as exc:
+            raise PlayerNotFoundError(self.slug, identifier) from exc
+        return payload.get("archives", [])
+
+    def _build_matches(
+        self, identifier: str, games: List[Dict[str, Any]], limit: int
+    ) -> List[Match]:
+        matches: List[Match] = []
+        lowered = identifier.lower()
+        for raw in reversed(games):
+            if len(matches) >= limit:
+                break
+            white = raw.get("white", {})
+            black = raw.get("black", {})
+            is_white = white.get("username", "").lower() == lowered
+            mine, opponent = (white, black) if is_white else (black, white)
+
+            result = _normalize_result(mine.get("result"))
+            played_at = None
+            if raw.get("end_time"):
+                played_at = datetime.fromtimestamp(raw["end_time"], tz=timezone.utc)
+
+            matches.append(
+                Match(
+                    id=raw.get("url", ""),
+                    game=self.slug,
+                    played_at=played_at,
+                    result=result,
+                    opponent=opponent.get("username"),
+                    game_data=ChessComMatchData(
+                        time_class=raw.get("time_class"),
+                        white=white.get("username"),
+                        black=black.get("username"),
+                        white_result=white.get("result"),
+                        black_result=black.get("result"),
+                        pgn_url=raw.get("url"),
+                    ),
+                )
+            )
+        return matches
+
+    def get_leaderboard(self, region: Optional[str] = None) -> Leaderboard:
+        payload = self.http.request("GET", endpoints.leaderboards_url(), headers=self._headers())
+        return self._build_leaderboard(payload, region)
+
+    async def get_leaderboard_async(self, region: Optional[str] = None) -> Leaderboard:
+        payload = await self.http.request_async(
+            "GET", endpoints.leaderboards_url(), headers=self._headers()
+        )
+        return self._build_leaderboard(payload, region)
+
+    def _build_leaderboard(self, payload: Dict[str, Any], region: Optional[str]) -> Leaderboard:
+        rows = payload.get(_DEFAULT_LEADERBOARD_CATEGORY, [])
+        entries = [
+            LeaderboardEntry(
+                position=row.get("rank", idx + 1),
+                name=row.get("username", "unknown"),
+                rating=row.get("score"),
+            )
+            for idx, row in enumerate(rows)
+        ]
+        return Leaderboard(game=self.slug, entries=entries, region=region)
+
+
+def _normalize_result(chess_com_result: Optional[str]) -> str:
+    if chess_com_result is None:
+        return "unknown"
+    if chess_com_result == "win":
+        return "win"
+    if chess_com_result in {
+        "agreed", "repetition", "stalemate", "insufficient", "50move", "timevsinsufficient"
+    }:
+        return "draw"
+    return "loss"