Skip to content

Commit 5f6891b

Browse files
committed
Added docs
1 parent 1acf36f commit 5f6891b

File tree

2 files changed

+140
-2
lines changed

2 files changed

+140
-2
lines changed

discord_slash/cog_ext.py

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,47 @@ def cog_slash(*,
88
auto_convert: dict = None,
99
guild_ids: typing.List[int] = None,
1010
options: typing.List[dict] = None):
11+
"""
12+
Decorator for Cog to add slash command.\n
13+
Almost same as :func:`.client.SlashCommand.slash`.
14+
15+
Example:
16+
.. code-block:: python
17+
18+
class ExampleCog(commands.Cog):
19+
def __init__(self, bot):
20+
if not hasattr(bot, "slash"):
21+
# Creates new SlashCommand instance to bot if bot doesn't have.
22+
bot.slash = SlashCommand(bot, override_type=True)
23+
self.bot = bot
24+
self.bot.slash.get_cog_commands(self)
25+
26+
def cog_unload(self):
27+
self.bot.slash.remove_cog_commands(self)
28+
29+
@cog_ext.cog_slash(name="ping")
30+
async def ping(self, ctx: SlashContext):
31+
await ctx.send(content="Pong!")
32+
33+
:param name: Name of the slash command. Default name of the coroutine.
34+
:type name: str
35+
:param description: Description of the slash command. Default ``None``.
36+
:type description: str
37+
:param auto_convert: Dictionary of how to convert option values. Default ``None``.
38+
:type auto_convert: dict
39+
:param guild_ids: List of Guild ID of where the command will be used. Default ``None``, which will be global command.
40+
:type guild_ids: List[int]
41+
:param options: Options of the slash command. This will affect ``auto_convert`` and command data at Discord API. Default ``None``.
42+
:type options: List[dict]
43+
"""
44+
if options:
45+
# Overrides original auto_convert.
46+
auto_convert = {}
47+
for x in options:
48+
if x["type"] < 3:
49+
raise Exception("Please use `cog_subcommand()` decorator for cog subcommands!")
50+
auto_convert[x["name"]] = x["type"]
51+
1152
def wrapper(cmd):
1253
_cmd = {
1354
"func": cmd,
@@ -28,6 +69,41 @@ def cog_subcommand(*,
2869
description: str = None,
2970
auto_convert: dict = None,
3071
guild_ids: typing.List[int] = None):
72+
"""
73+
Decorator for Cog to add subcommand.\n
74+
Almost same as :func:`.client.SlashCommand.subcommand`.
75+
76+
Example:
77+
.. code-block:: python
78+
79+
class ExampleCog(commands.Cog):
80+
def __init__(self, bot):
81+
if not hasattr(bot, "slash"):
82+
# Creates new SlashCommand instance to bot if bot doesn't have.
83+
bot.slash = SlashCommand(bot, override_type=True)
84+
self.bot = bot
85+
self.bot.slash.get_cog_commands(self)
86+
87+
def cog_unload(self):
88+
self.bot.slash.remove_cog_commands(self)
89+
90+
@cog_ext.cog_subcommand(base="group", name="say")
91+
async def group_say(self, ctx: SlashContext, text: str):
92+
await ctx.send(content=text)
93+
94+
:param base: Name of the base command.
95+
:type base: str
96+
:param subcommand_group: Name of the subcommand group, if any. Default ``None`` which represents there is no sub group.
97+
:type subcommand_group: str
98+
:param name: Name of the subcommand. Default name of the coroutine.
99+
:type name: str
100+
:param description: Description of the subcommand. Default ``None``.
101+
:type description: str
102+
:param auto_convert: Dictionary of how to convert option values. Default ``None``.
103+
:type auto_convert: dict
104+
:param guild_ids: List of guild ID of where the command will be used. Default ``None``, which will be global command.
105+
:type guild_ids: List[int]
106+
"""
31107
def wrapper(cmd):
32108
_sub = {
33109
"func": cmd,

discord_slash/model.py

Lines changed: 64 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -171,21 +171,53 @@ async def delete(self, message_id: typing.Union[int, str] = "@original"):
171171

172172

173173
class CommandObject:
174-
def __init__(self, name, cmd, *subcommands): # Let's reuse old command formatting.
174+
"""
175+
Slash command object of this extension.
176+
177+
.. warning::
178+
Do not manually init this model.
179+
180+
:ivar name: Name of the command.
181+
:ivar func: The coroutine of the command.
182+
:ivar description: Description of the command.
183+
:ivar auto_convert: Dictionary of the `auto_convert` of the command.
184+
:ivar allowed_guild_ids: List of the allowed guild id.
185+
:ivar options: List of the option of the command. Used for `auto_register`.
186+
"""
187+
def __init__(self, name, cmd): # Let's reuse old command formatting.
175188
self.name = name
176189
self.func = cmd["func"]
177190
self.description = cmd["description"]
178191
self.auto_convert = cmd["auto_convert"]
179192
self.allowed_guild_ids = cmd["guild_ids"]
180193
self.options = cmd["api_options"]
181194
self.has_subcommands = cmd["has_subcommands"]
182-
self.subcommands = subcommands
183195

184196
def invoke(self, *args):
197+
"""
198+
Invokes the command.
199+
200+
:param args: Args for the command.
201+
:return: Coroutine
202+
"""
185203
return self.func(*args)
186204

187205

188206
class SubcommandObject:
207+
"""
208+
Subcommand object of this extension.
209+
210+
.. warning::
211+
Do not manually init this model.
212+
213+
:ivar base: Name of the base slash command.
214+
:ivar subcommand_group: Name of the subcommand group. ``None`` if not exist.
215+
:ivar name: Name of the subcommand.
216+
:ivar func: The coroutine of the command.
217+
:ivar description: Description of the command.
218+
:ivar auto_convert: Dictionary of the `auto_convert` of the command.
219+
:ivar allowed_guild_ids: List of the allowed guild id.
220+
"""
189221
def __init__(self, sub, base, name, sub_group=None):
190222
self.base = base
191223
self.subcommand_group = sub_group
@@ -196,22 +228,52 @@ def __init__(self, sub, base, name, sub_group=None):
196228
self.allowed_guild_ids = sub["guild_ids"]
197229

198230
def invoke(self, *args):
231+
"""
232+
Invokes the command.
233+
234+
:param args: Args for the command.
235+
:return: Coroutine
236+
"""
199237
return self.func(*args)
200238

201239

202240
class CogCommandObject(CommandObject):
241+
"""
242+
Slash command object but for Cog.
243+
244+
.. warning::
245+
Do not manually init this model.
246+
"""
203247
def __init__(self, *args):
204248
super().__init__(*args)
205249
self.cog = None # Manually set this later.
206250

207251
def invoke(self, *args):
252+
"""
253+
Invokes the command.
254+
255+
:param args: Args for the command.
256+
:return: Coroutine
257+
"""
208258
return self.func(self.cog, *args)
209259

210260

211261
class CogSubcommandObject(SubcommandObject):
262+
"""
263+
Subcommand object but for Cog.
264+
265+
.. warning::
266+
Do not manually init this model.
267+
"""
212268
def __init__(self, *args):
213269
super().__init__(*args)
214270
self.cog = None # Manually set this later.
215271

216272
def invoke(self, *args):
273+
"""
274+
Invokes the command.
275+
276+
:param args: Args for the command.
277+
:return: Coroutine
278+
"""
217279
return self.func(self.cog, *args)

0 commit comments

Comments
 (0)