[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

@@ -40,6 +40,7 @@ __all__ = (
     'PartialMessageConverter',
     'TextChannelConverter',
     'InviteConverter',
+    'GuildConverter',
     'RoleConverter',
     'GameConverter',
     'ColourConverter',
@@ -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`.
 

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.

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: