feat: Add MLB support for Sport Suggestions (#1283)

* feat: Add MLB support for Sport Suggestions

Closes DISCO-3958

* feedback changes

---------

Co-authored-by: Tif Tran <ttran@mozilla.com>

Author: jrconlin

merino/configs/default.toml

@@ -374,7 +374,7 @@ hourly_forecast_ttl_sec = 1800
 type="sports"
 # MERINO_PROVIDERS__SPORTS__SPORTS
 # e.g. ["NFL","NBA","NHL"]
-sports=["NFL","NBA","NHL"]
+sports=["NFL","NBA","NHL","MLB"]
 # Index names for Elastic Search.
 event_index="sports-{lang}-event"
 team_index="sports-{lang}-team"

merino/jobs/sportsdata_jobs/__init__.py

@@ -45,6 +45,7 @@
     NFL,
     NBA,
     NHL,
+    MLB,
     # UCL,
     # MLB,
     # EPL,
@@ -109,8 +110,8 @@ def __init__(
                     sport = NHL(settings)
                 # case "UCL":
                 #    sport = UCL(settings)
-                # case "MLB":
-                #    sport = MLB(settings)
+                case "MLB":
+                    sport = MLB(settings)
                 # case "EPL":
                 #    sport = EPL(settings)
                 case _:

merino/providers/suggest/sports/backends/sportsdata/common/sports.py

@@ -431,78 +431,135 @@ async def update_events(self, client: AsyncClient, allow_no_teams: bool = False)
         return self
 
 
-# THE FOLLOWING CLASSES ARE WIP:::
+class MLB(Sport):
+    """Major League Baseball"""
 
+    season: str | None = None
+    _lock: asyncio.Lock
 
-# class MLB(Sport):
-#    """Major League Baseball"""
-#
-#    def __init__(self, settings: LazySettings, *args, **kwargs):
-#        name = self.__class__.__name__
-#
-#        super().__init__(
-#            name=name,
-#            base_url=settings.sportsdata.get(
-#                f"base_url.{name.lower()}",
-#                default=f"https://api.sportsdata.io/v3/{name.lower()}/scores/json",
-#            ),
-#            season=None,
-#            week=None,
-#            teams={},
-#            *args,
-#            **kwargs,
-#        )
-#        self._lock = asyncio.Lock()
-#
-#    async def update_events(self, client: AsyncClient) -> list[Event]:
-#        """Fetch the list of events for the sport. (5 min interval)"""
-#        # https://api.sportsdata.io/v3/mlb/scores/json/teams?key=
-#        # Sample:
-#        """
-#        [
-#            {
-#                "AwayTeamRuns": 0,
-#                "HomeTeamRuns": 0,
-#                "AwayTeamHits": 2,
-#                "HomeTeamHits": 5,
-#                "AwayTeamErrors": 0,
-#                "HomeTeamErrors": 0,
-#                "Attendance": null,
-#                "GlobalGameID": 10076415,
-#                "GlobalAwayTeamID": 10000012,
-#                "GlobalHomeTeamID": 10000032,
-#                "NeutralVenue": false,
-#                "Inning": 4,
-#                "InningHalf": "B",
-#                "GameID": 76415,
-#                "Season": 2025,
-#                "SeasonType": 1,
-#                "Status": "InProgress",
-#                "Day": "2025-09-04T00:00:00",
-#                "DateTime": "2025-09-04T16:10:00",
-#                "AwayTeam": "PHI",
-#                "HomeTeam": "MIL",
-#                "AwayTeamID": 12,
-#                "HomeTeamID": 32,
-#                "RescheduledGameID": null,
-#                "StadiumID": 92,
-#                "IsClosed": false,
-#                "Updated": "2025-09-04T17:19:20",
-#                "GameEndDateTime": null,
-#                "DateTimeUTC": "2025-09-04T20:10:00",
-#                "RescheduledFromGameID": null,
-#                "SuspensionResumeDay": null,
-#                "SuspensionResumeDateTime": null,
-#                "SeriesInfo": null
-#            },
-#        ...]
-#        """
-#        date = datetime.now(tz=ZoneInfo("America/New_York")).strftime("%Y-%b-%d")
-#        season = str(date)
-#        url = f"{self.base_url}/ScoresBasic/{season}?key={self.api_key}"
-#        await get_data(client, url)
-#        # TODO: Parse events
-#        return []
+    def __init__(self, settings: LazySettings, *args, **kwargs):
+        name = self.__class__.__name__
+        super().__init__(
+            settings=settings,
+            name=name,
+            base_url=settings.sportsdata.get(
+                f"base_url.{name.lower()}",
+                default=f"https://api.sportsdata.io/v3/{name.lower()}/scores/json",
+            ),
+            season=None,
+            cache_dir=settings.sportsdata.get("cache_dir"),
+            event_ttl=timedelta(hours=48),
+            team_ttl=timedelta(weeks=4),
+        )
+        self._lock = asyncio.Lock()
+
+    async def get_season(self, client: AsyncClient):
+        """Get the current season"""
+        if self.season is not None:
+            return self
+        logger = logging.getLogger(__name__)
+        logger.debug(f"{LOGGING_TAG} Getting {self.name} season")
+        url = f"{self.base_url}/CurrentSeason?key={self.api_key}"
+        response = await get_data(
+            client=client,
+            url=url,
+            ttl=timedelta(hours=4),
+            cache_dir=self.cache_dir,
+        )
+        """
+        {
+            "Season":2026,
+            "RegularSeasonStartDate":"2025-10-07T00:00:00",
+            "PostSeasonStartDate":"2026-04-18T00:00:00",
+            "SeasonType":"PRE",
+            "ApiSeason":"2026PRE"
+        }
+        """
+        self.season = response.get("ApiSeason")
+        return self
+
+    async def update_teams(self, client: AsyncClient):
+        """Fetch active team information"""
+        await self.get_season(client=client)
+        logger = logging.getLogger(__name__)
+        if self.season is None:
+            logger.info(f"{LOGGING_TAG} Skipping out of season {self.name}")
+            return self
+        logger.debug(f"{LOGGING_TAG} Getting {self.name} teams ")
+        url = f"{self.base_url}/teams?key={self.api_key}"
+        response = await get_data(
+            client=client,
+            url=url,
+            ttl=timedelta(hours=4),
+            cache_dir=self.cache_dir,
+        )
+        async with self._lock:
+            self.load_teams_from_source(response)
+        return self
+
+    async def get_team(self, id: int) -> Team | None:
+        """Attempt to find the team information in a thread-locking manner."""
+        async with self._lock:
+            team = self.teams.get(id)
+        return team
+
+    async def update_events(self, client: AsyncClient, allow_no_teams: bool = False):
+        """Fetch the list of events for the sport. (5 min interval)"""
+        local_timezone = ZoneInfo("America/New_York")
+        date = datetime.now(tz=local_timezone).strftime("%Y-%b-%d").upper()
+        url = f"{self.base_url}/ScoresBasic/{date}?key={self.api_key}"
+        """
+        [
+            {
+                "AwayTeamRuns": 0,
+                "HomeTeamRuns": 0,
+                "AwayTeamHits": 2,
+                "HomeTeamHits": 5,
+                "AwayTeamErrors": 0,
+                "HomeTeamErrors": 0,
+                "Attendance": null,
+                "GlobalGameID": 10076415,
+                "GlobalAwayTeamID": 10000012,
+                "GlobalHomeTeamID": 10000032,
+                "NeutralVenue": false,
+                "Inning": 4,
+                "InningHalf": "B",
+                "GameID": 76415,
+                "Season": 2025,
+                "SeasonType": 1,
+                "Status": "InProgress",
+                "Day": "2025-09-04T00:00:00",
+                "DateTime": "2025-09-04T16:10:00",
+                "AwayTeam": "PHI",
+                "HomeTeam": "MIL",
+                "AwayTeamID": 12,
+                "HomeTeamID": 32,
+                "RescheduledGameID": null,
+                "StadiumID": 92,
+                "IsClosed": false,
+                "Updated": "2025-09-04T17:19:20",
+                "GameEndDateTime": null,
+                "DateTimeUTC": "2025-09-04T20:10:00",
+                "RescheduledFromGameID": null,
+                "SuspensionResumeDay": null,
+                "SuspensionResumeDateTime": null,
+                "SeriesInfo": null
+            },
+        ...]
+        """
+        response = await get_data(
+            client=client,
+            url=url,
+            ttl=timedelta(minutes=5),
+            cache_dir=self.cache_dir,
+        )
+        self.load_scores_from_source(
+            response, event_timezone=local_timezone, allow_no_teams=allow_no_teams
+        )
+        return self
+
+
+# THE FOLLOWING CLASSES ARE WIP:::
 
 
 # class EPL(Sport):

tests/unit/providers/suggest/sports/backends/common/test_sports.py

@@ -23,6 +23,7 @@
     NHL,
     NBA,
     UCL,
+    MLB,
 )
 
 
@@ -60,6 +61,34 @@ def nfl_teams_payload() -> list[dict]:
     ]
 
 
