openmatchkit 0.2.1__py3-none-any.whl

openmatchkit/__init__.py

@@ -0,0 +1,41 @@
+from openmatchkit.client import MatchClient
+from openmatchkit.models import (
+    Match,
+    MatchClock,
+    MatchEvent,
+    MatchStatus,
+    Player,
+    PlayerHistory,
+    PlayerMatchAppearance,
+    PlayerMatchStats,
+    PlayerTotals,
+    Prediction,
+    Score,
+    Scoreboard,
+    StandingRow,
+    Team,
+    TeamInfo,
+    TeamLineup,
+    TeamMatchStats,
+)
+
+__all__ = [
+    "MatchClient",
+    "Match",
+    "MatchClock",
+    "MatchEvent",
+    "MatchStatus",
+    "Player",
+    "PlayerHistory",
+    "PlayerMatchAppearance",
+    "PlayerMatchStats",
+    "PlayerTotals",
+    "Prediction",
+    "Score",
+    "Scoreboard",
+    "StandingRow",
+    "Team",
+    "TeamInfo",
+    "TeamLineup",
+    "TeamMatchStats",
+]

openmatchkit/cli.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+import typer
+
+from openmatchkit.client import MatchClient
+from openmatchkit.export import (
+    to_csv,
+    to_csv_string,
+    to_json,
+    to_json_string,
+    to_model_json_string,
+)
+from openmatchkit.models import Match
+from openmatchkit.sources.json_file import JsonFileSource
+
+app = typer.Typer(help="Unofficial football public-data CLI.")
+
+
+def _client(data_file: Path | None = None) -> MatchClient:
+    if data_file is not None:
+        return MatchClient(sources=[JsonFileSource(data_file)])
+    return MatchClient()
+
+
+def _emit_matches(matches: list[Match], output_format: str, output: Path | None) -> None:
+    if output_format == "csv":
+        if output:
+            to_csv(matches, output)
+            typer.echo(str(output))
+        else:
+            typer.echo(to_csv_string(matches))
+        return
+
+    if output:
+        to_json(matches, output)
+        typer.echo(str(output))
+    else:
+        typer.echo(to_json_string(matches))
+
+
+@app.command()
+def fixtures(
+    competition: str = typer.Option(..., help="Example: worldcup or en.1"),
+    season: str = typer.Option(..., help="Example: 2026 or 2015-16"),
+    output_format: str = typer.Option("json", "--format", help="json or csv"),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Write to a file."),
+) -> None:
+    """Fetch fixtures and results from configured public sources."""
+
+    client = MatchClient()
+    matches = client.fixtures(competition=competition, season=season)
+    _emit_matches(matches, output_format.lower(), output)
+
+
+@app.command()
+def results(
+    competition: str = typer.Option(..., help="Example: worldcup or en.1"),
+    season: str = typer.Option(..., help="Example: 2026 or 2015-16"),
+    output_format: str = typer.Option("json", "--format", help="json or csv"),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Write to a file."),
+) -> None:
+    """Fetch completed matches from configured public sources."""
+
+    client = MatchClient()
+    matches = client.results(competition=competition, season=season)
+    _emit_matches(matches, output_format.lower(), output)
+
+
+@app.command()
+def live() -> None:
+    """Show best-effort live scores from configured live adapters."""
+
+    client = MatchClient()
+    matches = client.live_scores()
+    typer.echo(to_json_string(matches))
+
+
+@app.command()
+def live_scoreboards(
+    data_file: Path | None = typer.Option(None, "--data-file", help="Optional detailed JSON file."),
+) -> None:
+    """Show live scoreboards with any detailed fields provided by the source."""
+
+    client = _client(data_file)
+    boards = client.live_scoreboards()
+    typer.echo(to_model_json_string(boards))
+
+
+@app.command()
+def next_match(
+    competition: str = typer.Option(..., help="Example: worldcup or en.1"),
+    season: str = typer.Option(..., help="Example: 2026 or 2015-16"),
+) -> None:
+    """Show the next scheduled match from fixture data."""
+
+    client = MatchClient()
+    match = client.next_match(
+        competition=competition,
+        season=season,
+        after=datetime.now(timezone.utc),
+    )
+    typer.echo(to_model_json_string(match.model_dump(mode="json") if match else {}))
+
+
+@app.command()
+def scoreboards(
+    competition: str | None = typer.Option(None, help="Optional competition filter."),
+    season: str | None = typer.Option(None, help="Optional season filter."),
+    data_file: Path | None = typer.Option(None, "--data-file", help="Optional detailed JSON file."),
+) -> None:
+    """Return all available scoreboard details as JSON."""
+
+    client = _client(data_file)
+    boards = client.scoreboards(competition=competition, season=season)
+    typer.echo(to_model_json_string(boards))
+
+
+@app.command()
+def scoreboard(
+    match_id: str = typer.Option(..., help="Match ID from fixtures or scoreboards output."),
+    competition: str | None = typer.Option(None, help="Optional competition filter."),
+    season: str | None = typer.Option(None, help="Optional season filter."),
+    data_file: Path | None = typer.Option(None, "--data-file", help="Optional detailed JSON file."),
+) -> None:
+    """Return one scoreboard with match, events, lineups, stats, and player details."""
+
+    client = _client(data_file)
+    board = client.scoreboard(match_id=match_id, competition=competition, season=season)
+    if board is None:
+        typer.echo("{}")
+        raise typer.Exit(code=1)
+    typer.echo(to_model_json_string(board))
+
+
+@app.command()
+def player_history(
+    player: str = typer.Option(..., help="Player name."),
+    competition: str | None = typer.Option(None, help="Optional competition filter."),
+    season: str | None = typer.Option(None, help="Optional season filter."),
+    data_file: Path | None = typer.Option(None, "--data-file", help="Optional detailed JSON file."),
+) -> None:
+    """Return public player match history details provided by configured sources."""
+
+    client = _client(data_file)
+    history = client.player_history(player=player, competition=competition, season=season)
+    typer.echo(to_model_json_string(history))
+
+
+@app.command()
+def standings(
+    competition: str = typer.Option(..., help="Example: worldcup or en.1"),
+    season: str = typer.Option(..., help="Example: 2026 or 2015-16"),
+    group: str | None = typer.Option(None, help="Optional group name."),
+) -> None:
+    """Build a simple points table from full-time results."""
+
+    client = MatchClient()
+    rows = client.standings(competition=competition, season=season, group=group)
+    payload = [row.model_dump(mode="json") for row in rows]
+    typer.echo(json.dumps(payload, indent=2))
+
+
+@app.command()
+def predict(
+    home: str = typer.Option(...),
+    away: str = typer.Option(...),
+    competition: str | None = typer.Option(None, help="Optional history competition."),
+    season: str | None = typer.Option(None, help="Optional history season."),
+) -> None:
+    """Run the educational Poisson baseline."""
+
+    client = MatchClient()
+    prediction = client.predict(home=home, away=away, competition=competition, season=season)
+    typer.echo(json.dumps(prediction.model_dump(mode="json"), indent=2))
+
+
+if __name__ == "__main__":
+    app()

