#6 Add Broadcasts.get_team_standings

CHANGELOG.rst

@@ -4,6 +4,7 @@ Changelog
 To be released
 --------------
 
+* Added ``client.broadcasts.get_team_standings`` to get the team leaderboard of a broadcast.
 
 * Deprecate Python 3.9 support - minimum required version is now Python 3.10+. This does not mean the library will not work with Python 3.9, but it will not be tested against it anymore.
 
@@ -23,6 +24,7 @@ To be released
 
 
 Thanks to all the contributors who helped to this release:
+- Nick Stillman
 - @hsheth2
 - @DoraFgr
 - @MrElyazid

README.rst

@@ -119,6 +119,7 @@ Most of the API is available:
     client.broadcasts.get_top
     client.broadcasts.search
     client.broadcasts.get_by_user
+    client.broadcasts.get_team_standings
 
     client.bulk_pairings.get_upcoming
     client.bulk_pairings.create

berserk/clients/broadcasts.py

@@ -8,6 +8,7 @@
 
 from ..types.broadcast import (
     BroadcastPlayer,
+    BroadcastTeamStandingsItem,
     BroadcastTop,
     PaginatedBroadcasts,
     BroadcastsByUser,
@@ -296,3 +297,14 @@ def get_by_user(
         path = f"/api/broadcast/by/{username}"
         params = {"page": page, "html": html}
         return cast(BroadcastsByUser, self._r.get(path, params=params))
+
+    def get_team_standings(
+        self, broadcast_tournament_id: str
+    ) -> List[BroadcastTeamStandingsItem]:
+        """Get the team leaderboard of a broadcast.
+
+        :param broadcast_tournament_id: ID of the broadcast tournament
+        :return: list of teams with name, match/board points, matches, and players
+        """
+        path = f"/broadcast/{broadcast_tournament_id}/teams/standings"
+        return cast(List[BroadcastTeamStandingsItem], self._r.get(path))

berserk/types/__init__.py

@@ -11,6 +11,7 @@
 )
 from .broadcast import (
     BroadcastPlayer,
+    BroadcastTeamStandingsItem,
     BroadcastTop,
     PaginatedBroadcasts,
     BroadcastsByUser,
@@ -37,6 +38,7 @@
     "ArenaResult",
     "BroadcastPlayer",
     "BroadcastsByUser",
+    "BroadcastTeamStandingsItem",
     "BroadcastTop",
     "BulkPairing",
     "BulkPairingGame",

berserk/types/broadcast.py

@@ -104,3 +104,34 @@ class BroadcastsByUser(TypedDict):
     previousPage: int | None
     nextPage: int | None
     nbPages: int
+
+
+# Types for GET /broadcast/{id}/teams/standings (team leaderboard of a broadcast)
+
+
+class BroadcastTeamStandingsMatch(TypedDict):
+    roundId: str
+    opponent: str
+    points: str
+    mp: int | float
+    gp: int | float
+
+
+class BroadcastTeamStandingsPlayer(TypedDict):
+    name: str
+    score: int | float
+    title: NotRequired[Title]
+    rating: NotRequired[int]
+    fideId: NotRequired[int]
+    team: NotRequired[str]
+    fed: NotRequired[str]
+    played: NotRequired[int]
+
+
+class BroadcastTeamStandingsItem(TypedDict):
+    name: str
+    mp: int | float
+    gp: int | float
+    matches: List[BroadcastTeamStandingsMatch]
+    players: List[BroadcastTeamStandingsPlayer]
+    averageRating: NotRequired[int]

tests/clients/test_broadcasts.py

@@ -1,7 +1,14 @@
 import pytest
 
+from typing import List
+
 from berserk import Client
-from berserk.types import BroadcastTop, PaginatedBroadcasts, BroadcastsByUser
+from berserk.types import (
+    BroadcastTeamStandingsItem,
+    BroadcastTop,
+    PaginatedBroadcasts,
+    BroadcastsByUser,
+)
 from utils import skip_if_older_3_dot_10, validate
 
 
@@ -23,3 +30,21 @@ def test_search(self):
     def test_get_by_user(self):
         res = Client().broadcasts.get_by_user(username="lichess", page=1)
         validate(BroadcastsByUser, res)
+
+    @skip_if_older_3_dot_10
+    @pytest.mark.vcr
+    def test_get_team_standings(self):
+        """Get team leaderboard for a broadcast.
+
+        A broadcast is a Lichess relay of an external chess event (OTB/online);
+        it has a tour (tournament) and rounds with games. Standings exist when
+        the tour is a team event (tour.teamTable is true) and teams are assigned
+        (e.g. via WhiteTeam/BlackTeam in PGN or manual assignment). To find
+        broadcasts with non-empty standings: get_top() or search(), filter for
+        tour.teamTable, then call get_team_standings(tour.id) until len > 0.
+        This test uses a broadcast that has team standings (e.g. German
+        Bundesliga). Re-record if it later returns [] (delete cassette, make
+        test_record, or pick another tour.id from get_top with teamTable).
+        """
+        res = Client().broadcasts.get_team_standings("Y9YjcDKG")
+        validate(List[BroadcastTeamStandingsItem], res)