+@pytest.fixture
+def generic_teams_payload() -> list[dict]:
+    """Provide Generic team payload (for US based sports)."""
+    return [
+        {
+            "Key": "HOM",
+            "Name": "Homebodies",
+            "City": "Springfield",
+            "AreaName": "US",
+            "FullName": "Springfield Homebodies",
+            "Nickname1": "Homers",
+            "GlobalTeamId": 98,
+            "PrimaryColor": "000000",
+            "SecondaryColor": "FFFFFF",
+        },
+        {
+            "Key": "AWY",
+            "Name": "Visitors",
+            "City": "Elsewhere",
+            "AreaName": "OS",
+            "GlobalTeamId": 99,
+            "FullName": "Visitors from Elsewhere",
+            "PrimaryColor": "FFFFFF",
+            "SecondaryColor": "000000",
+        },
+    ]
+
+
 @pytest.fixture
 def nhl_nba_teams_payload() -> list[dict]:
     """NHL/NBA team payload."""
@@ -173,6 +202,61 @@ def schedules_payload() -> list[dict]:
     ]
 
 
+@pytest.fixture
+def generic_schedules_payload() -> list[dict]:
+    """Provide Generic team Schedules payload that are out and in window."""
+    return [
+        {
+            "GameId": 67890,
+            "Season": 2026,
+            "SeasonType": 2,
+            "Status": "Final",
+            "Day": "2025-09-21T00:00:00",
+            "DateTime": "2025-09-21T21:30:00",
+            "Updated": "2025-09-29T04:10:57",
+            "IsClosed": True,
+            "AwayTeam": "AWY",
+            "HomeTeam": "HOM",
+            "StadiumID": 9,
+            "AwayTeamScore": 2,
+            "HomeTeamScore": 3,
+            "GlobalGameID": 12345678,
+            "GlobalAwayTeamID": 99,
+            "GlobalHomeTeamID": 98,
+            "GameEndDateTime": "2025-09-22T00:10:17",
+            "NeutralVenue": False,
+            "DateTimeUTC": "2025-09-22T01:30:00",
+            "AwayTeamID": 99,
+            "HomeTeamID": 98,
+            "SeriesInfo": None,
+        },
+        {
+            "GameId": 11111,
+            "Season": 2000,
+            "SeasonType": 2,
+            "Status": "Final",
+            "Day": "2000-01-01T00:00:00",
+            "DateTime": "2000-01-01T21:30:00",
+            "Updated": "2000-01-01T04:10:57",
+            "IsClosed": True,
+            "AwayTeam": "AWY",
+            "HomeTeam": "HOM",
+            "StadiumID": 9,
+            "AwayTeamScore": 0,
+            "HomeTeamScore": 0,
+            "GlobalGameID": 0,
+            "GlobalAwayTeamID": 99,
+            "GlobalHomeTeamID": 98,
+            "GameEndDateTime": "2000-09-22T00:10:17",
+            "NeutralVenue": False,
+            "DateTimeUTC": "2000-09-22T01:30:00",
+            "AwayTeamID": 99,
+            "HomeTeamID": 98,
+            "SeriesInfo": None,
+        },
+    ]
+
+
 @pytest.fixture
 def nfl_scores_payload() -> list[dict[str, Any]]:
     """NFL scores payload."""
