[commands] Add a converter for discord.Object

2 files changed, 43 insertions, 0 deletions

diff --git a/discord/ext/commands/converter.py b/discord/ext/commands/converter.py
index b2d28075..e94a08ef 100644
--- a/discord/ext/commands/converter.py
+++ b/discord/ext/commands/converter.py
@@ -37,6 +37,7 @@ if TYPE_CHECKING:
 
 __all__ = (
     'Converter',
+    'ObjectConverter',
     'MemberConverter',
     'UserConverter',
     'MessageConverter',
@@ -122,6 +123,30 @@ class IDConverter(Converter[T_co]):
         return _ID_REGEX.match(argument)
 
 
+class ObjectConverter(IDConverter[discord.Object]):
+    """Converts to a :class:`~discord.Object`.
+
+    The argument must follow the valid ID or mention formats (e.g. `<@80088516616269824>`).
+
+    .. versionadded:: 2.0
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by member, role, or channel mention.
+    """
+
+    async def convert(self, ctx: Context, argument: str) -> discord.Object:
+        match = self._get_id_match(argument) or re.match(r'<(?:@(?:!|&)?|#)([0-9]{15,20})>$', argument)
+
+        if match is None:
+            raise ObjectNotFound(argument)
+
+        result = int(match.group(1))
+
+        return discord.Object(id=result)
+
+
 class MemberConverter(IDConverter[discord.Member]):
     """Converts to a :class:`~discord.Member`.
 
diff --git a/discord/ext/commands/errors.py b/discord/ext/commands/errors.py
index 98154d10..bfbe55fc 100644
--- a/discord/ext/commands/errors.py
+++ b/discord/ext/commands/errors.py
@@ -42,6 +42,7 @@ __all__ = (
     'MaxConcurrencyReached',
     'NotOwner',
     'MessageNotFound',
+    'ObjectNotFound',
     'MemberNotFound',
     'GuildNotFound',
     'UserNotFound',
@@ -213,6 +214,23 @@ class NotOwner(CheckFailure):
     """
     pass
 
+class ObjectNotFound(BadArgument):
+    """Exception raised when the argument provided did not match the format
+    of an ID or a mention.
+
+    This inherits from :exc:`BadArgument`
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    argument: :class:`str`
+        The argument supplied by the caller that was not matched
+    """
+    def __init__(self, argument):
+        self.argument = argument
+        super().__init__(f'{argument!r} does not follow a valid ID or mention format.')
+
 class MemberNotFound(BadArgument):
     """Exception raised when the member provided was not found in the bot's
     cache.