openmatchkit 0.2.1__py3-none-any.whl

openmatchkit/sources/football_data_uk.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import csv
+from datetime import datetime, timezone
+from hashlib import sha1
+from io import StringIO
+
+from openmatchkit.http import SafeHttpClient
+from openmatchkit.models import Match, MatchStatus, Score, Team
+
+
+class FootballDataUkSource:
+    """Adapter for football-data.co.uk CSV result files.
+
+    The source is free to download, but users should verify the site's current
+    terms before redistributing data. The adapter fetches facts from source and
+    does not bundle third-party data.
+    """
+
+    name = "football_data_uk"
+
+    def __init__(
+        self,
+        http: SafeHttpClient | None = None,
+        base_url: str = "https://www.football-data.co.uk/mmz4281",
+    ) -> None:
+        self.http = http or SafeHttpClient()
+        self.base_url = base_url.rstrip("/")
+
+    def _make_id(self, *parts: object) -> str:
+        raw = "|".join(str(part) for part in parts)
+        return sha1(raw.encode("utf-8")).hexdigest()[:16]
+
+    def csv_url(self, competition: str, season: str) -> str:
+        return f"{self.base_url}/{season}/{competition}.csv"
+
+    def _parse_date(self, value: str) -> datetime | None:
+        value = value.strip()
+        for fmt in ("%d/%m/%Y", "%d/%m/%y", "%Y-%m-%d"):
+            try:
+                return datetime.strptime(value, fmt)
+            except ValueError:
+                continue
+        return None
+
+    def _parse_int(self, value: object) -> int | None:
+        if value is None:
+            return None
+
+        text = str(value).strip()
+        if not text:
+            return None
+
+        try:
+            return int(float(text))
+        except ValueError:
+            return None
+
+    def parse_csv(
+        self,
+        text: str,
+        *,
+        source_url: str,
+        competition: str,
+        season: str,
+        fetched_at: datetime | None = None,
+    ) -> list[Match]:
+        fetched = fetched_at or datetime.now(timezone.utc)
+        reader = csv.DictReader(StringIO(text))
+        matches: list[Match] = []
+
+        for row in reader:
+            home = (row.get("HomeTeam") or "").strip()
+            away = (row.get("AwayTeam") or "").strip()
+
+            if not home or not away:
+                continue
+
+            home_goals = self._parse_int(row.get("FTHG"))
+            away_goals = self._parse_int(row.get("FTAG"))
+            has_score = home_goals is not None and away_goals is not None
+            status = MatchStatus.FULL_TIME if has_score else MatchStatus.SCHEDULED
+            kickoff = self._parse_date(row.get("Date") or "")
+
+            match_id = self._make_id(
+                self.name,
+                competition,
+                season,
+                row.get("Date"),
+                home,
+                away,
+            )
+
+            matches.append(
+                Match(
+                    match_id=match_id,
+                    competition=competition,
+                    season=season,
+                    kickoff=kickoff,
+                    home=Team(name=home),
+                    away=Team(name=away),
+                    score=Score(home=home_goals, away=away_goals),
+                    status=status,
+                    source=self.name,
+                    source_url=source_url,
+                    fetched_at=fetched,
+                )
+            )
+
+        return matches
+
+    def fixtures(self, competition: str, season: str | None = None) -> list[Match]:
+        if season is None:
+            raise ValueError("Football-Data adapter requires a season code, for example '2324'.")
+
+        url = self.csv_url(competition=competition, season=season)
+        text = self.http.get_text(url)
+        return self.parse_csv(text, source_url=url, competition=competition, season=season)
+
+    def live_scores(self) -> list[Match]:
+        return []

