mirror
/
Rapptz.discord.py
mirror of https://github.com/Rapptz/discord.py
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

[commands] Add description kwarg to parameters and show in default help

pull/8342/head
Soheab 3 years ago
committed by GitHub
parent
c92422d185
commit
668196c14c
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 108 additions and 4 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 1
      discord/ext/commands/core.py
  2. 91
      discord/ext/commands/help.py
  3. 20
      discord/ext/commands/parameters.py

1
discord/ext/commands/core.py
View File

@ -147,6 +147,7 @@ def get_signature_parameters(
parameter._annotation = default.annotation
parameter._default = default.default
parameter._description = default._description
parameter._displayed_default = default._displayed_default
annotation = parameter.annotation

91
discord/ext/commands/help.py
View File

@ -463,7 +463,6 @@ class HelpCommand:
:class:`str`
The signature for the command.
"""
parent: Optional[Group[Any, ..., Any]] = command.parent # type: ignore # the parent will be a Group
entries = []
while parent is not None:
@ -1004,9 +1003,25 @@ class DefaultHelpCommand(HelpCommand):
user if :attr:`dm_help` is set to ``None``. Defaults to 1000.
indent: :class:`int`
How much to indent the commands from a heading. Defaults to ``2``.
arguments_heading: :class:`str`
The arguments list's heading string used when the help command is invoked with a command name.
Useful for i18n. Defaults to ``"Arguments:"``.
Shown when :attr:`.show_parameter_descriptions` is ``True``.
.. versionadded:: 2.0
show_parameter_descriptions: :class:`bool`
Whether to show the parameter descriptions. Defaults to ``True``.
Setting this to ``False`` will revert to showing the :attr:`~.commands.Command.signature` instead.
.. versionadded:: 2.0
commands_heading: :class:`str`
The command list's heading string used when the help command is invoked with a category name.
Useful for i18n. Defaults to ``"Commands:"``
default_argument_description: :class:`str`
The default argument description string used when the argument's :attr:`~.commands.Parameter.description` is ``None``.
Useful for i18n. Defaults to ``"No description given."``
.. versionadded:: 2.0
no_category: :class:`str`
The string used when there is a command which does not belong to any category(cog).
Useful for i18n. Defaults to ``"No Category"``
@ -1020,9 +1035,12 @@ class DefaultHelpCommand(HelpCommand):
self.sort_commands: bool = options.pop('sort_commands', True)
self.dm_help: bool = options.pop('dm_help', False)
self.dm_help_threshold: int = options.pop('dm_help_threshold', 1000)
self.arguments_heading: str = options.pop('arguments_heading', "Arguments:")
self.commands_heading: str = options.pop('commands_heading', 'Commands:')
self.default_argument_description: str = options.pop('default_argument_description', 'No description given')
self.no_category: str = options.pop('no_category', 'No Category')
self.paginator: Paginator = options.pop('paginator', None)
self.show_parameter_descriptions: bool = options.pop('show_parameter_descriptions', True)
if self.paginator is None:
self.paginator: Paginator = Paginator()
@ -1048,6 +1066,34 @@ class DefaultHelpCommand(HelpCommand):
f'You can also type {self.context.clean_prefix}{command_name} category for more info on a category.'
)
def get_command_signature(self, command: Command[Any, ..., Any], /) -> str:
"""Retrieves the signature portion of the help page.
Calls :meth:`~.HelpCommand.get_command_signature` if :attr:`show_parameter_descriptions` is ``False``
else returns a modified signature where the command parameters are not shown.
.. versionadded:: 2.0
Parameters
------------
command: :class:`Command`
The command to get the signature of.
Returns
--------
:class:`str`
The signature for the command.
"""
if not self.show_parameter_descriptions:
return super().get_command_signature(command)
name = command.name
if len(command.aliases) > 0:
aliases = '|'.join(command.aliases)
name = f'[{command.name}|{aliases}]'
return f'{self.context.clean_prefix}{name}'
def add_indented_commands(
self, commands: Sequence[Command[Any, ..., Any]], /, *, heading: str, max_size: Optional[int] = None
) -> None:
@ -1061,7 +1107,6 @@ class DefaultHelpCommand(HelpCommand):
to fit into the :attr:`width`.
.. versionchanged:: 2.0
``commands`` parameter is now positional-only.
Parameters
@ -1090,6 +1135,42 @@ class DefaultHelpCommand(HelpCommand):
entry = f'{self.indent * " "}{name:<{width}} {command.short_doc}'
self.paginator.add_line(self.shorten_text(entry))
def add_command_arguments(self, command: Command[Any, ..., Any], /) -> None:
"""Indents a list of command arguments after the :attr:`.arguments_heading`.
The default implementation is the argument :attr:`~.commands.Parameter.name` indented by
:attr:`indent` spaces, padded to ``max_size`` using :meth:`~HelpCommand.get_max_size`
followed by the argument's :attr:`~.commands.Parameter.description` or
:attr:`.default_argument_description` and then shortened
to fit into the :attr:`width` and then :attr:`~.commands.Parameter.displayed_default`
between () if one is present after that.
.. versionadded:: 2.0
Parameters
-----------
command: :class:`Command`
The command to list the arguments for.
"""
arguments = command.clean_params.values()
if not arguments:
return
self.paginator.add_line(self.arguments_heading)
max_size = self.get_max_size(arguments) # type: ignore # not a command
get_width = discord.utils._string_width
for argument in arguments:
name = 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.
entry = self.shorten_text(entry)
if argument.displayed_default is not None:
entry += f' (default: {argument.displayed_default})'
self.paginator.add_line(entry)
async def send_pages(self) -> None:
"""A helper utility to send the page output from :attr:`paginator` to the destination."""
destination = self.get_destination()
@ -1103,6 +1184,9 @@ class DefaultHelpCommand(HelpCommand):
``command`` parameter is now positional-only.
.. versionchanged:: 2.0
:meth:`.add_command_arguments` is now called if :attr:`.show_parameter_descriptions` is ``True``.
Parameters
------------
command: :class:`Command`
@ -1123,6 +1207,9 @@ class DefaultHelpCommand(HelpCommand):
self.paginator.add_line(line)
self.paginator.add_line()
if self.show_parameter_descriptions:
self.add_command_arguments(command)
def get_destination(self) -> discord.abc.Messageable:
ctx = self.context
if self.dm_help is True:

20
discord/ext/commands/parameters.py
View File

@ -87,7 +87,7 @@ class Parameter(inspect.Parameter):
.. versionadded:: 2.0
"""
__slots__ = ('_displayed_default', '_fallback')
__slots__ = ('_displayed_default', '_description', '_fallback')
def __init__(
self,
@ -95,11 +95,13 @@ class Parameter(inspect.Parameter):
kind: ParamKinds,
default: Any = empty,
annotation: Any = empty,
description: str = empty,
displayed_default: str = empty,
) -> None:
super().__init__(name=name, kind=kind, default=default, annotation=annotation)
self._name = name
self._kind = kind
self._description = description
self._default = default
self._annotation = annotation
self._displayed_default = displayed_default
@ -112,6 +114,7 @@ class Parameter(inspect.Parameter):
kind: ParamKinds = MISSING,
default: Any = MISSING,
annotation: Any = MISSING,
description: str = MISSING,
displayed_default: Any = MISSING,
) -> Self:
if name is MISSING:
@ -122,6 +125,8 @@ class Parameter(inspect.Parameter):
default = self._default
if annotation is MISSING:
annotation = self._annotation
if description is MISSING:
description = self._description
if displayed_default is MISSING:
displayed_default = self._displayed_default
@ -130,6 +135,7 @@ class Parameter(inspect.Parameter):
kind=kind,
default=default,
annotation=annotation,
description=description,
displayed_default=displayed_default,
)
@ -152,6 +158,11 @@ class Parameter(inspect.Parameter):
return self.annotation
@property
def description(self) -> Optional[str]:
"""Optional[:class:`str`]: The description of this parameter."""
return self._description if self._description is not empty else None
@property
def displayed_default(self) -> Optional[str]:
"""Optional[:class:`str`]: The displayed default in :class:`Command.signature`."""
@ -180,6 +191,7 @@ def parameter(
*,
converter: Any = empty,
default: Any = empty,
description: str = empty,
displayed_default: str = empty,
) -> Any:
r"""parameter(\*, converter=..., default=..., displayed_default=...)
@ -205,6 +217,8 @@ def parameter(
default: Any
The default value for the parameter, if this is a :term:`callable` or a |coroutine_link|_ it is called with a
positional :class:`Context` argument.
description: :class:`str`
The description of this parameter.
displayed_default: :class:`str`
The displayed default in :attr:`Command.signature`.
"""
@ -213,6 +227,7 @@ def parameter(
kind=inspect.Parameter.POSITIONAL_OR_KEYWORD,
annotation=converter,
default=default,
description=description,
displayed_default=displayed_default,
)
@ -223,13 +238,14 @@ class ParameterAlias(Protocol):
*,
converter: Any = empty,
default: Any = empty,
description: str = empty,
displayed_default: str = empty,
) -> Any:
...
param: ParameterAlias = parameter
r"""param(\*, converter=..., default=..., displayed_default=...)
r"""param(\*, converter=..., default=..., description=..., displayed_default=...)
An alias for :func:`parameter`.

Write Preview
Loading…
Cancel
Save