From 68eb844d48be4aaeb55a264944b1a7164329ee75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Alex=20N=C3=B8rgaard?= <Umbra@AbstractUmbra.xyz>
Date: Sun, 7 Feb 2021 10:32:33 +0000
Subject: [PATCH] [commands] Add discord.Guild converter and GuildNotFound
 error

* Add discord.Guild converter and GuildNotFound error

* note for lack of disambiguation in Guilds with duplicate names, and removed the possibility of returning None

* edited converter to use `utils.get` over `utils.find` and docs edited with Converter and Exception.
---
 discord/ext/commands/converter.py | 29 ++++++++++++++++++++++++++++-
 discord/ext/commands/errors.py    | 17 +++++++++++++++++
 docs/ext/commands/api.rst         |  6 ++++++
 3 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/discord/ext/commands/converter.py b/discord/ext/commands/converter.py
index 27991eca0..db686a26d 100644
--- a/discord/ext/commands/converter.py
+++ b/discord/ext/commands/converter.py
@@ -40,6 +40,7 @@ __all__ = (
     'PartialMessageConverter',
     'TextChannelConverter',
     'InviteConverter',
+    'GuildConverter',
     'RoleConverter',
     'GameConverter',
     'ColourConverter',
@@ -282,7 +283,7 @@ class PartialMessageConverter(Converter):
         if not channel:
             raise ChannelNotFound(channel_id)
         return discord.PartialMessage(channel=channel, id=message_id)
-        
+
 class MessageConverter(PartialMessageConverter):
     """Converts to a :class:`discord.Message`.
 
@@ -524,6 +525,32 @@ class InviteConverter(Converter):
         except Exception as exc:
             raise BadInviteArgument() from exc
 
+class GuildConverter(IDConverter):
+    """Converts to a :class:`~discord.Guild`.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by name. (There is no disambiguation for Guilds with multiple matching names).
+
+    .. versionadded:: 1.7
+    """
+
+    async def convert(self, ctx, argument):
+        match = self._get_id_match(argument)
+        result = None
+
+        if match is not None:
+            guild_id = int(match.group(1))
+            result = ctx.bot.get_guild(guild_id)
+
+        if result is None:
+            result = discord.utils.get(ctx.bot.guilds, name=argument)
+
+            if result is None:
+                raise GuildNotFound(argument)
+        return result
+
 class EmojiConverter(IDConverter):
     """Converts to a :class:`~discord.Emoji`.
 
diff --git a/discord/ext/commands/errors.py b/discord/ext/commands/errors.py
index aa4c585b4..d533d96a7 100644
--- a/discord/ext/commands/errors.py
+++ b/discord/ext/commands/errors.py
@@ -45,6 +45,7 @@ __all__ = (
     'NotOwner',
     'MessageNotFound',
     'MemberNotFound',
+    'GuildNotFound',
     'UserNotFound',
     'ChannelNotFound',
     'ChannelNotReadable',
@@ -230,6 +231,22 @@ class MemberNotFound(BadArgument):
         self.argument = argument
         super().__init__('Member "{}" not found.'.format(argument))
 
+class GuildNotFound(BadArgument):
+    """Exception raised when the guild provided was not found in the bot's cache.
+
+    This inherits from :exc:`BadArgument`
+
+    .. versionadded:: 1.7
+
+    Attributes
+    -----------
+    argument: :class:`str`
+        The guild supplied by the called that was not found
+    """
+    def __init__(self, argument):
+        self.argument = argument
+        super().__init__('Guild "{}" not found.'.format(argument))
+
 class UserNotFound(BadArgument):
     """Exception raised when the user provided was not found in the bot's
     cache.
diff --git a/docs/ext/commands/api.rst b/docs/ext/commands/api.rst
index 86ceeb2ae..f66c29583 100644
--- a/docs/ext/commands/api.rst
+++ b/docs/ext/commands/api.rst
@@ -296,6 +296,9 @@ Converters
 .. autoclass:: discord.ext.commands.InviteConverter
     :members:
 
+.. autoclass:: discord.ext.commands.GuildConverter
+    :members:
+
 .. autoclass:: discord.ext.commands.RoleConverter
     :members:
 
@@ -410,6 +413,9 @@ Exceptions
 .. autoexception:: discord.ext.commands.MemberNotFound
     :members:
 
+.. autoexception:: discord.ext.commands.GuildNotFound
+    :members:
+
 .. autoexception:: discord.ext.commands.UserNotFound
     :members: