🏅Implement RankTier Medals

and a few brush ups

steam/ext/dota2/client.py

@@ -52,7 +52,7 @@ async def top_live_matches(self, *, hero: Hero = MISSING, limit: int = 100) -> l
         This is similar to game list in the Watch Tab of Dota 2 game app.
         "Top matches" in this context means
 
-        * tournament matches
+        * featured tournament matches
         * highest average MMR matches
 
         Parameters
@@ -163,16 +163,8 @@ async def live_matches(
         asyncio.TimeoutError
             Request time-outed. The reason is usually Dota 2 Game Coordinator lagging or being down.
         """
-        future = self._state.ws.gc_wait_for(
-            watch.GCToClientFindTopSourceTVGamesResponse,
-            check=lambda msg: msg.specific_games == True,
-        )
-        await self._state.ws.send_gc_message(watch.ClientToGCFindTopSourceTVGames(lobby_ids=lobby_ids))
-
-        async with timeout(15.0):
-            response = await future
-        # todo: test with more than 10 lobby_ids, Game Coordinator will probably chunk it wrongly or fail at all
 
+        response = await self._state.fetch_live_matches(lobby_ids)
         return [LiveMatch(self._state, match) for match in response.game_list]
 
     async def match_details(self, match_id: int) -> MatchDetails:

steam/ext/dota2/enums.py

@@ -15,8 +15,10 @@
     "Hero",
     "GameMode",
     "LobbyType",
+    "RankTier",
 )
 
+
 # fmt: off
 class Hero(IntEnum):
     """Enum representing Dota 2 hero.
@@ -144,6 +146,7 @@ class Hero(IntEnum):
     VoidSpirit        = 126
     Snapfire          = 128
     Mars              = 129
+    Ringmaster        = 131
     Dawnbreaker       = 135
     Marci             = 136
     PrimalBeast       = 137
@@ -273,6 +276,7 @@ def DISPLAY_NAMES(cls: type[Self]) -> Mapping[Hero, str]:  # type: ignore
             cls.VoidSpirit       : "Void Spirit",
             cls.Snapfire         : "Snapfire",
             cls.Mars             : "Mars",
+            cls.Ringmaster       : "Ringmaster",
             cls.Dawnbreaker      : "Dawnbreaker",
             cls.Marci            : "Marci",
             cls.PrimalBeast      : "Primal Beast",
@@ -386,6 +390,66 @@ def display_name(self) -> str:
         return self.DISPLAY_NAMES[self]
 
 
+class RankTier(IntEnum):
+    """Enum representing Dota 2 Rank Tier.
+
+    Commonly called "ranked medals".
+    """
+    Uncalibrated = 0
+
+    Herald1      = 11
+    Herald2      = 12
+    Herald3      = 13
+    Herald4      = 14
+    Herald5      = 15
+
+    Guardian1    = 21
+    Guardian2    = 22
+    Guardian3    = 23
+    Guardian4    = 24
+    Guardian5    = 25
+
+    Crusader1    = 31
+    Crusader2    = 32
+    Crusader3    = 33
+    Crusader4    = 34
+    Crusader5    = 35
+
+    Archon1      = 41
+    Archon2      = 42
+    Archon3      = 43
+    Archon4      = 44
+    Archon5      = 45
+
+    Legend1      = 51
+    Legend2      = 52
+    Legend3      = 53
+    Legend4      = 54
+    Legend5      = 55
+
+    Ancient1     = 61
+    Ancient2     = 62
+    Ancient3     = 63
+    Ancient4     = 64
+    Ancient5     = 65
+
+    Divine1      = 71
+    Divine2      = 72
+    Divine3      = 73
+    Divine4      = 74
+    Divine5      = 75
+
+    Immortal     = 80
+
+    @property
+    def display_name(self) -> str:
+        if self.value % 10 == 0:
+            return self.name
+        else:
+            return self.name[:-1] + ' ' + self.name[-1]
+
+
+
 class EMsg(IntEnum):
     # EGCBaseClientMsg - source: gcsystemmsgs.proto
     PingRequest                  = 3001

steam/ext/dota2/models.py

@@ -10,7 +10,7 @@
 from ... import abc, user
 from ..._gc.client import ClientUser as ClientUser_
 from ...utils import DateTime
-from .enums import GameMode, Hero, LobbyType
+from .enums import GameMode, Hero, LobbyType, RankTier
 from .protobufs import client_messages
 
 if TYPE_CHECKING:
@@ -325,20 +325,27 @@ class BehaviorSummary:
 class ProfileCard(Generic[UserT]):
     def __init__(self, user: UserT, proto: common.ProfileCard):
         self.user = user
-        self.slots = proto.slots
         self.badge_points = proto.badge_points
         self.event_points = proto.event_points
         self.event_id = proto.event_id
         self.recent_battle_cup_victory = proto.recent_battle_cup_victory
-        self.rank_tier = proto.rank_tier
+        self.rank_tier = RankTier.try_value(proto.rank_tier)
+        """Ranked medal like Herald-Immortal with a number of stars, i.e. Legend 5."""
         self.leaderboard_rank = proto.leaderboard_rank
+        """Leaderboard rank, i.e. found here https://www.dota2.com/leaderboards/#europe."""
         self.is_plus_subscriber = proto.is_plus_subscriber
+        """Is Dota Plus Subscriber."""
         self.plus_original_start_date = proto.plus_original_start_date
-        self.rank_tier_score = proto.rank_tier_score
-        self.leaderboard_rank_core = proto.leaderboard_rank_core
-        self.title = proto.title
+        """When user subscribed to Dota Plus for their very first time."""
         self.favorite_team_packed = proto.favorite_team_packed
         self.lifetime_games = proto.lifetime_games
+        """Amount of lifetime games, includes Turbo games as well."""
+
+        # (?) Unused/Deprecated by Valve
+        # self.slots = proto.slots  # profile page was reworked
+        # self.title = proto.title
+        # self.rank_tier_score = proto.rank_tier_score  # relic from time when support/core MMR were separated
+        # self.leaderboard_rank_core = proto.leaderboard_rank_core  # relic from time when support/core MMR were separated
 
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__} user={self.user!r}>"

