34class SofascoreClient:
 35    """
 36    Client for interacting with the Sofascore website.
 37    This class provides methods to access and retrieve data from Sofascore.
 38    """
 39
 40    def __init__(
 41        self,
 42        proxies: dict = None,
 43        use_playwright: bool = False,
 44        chrome_path: str = None,
 45        headless: bool = False,
 46    ) -> None:
 47        """
 48        Initializes the Sofascore client.
 49
 50        Args:
 51            proxies: Optional proxy dict.
 52            use_playwright: If True, falls back to a real browser (system
 53                Chrome) when curl_cffi is blocked by Sofascore's bot challenge.
 54            chrome_path: Optional path to Chrome executable.
 55            headless: Run the browser headless (silent). Some challenges detect
 56                headless, so headful is the default.
 57        """
 58        self.__service = SofascoreService(
 59            proxies=proxies,
 60            use_playwright=use_playwright,
 61            chrome_path=chrome_path,
 62            headless=headless,
 63        )
 64        _logger.debug("SofascoreClient initialized")
 65
 66    def get_events(self, date: str = "today", live: bool = False) -> list[Event]:
 67        """
 68        Get the scheduled events.
 69
 70        Args:
 71            date (str): The date of the events in the format "YYYY-MM-DD" or "today".
 72            live (bool): Whether to get the live events (more precise).
 73
 74        Returns:
 75            list[Event]: The scheduled events.
 76        """
 77        if live:
 78            return self.__service.get_live_events()
 79        return self.__service.get_events(date)
 80
 81    def get_event(self, event_id: int) -> Event:
 82        """
 83        Get the event information.
 84
 85        Args:
 86            event_id (int): The event id.
 87
 88        Returns:
 89            Event: The event information.
 90        """
 91        return self.__service.get_event(event_id)
 92
 93    def get_player(self, player_id: int) -> Player:
 94        """
 95        Get the player information.
 96
 97        Args:
 98            player_id (int): The player id.
 99
100        Returns:
101            Player: The player information.
102        """
103        return self.__service.get_player(player_id)
104
105    def get_match_incidents(self, event_id: int) -> list[Incident]:
106        """
107        Get the events of a match.
108
109        Args:
110            event_id (int): The event id.
111
112        Returns:
113            list[Incident]: The match incidents.
114        """
115        return self.__service.get_match_incidents(event_id)
116
117    def get_match_top_players(self, event_id: int) -> TopPlayersMatch:
118        """
119        Get the top players of a match.
120
121        Args:
122            event_id (int): The event id.
123
124        Returns:
125            TopPlayersMatch: The match top players.
126        """
127        return self.__service.get_match_top_players(event_id)
128
129    def get_match_comments(self, event_id: int) -> list[Comment]:
130        """
131        Get the comments of a match.
132
133        Args:
134            event_id (int): The event id.
135
136        Returns:
137            list[Comment]: The match comments.
138        """
139        return self.__service.get_match_comments(event_id)
140
141    def get_match_stats(self, event_id: int) -> MatchStats:
142        """
143        Get the match statistics by event id.
144
145        Args:
146            event_id (int): The event id (also known as match id).
147
148        Returns:
149            MatchStats: The match statistics.
150        """
151        return self.__service.get_match_stats(event_id)
152
153    def get_match_lineups(self, event_id: int) -> Lineups:
154        """
155        Get the match lineups.
156
157        Args:
158            event_id (int): The event id.
159
160        Returns:
161            Lineups: The match lineups.
162        """
163        return self.__service.get_match_lineups(event_id)
164
165    def get_match_shots(self, event_id: int) -> list[Shot]:
166        """
167        Get the shots of a match.
168
169        Args:
170            event_id (int): The event id.
171
172        Returns:
173            list[Shot]: The match shots.
174        """
175        return self.__service.get_match_shots(event_id)
176
177    def get_team(self, team_id: int) -> Team:
178        """
179        Get detailed information about a team.
180
181        Args:
182            team_id (int): The team id.
183
184        Returns:
185            TeamEx: The team information.
186        """
187        if not self.__service.use_playwright:
188            team, players = fetch_many(
189                [
190                    lambda: self.__service.get_team(team_id),
191                    lambda: self.__service.get_team_players(team_id),
192                ],
193                max_workers=2,
194            )
195        else:
196            team = self.__service.get_team(team_id)
197            players = self.__service.get_team_players(team_id)
198        team.players = players
199        return team
200
201    def get_team_players(self, team_id: int) -> list[Player]:
202        """
203        Get the players of a team.
204
205        Args:
206            team_id (int): The team id.
207
208        Returns:
209            list[Player]: The players of the team.
210        """
211        return self.__service.get_team_players(team_id)
212
213    def get_team_events(
214        self, team_id: int, upcoming: bool = False, page: int = 0
215    ) -> list[Event]:
216        """
217        Get the events (matchs) of a team.
218
219        Args:
220            team_id (int): The team id.
221            upcoming (bool): Whether to get the upcoming events.
222            page (int): The page number.
223
224        Returns:
225            list[Event]: The events of the team.
226        """
227        return self.__service.get_team_events(team_id, upcoming, page)
228
229    def get_tournaments(self, category_id: Category) -> list[Tournament]:
230        """
231        Get the tournaments by category.
232        TODO: maybe add a argument to include seasons.
233
234        Args:
235            category_id (Category): The category id.
236
237        Returns:
238            list[Tournament]: The tournaments.
239        """
240        return self.__service.get_tournaments_by_category(category_id)
241
242    def get_tournament_seasons(self, tournament_id: int) -> list[Season]:
243        """
244        Get the seasons of a tournament.
245
246        Args:
247            tournament_id (int): The tournament id.
248
249        Returns:
250            list[Season]: The seasons of the tournament.
251        """
252        return self.__service.get_tournament_seasons(tournament_id)
253
254    def get_tournament_brackets(
255        self, tournament_id: int | Tournament, season_id: int | Season
256    ) -> list[Bracket]:
257        """
258        Get the tournament bracket.
259
260        Args:
261            tournament_id (int, Tournament): The tournament id.
262            season_id (int, Season): The season id.
263
264        Returns:
265            list[Bracket]: The tournament bracket.
266        """
267        return self.__service.get_tournament_bracket(tournament_id, season_id)
268
269    def get_tournament_standings(
270        self, tournament_id: int | Tournament, season_id: int | Season
271    ) -> list[Standing]:
272        """
273        Get the tournament standings.
274
275        Args:
276            tournament_id (int, Tournament): The tournament id.
277            season_id (int, Season): The season id.
278
279        Returns:
280            list[Standing]: The tournament standings.
281        """
282        return self.__service.get_tournament_standings(tournament_id, season_id)
283
284    def get_tournament_top_teams(
285        self, tournament_id: int | Tournament, season_id: int | Season
286    ) -> TopTournamentTeams:
287        """
288        Get the top teams of the tournament.
289
290        Args:
291            tournament_id (int, Tournament): The tournament id.
292            season_id (int, Season): The season id.
293
294        Returns:
295            TopTournamentTeams: The top teams of the tournament.
296        """
297        return self.__service.get_tournament_top_teams(tournament_id, season_id)
298
299    def get_tournament_top_players(
300        self, tournament_id: int | Tournament, season_id: int | Season
301    ) -> TopTournamentPlayers:
302        """
303        Get the top players of the tournament.
304
305        Args:
306            tournament_id (int, Tournament): The tournament id.
307            season_id (int, Season): The season id.
308
309        Returns:
310            TopTournamentPlayers: The top players of the tournament.
311        """
312        return self.__service.get_tournament_top_players(tournament_id, season_id)
313
314    def get_tournament_events(
315        self,
316        tournament_id: int | Tournament,
317        season_id: int | Season,
318        upcoming: bool = False,
319        page: int = 0,
320    ) -> list[Event]:
321        """
322        Get the events of the tournament.
323
324        Args:
325            tournament_id (int, Tournament): The tournament id.
326            season_id (int, Season): The season id.
327            upcoming (bool): Whether to get the upcoming events.
328            page (int): The page number.
329
330        Returns:
331            list[Event]: The events of the tournament.
332        """
333        return self.__service.get_tournament_events(
334            tournament_id, season_id, upcoming, page
335        )
336
337    def search(
338        self, query: str, entity: str | EntityType = EntityType.ALL
339    ) -> list[Event | Team | Player | Tournament]:
340        """
341        Search query for matches, teams, players, and tournaments.
342
343        Args:
344            query (str): The search query.
345            entity (str, EntityType): The entity type to search for.
346
347        Returns:
348            list[Event | Team | Player | Tournament]: The search results.
349        """
350        if isinstance(entity, str):
351            entity = EntityType(entity)
352        return self.__service.search(query, entity)
353
354    def close(self) -> None:
355        """Close the reused browser, if any."""
356        self.__service.close()
357
358    def __enter__(self) -> SofascoreClient:
359        return self
360
361    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
362        self.close()

