[commands] Add displayed_name to commands.Parameter

discord/ext/commands/core.py

@@ -151,6 +151,7 @@ def get_signature_parameters(
             parameter._default = default.default
             parameter._description = default._description
             parameter._displayed_default = default._displayed_default
+            parameter._displayed_name = default._displayed_name
 
         annotation = parameter.annotation
 
@@ -194,8 +195,13 @@ def extract_descriptions_from_docstring(function: Callable[..., Any], params: Di
     description, param_docstring = divide
     for match in NUMPY_DOCSTRING_ARG_REGEX.finditer(param_docstring):
         name = match.group('name')
+
         if name not in params:
-            continue
+            is_display_name = discord.utils.get(params.values(), displayed_name=name)
+            if is_display_name:
+                name = is_display_name.name
+            else:
+                continue
 
         param = params[name]
         if param.description is None:
@@ -1169,7 +1175,9 @@ class Command(_BaseCommand, Generic[CogT, P, T]):
             return ''
 
         result = []
-        for name, param in params.items():
+        for param in params.values():
+            name = param.displayed_name or param.name
+
             greedy = isinstance(param.converter, Greedy)
             optional = False  # postpone evaluation of if it's an optional argument
 

discord/ext/commands/errors.py

@@ -182,7 +182,7 @@ class MissingRequiredArgument(UserInputError):
 
     def __init__(self, param: Parameter) -> None:
         self.param: Parameter = param
-        super().__init__(f'{param.name} is a required argument that is missing.')
+        super().__init__(f'{param.displayed_name or param.name} is a required argument that is missing.')
 
 
 class MissingRequiredAttachment(UserInputError):
@@ -201,7 +201,7 @@ class MissingRequiredAttachment(UserInputError):
 
     def __init__(self, param: Parameter) -> None:
         self.param: Parameter = param
-        super().__init__(f'{param.name} is a required argument that is missing an attachment.')
+        super().__init__(f'{param.displayed_name or param.name} is a required argument that is missing an attachment.')
 
 
 class TooManyArguments(UserInputError):
@@ -901,7 +901,7 @@ class BadUnionArgument(UserInputError):
         else:
             fmt = ' or '.join(to_string)
 
-        super().__init__(f'Could not convert "{param.name}" into {fmt}.')
+        super().__init__(f'Could not convert "{param.displayed_name or param.name}" into {fmt}.')
 
 
 class BadLiteralArgument(UserInputError):
@@ -938,7 +938,7 @@ class BadLiteralArgument(UserInputError):
         else:
             fmt = ' or '.join(to_string)
 
-        super().__init__(f'Could not convert "{param.name}" into the literal {fmt}.')
+        super().__init__(f'Could not convert "{param.displayed_name or param.name}" into the literal {fmt}.')
 
 
 class ArgumentParsingError(UserInputError):

discord/ext/commands/help.py

@@ -1166,7 +1166,7 @@ class DefaultHelpCommand(HelpCommand):
 
         get_width = discord.utils._string_width
         for argument in arguments:
-            name = argument.name
+            name = argument.displayed_name or argument.name
             width = max_size - (get_width(name) - len(name))
             entry = f'{self.indent * " "}{name:<{width}} {argument.description or self.default_argument_description}'
             # we do not want to shorten the default value, if any.

discord/ext/commands/parameters.py

@@ -87,7 +87,7 @@ class Parameter(inspect.Parameter):
     .. versionadded:: 2.0
     """
 
-    __slots__ = ('_displayed_default', '_description', '_fallback')
+    __slots__ = ('_displayed_default', '_description', '_fallback', '_displayed_name')
 
     def __init__(
         self,
@@ -97,6 +97,7 @@ class Parameter(inspect.Parameter):
         annotation: Any = empty,
         description: str = empty,
         displayed_default: str = empty,
+        displayed_name: str = empty,
     ) -> None:
         super().__init__(name=name, kind=kind, default=default, annotation=annotation)
         self._name = name
@@ -106,6 +107,7 @@ class Parameter(inspect.Parameter):
         self._annotation = annotation
         self._displayed_default = displayed_default
         self._fallback = False
+        self._displayed_name = displayed_name
 
     def replace(
         self,
@@ -116,6 +118,7 @@ class Parameter(inspect.Parameter):
         annotation: Any = MISSING,
         description: str = MISSING,
         displayed_default: Any = MISSING,
+        displayed_name: Any = MISSING,
     ) -> Self:
         if name is MISSING:
             name = self._name
@@ -129,6 +132,8 @@ class Parameter(inspect.Parameter):
             description = self._description
         if displayed_default is MISSING:
             displayed_default = self._displayed_default
+        if displayed_name is MISSING:
+            displayed_name = self._displayed_name
 
         return self.__class__(
             name=name,
@@ -137,6 +142,7 @@ class Parameter(inspect.Parameter):
             annotation=annotation,
             description=description,
             displayed_default=displayed_default,
+            displayed_name=displayed_name,
         )
 
     if not TYPE_CHECKING:  # this is to prevent anything breaking if inspect internals change
@@ -171,6 +177,14 @@ class Parameter(inspect.Parameter):
 
         return None if self.required else str(self.default)
 
+    @property
+    def displayed_name(self) -> Optional[str]:
+        """Optional[:class:`str`]: The name that is displayed to the user.
+
+        .. versionadded:: 2.3
+        """
+        return self._displayed_name if self._displayed_name is not empty else None
+
     async def get_default(self, ctx: Context[Any]) -> Any:
         """|coro|
 
@@ -193,8 +207,9 @@ def parameter(
     default: Any = empty,
     description: str = empty,
     displayed_default: str = empty,
+    displayed_name: str = empty,
 ) -> Any:
-    r"""parameter(\*, converter=..., default=..., description=..., displayed_default=...)
+    r"""parameter(\*, converter=..., default=..., description=..., displayed_default=..., displayed_name=...)
 
     A way to assign custom metadata for a :class:`Command`\'s parameter.
 
@@ -221,6 +236,10 @@ def parameter(
         The description of this parameter.
     displayed_default: :class:`str`
         The displayed default in :attr:`Command.signature`.
+    displayed_name: :class:`str`
+        The name that is displayed to the user.
+
+        .. versionadded:: 2.3
     """
     return Parameter(
         name='empty',
@@ -229,6 +248,7 @@ def parameter(
         default=default,
         description=description,
         displayed_default=displayed_default,
+        displayed_name=displayed_name,
     )
 
 
@@ -240,12 +260,13 @@ class ParameterAlias(Protocol):
         default: Any = empty,
         description: str = empty,
         displayed_default: str = empty,
+        displayed_name: str = empty,
     ) -> Any:
         ...
 
 
 param: ParameterAlias = parameter
-r"""param(\*, converter=..., default=..., description=..., displayed_default=...)
+r"""param(\*, converter=..., default=..., description=..., displayed_default=..., displayed_name=...)
 
 An alias for :func:`parameter`.