steam/ext/dota2/state.py

@@ -10,7 +10,7 @@
 from ...id import _ID64_TO_ID32
 from ...state import parser
 from .models import PartialUser, User
-from .protobufs import client_messages, common, sdk
+from .protobufs import client_messages, common, sdk, watch
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Sequence
@@ -54,32 +54,54 @@ async def _maybe_users(self, id64s: Iterable[ID64]) -> Sequence[User]: ...
     def _get_gc_message(self) -> sdk.ClientHello:
         return sdk.ClientHello()
 
+    @parser
+    def parse_client_goodbye(self, msg: sdk.ConnectionStatus | None = None) -> None:
+        if msg is None or msg.status == sdk.GCConnectionStatus.NoSession:
+            self.dispatch("gc_disconnect")
+            self._gc_connected.clear()
+            self._gc_ready.clear()
+        if msg is not None:
+            self.dispatch("gc_status_change", msg.status)
+
+    @parser
+    async def parse_gc_client_connect(self, msg: sdk.ClientWelcome) -> None:
+        if not self._gc_ready.is_set():
+            self._gc_ready.set()
+            self.dispatch("gc_ready")
+
+    # dota fetch proto calls
+    # the difference between these and the functions in `client`/`models` is that
+    # these give raw proto responses while the latter modelize/structure/refine them.
+
     async def fetch_user_dota2_profile_card(self, user_id: int) -> common.ProfileCard:
+        """Fetch User's Dota 2 Profile Card.
+
+        Contains basic info about the account. Kinda mirrors old profile page.
+        """
         await self.ws.send_gc_message(client_messages.ClientToGCGetProfileCard(account_id=user_id))
         return await self.ws.gc_wait_for(
             common.ProfileCard,
             check=lambda msg: msg.account_id == user_id,
         )
 
     async def fetch_match_details(self, match_id: int) -> client_messages.MatchDetailsResponse:
+        """Fetch Match Details.
+
+        This call is for already finished games. Contains most of the info that can be found in post-match stats.
+        """
         await self.ws.send_gc_message(client_messages.MatchDetailsRequest(match_id=match_id))
         async with timeout(15.0):
             return await self.ws.gc_wait_for(
                 client_messages.MatchDetailsResponse,
                 check=lambda msg: msg.match.match_id == match_id,
             )
 
-    @parser
-    def parse_client_goodbye(self, msg: sdk.ConnectionStatus | None = None) -> None:
-        if msg is None or msg.status == sdk.GCConnectionStatus.NoSession:
-            self.dispatch("gc_disconnect")
-            self._gc_connected.clear()
-            self._gc_ready.clear()
-        if msg is not None:
-            self.dispatch("gc_status_change", msg.status)
-
-    @parser
-    async def parse_gc_client_connect(self, msg: sdk.ClientWelcome) -> None:
-        if not self._gc_ready.is_set():
-            self._gc_ready.set()
-            self.dispatch("gc_ready")
+    async def fetch_live_matches(self, lobby_ids: list[int]) -> watch.GCToClientFindTopSourceTVGamesResponse:
+        """Fetch Live Match by lobby ids."""
+        await self.ws.send_gc_message(watch.ClientToGCFindTopSourceTVGames(lobby_ids=lobby_ids))
+        async with timeout(15.0):
+            # todo: test with more than 10 lobby_ids, Game Coordinator will probably chunk it wrongly or fail at all
+            return await self.ws.gc_wait_for(
+                watch.GCToClientFindTopSourceTVGamesResponse,
+                check=lambda msg: msg.specific_games == True,
+            )