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

@@ -1328,6 +1328,18 @@ class Client:
             print(f"Failed to fetch guild {guild_id}: {e}")
             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

@@ -843,6 +843,10 @@ class HTTPClient:
         """Fetches a user object for a given 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"
     ) -> Dict[str, Any]:

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