@@ -379,6 +463,23 @@ async def test_nba_update_teams(
     assert get_data.call_count == 2
 
 
+@pytest.mark.asyncio
+async def test_mlb_update_teams(
+    generic_teams_payload: list[dict], mock_client: AsyncClient, mocker: MockerFixture
+) -> None:
+    """Test MLB team updates."""
+    sport = MLB(settings=settings.providers.sports)
+    current_season = {"ApiSeason": "2026PRE"}
+    get_data = mocker.patch(
+        "merino.providers.suggest.sports.backends.sportsdata.common.sports.get_data",
+        side_effect=[current_season, generic_teams_payload],
+    )
+    await sport.update_teams(client=mock_client)
+    assert sport.season == "2026PRE"
+    assert set(sport.teams.keys()) == {98, 99}
+    assert get_data.call_count == 2
+
+
 @freezegun.freeze_time("2025-09-22T00:00:00", tz_offset=0)
 @pytest.mark.asyncio
 async def test_ucl_update_teams(
@@ -534,6 +635,31 @@ async def test_nba_update_events(
     get_data.assert_called_once()
 
 
+@freezegun.freeze_time("2025-09-22T00:00:00", tz_offset=0)
+@pytest.mark.asyncio
+async def test_mlb_update_events(
+    generic_teams_payload: list[dict],
+    generic_schedules_payload: list[dict],
+    mock_client: AsyncClient,
+    mocker: MockerFixture,
+) -> None:
+    """Test MLB event updates."""
+    sport = MLB(settings=settings.providers.sports)
+    sport.load_teams_from_source(generic_teams_payload)
+    sport.season = "2026PRE"
+    sport.event_ttl = timedelta(weeks=2)
+
+    get_data = mocker.patch(
+        "merino.providers.suggest.sports.backends.sportsdata.common.sports.get_data",
+        return_value=generic_schedules_payload,
+    )
+
+    await sport.update_events(client=mock_client)
+    assert 12345678 in sport.events and 0 not in sport.events
+    assert sport.events[12345678].status == GameStatus.Final
+    get_data.assert_called_once()
+
+
 @freezegun.freeze_time("2025-09-22T00:00:00", tz_offset=0)
 @pytest.mark.asyncio
 async def test_ucl_update_events(