Skip to content

Commit 62148b9

Browse files
i0bsi0bs
authored
New code docs.
1 parent 9fd6abd commit 62148b9

File tree

1 file changed

+209
-68
lines changed

1 file changed

+209
-68
lines changed

‎docs/gettingstarted.rst‎

Lines changed: 209 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,93 +1,234 @@
11
Getting Started
22
===============
33

4-
Now that things have been explained through the `quickstart`_ page for you
5-
to begin making slash commands for your bot, now it is time to discuss some
6-
of the much more rather advanced or complicated aspects of slash commands.
7-
Our first discussion will be covering over the implementation of options in
8-
your commands.
4+
Where do we start?
5+
******************
6+
7+
Before we begin getting started on everything else, it is recommended to
8+
check out the `quickstart`_ page first to get a basic grip on making
9+
slash commands for your bot.
10+
11+
Making a slash command.
12+
***********************
13+
14+
The basics.
15+
-----------
916

1017
First, let's explain by how commands are parsed through the Discord Bot API.
18+
1119
As you may know, Discord relies a lot on the interaction of HTTP Requests and
1220
JSON tables. As is with the case here, commands are the exact same way with
1321
having JSON tables to structure the design of it for Discord to understand. We
14-
can apply this information likewise with how options are to be designed in the
15-
Python code. Below attached is from the *Discord Developer Portal* on Slash
16-
Commands for showing how options are designed.
17-
18-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
19-
| **Field** | **Type** | **Description** |
20-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
21-
| type | int | value of ApplicationCommandOptionType |
22-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
23-
| name | string | 1-32 character name matching ``^[\w-]{1,32}$`` |
24-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
25-
| description | string | 1-100 character description |
26-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
27-
| default? | bool | the first required option for the user to complete--only one option can be default |
28-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
29-
| required? | bool | if the parameter is required or optional--default ``false`` |
30-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
31-
| choices? | array of `ApplicationCommandOptionChoice`_ | choices for ``string`` and ``int`` types for the user to pick from |
32-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
33-
| options? | array of `ApplicationCommandOption`_ | if the option is a subcommand or subcommand group type, this nested options will be the parameters |
34-
+-------------+--------------------------------------------+----------------------------------------------------------------------------------------------------+
35-
36-
This table shows us the way that Discord handles the structure of options for
22+
can apply this information likewise with how slash commands are to be designed
23+
in the Python code. Below attached is from the *Discord Developer Portal* on Slash
24+
Commands for showing how they are designed.
25+
26+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
27+
| **Field** | **Type** | **Description** |
28+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
29+
| name | string | 1-32 character name matching ``^[\w-]{1,32}$``. |
30+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
31+
| description | string | 1-100 character description. |
32+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
33+
| options? | array of `ApplicationCommandOption`_ | if the option is a subcommand or subcommand group type, this nested options will be the parameters. |
34+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
35+
36+
This table shows us the way that Discord handles the structure of commands for
3737
slash commands through their Bot API. For visualization purposes, we'll quickly
3838
make a JSON example (although we won't be using it) in order to explain how this
3939
works:
4040

4141
.. code-block:: python
4242
4343
{
44-
"name": "argone",
45-
"description": "description of first argument",
46-
"type": 3, # STRING type,
47-
"required": True
44+
"name": "test",
45+
"description": "This is just a test command, nothing more.",
46+
}
47+
48+
Now that we have a basic understanding of how the JSON table works, we can
49+
take this knowledge and convert it into a decorator method for the Python
50+
code as shown below:
51+
52+
.. code-block:: python
53+
54+
@slash.slash(name="test",
55+
description="This is just a test command, nothing more.")
56+
async def test(ctx):
57+
await ctx.respond()
58+
await ctx.send(content="Hello World!")
59+
60+
Now that we've gone over how Discord handles the declaration of slash commands
61+
through their Bot API, let's go over what some of the other things mean within
62+
the *logical* part of our code, the command function:
63+
64+
- ``ctx.respond()``: This is a way for us to handle responses. In short, the API
65+
requires some way to "acknowledge" an interaction response that we want to send off.
66+
67+
Giving some options for variety.
68+
--------------------------------
69+
70+
The next thing that we will begin to talk about is the implementation of options,
71+
otherwise well-known as "arguments" in discord.py commands.
72+
73+
The JSON structure of options are designed up to be similar to the same premise
74+
of how a slash command is declared. Below is the given table of how an option
75+
JSON would appear as:
76+
77+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
78+
| **Field** | **Type** | **Description** |
79+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
80+
| type | int | value of `ApplicationCommandOptionType`_. |
81+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
82+
| name | string | 1-32 character name matching ``^[\w-]{1,32}$``. |
83+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
84+
| description | string | 1-100 character description. |
85+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
86+
| default? | bool | the first required option for the user to complete--only one option can be default. |
87+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
88+
| required? | bool | if the parameter is required or optional--default ``false``. |
89+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
90+
| choices? | array of `ApplicationCommandOptionChoice`_ | choices for ``string`` and ``int`` types for the user to pick from. |
91+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
92+
| options? | array of `ApplicationCommandOption`_ | if the option is a subcommand or subcommand group type, this nested options will be the parameters. |
93+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
94+
95+
Now we have an idea of how options are declared. With this in mind, let's quickly make a JSON
96+
example in order to visualize this concept even further:
97+
98+
.. code-block:: python
99+
100+
{
101+
"name": "test",
102+
"description": "This is just a test command, nothing more.",
103+
"options": [
104+
{
105+
"name": "OptOne",
106+
"description": "This is the first option we have.",
107+
"type": 3,
108+
"required": "false"
109+
}
110+
]
48111
}
112+
113+
While the table in the basics mentions an array in particular called ``ApplicationCommandOptionType``,
114+
there isn't that much of an explanation on how this works. Let's put this into better laymen
115+
terms on what this means with a table below showing all of these values:
116+
117+
+-------------------+-----------+
118+
| **Name** | **Value** |
119+
+-------------------+-----------+
120+
| SUB_COMMAND | 1 |
121+
+-------------------+-----------+
122+
| SUB_COMMAND_GROUP | 2 |
123+
+-------------------+-----------+
124+
| STRING | 3 |
125+
+-------------------+-----------+
126+
| INTEGER | 4 |
127+
+-------------------+-----------+
128+
| BOOLEAN | 5 |
129+
+-------------------+-----------+
130+
| USER | 6 |
131+
+-------------------+-----------+
132+
| CHANNEL | 7 |
133+
+-------------------+-----------+
134+
| ROLE | 8 |
135+
+-------------------+-----------+
136+
137+
The purpose of having the ``ApplicationCommandOptionType`` value passed into our option JSON structure
138+
is so that we can help the Discord UI understand what kind of value we're inputting here. For instance,
139+
if we're wanting to put in a string response, we'll pass the ID 3 so that the UI of Discord chat bar
140+
knows to format it visually this way. If we're looking for a user, then we'll pass ID 6 so that it presents
141+
us with a list of users in our server instead, making it easier on our lives.
142+
143+
This is not to be confused, however, with formatting the response type itself. This is merely a method so
144+
that the API wrapper can help us with passing the correct type or instance variable with the arguments of the
145+
command function's code.
146+
147+
Now, we can finally visualize this by coding an example of this being used in the Python code shown below.
148+
149+
.. code-block:: python
150+
151+
from discord_slash.manage_commands import create_option
49152
50-
With this very basic understanding in mind, now we are able to begin programming
51-
a simple Python script that will allow us to utilize this ability through one of
52-
the many subclasses offered in *discord-py-slash-command*.
153+
@slash.slash(name="test",
154+
description="This is just a test command, nothing more.",
155+
options=[
156+
create_option(
157+
name="OptOne",
158+
description="This is the first option we have.",
159+
option_type=3,
160+
required=False
161+
)
162+
])
163+
async def test(ctx, OptOne: str):
164+
pass
165+
166+
Additionally, we could also declare the type of our command's option through this method shown here:
167+
168+
.. code-block:: python
169+
170+
from discord_slash.model import SubCommandOptionType
171+
172+
(...)
173+
174+
option_type=SubCommandOptionType.STRING
175+
176+
More in the option? Give them a choice.
177+
---------------------------------------
178+
179+
Alas, there is also a way to give even more information to options with Discord's Slash Commands:
180+
a choice. Not like something that you're given at birth of when you become of legal age as an adult,
181+
we're not here to give you *that* kind of life advice, but the choice of what value you want your
182+
option to rather pass. Below is a table that shows the JSON structure of how choices are represented
183+
for an option:
184+
185+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
186+
| **Field** | **Type** | **Description** |
187+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
188+
| name | string | 1-32 character choice name. |
189+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
190+
| value | string or int | value of the choice, up to 100 characters if string. |
191+
+-------------+--------------------------------------------+-----------------------------------------------------------------------------------------------------+
192+
193+
This time, only 2 fields are able to be passed for this. Below is a JSON example of how this would
194+
be designed:
195+
196+
.. code-block:: python
197+
198+
{
199+
"name": "ChoiceOne",
200+
"value": "Hello command, this is my value!"
201+
}
202+
203+
To make it really simple, the ``name`` field is only to be used for how you want the choice to be presented
204+
through Discord's UI. It's the "appearance" of how you want your choice shown, not the actual returned value
205+
of it. Hence, this is why ``value`` is the second field passed for that, which can be either in the form of
206+
a string or integer. Below is an implementation of this design in the Python code:
53207

54208
.. code-block:: python
55209
56-
import discord
57-
from discord_slash import SlashCommand
58-
from discord_slash.utils import manage_commands # Allows us to manage the command settings.
59-
60-
client = discord.Client(intents=discord.Intents.all())
61-
slash = SlashCommand(client, sync_commands=True)
62-
63-
guild_ids = [789032594456576001]
64-
65-
@client.event
66-
async def on_ready():
67-
print("Ready!")
68-
69-
@slash.slash(
70-
name="test",
71-
description="this returns the bot latency",
72-
options=[manage_commands.create_option(
73-
name = "argone",
74-
description = "description of first argument",
75-
option_type = 3,
76-
required = True
77-
)],
78-
guild_ids=guild_ids
79-
)
80-
async def _test(ctx, argone: str):
81-
await ctx.respond()
82-
await ctx.send(f"You responded with {argone}.")
83-
84-
client.run("your_bot_token_here")
210+
from discord_slash.manage_commands import create_option, create_choice
85211
86-
The main changes that you need to know about are with the lines calling the import
87-
of ``manage_commands``, as well as the ``options = [] ...`` code within the ``@slash.slash()``
88-
context coroutine. This will now create a new option called "argone" when shown for
89-
the slash command.
212+
@slash.slash(name="test",
213+
description="This is just a test command, nothing more.",
214+
options=[
215+
create_option(
216+
name="OptOne",
217+
description="This is the first option we have.",
218+
option_type=3,
219+
required=False,
220+
choices=[
221+
create_choice(
222+
name="ChoiceOne",
223+
value="Hello command, this is my value!"
224+
)
225+
]
226+
)
227+
])
228+
async def test(ctx, OptOne: str):
229+
pass
90230
91231
.. _quickstart: https://discord-py-slash-command.readthedocs.io/en/latest/quickstart.html
232+
.. _ApplicationCommandOptionType: https://discord.com/developers/docs/interactions/slash-commands#applicationcommandoptiontype
92233
.. _ApplicationCommandOptionChoice: https://discord.com/developers/docs/interactions/slash-commands#applicationcommandoptionchoice
93234
.. _ApplicationCommandOption: https://discord.com/developers/docs/interactions/slash-commands#applicationcommandoption

0 commit comments

Comments
 (0)