openmatchkit/sources/json_file.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from openmatchkit.models import (
+    Match,
+    MatchStatus,
+    Player,
+    PlayerHistory,
+    PlayerMatchAppearance,
+    PlayerTotals,
+    Scoreboard,
+)
+
+
+class JsonFileSource:
+    """Source adapter for local detailed JSON files.
+
+    This is useful for authorized/public detailed feeds, saved fixtures, and demos.
+    It never performs network requests.
+    """
+
+    name = "json_file"
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.source_url = self.path.resolve().as_uri()
+        self._data: dict[str, Any] | None = None
+
+    def _load(self) -> dict[str, Any]:
+        if self._data is None:
+            self._data = json.loads(self.path.read_text(encoding="utf-8"))
+        return self._data
+
+    def _scoreboards(self) -> list[Scoreboard]:
+        data = self._load()
+        return [Scoreboard.model_validate(item) for item in data.get("scoreboards", [])]
+
+    def _matches(self) -> list[Match]:
+        data = self._load()
+        matches: dict[str, Match] = {}
+
+        for item in data.get("matches", []):
+            match = Match.model_validate(item)
+            matches[match.match_id] = match
+
+        for board in self._scoreboards():
+            matches[board.match.match_id] = board.match
+
+        return list(matches.values())
+
+    def _match_filter(
+        self,
+        match: Match,
+        competition: str | None = None,
+        season: str | None = None,
+    ) -> bool:
+        if competition is not None and match.competition != competition:
+            return False
+        if season is not None and match.season != season:
+            return False
+        return True
+
+    def fixtures(self, competition: str, season: str | None = None) -> list[Match]:
+        return [
+            match
+            for match in self._matches()
+            if self._match_filter(match, competition=competition, season=season)
+        ]
+
+    def live_scores(self) -> list[Match]:
+        return [board.match for board in self.live_scoreboards()]
+
+    def scoreboards(
+        self,
+        competition: str | None = None,
+        season: str | None = None,
+    ) -> list[Scoreboard]:
+        return [
+            board
+            for board in self._scoreboards()
+            if self._match_filter(board.match, competition=competition, season=season)
+        ]
+
+    def scoreboard(
+        self,
+        match_id: str,
+        competition: str | None = None,
+        season: str | None = None,
+    ) -> Scoreboard | None:
+        for board in self.scoreboards(competition=competition, season=season):
+            if board.match.match_id == match_id:
+                return board
+        return None
+
+    def live_scoreboards(self) -> list[Scoreboard]:
+        return [
+            board
+            for board in self._scoreboards()
+            if board.match.status in {MatchStatus.LIVE, MatchStatus.HALF_TIME}
+        ]
+
+    def _appearance_from_stats(
+        self,
+        board: Scoreboard,
+        player_name: str,
+    ) -> PlayerMatchAppearance | None:
+        needle = player_name.casefold()
+
+        for stats in board.player_stats:
+            if stats.player.name.casefold() != needle:
+                continue
+
+            team = stats.player.team or ""
+            opponent = None
+            home_away = "unknown"
+
+            if team == board.match.home.name:
+                opponent = board.match.away.name
+                home_away = "home"
+            elif team == board.match.away.name:
+                opponent = board.match.home.name
+                home_away = "away"
+            elif team:
+                home_away = "neutral"
+
+            return PlayerMatchAppearance(
+                match_id=board.match.match_id,
+                competition=board.match.competition,
+                season=board.match.season,
+                kickoff=board.match.kickoff,
+                team=team or "unknown",
+                opponent=opponent,
+                home_away=home_away,
+                status=board.match.status,
+                minutes_played=stats.minutes_played,
+                started=stats.started,
+                goals=stats.goals,
+                assists=stats.assists,
+                yellow_cards=stats.yellow_cards,
+                red_cards=stats.red_cards,
+                source=stats.source or board.match.source,
+                source_url=board.match.source_url,
+            )
+
+        return None
+
+    def player_history(
+        self,
+        player: str,
+        competition: str | None = None,
+        season: str | None = None,
+    ) -> PlayerHistory:
+        appearances: list[PlayerMatchAppearance] = []
+        player_model = Player(name=player)
+
+        for board in self.scoreboards(competition=competition, season=season):
+            appearance = self._appearance_from_stats(board, player)
+            if appearance is None:
+                continue
+
+            appearances.append(appearance)
+            for stats in board.player_stats:
+                if stats.player.name.casefold() == player.casefold():
+                    player_model = stats.player
+                    break
+
+        totals = PlayerTotals(
+            appearances=len(appearances),
+            starts=sum(1 for item in appearances if item.started is True),
+            minutes_played=sum(item.minutes_played or 0 for item in appearances),
+            goals=sum(item.goals for item in appearances),
+            assists=sum(item.assists for item in appearances),
+            yellow_cards=sum(item.yellow_cards for item in appearances),
+            red_cards=sum(item.red_cards for item in appearances),
+        )
+
+        notes = []
+        if not appearances:
+            notes.append("No player-level appearances found in this JSON source.")
+
+        return PlayerHistory(
+            player=player_model,
+            totals=totals,
+            appearances=appearances,
+            source_notes=notes,
+        )

