Introduce ext.dota2 - Dota 2 Game Coordinator extension

docs/ext/dota2/api.rst

@@ -0,0 +1,28 @@
+.. currentmodule:: steam.ext.dota2
+
+API Reference
+===============
+
+The following section outlines the API of steam.py's Dota 2 extension module.
+
+
+Client
+------
+
+.. attributetable:: Client
+
+.. autoclass:: Client
+    :members:
+    :inherited-members:
+
+Bot
+----
+
+``ext.dota2`` also provides a :class:`Bot` class, which is a subclass of :class:`Client` and :class:`steam.ext.commands.Bot`.
+
+.. attributetable:: steam.ext.dota2.Bot
+
+.. autoclass:: steam.ext.dota2.Bot
+    :members:
+    :inherited-members:
+

docs/ext/dota2/index.md

@@ -0,0 +1,11 @@
+(steam-ext-dota2)=
+
+# `steam.ext.dota2` - A Team Fortress 2 Game Coordinator client
+
+This extension offers the ability to interact with the Dota 2 Game Coordinator (Dota 2 GC)
+
+```{toctree}
+:maxdepth: 2
+
+api
+```

docs/index.md

@@ -29,6 +29,7 @@ steam API Reference <api>
 steam.ext.commands API Reference <ext/commands/api.rst>
 steam.ext.csgo API Reference <ext/csgo/api.rst>
 steam.ext.tf2 API Reference <ext/tf2/api.rst>
+steam.ext.dota2 API Reference <ext/dota2/api.rst>
 ```
 
 ## Extensions
@@ -41,4 +42,5 @@ steam.py has extension modules to help with common tasks.
 ext/commands/index.rst
 ext/csgo/index.rst
 ext/tf2/index.rst
+ext/dota2/index.rst
 ```

steam/ext/dota2/__init__.py

@@ -0,0 +1,10 @@
+"""
+steam.ext.dota2
+~~~~~~~~~~~~~~
+
+A library for interacting with the Dota 2 Game Coordinator.
+
+Licensed under The MIT License (MIT) - Copyright (c) 2020-present James H-B. See LICENSE
+"""
+
+from .client import *

steam/ext/dota2/client.py

@@ -0,0 +1,127 @@
+"""Licensed under The MIT License (MIT) - Copyright (c) 2020-present James H-B. See LICENSE"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Final, Literal
+
+from ..._const import timeout
+from ..._gc import Client as Client_
+from ...app import DOTA2
+from ...ext import commands
+from ...utils import MISSING
+from .protobufs.dota_gcmessages_client_watch import (
+    CMsgClientToGCFindTopSourceTVGames,
+    CMsgGCToClientFindTopSourceTVGamesResponse,
+)
+from .state import GCState  # noqa: TCH001
+
+__all__ = (
+    "Client",
+    "Bot",
+)
+
+
+class Client(Client_):
+    """Represents a client connection that connects to Steam. This class is used to interact with the Steam API, CMs
+    and the Dota 2 Game Coordinator.
+
+    :class:`Client` is a subclass of :class:`steam.Client`, so whatever you can do with :class:`steam.Client` you can
+    do with :class:`Client`.
+    """
+
+    _APP: Final = DOTA2
+    _state: GCState  # type: ignore  # PEP 705
+
+    async def fetch_top_source_tv_games(
+        self,
+        *,
+        search_key: str = MISSING,
+        league_id: int = MISSING,
+        hero_id: int = MISSING,
+        start_game: Literal[0, 10, 20, 30, 40, 50, 60, 70, 80, 90] = 0,
+        game_list_index: int = MISSING,
+        lobby_ids: list[int] = MISSING,
+    ) -> list[CMsgGCToClientFindTopSourceTVGamesResponse]:
+        """Fetch Top Source TV Games.
+
+        This functionality is similar to game list in the Watch Tab of Dota 2 game application.
+        It fetches summary data for the currently on-going Dota 2 matches from the following categories:
+
+        * tournament games
+        * highest average mmr games
+        * specific lobbies, like friends' games by their lobby_ids
+
+        Note
+        -------
+        Note that the following documentation for keyword arguments to query against is rather observant
+        than from official. So, please, if you know more or description is incorrect, contact us.
+
+        Parameters
+        ----------
+        search_key : :class: `str`, optional
+            Unknown purpose.
+        league_id : :class: `int`, optional
+            `league_id` for the professional tournament.
+        hero_id : :class: `int`, optional
+            `hero_id` to filter results by, just like in-client Watch Tab feature.
+        start_game : :class: `Literal[0, 10, 20, 30, 40, 50, 60, 70, 80, 90]`, optional, by default 0
+            This argument controls how many responses the game coordinator should return.
+            For example, `start_game=0` returns a list with 1 Response,
+            `start_game=90` returns a list of 10 Responses.
+            Game coordinator fills each response in consequent manner with games that satisfy keyword arguments
+            or with currently live highest average MMR games in case no other argument was given.
+        game_list_index : :class: `int`, optional
+            Only get responses matching `game_list_index`. Responses from Game Coordinator change
+            from time to time. The `game_list_index` indicates that those responses belong to the same chunk.
+        lobby_ids : :class: `list[int]`, optional
+            Lobby ids to query against.
+
+        Returns
+        -------
+        list[dota_gcmessages_client_watch.CMsgGCToClientFindTopSourceTVGamesResponse]
+            The list of responses from Dota 2 Coordinator.
+            Those are grouped into grouped into chunks of 10 games.
+
+        Raises
+        ------
+        asyncio.TimeoutError
+            Request time-outed. The reason for this might be inappropriate combination of keyword arguments,
+            inappropriate argument values or simply Dota 2 Game Coordinator being down.
+        """
+        kwargs = locals()
+        kwargs.pop("self")
+        kwargs = {key: value for key, value in kwargs.items() if value is not MISSING}
+
+        def start_game_check(start_game: int):
+            def predicate(msg: CMsgGCToClientFindTopSourceTVGamesResponse) -> bool:
+                return msg.start_game == start_game
+
+            return predicate
+
+        futures = [
+            self._state.ws.gc_wait_for(
+                CMsgGCToClientFindTopSourceTVGamesResponse,
+                check=start_game_check(game_counter),
+            )
+            for game_counter in list(range(0, start_game + 1, 10))
+        ]
+
+        await self._state.ws.send_gc_message(CMsgClientToGCFindTopSourceTVGames(**kwargs))
+
+        try:
+            async with timeout(30.0):
+                return await asyncio.gather(*futures)
+        except asyncio.TimeoutError:
+            raise asyncio.TimeoutError(
+                "Request time-outed. The reason might be inappropriate combination of keyword arguments, "
+                + "inappropriate argument values or simply Dota 2 Game Coordinator being down."
+            )
+
+
+class Bot(commands.Bot, Client):
+    """Represents a Steam bot.
+
+    :class:`Bot` is a subclass of :class:`~steam.ext.commands.Bot`, so whatever you can do with
+    :class:`~steam.ext.commands.Bot` you can do with :class:`Bot`.
+    """

steam/ext/dota2/protobufs/__init__.py

@@ -0,0 +1,10 @@
+from typing import Final
+
+import betterproto
+
+APP_ID: Final = 570
+
+from ....protobufs.msg import GCProtobufMessage
+from . import dota_gcmessages_client_watch as dota_gcmessages_client_watch, gcsdk_gcmessages as gcsdk_gcmessages
+
+[setattr(cls, "_betterproto", betterproto.ProtoClassMetadata(cls)) for cls in GCProtobufMessage.__subclasses__()]