From 5fcd4e411fc6f7d58465c6766585afda0518e6ff Mon Sep 17 00:00:00 2001
From: Rapptz <rapptz@gmail.com>
Date: Fri, 22 Apr 2022 06:21:10 -0400
Subject: [PATCH] [commands] Add support for typing.Annotated

---
 discord/app_commands/transformers.py |  3 +++
 discord/ext/commands/core.py         |  6 ++++++
 docs/ext/commands/commands.rst       | 26 ++++++++++++++++++++++++++
 3 files changed, 35 insertions(+)

diff --git a/discord/app_commands/transformers.py b/discord/app_commands/transformers.py
index 6e9e70a47..cbcd45c46 100644
--- a/discord/app_commands/transformers.py
+++ b/discord/app_commands/transformers.py
@@ -625,6 +625,9 @@ def get_supported_annotation(
     if hasattr(annotation, '__discord_app_commands_transform__'):
         return (annotation.metadata, MISSING)
 
+    if hasattr(annotation, '__metadata__'):
+        return get_supported_annotation(annotation.__metadata__[0])
+
     if inspect.isclass(annotation):
         if issubclass(annotation, Transformer):
             return (annotation, MISSING)
diff --git a/discord/ext/commands/core.py b/discord/ext/commands/core.py
index 33801732a..918ecc2ec 100644
--- a/discord/ext/commands/core.py
+++ b/discord/ext/commands/core.py
@@ -161,6 +161,12 @@ def get_signature_parameters(
         if annotation is Greedy:
             raise TypeError('Unparameterized Greedy[...] is disallowed in signature.')
 
+        if hasattr(annotation, '__metadata__'):
+            # Annotated[X, Y] can access Y via __metadata__
+            metadata = annotation.__metadata__
+            if len(metadata) >= 1:
+                annotation = metadata[0]
+
         if isinstance(annotation, discord.app_commands.transformers._TransformMetadata):
             annotation = annotation.metadata
 
diff --git a/docs/ext/commands/commands.rst b/docs/ext/commands/commands.rst
index 3d1e60db9..a010232bc 100644
--- a/docs/ext/commands/commands.rst
+++ b/docs/ext/commands/commands.rst
@@ -530,6 +530,8 @@ resumes handling, which in this case would be to pass it into the ``liquid`` par
 typing.Literal
 ^^^^^^^^^^^^^^^^
 
+.. versionadded:: 2.0
+
 A :data:`typing.Literal` is a special type hint that requires the passed parameter to be equal to one of the listed values
 after being converted to the same type. For example, given the following:
 
@@ -548,6 +550,30 @@ The ``buy_sell`` parameter must be either the literal string ``"buy"`` or ``"sel
 
 Note that ``typing.Literal[True]`` and ``typing.Literal[False]`` still follow the :class:`bool` converter rules.
 
+typing.Annotated
+^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 2.0
+
+A :data:`typing.Annotated` is a special type introduced in Python 3.9 that allows the type checker to see one type, but allows the library to see another type. This is useful for appeasing the type checker for complicated converters. The second parameter of ``Annotated`` must be the converter that the library should use.
+
+For example, given the following:
+
+.. code-block:: python3
+
+    from typing import Annotated
+
+    @bot.command()
+    async def fun(ctx, arg: Annotated[str, lambda s: s.upper()]):
+        await ctx.send(arg)
+
+The type checker will see ``arg`` as a regular :class:`str` but the library will know you wanted to change the input into all upper-case.
+
+.. note::
+
+    For Python versions below 3.9, it is recommended to install the ``typing_extensions`` library and import ``Annotated`` from there.
+
+
 Greedy
 ^^^^^^^^