tacoscore 0.1.0__py3-none-any.whl

tacoscore/__init__.py

@@ -0,0 +1,149 @@
+"""TacosScore — football analytics from Sofascore.
+
+Public API surface — import from here for everything you'll typically need.
+"""
+
+from tacoscore.async_client import AsyncSofascoreClient
+from tacoscore.client import SofascoreClient
+from tacoscore.extraction import (
+    ANALYTICS_EVENT_ENDPOINTS,
+    MATCH_EXTRACTION_ORDER,
+    strip_ui_fields,
+)
+from tacoscore.help_catalog import format_help_entry, get_help_entry, list_help_entries
+from tacoscore.interactive_help import show_help
+from tacoscore.dataframe import (
+    actions_to_dataframe,
+    graph_to_dataframe,
+    heatmap_to_dataframe,
+    incidents_to_dataframe,
+    lineups_to_dataframe,
+    matches_to_dataframe,
+    player_stats_to_dataframe,
+    rounds_to_dataframe,
+    season_player_stats_to_dataframe,
+    shotmap_to_dataframe,
+    standings_to_dataframe,
+    team_stats_to_dataframe,
+)
+from tacoscore.exceptions import (
+    APIError,
+    NotFoundError,
+    ParseError,
+    RateLimitError,
+    SofascoreError,
+)
+from tacoscore.models.actions import Action, ActionStream
+from tacoscore.models.common import Country, Sport
+from tacoscore.models.event import FullMatch, PlayerMatchData
+from tacoscore.models.graph import GraphPoint, MatchGraph
+from tacoscore.models.h2h import DuelRecord, HeadToHead
+from tacoscore.models.heatmap import Heatmap, HeatmapPoint
+from tacoscore.models.incidents import Incident, Incidents
+from tacoscore.models.lineups import LineupEntry, Lineups, LineupSide
+from tacoscore.models.match_detail import EventDetail, EventManagers, Manager, Referee, Venue
+from tacoscore.models.player import Player
+from tacoscore.models.pregame_form import PregameForm, TeamFormSnapshot
+from tacoscore.models.profile import PlayerProfile, SeasonPlayerStatistics, TeamProfile
+from tacoscore.models.shotmap import Shot, Shotmap
+from tacoscore.models.standings import StandingRow, Standings, StandingsTable
+from tacoscore.models.statistics import (
+    PlayerStats,
+    SinglePlayerStats,
+    TeamStatistics,
+    TeamStatValue,
+)
+from tacoscore.models.team import Team
+from tacoscore.models.team_rankings import TeamRankingEntry, TeamRankings
+from tacoscore.models.transfers import Transfer, TransferHistory
+from tacoscore.models.tournament import (
+    MatchList,
+    MatchScore,
+    MatchSummary,
+    Round,
+    RoundList,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [  # noqa: RUF022 -- grouped by category for readability
+    # Client
+    "SofascoreClient",
+    "AsyncSofascoreClient",
+    "ANALYTICS_EVENT_ENDPOINTS",
+    "MATCH_EXTRACTION_ORDER",
+    "strip_ui_fields",
+    "format_help_entry",
+    "get_help_entry",
+    "list_help_entries",
+    "show_help",
+    # Exceptions
+    "SofascoreError",
+    "APIError",
+    "RateLimitError",
+    "NotFoundError",
+    "ParseError",
+    # Models
+    "Action",
+    "ActionStream",
+    "Country",
+    "DuelRecord",
+    "EventDetail",
+    "EventManagers",
+    "FullMatch",
+    "GraphPoint",
+    "HeadToHead",
+    "Heatmap",
+    "HeatmapPoint",
+    "Incident",
+    "Incidents",
+    "LineupEntry",
+    "Lineups",
+    "LineupSide",
+    "Manager",
+    "MatchGraph",
+    "MatchList",
+    "MatchScore",
+    "MatchSummary",
+    "Player",
+    "PlayerMatchData",
+    "PregameForm",
+    "PlayerProfile",
+    "PlayerStats",
+    "Referee",
+    "Round",
+    "RoundList",
+    "SeasonPlayerStatistics",
+    "Shot",
+    "Shotmap",
+    "SinglePlayerStats",
+    "Sport",
+    "StandingRow",
+    "Standings",
+    "StandingsTable",
+    "Team",
+    "TeamFormSnapshot",
+    "TeamProfile",
+    "TeamRankingEntry",
+    "TeamRankings",
+    "Transfer",
+    "TransferHistory",
+    "TeamStatistics",
+    "TeamStatValue",
+    "Venue",
+    # DataFrame export (requires pandas)
+    "actions_to_dataframe",
+    "graph_to_dataframe",
+    "heatmap_to_dataframe",
+    "incidents_to_dataframe",
+    "lineups_to_dataframe",
+    "matches_to_dataframe",
+    "player_stats_to_dataframe",
+    "rounds_to_dataframe",
+    "season_player_stats_to_dataframe",
+    "shotmap_to_dataframe",
+    "standings_to_dataframe",
+    "team_stats_to_dataframe",
+    # Meta
+    "__version__",
+]

tacoscore/_serialize.py

@@ -0,0 +1,61 @@
+"""Internal: convert dataclass models to JSON-compatible dicts.
+
+Used by the CLI to serialize parsed models. The ``raw`` field on each model
+is excluded by default to give clean output; pass ``include_raw=True`` to
+preserve the original API payload nested under each model.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from datetime import date, datetime
+from typing import Any
+
+from tacoscore.extraction import strip_ui_fields
+
+
+def to_jsonable(
+    obj: Any,
+    include_raw: bool = False,
+    *,
+    analytics_only: bool = False,
+) -> Any:
+    """Recursively convert ``obj`` into JSON-serializable primitives.
+
+    Args:
+        obj: A dataclass, dict, list, tuple, date/datetime, or primitive.
+        include_raw: If False (default), strip ``raw`` fields from any
+            dataclass to give a clean typed view. If True, keep them.
+        analytics_only: If True, strip UI-only Sofascore keys per
+            ``docs/sofascore-api-reference.md`` (DROP fields).
+
+    Returns:
+        A structure that ``json.dumps`` can serialize directly.
+    """
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        result: dict[str, Any] = {}
+        for f in dataclasses.fields(obj):
+            if not include_raw and f.name == "raw":
+                continue
+            result[f.name] = to_jsonable(
+                getattr(obj, f.name), include_raw, analytics_only=analytics_only
+            )
+        return result
+
+    if isinstance(obj, dict):
+        cleaned = {
+            str(k): to_jsonable(v, include_raw, analytics_only=analytics_only)
+            for k, v in obj.items()
+        }
+        return strip_ui_fields(cleaned) if analytics_only else cleaned
+
+    if isinstance(obj, (list, tuple)):
+        items = [
+            to_jsonable(x, include_raw, analytics_only=analytics_only) for x in obj
+        ]
+        return strip_ui_fields(items) if analytics_only else items
+
+    if isinstance(obj, (date, datetime)):
+        return obj.isoformat()
+
+    return obj

tacoscore/async_client.py

@@ -0,0 +1,411 @@
+"""Async client for the Sofascore API.
+
+Mirror of :class:`tacoscore.client.SofascoreClient` with ``async def``
+methods and an ``httpx.AsyncClient`` under the hood. Use this when you need
+to integrate with an existing asyncio application (FastAPI, Discord bots,
+background jobs).
+
+Important:
+    Async **does not make scraping faster** — the rate limiter is the
+    bottleneck and it's shared across all concurrent calls. The benefit is
+    that *other coroutines* can do work while waiting for the next request
+    slot, which matters in event-driven applications but not in a simple
+    extraction script. For batch extraction, the sync client is just as
+    fast and simpler.
+
+Example::
+
+    import asyncio
+    from tacoscore import AsyncSofascoreClient
+
+    async def main():
+        async with AsyncSofascoreClient() as client:
+            stats = await client.event_statistics(15186861)
+            lineups = await client.event_lineups(15186861)
+            print(f"{lineups.home.formation} vs {lineups.away.formation}")
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from typing import Any
+
+from tacoscore.async_http import AsyncHttpTransport
+from tacoscore.async_rate_limiter import AsyncRateLimiter
+from tacoscore.client import DEFAULT_BASE_URL
+from tacoscore.extraction import (
+    should_fetch_heatmap,
+    should_fetch_shotmap,
+    should_fetch_spatial,
+)
+from tacoscore.exceptions import NotFoundError
+from tacoscore.models.actions import ActionStream
+from tacoscore.models.event import FullMatch, PlayerMatchData
+from tacoscore.models.graph import MatchGraph
+from tacoscore.models.h2h import HeadToHead
+from tacoscore.models.heatmap import Heatmap
+from tacoscore.models.incidents import Incidents
+from tacoscore.models.lineups import Lineups
+from tacoscore.models.match_detail import EventDetail, EventManagers
+from tacoscore.models.pregame_form import PregameForm
+from tacoscore.models.profile import PlayerProfile, SeasonPlayerStatistics, TeamProfile
+from tacoscore.models.shotmap import Shotmap
+from tacoscore.models.standings import Standings
+from tacoscore.models.statistics import SinglePlayerStats, TeamStatistics
+from tacoscore.models.team_rankings import TeamRankings
+from tacoscore.models.tournament import MatchList, RoundList
+from tacoscore.models.transfers import TransferHistory
+from tacoscore.parsers import (
+    parse_action_stream,
+    parse_event_detail,
+    parse_event_managers,
+    parse_head_to_head,
+    parse_heatmap,
+    parse_incidents,
+    parse_lineups,
+    parse_match_graph,
+    parse_match_list,
+    parse_player_profile,
+    parse_pregame_form,
+    parse_round_list,
+    parse_season_player_statistics,
+    parse_shotmap,
+    parse_single_player_stats,
+    parse_standings,
+    parse_team_profile,
+    parse_team_rankings,
+    parse_team_statistics,
+    parse_transfer_history,
+)
+
+
+class AsyncSofascoreClient:
+    """Async client for the Sofascore football API.
+
+    Construction options match :class:`SofascoreClient`. Use as an async
+    context manager so the connection pool closes cleanly.
+
+    Example:
+        >>> async with AsyncSofascoreClient(rate_limit_seconds=2.0) as client:
+        ...     heatmap = await client.player_heatmap(15186861, 868812)
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        rate_limit_seconds: float = 1.5,
+        rate_jitter_seconds: float = 0.5,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        user_agent: str | None = None,
+    ) -> None:
+        self._rate_limiter = AsyncRateLimiter(
+            min_interval=rate_limit_seconds,
+            jitter=rate_jitter_seconds,
+        )
+        self._http = AsyncHttpTransport(
+            base_url=base_url,
+            rate_limiter=self._rate_limiter,
+            timeout=timeout,
+            max_retries=max_retries,
+            user_agent=user_agent,
+        )
+
+    # ----- low-level access -----
+
+    async def get_raw(self, path: str) -> dict[str, Any]:
+        """Issue a GET against the API and return the raw JSON dict."""
+        return await self._http.get(path)
+
+    # ----- match-level endpoints -----
+
+    async def event(self, event_id: int) -> EventDetail:
+        """Match metadata — teams, score, venue, referee, attendance."""
+        raw = await self._http.get(f"event/{event_id}")
+        return parse_event_detail(raw)
+
+    async def event_incidents(self, event_id: int) -> Incidents:
+        """Match timeline — goals, cards, substitutions, period markers."""
+        raw = await self._http.get(f"event/{event_id}/incidents")
+        return parse_incidents(raw)
+
+    async def event_graph(self, event_id: int) -> MatchGraph:
+        """Attack momentum graph (minute-by-minute pressure values)."""
+        raw = await self._http.get(f"event/{event_id}/graph")
+        return parse_match_graph(raw)
+
+    async def event_managers(self, event_id: int) -> EventManagers:
+        """Managers for both teams in a match."""
+        raw = await self._http.get(f"event/{event_id}/managers")
+        return parse_event_managers(raw)
+
+    async def event_statistics(self, event_id: int) -> TeamStatistics:
+        """Team statistics by period for one match."""
+        raw = await self._http.get(f"event/{event_id}/statistics")
+        return parse_team_statistics(raw)
+
+    async def event_lineups(self, event_id: int) -> Lineups:
+        """Lineups and per-player match statistics."""
+        raw = await self._http.get(f"event/{event_id}/lineups")
+        return parse_lineups(raw)
+
+    async def event_shotmap(self, event_id: int) -> Shotmap:
+        """All shots in a match (every player)."""
+        raw = await self._http.get(f"event/{event_id}/shotmap")
+        return parse_shotmap(raw)
+
+    async def event_h2h(self, event_id: int) -> HeadToHead:
+        """Head-to-head win/draw record."""
+        raw = await self._http.get(f"event/{event_id}/h2h")
+        return parse_head_to_head(raw)
+
+    async def event_pregame_form(self, event_id: int) -> PregameForm:
+        """Pre-match form for both teams."""
+        raw = await self._http.get(f"event/{event_id}/pregame-form")
+        return parse_pregame_form(raw)
+
+    # ----- player-level endpoints -----
+
+    async def player_heatmap(self, event_id: int, player_id: int) -> Heatmap:
+        """Touch heatmap for one player in one match."""
+        raw = await self._http.get(f"event/{event_id}/player/{player_id}/heatmap")
+        return parse_heatmap(raw)
+
+    async def player_actions(self, event_id: int, player_id: int) -> ActionStream:
+        """Action stream (passes, dribbles, defensive, ball-carries)."""
+        raw = await self._http.get(
+            f"event/{event_id}/player/{player_id}/rating-breakdown"
+        )
+        return parse_action_stream(raw)
+
+    async def player_shotmap(self, event_id: int, player_id: int) -> Shotmap:
+        """Shot map for one player in one match."""
+        raw = await self._http.get(f"event/{event_id}/shotmap/player/{player_id}")
+        return parse_shotmap(raw)
+
+    async def player_statistics(
+        self, event_id: int, player_id: int
+    ) -> SinglePlayerStats:
+        """Single-player match statistics."""
+        raw = await self._http.get(f"event/{event_id}/player/{player_id}/statistics")
+        return parse_single_player_stats(raw)
+
+    # ----- tournament discovery -----
+
+    async def tournament_rounds(
+        self, tournament_id: int, season_id: int
+    ) -> RoundList:
+        """List all rounds in a tournament season."""
+        raw = await self._http.get(
+            f"unique-tournament/{tournament_id}/season/{season_id}/rounds"
+        )
+        return parse_round_list(raw)
+
+    async def round_events(
+        self,
+        tournament_id: int,
+        season_id: int,
+        round_number: int,
+        slug: str | None = None,
+    ) -> MatchList:
+        """List matches in a specific round."""
+        if slug:
+            path = (
+                f"unique-tournament/{tournament_id}/season/{season_id}"
+                f"/events/round/{round_number}/slug/{slug}"
+            )
+        else:
+            path = (
+                f"unique-tournament/{tournament_id}/season/{season_id}"
+                f"/events/round/{round_number}"
+            )
+        raw = await self._http.get(path)
+        return parse_match_list(raw)
+
+    async def season_events(
+        self, tournament_id: int, season_id: int
+    ) -> dict[int, MatchList]:
+        """Fetch every round's matches for one season concurrently.
+
+        Per-round calls are launched via ``asyncio.gather``; the shared rate
+        limiter still serializes them, so total time is the same as the sync
+        version. Async lets *other* coroutines do work in the meantime.
+        """
+        rounds = await self.tournament_rounds(tournament_id, season_id)
+
+        async def _fetch_round(round_number: int, slug: str | None) -> tuple[int, MatchList]:
+            ml = await self.round_events(tournament_id, season_id, round_number, slug)
+            return round_number, ml
+
+        tasks = [_fetch_round(r.round, r.slug) for r in rounds.rounds]
+        results = await asyncio.gather(*tasks) if tasks else []
+        return dict(results)
+
+    # ----- standings & profiles -----
+
+    async def tournament_standings(
+        self,
+        tournament_id: int,
+        season_id: int,
+        table_type: str = "total",
+    ) -> Standings:
+        """League table for a tournament season."""
+        raw = await self._http.get(
+            f"unique-tournament/{tournament_id}/season/{season_id}/standings/{table_type}"
+        )
+        return parse_standings(raw)
+
+    async def team(self, team_id: int) -> TeamProfile:
+        """Team profile — logo, country, venue, manager."""
+        raw = await self._http.get(f"team/{team_id}")
+        return parse_team_profile(raw)
+
+    async def player(self, player_id: int) -> PlayerProfile:
+        """Player profile — bio, position, market value."""
+        raw = await self._http.get(f"player/{player_id}")
+        return parse_player_profile(raw)
+
+    async def player_season_statistics(
+        self,
+        player_id: int,
+        tournament_id: int,
+        season_id: int,
+    ) -> SeasonPlayerStatistics:
+        """Season aggregate statistics for one player in one competition."""
+        raw = await self._http.get(
+            f"player/{player_id}/unique-tournament/{tournament_id}/season/{season_id}/statistics/overall"
+        )
+        return parse_season_player_statistics(raw)
+
+    async def team_events(self, team_id: int, page: int = 0) -> MatchList:
+        """Recent fixtures for a team."""
+        raw = await self._http.get(f"team/{team_id}/events/last/{page}")
+        return parse_match_list(raw)
+
+    async def team_events_next(self, team_id: int, page: int = 0) -> MatchList:
+        """Upcoming fixtures for a team."""
+        raw = await self._http.get(f"team/{team_id}/events/next/{page}")
+        return parse_match_list(raw)
+
+    async def team_rankings(self, team_id: int) -> TeamRankings:
+        """FIFA-style ranking rows for a team."""
+        raw = await self._http.get(f"team/{team_id}/rankings")
+        return parse_team_rankings(raw)
+
+    async def player_transfer_history(self, player_id: int) -> TransferHistory:
+        """Career transfer history for a player."""
+        raw = await self._http.get(f"player/{player_id}/transfer-history")
+        return parse_transfer_history(raw)
+
+    async def player_events_last(self, player_id: int, page: int = 0) -> MatchList:
+        """Recent matches involving a player."""
+        raw = await self._http.get(f"player/{player_id}/events/last/{page}")
+        return parse_match_list(raw)
+
+    # ----- high-level workflow -----
+
+    async def fetch_full_match(
+        self,
+        event_id: int,
+        skip_no_minutes: bool = True,
+        skip_no_shots: bool = True,
+        skip_sparse_heatmap: bool = True,
+        min_touches_for_heatmap: int = 5,
+        include_match_shotmap: bool = True,
+        include_h2h: bool = True,
+        include_pregame_form: bool = True,
+    ) -> FullMatch:
+        """Fetch analytics endpoints for one match (mirrors sync client)."""
+        event_detail = await self.event(event_id)
+        lineups = await self.event_lineups(event_id)
+        team_stats = await self.event_statistics(event_id)
+
+        incidents: Incidents | None = None
+        managers: EventManagers | None = None
+        graph: MatchGraph | None = None
+        head_to_head: HeadToHead | None = None
+        pregame_form: PregameForm | None = None
+        match_shotmap: Shotmap | None = None
+
+        with contextlib.suppress(NotFoundError):
+            incidents = await self.event_incidents(event_id)
+        with contextlib.suppress(NotFoundError):
+            managers = await self.event_managers(event_id)
+        with contextlib.suppress(NotFoundError):
+            graph = await self.event_graph(event_id)
+        if include_h2h:
+            with contextlib.suppress(NotFoundError):
+                head_to_head = await self.event_h2h(event_id)
+        if include_pregame_form:
+            with contextlib.suppress(NotFoundError):
+                pregame_form = await self.event_pregame_form(event_id)
+        if include_match_shotmap:
+            with contextlib.suppress(NotFoundError):
+                match_shotmap = await self.event_shotmap(event_id)
+
+        async def _fetch_one(entry: Any) -> tuple[int, PlayerMatchData]:
+            stats = entry.statistics
+            player_id = entry.player.id
+            heatmap: Heatmap | None = None
+            actions: ActionStream | None = None
+            shotmap: Shotmap | None = None
+
+            if should_fetch_heatmap(
+                stats.touches,
+                skip_sparse=skip_sparse_heatmap,
+                min_touches=min_touches_for_heatmap,
+            ):
+                with contextlib.suppress(NotFoundError):
+                    heatmap = await self.player_heatmap(event_id, player_id)
+
+            with contextlib.suppress(NotFoundError):
+                actions = await self.player_actions(event_id, player_id)
+
+            if not skip_no_shots or should_fetch_shotmap(stats.total_shots):
+                with contextlib.suppress(NotFoundError):
+                    shotmap = await self.player_shotmap(event_id, player_id)
+
+            return player_id, PlayerMatchData(
+                player_id=player_id,
+                heatmap=heatmap,
+                actions=actions,
+                shotmap=shotmap,
+            )
+
+        tasks = [
+            _fetch_one(entry)
+            for entry in lineups.all_players()
+            if should_fetch_spatial(
+                entry.statistics.minutes_played, skip_no_minutes=skip_no_minutes
+            )
+        ]
+        results = await asyncio.gather(*tasks) if tasks else []
+
+        return FullMatch(
+            event_id=event_id,
+            team_statistics=team_stats,
+            lineups=lineups,
+            player_data=dict(results),
+            event_detail=event_detail,
+            incidents=incidents,
+            graph=graph,
+            managers=managers,
+            head_to_head=head_to_head,
+            pregame_form=pregame_form,
+            match_shotmap=match_shotmap,
+        )
+
+    # ----- lifecycle -----
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._http.close()
+
+    async def __aenter__(self) -> AsyncSofascoreClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

tacoscore/async_http.py

@@ -0,0 +1,5 @@
+"""Async HTTP transport — re-exported from :mod:`tacoscore.http`."""
+
+from tacoscore.http import AsyncHttpTransport
+
+__all__ = ["AsyncHttpTransport"]

tacoscore/async_rate_limiter.py

@@ -0,0 +1,64 @@
+"""asyncio-compatible rate limiter.
+
+Mirrors :class:`tacoscore.rate_limiter.RateLimiter` but uses ``asyncio.Lock``
+and ``asyncio.sleep`` so it doesn't block the event loop.
+
+Note:
+    Sharing one limiter across many concurrent coroutines still serializes
+    their requests one-per-interval — the limiter holds its lock during the
+    sleep. Async doesn't make rate-limited scraping faster; it just lets
+    other coroutines do work *during* the wait.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+
+
+class AsyncRateLimiter:
+    """Async rate limiter with optional jitter.
+
+    Args:
+        min_interval: Minimum seconds between calls.
+        jitter: Random uniform noise added to each interval (\u00b1 jitter / 2).
+
+    Example:
+        >>> limiter = AsyncRateLimiter(min_interval=1.5, jitter=0.5)
+        >>> await limiter.wait()  # Returns 0 on first call
+        >>> await limiter.wait()  # Sleeps 1.0-2.0 seconds
+    """
+
+    def __init__(self, min_interval: float = 1.5, jitter: float = 0.5) -> None:
+        if min_interval < 0:
+            raise ValueError("min_interval must be non-negative")
+        if jitter < 0:
+            raise ValueError("jitter must be non-negative")
+        self.min_interval = min_interval
+        self.jitter = jitter
+        self._lock = asyncio.Lock()
+        self._last_call: float = 0.0
+
+    async def wait(self) -> float:
+        """Block until the next call is allowed.
+
+        Returns:
+            Seconds actually slept (zero for the first call).
+        """
+        async with self._lock:
+            now = time.monotonic()
+            elapsed = now - self._last_call
+            target = self.min_interval + random.uniform(
+                -self.jitter / 2, self.jitter / 2
+            )
+            sleep_for = max(0.0, target - elapsed)
+            if sleep_for > 0:
+                await asyncio.sleep(sleep_for)
+            self._last_call = time.monotonic()
+            return sleep_for
+
+    async def reset(self) -> None:
+        """Reset the limiter so the next call returns immediately."""
+        async with self._lock:
+            self._last_call = 0.0