Browse Source

[commands] Fix up Greedy documentation a bit.

pull/796/merge
Rapptz 7 years ago
parent
commit
418048b98a
  1. 4
      discord/ext/commands/errors.py
  2. 2
      docs/ext/commands/api.rst
  3. 20
      docs/ext/commands/commands.rst

4
discord/ext/commands/errors.py

@ -54,6 +54,8 @@ class CommandError(DiscordException):
class ConversionError(CommandError): class ConversionError(CommandError):
"""Exception raised when a Converter class raises non-CommandError. """Exception raised when a Converter class raises non-CommandError.
This inherits from :exc:`.CommandError`.
Attributes Attributes
---------- ----------
converter: :class:`discord.ext.commands.Converter` converter: :class:`discord.ext.commands.Converter`
@ -61,8 +63,6 @@ class ConversionError(CommandError):
original original
The original exception that was raised. You can also get this via The original exception that was raised. You can also get this via
the ``__cause__`` attribute. the ``__cause__`` attribute.
This inherits from :exc:`.CommandError`.
""" """
def __init__(self, converter, original): def __init__(self, converter, original):
self.converter = converter self.converter = converter

2
docs/ext/commands/api.rst

@ -179,7 +179,7 @@ Converters
.. autoclass:: discord.ext.commands.clean_content .. autoclass:: discord.ext.commands.clean_content
:members: :members:
.. class:: Greedy .. data:: ext.commands.Greedy
A special converter that greedily consumes arguments until it can't. A special converter that greedily consumes arguments until it can't.
As a consequence of this behaviour, most input errors are silently discarded, As a consequence of this behaviour, most input errors are silently discarded,

20
docs/ext/commands/commands.rst

@ -429,7 +429,7 @@ commands in an easy to use manner.
typing.Union typing.Union
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
A :class:`typing.Union` is a special type hint that allows for the command to take in any of the specific types instead of A :data:`typing.Union` is a special type hint that allows for the command to take in any of the specific types instead of
a singular type. For example, given the following: a singular type. For example, given the following:
.. code-block:: python3 .. code-block:: python3
@ -446,12 +446,12 @@ The way this works is through a left-to-right order. It first attempts to conver
:class:`discord.TextChannel`, and if it fails it tries to convert it to a :class:`discord.Member`. If all converters fail, :class:`discord.TextChannel`, and if it fails it tries to convert it to a :class:`discord.Member`. If all converters fail,
then a special error is raised, :exc:`~ext.commands.BadUnionArgument`. then a special error is raised, :exc:`~ext.commands.BadUnionArgument`.
Note that any valid converter discussed above can be passed in to the argument list of a :class:`typing.Union`. Note that any valid converter discussed above can be passed in to the argument list of a :data:`typing.Union`.
typing.Optional typing.Optional
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
A :class:`typing.Optional` is a special type hint that allows for "back-referencing" behaviour. If the converter fails to A :data:`typing.Optional` is a special type hint that allows for "back-referencing" behaviour. If the converter fails to
parse into the specified type, the parser will skip the parameter and then either ``None`` or the specified default will be parse into the specified type, the parser will skip the parameter and then either ``None`` or the specified default will be
passed into the parameter instead. The parser will then continue on to the next parameters and converters, if any. passed into the parameter instead. The parser will then continue on to the next parameters and converters, if any.
@ -474,7 +474,7 @@ resumes handling, which in this case would be to pass it into the ``liquid`` par
Greedy Greedy
^^^^^^^^ ^^^^^^^^
The :class:`~ext.commands.Greedy` converter is a generalisation of the :class:`typing.Optional` converter, except applied The :data:`~ext.commands.Greedy` converter is a generalisation of the :data:`typing.Optional` converter, except applied
to a list of arguments. In simple terms, this means that it tries to convert as much as it can until it can't convert to a list of arguments. In simple terms, this means that it tries to convert as much as it can until it can't convert
any further. any further.
@ -495,13 +495,13 @@ The type passed when using this converter depends on the parameter type that it
- Positional parameter types will receive either the default parameter or a :class:`list` of the converted values. - Positional parameter types will receive either the default parameter or a :class:`list` of the converted values.
- Variable parameter types will be a :class:`tuple` as usual. - Variable parameter types will be a :class:`tuple` as usual.
- Keyword-only parameter types will be the same as if :class:`~ext.commands.Greedy` was not passed at all. - Keyword-only parameter types will be the same as if :data:`~ext.commands.Greedy` was not passed at all.
:class:`~ext.commands.Greedy` parameters can also be made optional by specifying an optional value. :data:`~ext.commands.Greedy` parameters can also be made optional by specifying an optional value.
When mixed with the :class:`typing.Optional` converter you can provide simple and expressive command invocation syntaxes: When mixed with the :data:`typing.Optional` converter you can provide simple and expressive command invocation syntaxes:
.. command-block:: python3 .. code-block:: python3
import typing import typing
@ -524,10 +524,10 @@ This command can be invoked any of the following ways:
.. warning:: .. warning::
The usage of :class:`~ext.commands.Greedy` and :class:`typing.Optional` are powerful and useful, however as a The usage of :data:`~ext.commands.Greedy` and :data:`typing.Optional` are powerful and useful, however as a
price, they open you up to some parsing ambiguities that might surprise some people. price, they open you up to some parsing ambiguities that might surprise some people.
For example, a signature expecting a :class:`typing.Union` of a :class:`discord.Member` followed by a For example, a signature expecting a :data:`typing.Optional` of a :class:`discord.Member` followed by a
:class:`int` could catch a member named after a number due to the different ways a :class:`int` could catch a member named after a number due to the different ways a
:class:`~ext.commands.MemberConverter` decides to fetch members. You should take care to not introduce :class:`~ext.commands.MemberConverter` decides to fetch members. You should take care to not introduce
unintended parsing ambiguities in your code. One technique would be to clamp down the expected syntaxes unintended parsing ambiguities in your code. One technique would be to clamp down the expected syntaxes

Loading…
Cancel
Save