Coverage for src/usls/application/service.py: 100%
69 statements
« prev ^ index » next coverage.py v7.15.3, created at 2026-08-05 10:11 +0000
1"""Application service — the core of the hexagonal architecture.
3This layer orchestrates work by delegating to outbound ports. It knows nothing
4about MCP, HTTP, or JSON — those are adapter concerns.
5"""
7from ..domain.models import (
8 AdjustedPointsPerGame,
9 Match,
10 MatchDetails,
11 NewsArticle,
12 OpponentPPG,
13 Player,
14 ResultsByOpponentTier,
15 Standing,
16 StrengthOfSchedule,
17 Team,
18)
19from ..ports.outbound import USLSAPIPort
20from ._analytics_helpers import (
21 _build_ppg_index,
22 _build_tier_record,
23 _build_tier_specs,
24 _league_average_ppg,
25 _mean,
26 _opponent_ppgs,
27 _played_opponents,
28 _resolve_team,
29 _safe_ratio,
30 _self_record,
31 _tally_tier_results,
32 _validate_team_id,
33 _validate_tier_size,
34)
35from ._helpers import _validate_yyyymmdd
38class USLSService:
39 """Coordinates USL Super League data lookups through the outbound ports.
41 One driven port is injected: the ESPN-backed ``repo`` (read-only league
42 feeds). Additional data sources (SDP/Opta, CMS) can be added as separate
43 ports as they come online.
44 """
46 def __init__(self, repo: USLSAPIPort) -> None:
47 self._repo = repo
49 async def get_teams(self) -> list[Team]:
50 """Return all active USL Super League teams."""
51 return await self._repo.get_teams()
53 async def get_team(self, team_id: str) -> Team:
54 """Return a single team by its ESPN team ID.
56 Args:
57 team_id: ESPN numeric team ID or team abbreviation.
59 Raises:
60 ValueError: If team_id is empty.
61 USLSNotFoundError: If no team with that ID exists.
62 """
63 if not team_id or not team_id.strip():
64 raise ValueError("team_id must not be empty")
65 return await self._repo.get_team(team_id.strip())
67 async def get_scoreboard(self, date: str | None = None, end_date: str | None = None) -> list[Match]:
68 """Return matches for a date, a date range, or today if date is None.
70 Args:
71 date: Optional date string in YYYYMMDD format (e.g. "20260601").
72 end_date: Optional end of a range in YYYYMMDD format. Requires ``date``
73 to be provided as the start of the range.
75 Raises:
76 ValueError: If either argument is malformed, or if end_date is given
77 without a starting date.
78 """
79 if end_date is not None and date is None:
80 raise ValueError("end_date requires a starting date")
81 if date is not None:
82 date = _validate_yyyymmdd(date.strip(), "date")
83 if end_date is not None:
84 end_date = _validate_yyyymmdd(end_date.strip(), "end_date")
85 return await self._repo.get_scoreboard(date, end_date)
87 async def get_news(self, limit: int = 10) -> list[NewsArticle]:
88 """Return up to ``limit`` recent USL Super League news articles.
90 Args:
91 limit: Maximum number of articles to return (must be positive).
93 Raises:
94 ValueError: If limit is not a positive integer.
95 """
96 if limit <= 0:
97 raise ValueError("limit must be positive")
98 return await self._repo.get_news(limit)
100 async def get_roster(self, team_id: str) -> list[Player]:
101 """Return the active roster for a team.
103 Args:
104 team_id: ESPN numeric team ID.
106 Raises:
107 ValueError: If team_id is empty.
108 USLSNotFoundError: If no team with that ID exists.
109 """
110 if not team_id or not team_id.strip():
111 raise ValueError("team_id must not be empty")
112 return await self._repo.get_roster(team_id.strip())
114 async def get_match_details(self, match_id: str) -> MatchDetails:
115 """Return detailed information for a single match.
117 Args:
118 match_id: ESPN numeric event ID.
120 Raises:
121 ValueError: If match_id is empty.
122 USLSNotFoundError: If no match with that ID exists.
123 """
124 if not match_id or not match_id.strip():
125 raise ValueError("match_id must not be empty")
126 return await self._repo.get_match_details(match_id.strip())
128 async def get_team_schedule(self, team_id: str) -> list[Match]:
129 """Return all scheduled and completed matches for a team in the current season.
131 Args:
132 team_id: ESPN numeric team ID.
134 Raises:
135 ValueError: If team_id is empty.
136 USLSNotFoundError: If no team with that ID exists.
137 """
138 if not team_id or not team_id.strip():
139 raise ValueError("team_id must not be empty")
140 return await self._repo.get_team_schedule(team_id.strip())
142 async def get_standings(self) -> list[Standing]:
143 """Return the current USL Super League standings ordered by points descending."""
144 return await self._repo.get_standings()
146 async def get_strength_of_schedule(self, team_id: str) -> StrengthOfSchedule:
147 """Return the average current PPG of opponents this team has faced.
149 Walks the team's completed matches and aggregates each opponent's
150 league-table points-per-game (no self-exclusion). Useful for "who has
151 played the tougher schedule so far?" questions.
153 Args:
154 team_id: ESPN numeric team ID.
156 Raises:
157 ValueError: If team_id is empty.
158 USLSNotFoundError: If no team with that ID exists.
159 """
160 team_id = _validate_team_id(team_id)
161 standings = await self._repo.get_standings()
162 schedule = await self._repo.get_team_schedule(team_id)
163 ppg_index = _build_ppg_index(standings)
164 team = _resolve_team(standings, schedule, team_id)
165 opponents = [
166 OpponentPPG(
167 team=opp,
168 matches_played=ppg_index[opp.id].matches_played,
169 points=ppg_index[opp.id].points,
170 points_per_game=ppg_index[opp.id].ppg,
171 )
172 for opp in _played_opponents(schedule, team_id)
173 if opp.id in ppg_index
174 ]
175 return StrengthOfSchedule(
176 team=team,
177 matches_played=len(opponents),
178 opponents=opponents,
179 average_opponent_ppg=_mean([o.points_per_game for o in opponents]),
180 )
182 async def get_results_by_opponent_tier(self, team_id: str, tier_size: int = 5) -> ResultsByOpponentTier:
183 """Return W-L-T splits against current top-tier, middle, and bottom-tier teams.
185 Tiers are derived from the current league standings: the top ``tier_size``,
186 the bottom ``tier_size``, and everyone in between. Draws (no declared winner)
187 count as ties; matches against teams not in the current standings are
188 skipped.
190 Args:
191 team_id: ESPN numeric team ID.
192 tier_size: Number of teams in each of the top and bottom tiers.
193 Defaults to 5. Must be at least 1, and 2*tier_size must not
194 exceed the league size.
196 Raises:
197 ValueError: If team_id is empty or tier_size is invalid.
198 USLSNotFoundError: If no team with that ID exists.
199 """
200 team_id = _validate_team_id(team_id)
201 standings = await self._repo.get_standings()
202 _validate_tier_size(tier_size, len(standings))
203 schedule = await self._repo.get_team_schedule(team_id)
204 rank_by_id = {s.team.id: i + 1 for i, s in enumerate(standings)}
205 team = _resolve_team(standings, schedule, team_id)
206 tier_specs = _build_tier_specs(tier_size, len(standings))
207 tally = _tally_tier_results(schedule, team_id, rank_by_id, tier_specs)
208 tiers = [_build_tier_record(name, low, high, tally) for name, low, high in tier_specs if high >= low]
209 return ResultsByOpponentTier(team=team, tier_size=tier_size, tiers=tiers)
211 async def get_adjusted_points_per_game(self, team_id: str) -> AdjustedPointsPerGame:
212 """Return raw PPG plus a schedule-strength-adjusted PPG.
214 Adjusted PPG = raw_ppg * (avg_opponent_ppg / league_average_ppg). Values
215 above raw_ppg mean the team has earned points against a tougher
216 schedule than league average.
218 Args:
219 team_id: ESPN numeric team ID.
221 Raises:
222 ValueError: If team_id is empty.
223 USLSNotFoundError: If no team with that ID exists.
224 """
225 team_id = _validate_team_id(team_id)
226 standings = await self._repo.get_standings()
227 schedule = await self._repo.get_team_schedule(team_id)
228 ppg_index = _build_ppg_index(standings)
229 team = _resolve_team(standings, schedule, team_id)
230 matches_played, points, raw_ppg = _self_record(ppg_index, team_id)
231 opp_entries = _opponent_ppgs(schedule, team_id, ppg_index)
232 avg_opp_ppg = _mean([e.ppg for e in opp_entries])
233 league_avg = _league_average_ppg(standings)
234 return AdjustedPointsPerGame(
235 team=team,
236 matches_played=matches_played,
237 points=points,
238 raw_ppg=raw_ppg,
239 average_opponent_ppg=avg_opp_ppg,
240 league_average_ppg=league_avg,
241 adjusted_ppg=raw_ppg * _safe_ratio(avg_opp_ppg, league_avg),
242 )