openmatchkit 0.2.1__py3-none-any.whl

openmatchkit/export.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import csv
+import json
+from io import StringIO
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from openmatchkit.models import Match
+
+
+def matches_to_rows(matches: list[Match]) -> list[dict[str, object]]:
+    rows: list[dict[str, object]] = []
+
+    for match in matches:
+        rows.append(
+            {
+                "match_id": match.match_id,
+                "competition": match.competition,
+                "season": match.season,
+                "round": match.round,
+                "group": match.group,
+                "kickoff": match.kickoff.isoformat() if match.kickoff else None,
+                "home": match.home.name,
+                "away": match.away.name,
+                "home_score": match.score.home,
+                "away_score": match.score.away,
+                "status": match.status.value,
+                "venue": match.venue,
+                "source": match.source,
+                "source_url": match.source_url,
+                "fetched_at": match.fetched_at.isoformat() if match.fetched_at else None,
+            }
+        )
+
+    return rows
+
+
+def to_json_string(matches: list[Match]) -> str:
+    payload = [match.model_dump(mode="json") for match in matches]
+    return json.dumps(payload, indent=2)
+
+
+def to_model_json_string(value: BaseModel | list[BaseModel] | dict[str, Any] | list[Any]) -> str:
+    if isinstance(value, BaseModel):
+        payload: Any = value.model_dump(mode="json")
+    elif isinstance(value, list):
+        payload = [
+            item.model_dump(mode="json") if isinstance(item, BaseModel) else item for item in value
+        ]
+    else:
+        payload = value
+
+    return json.dumps(payload, indent=2)
+
+
+def to_csv_string(matches: list[Match]) -> str:
+    rows = matches_to_rows(matches)
+    fieldnames = [
+        "match_id",
+        "competition",
+        "season",
+        "round",
+        "group",
+        "kickoff",
+        "home",
+        "away",
+        "home_score",
+        "away_score",
+        "status",
+        "venue",
+        "source",
+        "source_url",
+        "fetched_at",
+    ]
+    output = StringIO()
+    writer = csv.DictWriter(output, fieldnames=fieldnames)
+    writer.writeheader()
+    writer.writerows(rows)
+    return output.getvalue()
+
+
+def to_json(matches: list[Match], path: str | Path) -> Path:
+    target = Path(path)
+    target.write_text(to_json_string(matches), encoding="utf-8")
+    return target
+
+
+def to_csv(matches: list[Match], path: str | Path) -> Path:
+    target = Path(path)
+    target.write_text(to_csv_string(matches), encoding="utf-8", newline="")
+    return target