16class PromiedosClient:
17    """
18    Client for interacting with the Promiedos website.
19    This class provides methods to access and retrieve data from Promiedos.
20    """
21
22    def __init__(self, proxies: dict = None) -> None:
23        """
24        Initializes the Promiedos client.
25
26        Args:
27            proxies: Optional proxy dict.
28        """
29        self.__service = PromiedosService(proxies=proxies)
30
31    def get_events(self, date: str = "today") -> list[Event]:
32        """
33        Get the events for the given date.
34
35        Args:
36            date (str): The date to get the events. Defaults to "today".
37
38        Returns:
39            list[Event]: The events for the given date.
40        """
41        return self.__service.get_events(date)
42
43    def get_match(self, match_id: str = None, match: Match = None) -> Match:
44        """
45        Get the match for the given slug and match ID.
46
47        Args:
48            match_id (str): The match ID. E.g. "ediecji".
49            Match (Match): The match object.
50
51        Returns:
52            Match: The match for the given slug and match ID.
53        """
54        if not match_id and not match:
55            raise NotMatchIdProvided(
56                "No match ID provided OR no match object provided."
57            )
58        if match:
59            return self.__service.get_match(match.id)
60        return self.__service.get_match(match_id)
61
62    def get_tournament(self, tournament_id: str) -> Tournament:
63        """
64        Get the matches for the given tournament ID.
65
66        Args:
67            tournament_id (str): The tournament ID. E.g. "hc".
68
69        Returns:
70            Tournament: The tournament for the given tournament ID.
71        """
72        return self.__service.get_tournament(tournament_id)
73
74    def get_tournament_matchs(
75        self, tournament_id: str, stage_id: str = None
76    ) -> list[Match]:
77        """
78        Get the matches for the given tournament ID using the stage ID.
79
80        Args:
81            tournament_id (str): The tournament ID. E.g. "hc".
82            stage_id (str): The stage ID.
83        Returns:
84            list[Match]: The matches for the given tournament ID.
85        """
86        return self.__service.get_tournament_matchs(tournament_id, stage_id)

 16class FBrefClient:
 17    """
 18    A class to represent the client for interacting with the FBref website.
 19    """
 20
 21    def __init__(
 22        self,
 23        language: str = "en",
 24        proxies: dict = None,
 25        use_playwright: bool = False,
 26        chrome_path: str = None,
 27        use_curl_cffi: bool = True,
 28        impersonate: str = "chrome",
 29        delay: float = 3.0,
 30        headless: bool = False,
 31    ) -> None:
 32        """
 33        Initializes the FBref client.
 34
 35        Args:
 36            language: The language for FBref URLs (e.g. 'en', 'es').
 37            proxies: Optional proxy dict.
 38            use_playwright: If True, uses Playwright with system Chrome
 39                instead of httpx. No 'playwright install' needed.
 40                Defaults to False (curl_cffi is preferred for FBref).
 41            chrome_path: Optional path to Chrome executable.
 42            use_curl_cffi: If True, uses curl_cffi with browser impersonation
 43                to bypass Cloudflare. Defaults to True.
 44            impersonate: Browser fingerprint for curl_cffi (default "chrome").
 45            delay: Minimum seconds between requests (default 3.0).
 46            headless: Run Playwright headless. Defaults to False. Headful
 47                Chrome is required to pass Cloudflare's challenge.
 48        """
 49        self.__service = FBrefService(
 50            language=language,
 51            proxies=proxies,
 52            use_playwright=use_playwright,
 53            chrome_path=chrome_path,
 54            use_curl_cffi=use_curl_cffi,
 55            impersonate=impersonate,
 56            delay=delay,
 57            headless=headless,
 58        )
 59        _logger.debug(
 60            "initialized with language=%s playwright=%s cffi=%s",
 61            language,
 62            use_playwright,
 63            use_curl_cffi,
 64        )
 65
 66    def get_matchs(self, date: str = None) -> list[Match]:
 67        """
 68        Get the scheduled matchs.
 69
 70        Args:
 71            date (str): The date of the matchs in the format "YYYY-MM-DD".
 72
 73        Returns:
 74            list[Match]: The scheduled matchs.
 75        """
 76        return self.__service.get_matchs(date)
 77
 78    def get_match_details(self, match_id: str) -> MatchDetails:
 79        """
 80        Get the match report.
 81
 82        Args:
 83            match_id (str): The match id.
 84
 85        Returns:
 86            MatchDetails: The match details.
 87        """
 88        return self.__service.get_match_details(match_id)
 89
 90    def get_league_players(
 91        self,
 92        comp_id: int,
 93        league_slug: str,
 94        table_id: str = "stats_standard",
 95    ) -> list[LeaguePlayerStandard]:
 96        """
 97        Get player statistics for a league/competition.
 98
 99        Args:
100            comp_id: The competition ID on FBref (e.g. 9 for Premier League).
101            league_slug: The league slug (e.g. "Premier-League").
102            table_id: The HTML table id to parse (default "stats_standard").
103                Other options: "stats_shooting", "stats_passing", etc.
104
105        Returns:
106            list[LeaguePlayerStandard]: Parsed player statistics rows.
107        """
108        return self.__service.get_league_players(
109            comp_id, league_slug, table_id=table_id
110        )
111
112    def close(self) -> None:
113        """Close the reused browser, if any."""
114        self.__service.close()
115
116    def __enter__(self) -> FBrefClient:
117        return self
118
119    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
120        self.close()

 25class GoalooClient:
 26    """
 27    Client for interacting with Goaloo.
 28
 29    This class provides methods to access and retrieve football data
 30    (leagues, schedules and standings) from Goaloo.
 31    """
 32
 33    def __init__(self, proxies: dict = None) -> None:
 34        """
 35        Initializes the Goaloo client.
 36
 37        Args:
 38            proxies: Optional proxy dict.
 39        """
 40        self.__service = GoalooService(proxies=proxies)
 41
 42    def get_league(self, league_id: int, season: str = None) -> League:
 43        """
 44        Get a competition's metadata and team list.
 45
 46        Args:
 47            league_id (int): The Goaloo competition id (e.g. 36 for Premier League).
 48            season (str): The season (e.g. "2026-2027"). Defaults to current.
 49
 50        Returns:
 51            League: The competition metadata.
 52        """
 53        return self.__service.get_league(league_id, season)
 54
 55    def get_matches(self, league_id: int, season: str = None) -> list[Match]:
 56        """
 57        Get all matches of a competition for a season.
 58
 59        Args:
 60            league_id (int): The Goaloo competition id.
 61            season (str): The season (e.g. "2026-2027"). Defaults to current.
 62
 63        Returns:
 64            list[Match]: The matches of the competition.
 65        """
 66        return self.__service.get_matches(league_id, season)
 67
 68    def get_standings(self, league_id: int, season: str = None) -> list[Standing]:
 69        """
 70        Get the standings of a competition for a season.
 71
 72        Args:
 73            league_id (int): The Goaloo competition id.
 74            season (str): The season (e.g. "2026-2027"). Defaults to current.
 75
 76        Returns:
 77            list[Standing]: The standings of the competition.
 78        """
 79        return self.__service.get_standings(league_id, season)
 80
 81    def get_seasons(self, league_id: int) -> list[str]:
 82        """
 83        Get the available seasons for a competition.
 84
 85        Args:
 86            league_id (int): The Goaloo competition id.
 87
 88        Returns:
 89            list[str]: The available seasons.
 90        """
 91        return self.__service.get_seasons(league_id)
 92
 93    def get_h2h(self, match_id: int) -> HeadToHead:
 94        """
 95        Get the head-to-head history between the two teams of a match.
 96
 97        Args:
 98            match_id (int): The Goaloo match id.
 99
100        Returns:
101            HeadToHead: The H2H meetings and aggregate record.
102        """
103        return self.__service.get_h2h(match_id)
104
105    def get_last_matches(self, match_id: int) -> RecentForm:
106        """
107        Get the recent match results for both teams of a match.
108
109        Args:
110            match_id (int): The Goaloo match id.
111
112        Returns:
113            RecentForm: The recent results for both teams.
114        """
115        return self.__service.get_last_matches(match_id)
116
117    def get_over_under(self, league_id: int, season: str = None) -> list[OverUnder]:
118        """
119        Get the over/under result distribution for a competition.
120
121        Args:
122            league_id (int): The Goaloo competition id.
123            season (str): The season (e.g. "2026-2027"). Defaults to current.
124
125        Returns:
126            list[OverUnder]: The over/under distribution per team.
127        """
128        return self.__service.get_over_under(league_id, season)
129
130    def get_asian_handicap(
131        self, league_id: int, season: str = None
132    ) -> list[AsianHandicap]:
133        """
134        Get the Asian handicap result distribution for a competition.
135
136        Args:
137            league_id (int): The Goaloo competition id.
138            season (str): The season (e.g. "2026-2027"). Defaults to current.
139
140        Returns:
141            list[AsianHandicap]: The Asian handicap distribution per team.
142        """
143        return self.__service.get_asian_handicap(league_id, season)
144
145    def get_home_standings(self, league_id: int, season: str = None) -> list[Standing]:
146        """
147        Get the home-only standings of a competition for a season.
148
149        Args:
150            league_id (int): The Goaloo competition id.
151            season (str): The season (e.g. "2026-2027"). Defaults to current.
152
153        Returns:
154            list[Standing]: The home-only standings.
155        """
156        return self.__service.get_home_standings(league_id, season)
157
158    def get_away_standings(self, league_id: int, season: str = None) -> list[Standing]:
159        """
160        Get the away-only standings of a competition for a season.
161
162        Args:
163            league_id (int): The Goaloo competition id.
164            season (str): The season (e.g. "2026-2027"). Defaults to current.
165
166        Returns:
167            list[Standing]: The away-only standings.
168        """
169        return self.__service.get_away_standings(league_id, season)
170
171    def get_goal_timings(self, league_id: int, season: str = None) -> list[GoalTiming]:
172        """
173        Get the goal timing distribution for each team of a competition.
174
175        Args:
176            league_id (int): The Goaloo competition id.
177            season (str): The season (e.g. "2026-2027"). Defaults to current.
178
179        Returns:
180            list[GoalTiming]: The goals per ten-minute block for each team.
181        """
182        return self.__service.get_goal_timings(league_id, season)
183
184    def get_match_score(self, match_id: int) -> MatchScore:
185        """
186        Get the live score and status of a match.
187
188        Args:
189            match_id (int): The Goaloo match id.
190
191        Returns:
192            MatchScore: The current score, state and time.
193        """
194        return self.__service.get_match_score(match_id)
195
196    def get_live_odds(self, match_id: int, company_id: int = 0) -> LiveOdds:
197        """
198        Get the live odds of a match for a bookmaker.
199
200        Only available for matches that are upcoming or in play.
201
202        Args:
203            match_id (int): The Goaloo match id.
204            company_id (int): The bookmaker id (default 0).
205
206        Returns:
207            LiveOdds: The Asian handicap, over/under, 1x2 and corner odds.
208        """
209        return self.__service.get_live_odds(match_id, company_id)
210
211    def get_match_events(self, match_id: int) -> list[MatchEvent]:
212        """
213        Get the events (goals, cards and substitutions) of a match.
214
215        Args:
216            match_id (int): The Goaloo match id.
217
218        Returns:
219            list[MatchEvent]: The match events in chronological order.
220        """
221        return self.__service.get_match_events(match_id)
222
223    def get_team(self, team_id: int) -> TeamDetail:
224        """
225        Get a team's squad, coach and honors.
226
227        Args:
228            team_id (int): The Goaloo team id.
229
230        Returns:
231            TeamDetail: The team metadata, players, coach and honors.
232        """
233        return self.__service.get_team(team_id)