Add guild listing methods (#71)

README.md

@@ -158,6 +158,14 @@ guild = await client.fetch_guild("123456789012345678")
 roles = await client.fetch_roles(guild.id)
 ```
 
+Call `Client.fetch_guilds` to list all guilds the current user has access to.
+
+```python
+guilds = await client.fetch_guilds()
+for g in guilds:
+    print(g.name)
+```
+
 ## Sharding
 
 To run your bot across multiple gateway shards, pass ``shard_count`` when creating

disagreement/client.py

@@ -1311,8 +1311,8 @@ class Client:
 
         return self._messages.get(message_id)
 
-    async def fetch_guild(self, guild_id: Snowflake) -> Optional["Guild"]:
+    async def fetch_guild(self, guild_id: Snowflake) -> Optional["Guild"]:
-        """Fetches a guild by ID from Discord and caches it."""
+        """Fetches a guild by ID from Discord and caches it."""
 
         if self._closed:
             raise DisagreementException("Client is closed.")
@@ -1326,7 +1326,19 @@ class Client:
             return self.parse_guild(guild_data)
         except DisagreementException as e:
             print(f"Failed to fetch guild {guild_id}: {e}")
-            return None
+            return None
+
+    async def fetch_guilds(self) -> List["Guild"]:
+        """Fetch all guilds the current user is in."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.get_current_user_guilds()
+        guilds: List["Guild"] = []
+        for guild_data in data:
+            guilds.append(self.parse_guild(guild_data))
+        return guilds
 
     async def fetch_channel(self, channel_id: Snowflake) -> Optional["Channel"]:
         """Fetches a channel from Discord by its ID and updates the cache."""

disagreement/http.py

@@ -839,9 +839,13 @@ class HTTPClient:
             use_auth_header=False,
         )
 
-    async def get_user(self, user_id: "Snowflake") -> Dict[str, Any]:
+    async def get_user(self, user_id: "Snowflake") -> Dict[str, Any]:
-        """Fetches a user object for a given user ID."""
+        """Fetches a user object for a given user ID."""
-        return await self.request("GET", f"/users/{user_id}")
+        return await self.request("GET", f"/users/{user_id}")
+
+    async def get_current_user_guilds(self) -> List[Dict[str, Any]]:
+        """Returns the guilds the current user is in."""
+        return await self.request("GET", "/users/@me/guilds")
 
     async def get_guild_member(
         self, guild_id: "Snowflake", user_id: "Snowflake"

docs/http_client.md

@@ -18,3 +18,14 @@ client = Client(
 These options are passed through to `aiohttp.ClientSession` when the session is
 created. You can set a proxy URL, provide a custom connector, or supply any
 other supported session argument.
+
+## Get Current User Guilds
+
+The HTTP client can list the guilds the bot user is in:
+
+```python
+from disagreement.http import HTTPClient
+
+http = HTTPClient(token="TOKEN")
+guilds = await http.get_current_user_guilds()
+```

docs/introduction.md

@@ -161,6 +161,12 @@ guild = await client.fetch_guild("123456789012345678")
 roles = await client.fetch_roles(guild.id)
 ```
 
+To retrieve all guilds available to the bot, use `Client.fetch_guilds`.
+
+```python
+guilds = await client.fetch_guilds()
+```
+
 ## Sharding
 
 To run your bot across multiple gateway shards, pass ``shard_count`` when creating