openmatchkit/sources/openfootball.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+from hashlib import sha1
+from typing import Any
+
+from openmatchkit.exceptions import ParseError
+from openmatchkit.http import SafeHttpClient
+from openmatchkit.models import Match, MatchStatus, Player, PlayerHistory, Score, Scoreboard, Team
+
+
+class OpenFootballSource:
+    """Adapter for OpenFootball JSON datasets."""
+
+    name = "openfootball"
+
+    WORLD_CUP_ALIASES = {
+        "fifa-world-cup",
+        "fifa_world_cup",
+        "world-cup",
+        "world_cup",
+        "worldcup",
+    }
+
+    def __init__(
+        self,
+        http: SafeHttpClient | None = None,
+        league_base_url: str = "https://raw.githubusercontent.com/openfootball/football.json/master",
+        worldcup_base_url: str = "https://raw.githubusercontent.com/openfootball/worldcup.json/master",
+    ) -> None:
+        self.http = http or SafeHttpClient()
+        self.league_base_url = league_base_url.rstrip("/")
+        self.worldcup_base_url = worldcup_base_url.rstrip("/")
+
+    def _make_id(self, *parts: object) -> str:
+        raw = "|".join(str(part) for part in parts)
+        return sha1(raw.encode("utf-8")).hexdigest()[:16]
+
+    def dataset_url(self, competition: str, season: str) -> str:
+        normalized = competition.strip().lower()
+
+        if normalized in self.WORLD_CUP_ALIASES:
+            return f"{self.worldcup_base_url}/{season}/worldcup.json"
+
+        return f"{self.league_base_url}/{season}/{competition}.json"
+
+    def league_json(self, season: str, league_code: str) -> dict[str, Any]:
+        url = self.dataset_url(competition=league_code, season=season)
+        data = self.http.get_json(url)
+
+        if not isinstance(data, dict):
+            raise ParseError(f"Expected JSON object from {url}")
+
+        return data
+
+    def _parse_kickoff(
+        self, date_value: object, time_value: object | None = None
+    ) -> datetime | None:
+        if not date_value:
+            return None
+
+        date_text = str(date_value).strip()
+        time_text = str(time_value).strip() if time_value else ""
+
+        if not time_text:
+            try:
+                return datetime.fromisoformat(date_text)
+            except ValueError:
+                return None
+
+        tzinfo = None
+        time_part = time_text
+        match = re.search(r"UTC\s*([+-]\d{1,2})(?::?(\d{2}))?", time_text)
+        if match:
+            hours = int(match.group(1))
+            minutes = int(match.group(2) or "0")
+            sign = 1 if hours >= 0 else -1
+            tzinfo = timezone(timedelta(hours=hours, minutes=sign * minutes))
+            time_part = time_text.split("UTC", 1)[0].strip()
+
+        try:
+            parsed = datetime.fromisoformat(f"{date_text}T{time_part}")
+        except ValueError:
+            return None
+
+        if tzinfo is not None:
+            parsed = parsed.replace(tzinfo=tzinfo)
+
+        return parsed
+
+    def _score_from_item(self, item: dict[str, Any]) -> tuple[Score, MatchStatus]:
+        score_data = item.get("score") or {}
+        ft_score = score_data.get("ft") if isinstance(score_data, dict) else None
+
+        if not isinstance(ft_score, list) or len(ft_score) < 2:
+            return Score(), MatchStatus.SCHEDULED
+
+        home, away = ft_score[0], ft_score[1]
+        if home is None or away is None:
+            return Score(), MatchStatus.SCHEDULED
+
+        try:
+            return Score(home=int(home), away=int(away)), MatchStatus.FULL_TIME
+        except (TypeError, ValueError):
+            return Score(), MatchStatus.UNKNOWN
+
+    def parse_matches(
+        self,
+        data: dict[str, Any],
+        *,
+        source_url: str,
+        competition: str,
+        season: str,
+        fetched_at: datetime | None = None,
+    ) -> list[Match]:
+        fetched = fetched_at or datetime.now(timezone.utc)
+        raw_matches = data.get("matches", [])
+
+        if not isinstance(raw_matches, list):
+            raise ParseError("OpenFootball JSON did not contain a list at 'matches'.")
+
+        competition_name = str(data.get("name") or competition)
+        matches: list[Match] = []
+
+        for item in raw_matches:
+            if not isinstance(item, dict):
+                continue
+
+            home_name = item.get("team1")
+            away_name = item.get("team2")
+            if not home_name or not away_name:
+                continue
+
+            score, status = self._score_from_item(item)
+            kickoff = self._parse_kickoff(item.get("date"), item.get("time"))
+
+            match_id = self._make_id(
+                self.name,
+                competition_name,
+                season,
+                item.get("round"),
+                item.get("group"),
+                item.get("date"),
+                item.get("time"),
+                home_name,
+                away_name,
+            )
+
+            matches.append(
+                Match(
+                    match_id=match_id,
+                    competition=competition_name,
+                    season=season,
+                    round=item.get("round") or item.get("stage"),
+                    group=item.get("group"),
+                    kickoff=kickoff,
+                    home=Team(name=str(home_name)),
+                    away=Team(name=str(away_name)),
+                    score=score,
+                    status=status,
+                    venue=item.get("ground") or item.get("venue"),
+                    source=self.name,
+                    source_url=source_url,
+                    fetched_at=fetched,
+                )
+            )
+
+        return matches
+
+    def fixtures(self, competition: str, season: str | None = None) -> list[Match]:
+        if season is None:
+            raise ValueError("OpenFootball fixtures require a season, for example '2026'.")
+
+        url = self.dataset_url(competition=competition, season=season)
+        data = self.league_json(season=season, league_code=competition)
+        return self.parse_matches(data, source_url=url, competition=competition, season=season)
+
+    def live_scores(self) -> list[Match]:
+        return []
+
+    def scoreboard(
+        self,
+        match_id: str,
+        competition: str | None = None,
+        season: str | None = None,
+    ) -> Scoreboard | None:
+        if competition is None or season is None:
+            raise ValueError("OpenFootball scoreboard lookup requires competition and season.")
+
+        for match in self.fixtures(competition=competition, season=season):
+            if match.match_id == match_id:
+                return Scoreboard(
+                    match=match,
+                    source_notes=[
+                        "OpenFootball provides fixtures/results only for this match.",
+                        "Player stats, lineups, detailed events, and live clock are not available from this source.",
+                    ],
+                )
+        return None
+
+    def scoreboards(
+        self,
+        competition: str | None = None,
+        season: str | None = None,
+    ) -> list[Scoreboard]:
+        if competition is None or season is None:
+            raise ValueError("OpenFootball scoreboards require competition and season.")
+
+        return [
+            Scoreboard(
+                match=match,
+                source_notes=[
+                    "OpenFootball provides fixtures/results only for this match.",
+                    "Player stats, lineups, detailed events, and live clock are not available from this source.",
+                ],
+            )
+            for match in self.fixtures(competition=competition, season=season)
+        ]
+
+    def live_scoreboards(self) -> list[Scoreboard]:
+        return []
+
+    def player_history(
+        self,
+        player: str,
+        competition: str | None = None,
+        season: str | None = None,
+    ) -> PlayerHistory:
+        return PlayerHistory(
+            player=Player(name=player),
+            source_notes=[
+                "OpenFootball does not provide player-level match histories in this adapter."
+            ],
+        )

openmatchkit/sources/public_html.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime, timezone
+
+from bs4 import BeautifulSoup
+
+from openmatchkit.http import SafeHttpClient
+from openmatchkit.models import Match
+
+HtmlParser = Callable[[BeautifulSoup, str, datetime], list[Match]]
+
+
+class PublicHtmlSource:
+    """Generic public HTML adapter.
+
+    It is intentionally parser-driven. Site-specific parsers should live in
+    optional modules and include source-specific policy notes and fixture tests.
+    """
+
+    name = "public_html"
+
+    def __init__(
+        self,
+        url: str,
+        parser: HtmlParser,
+        http: SafeHttpClient | None = None,
+        min_delay_seconds: float = 60.0,
+    ) -> None:
+        self.url = url
+        self.parser = parser
+        self.http = http or SafeHttpClient(min_delay_seconds=min_delay_seconds)
+
+    def live_scores(self) -> list[Match]:
+        html = self.http.get_text(self.url)
+        soup = BeautifulSoup(html, "lxml")
+        fetched_at = datetime.now(timezone.utc)
+        return self.parser(soup, self.url, fetched_at)
+
+    def fixtures(self, competition: str, season: str | None = None) -> list[Match]:
+        return self.live_scores()