openmatchkit/client.py

@@ -0,0 +1,405 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from openmatchkit.export import to_csv, to_json
+from openmatchkit.models import (
+    Match,
+    MatchStatus,
+    Player,
+    PlayerHistory,
+    PlayerTotals,
+    Prediction,
+    Scoreboard,
+    StandingRow,
+    TeamInfo,
+)
+from openmatchkit.prediction.poisson import SimplePoissonPredictor
+from openmatchkit.sources.openfootball import OpenFootballSource
+
+
+@dataclass(frozen=True)
+class SourceError:
+    source: str
+    operation: str
+    message: str
+
+
+class MatchClient:
+    """Main public client for fixtures, results, standings, prediction, and export."""
+
+    def __init__(self, sources: list[object] | None = None, *, strict: bool = False) -> None:
+        self.sources = sources if sources is not None else [OpenFootballSource()]
+        self.strict = strict
+        self.last_errors: list[SourceError] = []
+
+    def _matching_sources(self, source: str | None = None) -> list[object]:
+        if source is None:
+            return list(self.sources)
+        return [
+            candidate for candidate in self.sources if getattr(candidate, "name", None) == source
+        ]
+
+    def _record_error(self, source: object, operation: str, exc: Exception) -> None:
+        error = SourceError(
+            source=str(getattr(source, "name", source.__class__.__name__)),
+            operation=operation,
+            message=str(exc),
+        )
+        self.last_errors.append(error)
+
+        if self.strict:
+            raise exc
+
+    def _as_utc(self, value: datetime | None, *, default: datetime) -> datetime:
+        if value is None:
+            return default
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+
+    def fixtures(
+        self,
+        competition: str,
+        season: str | None = None,
+        *,
+        source: str | None = None,
+    ) -> list[Match]:
+        self.last_errors = []
+        results: list[Match] = []
+
+        for match_source in self._matching_sources(source):
+            fixtures = getattr(match_source, "fixtures", None)
+            if fixtures is None:
+                continue
+
+            try:
+                results.extend(fixtures(competition=competition, season=season))
+            except Exception as exc:  # pragma: no cover - strict mode re-raises this path
+                self._record_error(match_source, "fixtures", exc)
+
+        return sorted(results, key=lambda match: match.kickoff or match.match_id)
+
+    def results(
+        self,
+        competition: str,
+        season: str | None = None,
+        *,
+        source: str | None = None,
+    ) -> list[Match]:
+        return [
+            match
+            for match in self.fixtures(competition=competition, season=season, source=source)
+            if match.status == MatchStatus.FULL_TIME
+            or (match.score.home is not None and match.score.away is not None)
+        ]
+
+    def live_scores(self, *, source: str | None = None) -> list[Match]:
+        self.last_errors = []
+        results: list[Match] = []
+
+        for match_source in self._matching_sources(source):
+            live_scores = getattr(match_source, "live_scores", None)
+            if live_scores is None:
+                continue
+
+            try:
+                results.extend(live_scores())
+            except Exception as exc:  # pragma: no cover - strict mode re-raises this path
+                self._record_error(match_source, "live_scores", exc)
+
+        return results
+
+    def next_match(
+        self,
+        competition: str,
+        season: str | None = None,
+        *,
+        source: str | None = None,
+        after: datetime | None = None,
+    ) -> Match | None:
+        after_time = after or datetime.now(timezone.utc)
+        after_utc = self._as_utc(after_time, default=datetime.min.replace(tzinfo=timezone.utc))
+        upcoming = [
+            match
+            for match in self.fixtures(competition=competition, season=season, source=source)
+            if match.kickoff
+            and self._as_utc(
+                match.kickoff,
+                default=datetime.min.replace(tzinfo=timezone.utc),
+            )
+            >= after_utc
+        ]
+        upcoming.sort(
+            key=lambda match: self._as_utc(
+                match.kickoff,
+                default=datetime.max.replace(tzinfo=timezone.utc),
+            )
+        )
+        return upcoming[0] if upcoming else None
+
+    def scoreboards(
+        self,
+        competition: str | None = None,
+        season: str | None = None,
+        *,
+        source: str | None = None,
+    ) -> list[Scoreboard]:
+        self.last_errors = []
+        results: list[Scoreboard] = []
+
+        for match_source in self._matching_sources(source):
+            scoreboards = getattr(match_source, "scoreboards", None)
+            if scoreboards is not None:
+                try:
+                    results.extend(scoreboards(competition=competition, season=season))
+                    continue
+                except Exception as exc:  # pragma: no cover - strict mode re-raises this path
+                    self._record_error(match_source, "scoreboards", exc)
+                    continue
+
+            if competition is None:
+                continue
+
+            fixtures = getattr(match_source, "fixtures", None)
+            if fixtures is None:
+                continue
+
+            try:
+                for match in fixtures(competition=competition, season=season):
+                    results.append(
+                        Scoreboard(
+                            match=match,
+                            source_notes=[
+                                "This source returned match-level data only.",
+                                "Detailed events, lineups, team stats, and player stats are unavailable.",
+                            ],
+                        )
+                    )
+            except Exception as exc:  # pragma: no cover - strict mode re-raises this path
+                self._record_error(match_source, "scoreboards", exc)
+
+        return sorted(results, key=lambda board: board.match.kickoff or board.match.match_id)
+
+    def scoreboard(
+        self,
+        match_id: str,
+        competition: str | None = None,
+        season: str | None = None,
+        *,
+        source: str | None = None,
+    ) -> Scoreboard | None:
+        self.last_errors = []
+
+        for match_source in self._matching_sources(source):
+            scoreboard = getattr(match_source, "scoreboard", None)
+            if scoreboard is None:
+                continue
+
+            try:
+                board = scoreboard(match_id=match_id, competition=competition, season=season)
+            except Exception as exc:  # pragma: no cover - strict mode re-raises this path
+                self._record_error(match_source, "scoreboard", exc)
+                continue
+
+            if board is not None:
+                return board
+
+        for board in self.scoreboards(competition=competition, season=season, source=source):
+            if board.match.match_id == match_id:
+                return board
+
+        return None
+
+    def live_scoreboards(self, *, source: str | None = None) -> list[Scoreboard]:
+        self.last_errors = []
+        results: list[Scoreboard] = []
+
+        for match_source in self._matching_sources(source):
+            live_scoreboards = getattr(match_source, "live_scoreboards", None)
+            if live_scoreboards is not None:
+                try:
+                    results.extend(live_scoreboards())
+                    continue
+                except Exception as exc:  # pragma: no cover - strict mode re-raises this path
+                    self._record_error(match_source, "live_scoreboards", exc)
+                    continue
+
+            live_scores = getattr(match_source, "live_scores", None)
+            if live_scores is None:
+                continue
+
+            try:
+                for match in live_scores():
+                    results.append(
+                        Scoreboard(
+                            match=match,
+                            source_notes=[
+                                "This live source returned match-level score data only.",
+                                "Detailed events, lineups, team stats, and player stats are unavailable.",
+                            ],
+                        )
+                    )
+            except Exception as exc:  # pragma: no cover - strict mode re-raises this path
+                self._record_error(match_source, "live_scoreboards", exc)
+
+        return results
+
+    def player_history(
+        self,
+        player: str,
+        competition: str | None = None,
+        season: str | None = None,
+        *,
+        source: str | None = None,
+    ) -> PlayerHistory:
+        self.last_errors = []
+        merged = PlayerHistory(
+            player=Player(name=player),
+            source_notes=[
+                "Player history is available only from adapters that provide player-level public data."
+            ],
+        )
+
+        for match_source in self._matching_sources(source):
+            source_player_history = getattr(match_source, "player_history", None)
+            if source_player_history is None:
+                continue
+
+            try:
+                history = source_player_history(
+                    player=player,
+                    competition=competition,
+                    season=season,
+                )
+            except Exception as exc:  # pragma: no cover - strict mode re-raises this path
+                self._record_error(match_source, "player_history", exc)
+                continue
+
+            if history.appearances:
+                if not merged.appearances:
+                    merged.player = history.player
+                    merged.source_notes = []
+                merged.appearances.extend(history.appearances)
+            merged.source_notes.extend(history.source_notes)
+
+        merged.appearances.sort(
+            key=lambda item: self._as_utc(
+                item.kickoff,
+                default=datetime.min.replace(tzinfo=timezone.utc),
+            )
+        )
+        merged.totals = PlayerTotals(
+            appearances=len(merged.appearances),
+            starts=sum(1 for item in merged.appearances if item.started is True),
+            minutes_played=sum(item.minutes_played or 0 for item in merged.appearances),
+            goals=sum(item.goals for item in merged.appearances),
+            assists=sum(item.assists for item in merged.appearances),
+            yellow_cards=sum(item.yellow_cards for item in merged.appearances),
+            red_cards=sum(item.red_cards for item in merged.appearances),
+        )
+
+        return merged
+
+    def teams(
+        self,
+        competition: str,
+        season: str | None = None,
+        *,
+        source: str | None = None,
+    ) -> list[TeamInfo]:
+        teams: dict[str, TeamInfo] = {}
+
+        for match in self.fixtures(competition=competition, season=season, source=source):
+            for team in (match.home, match.away):
+                info = teams.setdefault(
+                    team.name,
+                    TeamInfo(name=team.name, code=team.code, country=team.country),
+                )
+                info.appearances += 1
+                if match.source not in info.sources:
+                    info.sources.append(match.source)
+
+        return sorted(teams.values(), key=lambda team: team.name.lower())
+
+    def standings(
+        self,
+        competition: str,
+        season: str | None = None,
+        *,
+        group: str | None = None,
+        source: str | None = None,
+    ) -> list[StandingRow]:
+        table: dict[tuple[str | None, str], StandingRow] = {}
+
+        def row_for(team: str, group_name: str | None) -> StandingRow:
+            key = (group_name, team)
+            if key not in table:
+                table[key] = StandingRow(team=team, group=group_name)
+            return table[key]
+
+        for match in self.results(competition=competition, season=season, source=source):
+            if group is not None and match.group != group:
+                continue
+            if match.score.home is None or match.score.away is None:
+                continue
+
+            home = row_for(match.home.name, match.group)
+            away = row_for(match.away.name, match.group)
+
+            home.played += 1
+            away.played += 1
+            home.goals_for += match.score.home
+            home.goals_against += match.score.away
+            away.goals_for += match.score.away
+            away.goals_against += match.score.home
+
+            if match.score.home > match.score.away:
+                home.won += 1
+                away.lost += 1
+                home.points += 3
+            elif match.score.home < match.score.away:
+                away.won += 1
+                home.lost += 1
+                away.points += 3
+            else:
+                home.drawn += 1
+                away.drawn += 1
+                home.points += 1
+                away.points += 1
+
+        for row in table.values():
+            row.goal_difference = row.goals_for - row.goals_against
+
+        return sorted(
+            table.values(),
+            key=lambda row: (-row.points, -row.goal_difference, -row.goals_for, row.team.lower()),
+        )
+
+    def predict(
+        self,
+        home: str,
+        away: str,
+        history: list[Match] | None = None,
+        *,
+        competition: str | None = None,
+        season: str | None = None,
+        source: str | None = None,
+    ) -> Prediction:
+        if history is None:
+            history = (
+                self.results(competition=competition, season=season, source=source)
+                if competition
+                else []
+            )
+
+        model = SimplePoissonPredictor()
+        model.fit(history)
+        return model.predict(home=home, away=away)
+
+    def export_json(self, matches: list[Match], path: str) -> None:
+        to_json(matches, path)
+
+    def export_csv(self, matches: list[Match], path: str) -> None:
+        to_csv(matches, path)

openmatchkit/exceptions.py

@@ -0,0 +1,14 @@
+class OpenMatchKitError(Exception):
+    """Base exception for openmatchkit."""
+
+
+class SourceNotAllowedError(OpenMatchKitError):
+    """Raised when a source is blocked by robots.txt or source policy."""
+
+
+class SourceFetchError(OpenMatchKitError):
+    """Raised when a source cannot be fetched."""
+
+
+class ParseError(OpenMatchKitError):
+    """Raised when a source response cannot be parsed."""