openmatchkit/http.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from urllib.parse import urlparse
+from urllib.robotparser import RobotFileParser
+
+import httpx
+
+from openmatchkit.exceptions import SourceFetchError, SourceNotAllowedError
+
+
+@dataclass
+class _RobotsEntry:
+    parser: RobotFileParser
+    fetched_at: datetime
+
+
+@dataclass
+class _CacheEntry:
+    body: str
+    fetched_at: datetime
+
+
+@dataclass
+class SafeHttpClient:
+    """HTTP client with conservative scraping defaults.
+
+    It respects robots.txt, keeps an in-memory cache, applies per-origin delays,
+    and never attempts to bypass login, CAPTCHA, paywalls, or other protections.
+    """
+
+    user_agent: str = "openmatchkit/0.2.1 (+https://github.com/patilprashan246/openmatchkit)"
+    min_delay_seconds: float = 2.0
+    timeout_seconds: float = 20.0
+    respect_robots: bool = True
+    cache_ttl_seconds: float = 300.0
+    robots_ttl_seconds: float = 24 * 60 * 60
+    transport: httpx.BaseTransport | None = field(default=None, repr=False)
+
+    _client: httpx.Client = field(init=False, repr=False)
+    _last_request_at: dict[str, float] = field(default_factory=dict, init=False, repr=False)
+    _robots_cache: dict[str, _RobotsEntry] = field(default_factory=dict, init=False, repr=False)
+    _response_cache: dict[str, _CacheEntry] = field(default_factory=dict, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._client = httpx.Client(
+            timeout=self.timeout_seconds,
+            headers={"User-Agent": self.user_agent},
+            follow_redirects=True,
+            transport=self.transport,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> SafeHttpClient:
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()
+
+    def _origin(self, url: str) -> str:
+        parsed = urlparse(url)
+        return f"{parsed.scheme}://{parsed.netloc}"
+
+    def _robots_url(self, url: str) -> str:
+        return f"{self._origin(url)}/robots.txt"
+
+    def _allow_all_robots(self, robots_url: str) -> RobotFileParser:
+        parser = RobotFileParser(robots_url)
+        parser.parse([])
+        return parser
+
+    def _block_all_robots(self, robots_url: str) -> RobotFileParser:
+        parser = RobotFileParser(robots_url)
+        parser.parse(["User-agent: *", "Disallow: /"])
+        return parser
+
+    def _get_robots(self, url: str) -> RobotFileParser:
+        origin = self._origin(url)
+        now = datetime.now(timezone.utc)
+        cached = self._robots_cache.get(origin)
+
+        if cached and now - cached.fetched_at < timedelta(seconds=self.robots_ttl_seconds):
+            return cached.parser
+
+        robots_url = self._robots_url(url)
+
+        try:
+            response = self._client.get(robots_url)
+        except httpx.HTTPError:
+            parser = self._block_all_robots(robots_url)
+        else:
+            if response.status_code == 404:
+                parser = self._allow_all_robots(robots_url)
+            elif response.status_code in {401, 403} or response.status_code >= 500:
+                parser = self._block_all_robots(robots_url)
+            elif response.status_code >= 400:
+                parser = self._allow_all_robots(robots_url)
+            else:
+                parser = RobotFileParser(robots_url)
+                parser.parse(response.text.splitlines())
+
+        self._robots_cache[origin] = _RobotsEntry(parser=parser, fetched_at=now)
+        return parser
+
+    def _ensure_allowed(self, url: str) -> None:
+        if not self.respect_robots:
+            return
+
+        robots = self._get_robots(url)
+        if not robots.can_fetch(self.user_agent, url):
+            raise SourceNotAllowedError(f"Blocked by robots.txt: {url}")
+
+    def _rate_limit(self, url: str) -> None:
+        origin = self._origin(url)
+        now = time.monotonic()
+        last = self._last_request_at.get(origin)
+
+        if last is not None:
+            elapsed = now - last
+            wait_time = self.min_delay_seconds - elapsed
+            if wait_time > 0:
+                time.sleep(wait_time)
+
+        self._last_request_at[origin] = time.monotonic()
+
+    def _cache_key(self, url: str) -> str:
+        return f"GET {url}"
+
+    def _cache_get(self, url: str) -> str | None:
+        if self.cache_ttl_seconds <= 0:
+            return None
+
+        entry = self._response_cache.get(self._cache_key(url))
+        if entry is None:
+            return None
+
+        now = datetime.now(timezone.utc)
+        if now - entry.fetched_at >= timedelta(seconds=self.cache_ttl_seconds):
+            self._response_cache.pop(self._cache_key(url), None)
+            return None
+
+        return entry.body
+
+    def _cache_set(self, url: str, body: str) -> None:
+        if self.cache_ttl_seconds <= 0:
+            return
+
+        self._response_cache[self._cache_key(url)] = _CacheEntry(
+            body=body,
+            fetched_at=datetime.now(timezone.utc),
+        )
+
+    def get_text(self, url: str) -> str:
+        cached = self._cache_get(url)
+        if cached is not None:
+            return cached
+
+        self._ensure_allowed(url)
+        self._rate_limit(url)
+
+        try:
+            response = self._client.get(url)
+            response.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise SourceFetchError(f"Failed to fetch {url}: {exc}") from exc
+
+        self._cache_set(url, response.text)
+        return response.text
+
+    def get_json(self, url: str) -> object:
+        text = self.get_text(url)
+
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise SourceFetchError(f"Failed to parse JSON from {url}: {exc}") from exc

openmatchkit/models.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class MatchStatus(str, Enum):
+    SCHEDULED = "scheduled"
+    LIVE = "live"
+    HALF_TIME = "half_time"
+    FULL_TIME = "full_time"
+    POSTPONED = "postponed"
+    CANCELLED = "cancelled"
+    UNKNOWN = "unknown"
+
+
+class Team(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    name: str = Field(min_length=1)
+    code: str | None = None
+    country: str | None = None
+
+
+class TeamInfo(BaseModel):
+    name: str
+    code: str | None = None
+    country: str | None = None
+    appearances: int = 0
+    sources: list[str] = Field(default_factory=list)
+
+
+class Player(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    name: str = Field(min_length=1)
+    player_id: str | None = None
+    team: str | None = None
+    position: str | None = None
+    shirt_number: int | None = None
+    country: str | None = None
+
+
+class Score(BaseModel):
+    home: int | None = None
+    away: int | None = None
+
+
+class Match(BaseModel):
+    match_id: str
+    competition: str
+    season: str | None = None
+    round: str | None = None
+    group: str | None = None
+    kickoff: datetime | None = None
+    home: Team
+    away: Team
+    score: Score = Field(default_factory=Score)
+    status: MatchStatus = MatchStatus.UNKNOWN
+    venue: str | None = None
+    source: str
+    source_url: str | None = None
+    fetched_at: datetime | None = None
+
+
+class StandingRow(BaseModel):
+    team: str
+    group: str | None = None
+    played: int = 0
+    won: int = 0
+    drawn: int = 0
+    lost: int = 0
+    goals_for: int = 0
+    goals_against: int = 0
+    goal_difference: int = 0
+    points: int = 0
+
+
+class MatchClock(BaseModel):
+    minute: int | None = None
+    added_time: int | None = None
+    period: str | None = None
+    display: str | None = None
+
+
+class MatchEvent(BaseModel):
+    event_type: str
+    team: str | None = None
+    player: str | None = None
+    assist: str | None = None
+    minute: int | None = None
+    added_time: int | None = None
+    detail: str | None = None
+    home_score: int | None = None
+    away_score: int | None = None
+
+
+class TeamMatchStats(BaseModel):
+    team: str
+    possession: float | None = None
+    shots: int | None = None
+    shots_on_target: int | None = None
+    corners: int | None = None
+    fouls: int | None = None
+    offsides: int | None = None
+    yellow_cards: int | None = None
+    red_cards: int | None = None
+    saves: int | None = None
+    passes: int | None = None
+    pass_accuracy: float | None = None
+    expected_goals: float | None = None
+
+
+class PlayerMatchStats(BaseModel):
+    player: Player
+    started: bool | None = None
+    minutes_played: int | None = None
+    goals: int = 0
+    assists: int = 0
+    yellow_cards: int = 0
+    red_cards: int = 0
+    shots: int | None = None
+    shots_on_target: int | None = None
+    saves: int | None = None
+    passes: int | None = None
+    tackles: int | None = None
+    rating: float | None = None
+    source: str | None = None
+
+
+class TeamLineup(BaseModel):
+    team: Team
+    formation: str | None = None
+    coach: str | None = None
+    starters: list[Player] = Field(default_factory=list)
+    substitutes: list[Player] = Field(default_factory=list)
+
+
+class Scoreboard(BaseModel):
+    match: Match
+    clock: MatchClock = Field(default_factory=MatchClock)
+    team_stats: list[TeamMatchStats] = Field(default_factory=list)
+    lineups: list[TeamLineup] = Field(default_factory=list)
+    events: list[MatchEvent] = Field(default_factory=list)
+    player_stats: list[PlayerMatchStats] = Field(default_factory=list)
+    source_notes: list[str] = Field(default_factory=list)
+
+
+class PlayerTotals(BaseModel):
+    appearances: int = 0
+    starts: int = 0
+    minutes_played: int = 0
+    goals: int = 0
+    assists: int = 0
+    yellow_cards: int = 0
+    red_cards: int = 0
+
+
+class PlayerMatchAppearance(BaseModel):
+    match_id: str
+    competition: str
+    season: str | None = None
+    kickoff: datetime | None = None
+    team: str
+    opponent: str | None = None
+    home_away: Literal["home", "away", "neutral", "unknown"] = "unknown"
+    status: MatchStatus = MatchStatus.UNKNOWN
+    minutes_played: int | None = None
+    started: bool | None = None
+    goals: int = 0
+    assists: int = 0
+    yellow_cards: int = 0
+    red_cards: int = 0
+    source: str
+    source_url: str | None = None
+
+
+class PlayerHistory(BaseModel):
+    player: Player
+    totals: PlayerTotals = Field(default_factory=PlayerTotals)
+    appearances: list[PlayerMatchAppearance] = Field(default_factory=list)
+    source_notes: list[str] = Field(default_factory=list)
+
+
+class Prediction(BaseModel):
+    home: str
+    away: str
+    home_win_probability: float
+    draw_probability: float
+    away_win_probability: float
+    expected_home_goals: float
+    expected_away_goals: float
+    model: str
+    training_matches: int = 0
+    note: str = "Educational baseline only. Not betting, financial, or professional advice."

openmatchkit/prediction/__init__.py

@@ -0,0 +1,7 @@
+from openmatchkit.prediction.elo import EloRatings
+from openmatchkit.prediction.poisson import SimplePoissonPredictor
+
+__all__ = [
+    "EloRatings",
+    "SimplePoissonPredictor",
+]

openmatchkit/prediction/elo.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from openmatchkit.models import Match
+
+
+class EloRatings:
+    """Small Elo baseline for team strength summaries."""
+
+    def __init__(self, default_rating: float = 1500.0, k_factor: float = 24.0) -> None:
+        self.default_rating = default_rating
+        self.k_factor = k_factor
+        self.ratings: dict[str, float] = {}
+
+    def rating(self, team: str) -> float:
+        return self.ratings.get(team, self.default_rating)
+
+    def _expected(self, team: str, opponent: str) -> float:
+        return 1 / (1 + 10 ** ((self.rating(opponent) - self.rating(team)) / 400))
+
+    def _actual_scores(self, match: Match) -> tuple[float, float] | None:
+        if match.score.home is None or match.score.away is None:
+            return None
+
+        if match.score.home > match.score.away:
+            return 1.0, 0.0
+        if match.score.home < match.score.away:
+            return 0.0, 1.0
+        return 0.5, 0.5
+
+    def fit(self, matches: list[Match]) -> None:
+        for match in matches:
+            actual = self._actual_scores(match)
+            if actual is None:
+                continue
+
+            home = match.home.name
+            away = match.away.name
+            home_actual, away_actual = actual
+            home_expected = self._expected(home, away)
+            away_expected = self._expected(away, home)
+
+            self.ratings[home] = self.rating(home) + self.k_factor * (home_actual - home_expected)
+            self.ratings[away] = self.rating(away) + self.k_factor * (away_actual - away_expected)

openmatchkit/prediction/poisson.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+
+from openmatchkit.models import Match, Prediction
+
+
+class SimplePoissonPredictor:
+    """Educational Poisson baseline for win/draw/loss probabilities."""
+
+    def __init__(self, max_goals: int = 8) -> None:
+        self.max_goals = max_goals
+        self.team_for_goals: dict[str, float] = {}
+        self.team_against_goals: dict[str, float] = {}
+        self.global_home_goals = 1.35
+        self.global_away_goals = 1.10
+        self.training_matches = 0
+
+    def fit(self, matches: list[Match]) -> None:
+        scored = [m for m in matches if m.score.home is not None and m.score.away is not None]
+        self.training_matches = len(scored)
+
+        if not scored:
+            return
+
+        home_goals = sum(m.score.home or 0 for m in scored)
+        away_goals = sum(m.score.away or 0 for m in scored)
+
+        self.global_home_goals = home_goals / len(scored)
+        self.global_away_goals = away_goals / len(scored)
+
+        goals_for: dict[str, list[int]] = defaultdict(list)
+        goals_against: dict[str, list[int]] = defaultdict(list)
+
+        for match in scored:
+            home = match.home.name
+            away = match.away.name
+            hg = match.score.home or 0
+            ag = match.score.away or 0
+
+            goals_for[home].append(hg)
+            goals_against[home].append(ag)
+            goals_for[away].append(ag)
+            goals_against[away].append(hg)
+
+        self.team_for_goals = {
+            team: sum(values) / len(values) for team, values in goals_for.items()
+        }
+        self.team_against_goals = {
+            team: sum(values) / len(values) for team, values in goals_against.items()
+        }
+
+    def _poisson(self, goals: int, expected: float) -> float:
+        return (expected**goals) * math.exp(-expected) / math.factorial(goals)
+
+    def _expected_goals(self, home: str, away: str) -> tuple[float, float]:
+        home_attack = self.team_for_goals.get(home, self.global_home_goals)
+        away_defense = self.team_against_goals.get(away, self.global_home_goals)
+
+        away_attack = self.team_for_goals.get(away, self.global_away_goals)
+        home_defense = self.team_against_goals.get(home, self.global_away_goals)
+
+        expected_home = max(0.2, (home_attack + away_defense) / 2)
+        expected_away = max(0.2, (away_attack + home_defense) / 2)
+
+        return expected_home, expected_away
+
+    def predict(self, home: str, away: str) -> Prediction:
+        expected_home, expected_away = self._expected_goals(home, away)
+
+        home_win = 0.0
+        draw = 0.0
+        away_win = 0.0
+
+        for hg in range(self.max_goals + 1):
+            for ag in range(self.max_goals + 1):
+                probability = self._poisson(hg, expected_home) * self._poisson(ag, expected_away)
+
+                if hg > ag:
+                    home_win += probability
+                elif hg == ag:
+                    draw += probability
+                else:
+                    away_win += probability
+
+        total = home_win + draw + away_win
+
+        return Prediction(
+            home=home,
+            away=away,
+            home_win_probability=home_win / total,
+            draw_probability=draw / total,
+            away_win_probability=away_win / total,
+            expected_home_goals=expected_home,
+            expected_away_goals=expected_away,
+            model="simple_poisson",
+            training_matches=self.training_matches,
+        )

openmatchkit/sources/__init__.py

@@ -0,0 +1,11 @@
+from openmatchkit.sources.football_data_uk import FootballDataUkSource
+from openmatchkit.sources.json_file import JsonFileSource
+from openmatchkit.sources.openfootball import OpenFootballSource
+from openmatchkit.sources.public_html import PublicHtmlSource
+
+__all__ = [
+    "FootballDataUkSource",
+    "JsonFileSource",
+    "OpenFootballSource",
+    "PublicHtmlSource",
+]

openmatchkit/sources/base.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from openmatchkit.models import Match, PlayerHistory, Scoreboard
+
+
+class MatchSource(Protocol):
+    name: str
+
+    def fixtures(self, competition: str, season: str | None = None) -> list[Match]: ...
+
+    def live_scores(self) -> list[Match]: ...
+
+    def scoreboard(
+        self,
+        match_id: str,
+        competition: str | None = None,
+        season: str | None = None,
+    ) -> Scoreboard | None: ...
+
+    def live_scoreboards(self) -> list[Scoreboard]: ...
+
+    def player_history(
+        self,
+        player: str,
+        competition: str | None = None,
+        season: str | None = None,
+    ) -> PlayerHistory: ...