Skip to content

Commit cbcda16

Browse files
LulalabyDorukyumMiddledot
authored
Add missing docs (#877)
* Document attachment slash * Typo * Missing audit log docs for thread and s event * Fix stage privacy level. it can only be guild_only * remove public stage level * Add warning for usage of embedded activites * fix documentation of privacy_level * Base docs for application-cogs * Use slash command * Update docs/api.rst Co-authored-by: Middledot <[email protected]> * Update docs/api.rst Co-authored-by: Middledot <[email protected]> * Update docs/api.rst Co-authored-by: Middledot <[email protected]> Co-authored-by: Dorukyum <[email protected]> Co-authored-by: Middledot <[email protected]>
1 parent 8d17617 commit cbcda16

File tree

3 files changed

+159
-7
lines changed

3 files changed

+159
-7
lines changed

‎discord/enums.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -607,7 +607,7 @@ class ApplicationType(Enum):
607607

608608

609609
class StagePrivacyLevel(Enum):
610-
public = 1
610+
# public = 1 Deprecated
611611
closed = 2
612612
guild_only = 2
613613

‎docs/api.rst‎

Lines changed: 61 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1381,6 +1381,10 @@ of :class:`enum.Enum`.
13811381

13821382
A floating number.
13831383

1384+
.. attribute:: attachment
1385+
1386+
An attachment. Currently in beta.
1387+
13841388
.. class:: ChannelType
13851389

13861390
Specifies the type of channel.
@@ -2613,18 +2617,60 @@ of :class:`enum.Enum`.
26132617

26142618
A scheduled event was created.
26152619

2620+
When this is the action, the type of :attr:`~AuditLogEntry.target` is
2621+
the :class:`ScheduledEvent` or :class:`Object` with the ID of the thread which
2622+
was deleted.
2623+
2624+
Possible attributes for :class:`AuditLogDiff`:
2625+
2626+
- :attr:`~AuditLogDiff.name`
2627+
- :attr:`~AuditLogDiff.description`
2628+
- :attr:`~AuditLogDiff.channel`
2629+
- :attr:`~AuditLogDiff.privacy_level`
2630+
- :attr:`~AuditLogDiff.location`
2631+
- :attr:`~AuditLogDiff.status`
2632+
- :attr:`~AuditLogDiff.location_type`
2633+
26162634
.. versionadded:: 2.0
26172635

26182636
.. attribute:: scheduled_event_update
26192637

26202638
A scheduled event was updated.
26212639

2640+
When this is the action, the type of :attr:`~AuditLogEntry.target` is
2641+
the :class:`ScheduledEvent` or :class:`Object` with the ID of the thread which
2642+
was deleted.
2643+
2644+
Possible attributes for :class:`AuditLogDiff`:
2645+
2646+
- :attr:`~AuditLogDiff.name`
2647+
- :attr:`~AuditLogDiff.description`
2648+
- :attr:`~AuditLogDiff.channel`
2649+
- :attr:`~AuditLogDiff.privacy_level`
2650+
- :attr:`~AuditLogDiff.location`
2651+
- :attr:`~AuditLogDiff.status`
2652+
- :attr:`~AuditLogDiff.location_type`
2653+
26222654
.. versionadded:: 2.0
26232655

26242656
.. attribute:: scheduled_event_delete
26252657

26262658
A scheduled event was deleted.
26272659

2660+
When this is the action, the type of :attr:`~AuditLogEntry.target` is
2661+
the :class:`ScheduledEvent` or :class:`Object` with the ID of the thread which
2662+
was deleted.
2663+
2664+
Possible attributes for :class:`AuditLogDiff`:
2665+
2666+
- :attr:`~AuditLogDiff.name`
2667+
- :attr:`~AuditLogDiff.description`
2668+
- :attr:`~AuditLogDiff.channel`
2669+
- :attr:`~AuditLogDiff.privacy_level`
2670+
- :attr:`~AuditLogDiff.location`
2671+
- :attr:`~AuditLogDiff.status`
2672+
- :attr:`~AuditLogDiff.location_type`
2673+
26282674
.. versionadded:: 2.0
26292675

26302676
.. attribute:: thread_create
@@ -2641,6 +2687,7 @@ of :class:`enum.Enum`.
26412687
- :attr:`~AuditLogDiff.archived`
26422688
- :attr:`~AuditLogDiff.locked`
26432689
- :attr:`~AuditLogDiff.auto_archive_duration`
2690+
- :attr:`~AuditLogDiff.invitable`
26442691

26452692
.. versionadded:: 2.0
26462693

@@ -2658,6 +2705,7 @@ of :class:`enum.Enum`.
26582705
- :attr:`~AuditLogDiff.archived`
26592706
- :attr:`~AuditLogDiff.locked`
26602707
- :attr:`~AuditLogDiff.auto_archive_duration`
2708+
- :attr:`~AuditLogDiff.invitable`
26612709

26622710
.. versionadded:: 2.0
26632711

@@ -2675,6 +2723,7 @@ of :class:`enum.Enum`.
26752723
- :attr:`~AuditLogDiff.archived`
26762724
- :attr:`~AuditLogDiff.locked`
26772725
- :attr:`~AuditLogDiff.auto_archive_duration`
2726+
- :attr:`~AuditLogDiff.invitable`
26782727

26792728
.. versionadded:: 2.0
26802729

@@ -2845,13 +2894,11 @@ of :class:`enum.Enum`.
28452894
.. class:: StagePrivacyLevel
28462895

28472896
Represents a stage instance's privacy level.
2897+
Stage event privacy levels can only have 1 possible value at the moment so
2898+
this shouldn't really be used.
28482899

28492900
.. versionadded:: 2.0
28502901

2851-
.. attribute:: public
2852-
2853-
The stage instance can be joined by external users.
2854-
28552902
.. attribute:: closed
28562903

28572904
The stage instance can only be joined by members of the guild.
@@ -2907,6 +2954,14 @@ of :class:`enum.Enum`.
29072954

29082955
Represents an embedded activity application.
29092956

2957+
Some might be boost-only or gated.
2958+
2959+
.. warning::
2960+
2961+
Discord said that they won't verify bots who gives access to embedded activities.
2962+
2963+
Read more here: https://discord.com/channels/613425648685547541/697236247739105340/901153332075315321.
2964+
29102965
.. versionadded:: 2.0
29112966

29122967
.. attribute:: awkword
@@ -3496,9 +3551,9 @@ AuditLogDiff
34963551

34973552
.. attribute:: privacy_level
34983553

3499-
The privacy level of the stage instance.
3554+
The privacy level of the stage instance or scheduled event.
35003555

3501-
:type: :class:`StagePrivacyLevel`
3556+
:type: :class:`StagePrivacyLevel` or :class:`ScheduledEventPrivacyLevel`
35023557

35033558
.. attribute:: roles
35043559

‎docs/cogs.rst‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
:orphan:
2+
3+
.. currentmodule:: discord
4+
.. _cogs:
5+
6+
Cogs
7+
======
8+
9+
There comes a point in your bot's development when you want to organize a collection of commands, listeners, and some state into one class. Cogs allow you to do just that.
10+
11+
The gist:
12+
13+
- Each cog is a Python class that subclasses :class:`.Cog`.
14+
- Every command is marked with the :func:`.command` decorator or the corresponding shortcut command decorator.
15+
- Every listener is marked with the :meth:`.Cog.listener` decorator.
16+
- Cogs are then registered with the :meth:`.Bot.add_cog` call.
17+
- Cogs are subsequently removed with the :meth:`.Bot.remove_cog` call.
18+
19+
Quick Example
20+
---------------
21+
22+
This example cog defines a ``Greetings`` category for your commands, with a single slash command named ``hello`` as well as a listener to listen to an :ref:`Event <discord-api-events>`.
23+
24+
.. code-block:: python3
25+
26+
class Greetings(discord.Cog):
27+
def __init__(self, bot):
28+
self.bot = bot
29+
self._last_member = None
30+
31+
@discord.Cog.listener()
32+
async def on_member_join(self, member):
33+
channel = member.guild.system_channel
34+
if channel is not None:
35+
await channel.send(f'Welcome {member.mention}.')
36+
37+
@discord.slash_command()
38+
async def hello(self, ctx, *, member: discord.Member = None):
39+
"""Says hello"""
40+
member = member or ctx.author
41+
if self._last_member is None or self._last_member.id != member.id:
42+
await ctx.send(f'Hello {member.name}~')
43+
else:
44+
await ctx.send(f'Hello {member.name}... This feels familiar.')
45+
self._last_member = member
46+
47+
A couple of technical notes to take into consideration:
48+
49+
- All listeners must be explicitly marked via decorator, :meth:`~.Cog.listener`.
50+
- The name of the cog is automatically derived from the class name but can be overridden.
51+
- All commands must now take a ``self`` parameter to allow usage of instance attributes that can be used to maintain state.
52+
53+
Cog Registration
54+
-------------------
55+
56+
Once you have defined your cogs, you need to tell the bot to register the cogs to be used. We do this via the :meth:`~.Bot.add_cog` method.
57+
58+
.. code-block:: python3
59+
60+
bot.add_cog(Greetings(bot))
61+
62+
This binds the cog to the bot, adding all commands and listeners to the bot automatically.
63+
64+
Using Cogs
65+
-------------
66+
67+
Just as we remove a cog by its name, we can also retrieve it by its name as well. This allows us to use a cog as an inter-command communication protocol to share data. For example:
68+
69+
.. code-block:: python3
70+
:emphasize-lines: 22,24
71+
72+
class Economy(discord.Cog):
73+
...
74+
75+
async def withdraw_money(self, member, money):
76+
# implementation here
77+
...
78+
79+
async def deposit_money(self, member, money):
80+
# implementation here
81+
...
82+
83+
class Gambling(discord.Cog):
84+
def __init__(self, bot):
85+
self.bot = bot
86+
87+
def coinflip(self):
88+
return random.randint(0, 1)
89+
90+
@discord.slash_command()
91+
async def gamble(self, ctx, money: int):
92+
"""Gambles some money."""
93+
economy = self.bot.get_cog('Economy')
94+
if economy is not None:
95+
await economy.withdraw_money(ctx.author, money)
96+
if self.coinflip() == 1:
97+
await economy.deposit_money(ctx.author, money * 1.5)

0 commit comments

Comments
 (0)