#6 Implement Broadcasts.get_players

CHANGELOG.rst

@@ -4,6 +4,7 @@ Changelog
 To be released
 --------------
 
+* Added ``client.broadcasts.get_players`` to get the list of players of a broadcast tournament.
 
 * 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.
 

README.rst

@@ -117,6 +117,7 @@ Most of the API is available:
     client.broadcasts.get_pgns
     client.broadcasts.stream_round
     client.broadcasts.get_top
+    client.broadcasts.get_players
     client.broadcasts.search
     client.broadcasts.get_by_user
 

berserk/clients/broadcasts.py

@@ -9,6 +9,7 @@
 from ..types.broadcast import (
     BroadcastPlayer,
     BroadcastTop,
+    BroadcastTournamentPlayer,
     PaginatedBroadcasts,
     BroadcastsByUser,
 )
@@ -280,6 +281,17 @@ def search(
         params = {"q": query, "page": page}
         return cast(PaginatedBroadcasts, self._r.get(path, params=params))
 
+    def get_players(
+        self, broadcast_tournament_id: str
+    ) -> List[BroadcastTournamentPlayer]:
+        """Get the list of players of a broadcast tournament.
+
+        :param broadcast_tournament_id: ID of the broadcast tournament
+        :return: list of broadcast tournament players (name, team, fed, score, etc.)
+        """
+        path = f"/broadcast/{broadcast_tournament_id}/players"
+        return cast(List[BroadcastTournamentPlayer], self._r.get(path))
+
     def get_by_user(
         self,
         username: str,

berserk/types/__init__.py

@@ -12,6 +12,7 @@
 from .broadcast import (
     BroadcastPlayer,
     BroadcastTop,
+    BroadcastTournamentPlayer,
     PaginatedBroadcasts,
     BroadcastsByUser,
 )
@@ -36,6 +37,7 @@
     "AccountInformation",
     "ArenaResult",
     "BroadcastPlayer",
+    "BroadcastTournamentPlayer",
     "BroadcastsByUser",
     "BroadcastTop",
     "BulkPairing",

berserk/types/broadcast.py

@@ -1,12 +1,30 @@
 from __future__ import annotations
 
-from typing import List
+from typing import Dict, List
 
 from typing_extensions import NotRequired, TypedDict
 
 from .common import LightUser, Title
 
 
+class BroadcastTournamentPlayer(TypedDict):
+    """Player entry from GET /broadcast/{id}/players."""
+
+    name: str
+    rating: NotRequired[int]
+    title: NotRequired[str]
+    fideId: NotRequired[int]
+    team: NotRequired[str]
+    fed: NotRequired[str]
+    played: NotRequired[int]
+    score: NotRequired[int | float]
+    ratingDiff: NotRequired[int]
+    ratingsMap: NotRequired[Dict[str, int]]
+    ratingDiffs: NotRequired[Dict[str, int]]
+    performance: NotRequired[int]
+    performances: NotRequired[Dict[str, int]]
+
+
 class BroadcastPlayer(TypedDict):
     # The name of the player as it appears on the source PGN
     source_name: str

tests/clients/test_broadcasts.py

@@ -1,7 +1,14 @@
+from typing import List
+
 import pytest
 
 from berserk import Client
-from berserk.types import BroadcastTop, PaginatedBroadcasts, BroadcastsByUser
+from berserk.types import (
+    BroadcastTop,
+    BroadcastTournamentPlayer,
+    PaginatedBroadcasts,
+    BroadcastsByUser,
+)
 from utils import skip_if_older_3_dot_10, validate
 
 
@@ -23,3 +30,9 @@ 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_players(self):
+        res = Client().broadcasts.get_players(broadcast_tournament_id="8jXzp45R")
+        validate(List[BroadcastTournamentPlayer], res)