mirrors/discord.py
1
0
Fork 0
mirror of https://github.com/Rapptz/discord.py.git synced 2025-07-04 01:00:00 +00:00
Code Issues Projects Releases Wiki Activity

[commands] Some minor clean up of the flag converter documentation

Browse Source 
Fix #6761
This commit is contained in:
Rapptz 2021-04-19 22:50:34 -04:00
parent 7bfb0f8133
commit 212d308835
1 changed files with 15 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docs/ext/commands/commands.rst
View File

@ -625,14 +625,15 @@ Allows the user to invoke the command using a simple flag-like syntax:
.. image:: /images/commands/flags1.png .. image:: /images/commands/flags1.png
Flags use a syntax that allows the user to not require quotes when passing flags. The goal of the flag syntax is to be as Flags use a syntax that allows the user to not require quotes when passing in values to the flag. The goal of the
user-friendly as possible. This makes flags a good choice for complicated commands that can have multiple knobs. flag syntax is to be as user-friendly as possible. This makes flags a good choice for complicated commands that can have
**It is recommended to use keyword-only parameters with the flag converter**. This ensures proper parsing and multiple knobs to turn or simulating keyword-only parameters in your external command interface. **It is recommended to use
behaviour with quoting. keyword-only parameters with the flag converter**. This ensures proper parsing and behaviour with quoting.
The :class:`~ext.commands.FlagConverter` class examines the class to find flags. A flag can either be a Internally, the :class:`~ext.commands.FlagConverter` class examines the class to find flags. A flag can either be a
class variable with a type annotation or a class variable that's been assigned the result of the :func:`~ext.commands.flag` class variable with a type annotation or a class variable that's been assigned the result of the :func:`~ext.commands.flag`
function. function. These flags are then used to define the interface that your users will use. The annotations correspond to
the converters that the flag arguments must adhere to.
For most use cases, no extra work is required to define flags. However, if customisation is needed to control the flag name For most use cases, no extra work is required to define flags. However, if customisation is needed to control the flag name
or the default value then the :func:`~ext.commands.flag` function can come in handy: or the default value then the :func:`~ext.commands.flag` function can come in handy:
@ -652,8 +653,8 @@ In order to customise the flag syntax we also have a few options that can be pas
.. code-block:: python3 .. code-block:: python3
# --hello=world syntax # --hello world syntax
class PosixLikeFlags(commands.FlagConverter, delimiter='=', prefix='--'): class PosixLikeFlags(commands.FlagConverter, delimiter=' ', prefix='--'):
hello: str hello: str
@ -667,6 +668,12 @@ In order to customise the flag syntax we also have a few options that can be pas
nsfw: Optional[bool] nsfw: Optional[bool]
slowmode: Optional[int] slowmode: Optional[int]
.. note::
Despite the similarities in these examples to command like arguments, the syntax and parser is not
a command line parser. The syntax is mainly inspired by Discord's search bar input and as a result
all flags need a corresponding value.
The flag converter is similar to regular commands and allows you to use most types of converters The flag converter is similar to regular commands and allows you to use most types of converters
(with the exception of :class:`~ext.commands.Greedy`) as the type annotation. Some extra support is added for specific (with the exception of :class:`~ext.commands.Greedy`) as the type annotation. Some extra support is added for specific
annotations as described below. annotations as described below.