mirror
/
Rapptz.discord.py
mirror of https://github.com/Rapptz/discord.py
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Fix permissions-based docstrings to be more consistent

pull/10109/head
Steve C 3 years ago
committed by dolfies
parent
94fbdcb270
commit
14875c45e3
20 changed files with 160 additions and 164 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 15
      discord/abc.py
  2. 2
      discord/automod.py
  3. 45
      discord/channel.py
  4. 2
      discord/client.py
  5. 8
      discord/emoji.py
  6. 105
      discord/guild.py
  7. 4
      discord/http.py
  8. 15
      discord/integrations.py
  9. 2
      discord/invite.py
  10. 10
      discord/member.py
  11. 25
      discord/message.py
  12. 4
      discord/reaction.py
  13. 14
      discord/role.py
  14. 4
      discord/scheduled_event.py
  15. 6
      discord/stage_instance.py
  16. 5
      discord/sticker.py
  17. 9
      discord/template.py
  18. 15
      discord/threads.py
  19. 30
      discord/welcome_screen.py
  20. 4
      docs/api.rst

15
discord/abc.py
View File

@ -906,7 +906,7 @@ class GuildChannel:
Deletes the channel.
You must have :attr:`~discord.Permissions.manage_channels` permission to use this.
You must have :attr:`~discord.Permissions.manage_channels` to do this.
Parameters
-----------
@ -970,7 +970,7 @@ class GuildChannel:
If the ``overwrite`` parameter is ``None``, then the permission
overwrites are deleted.
You must have the :attr:`~discord.Permissions.manage_roles` permission to use this.
You must have :attr:`~discord.Permissions.manage_roles` to do this.
.. note::
@ -1086,8 +1086,7 @@ class GuildChannel:
Clones this channel. This creates a channel with the same properties
as this channel.
You must have the :attr:`~discord.Permissions.manage_channels` permission to
do this.
You must have :attr:`~discord.Permissions.manage_channels` to do this.
.. versionadded:: 1.1
@ -1168,8 +1167,7 @@ class GuildChannel:
If exact position movement is required, ``edit`` should be used instead.
You must have the :attr:`~discord.Permissions.manage_channels` permission to
do this.
You must have :attr:`~discord.Permissions.manage_channels` to do this.
.. note::
@ -1307,8 +1305,7 @@ class GuildChannel:
Creates an instant invite from a text or voice channel.
You must have the :attr:`~discord.Permissions.create_instant_invite` permission to
do this.
You must have :attr:`~discord.Permissions.create_instant_invite` to do this.
Parameters
------------
@ -1757,7 +1754,7 @@ class Messageable:
) -> AsyncIterator[Message]:
"""Returns an :term:`asynchronous iterator` that enables receiving the destination's message history.
You must have :attr:`~discord.Permissions.read_message_history` permissions to use this.
You must have :attr:`~discord.Permissions.read_message_history` to do this.
Examples
---------

2
discord/automod.py
View File

@ -521,7 +521,7 @@ class AutoModAction:
Fetch the rule whose action was taken.
You must have the :attr:`Permissions.manage_guild` permission to use this.
You must have :attr:`Permissions.manage_guild` to do this.
Raises
-------

45
discord/channel.py
View File

@ -305,8 +305,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
Edits the channel.
You must have the :attr:`~Permissions.manage_channels` permission to
use this.
You must have :attr:`~Permissions.manage_channels` to do this.
.. versionchanged:: 1.3
The ``overwrites`` keyword-only parameter was added.
@ -390,8 +389,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
Deletes a list of messages. This is similar to :meth:`Message.delete`
except it bulk deletes multiple messages.
You must have the :attr:`~Permissions.manage_messages` permission to
use this (unless they're your own).
You must have :attr:`~Permissions.manage_messages` to use this (unless they're your own).
.. note::
Users do not have access to the message bulk-delete endpoint.
@ -443,7 +441,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
``check``. If a ``check`` is not provided then all messages are deleted
without discrimination.
The :attr:`~Permissions.read_message_history` permission is needed to
Having :attr:`~Permissions.read_message_history` is needed to
retrieve message history.
.. versionchanged:: 2.0
@ -508,7 +506,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
Gets the list of webhooks from this channel.
Requires :attr:`~.Permissions.manage_webhooks` permissions.
You must have :attr:`~.Permissions.manage_webhooks` to do this.
Raises
-------
@ -531,7 +529,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
Creates a webhook for this channel.
Requires :attr:`~.Permissions.manage_webhooks` permissions.
You must have :attr:`~.Permissions.manage_webhooks` to do this.
.. versionchanged:: 1.1
Added the ``reason`` keyword-only parameter.
@ -764,7 +762,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
"""Returns an :term:`asynchronous iterator` that iterates over all archived threads in this text channel,
in order of decreasing ID for joined threads, and decreasing :attr:`Thread.archive_timestamp` otherwise.
You must have :attr:`~Permissions.read_message_history` to use this. If iterating over private threads
You must have :attr:`~Permissions.read_message_history` to do this. If iterating over private threads
then :attr:`~Permissions.manage_threads` is also required.
.. versionadded:: 2.0
@ -1093,8 +1091,7 @@ class VoiceChannel(discord.abc.Messageable, VocalGuildChannel):
Deletes a list of messages. This is similar to :meth:`Message.delete`
except it bulk deletes multiple messages.
You must have the :attr:`~Permissions.manage_messages` permission to
use this (unless they're your own).
You must have :attr:`~Permissions.manage_messages` to use this (unless they're your own).
.. note::
Users do not have access to the message bulk-delete endpoint.
@ -1142,7 +1139,7 @@ class VoiceChannel(discord.abc.Messageable, VocalGuildChannel):
``check``. If a ``check`` is not provided then all messages are deleted
without discrimination.
The :attr:`~Permissions.read_message_history` permission is needed to
Having :attr:`~Permissions.read_message_history` is needed to
retrieve message history.
.. versionadded:: 2.0
@ -1205,7 +1202,7 @@ class VoiceChannel(discord.abc.Messageable, VocalGuildChannel):
Gets the list of webhooks from this channel.
Requires :attr:`~.Permissions.manage_webhooks` permissions.
You must have :attr:`~.Permissions.manage_webhooks` to do this.
.. versionadded:: 2.0
@ -1230,7 +1227,7 @@ class VoiceChannel(discord.abc.Messageable, VocalGuildChannel):
Creates a webhook for this channel.
Requires :attr:`~.Permissions.manage_webhooks` permissions.
You must have :attr:`~.Permissions.manage_webhooks` to do this.
.. versionadded:: 2.0
@ -1300,8 +1297,7 @@ class VoiceChannel(discord.abc.Messageable, VocalGuildChannel):
Edits the channel.
You must have the :attr:`~Permissions.manage_channels` permission to
use this.
You must have :attr:`~Permissions.manage_channels` to do this.
.. versionchanged:: 1.3
The ``overwrites`` keyword-only parameter was added.
@ -1505,8 +1501,7 @@ class StageChannel(VocalGuildChannel):
Create a stage instance.
You must have the :attr:`~Permissions.manage_channels` permission to
use this.
You must have :attr:`~Permissions.manage_channels` to do this.
.. versionadded:: 2.0
@ -1596,8 +1591,7 @@ class StageChannel(VocalGuildChannel):
Edits the channel.
You must have the :attr:`~Permissions.manage_channels` permission to
use this.
You must have :attr:`~Permissions.manage_channels` to do this.
.. versionchanged:: 2.0
The ``topic`` parameter must now be set via :attr:`create_instance`.
@ -1763,8 +1757,7 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
Edits the channel.
You must have the :attr:`~Permissions.manage_channels` permission to
use this.
You must have :attr:`~Permissions.manage_channels` to do this.
.. versionchanged:: 1.3
The ``overwrites`` keyword-only parameter was added.
@ -2219,8 +2212,7 @@ class ForumChannel(discord.abc.GuildChannel, Hashable):
Edits the forum.
You must have the :attr:`~Permissions.manage_channels` permission to
use this.
You must have :attr:`~Permissions.manage_channels` to do this.
Parameters
----------
@ -2333,8 +2325,7 @@ class ForumChannel(discord.abc.GuildChannel, Hashable):
Creates a new tag in this forum.
You must have the :attr:`~Permissions.manage_channels` permission to
use this.
You must have :attr:`~Permissions.manage_channels` to do this.
Parameters
----------
@ -2509,7 +2500,7 @@ class ForumChannel(discord.abc.GuildChannel, Hashable):
Gets the list of webhooks from this channel.
Requires :attr:`~.Permissions.manage_webhooks` permissions.
You must have :attr:`~.Permissions.manage_webhooks` to do this.
Raises
-------
@ -2532,7 +2523,7 @@ class ForumChannel(discord.abc.GuildChannel, Hashable):
Creates a webhook for this channel.
Requires :attr:`~.Permissions.manage_webhooks` permissions.
You must have :attr:`~.Permissions.manage_webhooks` to do this.
Parameters
-------------

2
discord/client.py
View File

@ -2048,7 +2048,7 @@ class Client:
Revokes an :class:`.Invite`, URL, or ID to an invite.
You must have the :attr:`~.Permissions.manage_channels` permission in
You must have :attr:`~.Permissions.manage_channels` in
the associated guild to do this.
.. versionchanged:: 2.0

8
discord/emoji.py
View File

@ -92,7 +92,7 @@ class Emoji(_EmojiTag, AssetMixin):
Whether the emoji is available for use.
user: Optional[:class:`User`]
The user that created the emoji. This can only be retrieved using :meth:`Guild.fetch_emoji` and
having the :attr:`~Permissions.manage_emojis` permission.
having :attr:`~Permissions.manage_emojis`.
"""
__slots__: Tuple[str, ...] = (
@ -196,8 +196,7 @@ class Emoji(_EmojiTag, AssetMixin):
Deletes the custom emoji.
You must have :attr:`~Permissions.manage_emojis` permission to
do this.
You must have :attr:`~Permissions.manage_emojis` to do this.
Parameters
-----------
@ -221,8 +220,7 @@ class Emoji(_EmojiTag, AssetMixin):
Edits the custom emoji.
You must have :attr:`~Permissions.manage_emojis` permission to
do this.
You must have :attr:`~Permissions.manage_emojis` to do this.
.. versionchanged:: 2.0
The newly updated emoji is returned.

105
discord/guild.py
View File

@ -1270,8 +1270,7 @@ class Guild(Hashable):
Creates a :class:`TextChannel` for the guild.
Note that you need the :attr:`~Permissions.manage_channels` permission
to create the channel.
Note that you must have :attr:`~Permissions.manage_channels` to create the channel.
The ``overwrites`` parameter can be used to create a 'secret'
channel upon creation. This parameter expects a :class:`dict` of
@ -1767,7 +1766,7 @@ class Guild(Hashable):
Edits the guild.
You must have the :attr:`~Permissions.manage_guild` permission to edit the guild.
You must have :attr:`~Permissions.manage_guild` to edit the guild.
.. versionchanged:: 1.4
The ``rules_channel`` and ``public_updates_channel`` keyword parameters were added.
@ -2139,8 +2138,7 @@ class Guild(Hashable):
Retrieves the :class:`BanEntry` for a user.
You must have the :attr:`~Permissions.ban_members` permission
to get this information.
You must have :attr:`~Permissions.ban_members` to get this information.
Parameters
-----------
@ -2219,8 +2217,7 @@ class Guild(Hashable):
) -> AsyncIterator[BanEntry]:
"""Retrieves an :term:`asynchronous iterator` of the users that are banned from the guild as a :class:`BanEntry`.
You must have the :attr:`~Permissions.ban_members` permission
to get this information.
You must have :attr:`~Permissions.ban_members` to get this information.
.. versionchanged:: 2.0
Due to a breaking change in Discord's API, this now returns a paginated iterator instead of a list.
@ -2345,8 +2342,7 @@ class Guild(Hashable):
The inactive members are denoted if they have not logged on in
``days`` number of days and they have no roles.
You must have the :attr:`~Permissions.kick_members` permission
to use this.
You must have :attr:`~Permissions.kick_members` to do this.
To check how many members you would prune without actually pruning,
see the :meth:`estimate_pruned_members` function.
@ -2408,7 +2404,7 @@ class Guild(Hashable):
Gets the list of templates from this guild.
Requires :attr:`~.Permissions.manage_guild` permissions.
You must have :attr:`~.Permissions.manage_guild` to do this.
.. versionadded:: 1.7
@ -2432,7 +2428,7 @@ class Guild(Hashable):
Gets the list of webhooks from this guild.
Requires :attr:`~.Permissions.manage_webhooks` permissions.
You must have :attr:`~.Permissions.manage_webhooks` to do this.
Raises
-------
@ -2503,8 +2499,7 @@ class Guild(Hashable):
Returns a list of all active instant invites from the guild.
You must have the :attr:`~Permissions.manage_guild` permission to get
this information.
You must have :attr:`~Permissions.manage_guild` to get this information.
Raises
-------
@ -2531,8 +2526,7 @@ class Guild(Hashable):
Creates a template for the guild.
You must have the :attr:`~Permissions.manage_guild` permission to
do this.
You must have :attr:`~Permissions.manage_guild` to do this.
.. versionadded:: 1.7
@ -2559,8 +2553,7 @@ class Guild(Hashable):
Attaches an integration to the guild. This "enables" an existing integration.
You must have the :attr:`~Permissions.manage_guild` permission to
do this.
You must have :attr:`~Permissions.manage_guild` to do this.
.. versionadded:: 1.4
@ -2589,8 +2582,7 @@ class Guild(Hashable):
Returns a list of all integrations attached to the guild.
You must have the :attr:`~Permissions.manage_guild` permission to
do this.
You must have :attr:`~Permissions.manage_guild` to do this.
.. versionadded:: 1.4
@ -2690,8 +2682,7 @@ class Guild(Hashable):
Creates a :class:`Sticker` for the guild.
You must have :attr:`~Permissions.manage_emojis_and_stickers` permission to
do this.
You must have :attr:`~Permissions.manage_emojis_and_stickers` to do this.
.. versionadded:: 2.0
@ -2742,8 +2733,7 @@ class Guild(Hashable):
Deletes the custom :class:`Sticker` from the guild.
You must have :attr:`~Permissions.manage_emojis_and_stickers` permission to
do this.
You must have :attr:`~Permissions.manage_emojis_and_stickers` to do this.
.. versionadded:: 2.0
@ -2837,7 +2827,7 @@ class Guild(Hashable):
Creates a scheduled event for the guild.
Requires :attr:`~Permissions.manage_events` permissions.
You must have :attr:`~Permissions.manage_events` to do this.
.. versionadded:: 2.0
@ -3042,8 +3032,7 @@ class Guild(Hashable):
There is currently a limit of 50 static and animated emojis respectively per guild,
unless the guild has the ``MORE_EMOJI`` feature which extends the limit to 200.
You must have the :attr:`~Permissions.manage_emojis` permission to
do this.
You must have :attr:`~Permissions.manage_emojis` to do this.
Parameters
-----------
@ -3083,8 +3072,7 @@ class Guild(Hashable):
Deletes the custom :class:`Emoji` from the guild.
You must have :attr:`~Permissions.manage_emojis` permission to
do this.
You must have :attr:`~Permissions.manage_emojis` to do this.
.. versionchanged:: 2.0
@ -3180,8 +3168,7 @@ class Guild(Hashable):
All fields are optional.
You must have the :attr:`~Permissions.manage_roles` permission to
do this.
You must have :attr:`~Permissions.manage_roles` to do this.
.. versionchanged:: 1.6
Can now pass ``int`` to ``colour`` keyword-only parameter.
@ -3289,8 +3276,7 @@ class Guild(Hashable):
Bulk edits a list of :class:`Role` in the guild.
You must have the :attr:`~Permissions.manage_roles` permission to
do this.
You must have :attr:`~Permissions.manage_roles` to do this.
.. versionadded:: 1.4
@ -3359,8 +3345,7 @@ class Guild(Hashable):
The user must meet the :class:`abc.Snowflake` abc.
You must have the :attr:`~Permissions.kick_members` permission to
do this.
You must have :attr:`~Permissions.kick_members` to do this.
Parameters
-----------
@ -3392,8 +3377,7 @@ class Guild(Hashable):
The user must meet the :class:`abc.Snowflake` abc.
You must have the :attr:`~Permissions.ban_members` permission to
do this.
You must have :attr:`~Permissions.ban_members` to do this.
Parameters
-----------
@ -3443,8 +3427,7 @@ class Guild(Hashable):
The user must meet the :class:`abc.Snowflake` abc.
You must have the :attr:`~Permissions.ban_members` permission to
do this.
You must have :attr:`~Permissions.ban_members` to do this.
Parameters
-----------
@ -3481,8 +3464,7 @@ class Guild(Hashable):
The guild must have ``VANITY_URL`` in :attr:`~Guild.features`.
You must have the :attr:`~Permissions.manage_guild` permission to use
this as well.
You must have :attr:`~Permissions.manage_guild` to do this.as well.
Raises
-------
@ -3525,7 +3507,7 @@ class Guild(Hashable):
) -> AsyncIterator[AuditLogEntry]:
"""Returns an :term:`asynchronous iterator` that enables receiving the guild's audit logs.
You must have the :attr:`~Permissions.view_audit_log` permission to use this.
You must have :attr:`~Permissions.view_audit_log` to do this.
Examples
----------
@ -3724,8 +3706,7 @@ class Guild(Hashable):
Edits the widget of the guild.
You must have the :attr:`~Permissions.manage_guild` permission to
use this
You must have :attr:`~Permissions.manage_guild` to do this.
.. versionadded:: 2.0
@ -3758,8 +3739,7 @@ class Guild(Hashable):
Returns the guild's welcome screen.
You must have the :attr:`~Permissions.manage_guild` permission to
use this.
You must have :attr:`~Permissions.manage_guild` permission to use this.
.. note::
@ -3772,7 +3752,7 @@ class Guild(Hashable):
NotFound
The guild does not have a welcome screen.
Forbidden
You do not have the :attr:`~Permissions.manage_guild` permission.
You do not have :attr:`~Permissions.manage_guild`.
HTTPException
Retrieving the welcome screen failed.
@ -3790,14 +3770,35 @@ class Guild(Hashable):
description: str = MISSING,
welcome_channels: Sequence[WelcomeChannel] = MISSING,
enabled: bool = MISSING,
reason: Optional[str] = None,
):
"""|coro|
Edit the welcome screen.
You must have the :attr:`~Permissions.manage_guild` permission to do this.
Welcome channels can only accept custom emojis if :attr:`Guild.premium_tier` is level 2 or above.
You must have :attr:`~Permissions.manage_guild` in the guild to do this.
All parameters are optional.
.. versionadded:: 2.0
Usage: ::
rules_channel = guild.get_channel(12345678)
announcements_channel = guild.get_channel(87654321)
custom_emoji = utils.get(guild.emojis, name='loudspeaker')
await welcome_screen.edit(
description='This is a very cool community server!',
welcome_channels=[
WelcomeChannel(channel=rules_channel, description='Read the rules!', emoji='👨‍🏫'),
WelcomeChannel(channel=announcements_channel, description='Watch out for announcements!', emoji=custom_emoji),
]
)
Parameters
------------
enabled: :class:`bool`
@ -3806,6 +3807,8 @@ class Guild(Hashable):
The welcome screen's description.
welcome_channels: Optional[List[:class:`WelcomeChannel`]]
The welcome channels (in order).
reason: Optional[:class:`str`]
The reason for editing the welcome screen. Shows up on the audit log.
Raises
-------
@ -3827,7 +3830,7 @@ class Guild(Hashable):
payload['welcome_channels'] = channels
if payload:
await self._state.http.edit_welcome_screen(self.id, payload)
await self._state.http.edit_welcome_screen(self.id, payload, reason=reason)
async def applications(
self, *, with_team: bool = False, type: Optional[ApplicationType] = None, channel: Optional[Snowflake] = None
@ -4220,7 +4223,7 @@ class Guild(Hashable):
Fetches all automod rules from the guild.
You must have the :attr:`Permissions.manage_guild` to use this.
You must have :attr:`Permissions.manage_guild` to do this.
.. versionadded:: 2.0
@ -4244,7 +4247,7 @@ class Guild(Hashable):
Fetches an active automod rule from the guild.
You must have the :attr:`Permissions.manage_guild` to use this.
You must have :attr:`Permissions.manage_guild` to do this.
.. versionadded:: 2.0
@ -4282,7 +4285,7 @@ class Guild(Hashable):
Create an automod rule.
You must have the :attr:`Permissions.manage_guild` permission to use this.
You must have :attr:`Permissions.manage_guild` to do this.
.. versionadded:: 2.0

4
discord/http.py
View File

@ -2020,8 +2020,8 @@ class HTTPClient:
def get_welcome_screen(self, guild_id: Snowflake) -> Response[welcome_screen.WelcomeScreen]:
return self.request(Route('GET', '/guilds/{guild_id}/welcome-screen', guild_id=guild_id))
def edit_welcome_screen(self, guild_id: Snowflake, payload) -> Response[welcome_screen.WelcomeScreen]:
return self.request(Route('PATCH', '/guilds/{guild_id}/welcome-screen', guild_id=guild_id), json=payload)
def edit_welcome_screen(self, guild_id: Snowflake, payload: dict, reason: Optional[str] = None) -> Response[welcome_screen.WelcomeScreen]:
return self.request(Route('PATCH', '/guilds/{guild_id}/welcome-screen', guild_id=guild_id), json=payload, reason=reason)
# Invite management

15
discord/integrations.py
View File

@ -133,8 +133,7 @@ class Integration:
Deletes the integration.
You must have the :attr:`~Permissions.manage_guild` permission to
do this.
You must have :attr:`~Permissions.manage_guild` to do this.
Parameters
-----------
@ -231,8 +230,7 @@ class StreamIntegration(Integration):
Edits the integration.
You must have the :attr:`~Permissions.manage_guild` permission to
do this.
You must have :attr:`~Permissions.manage_guild` to do this.
Parameters
-----------
@ -267,8 +265,7 @@ class StreamIntegration(Integration):
Syncs the integration.
You must have the :attr:`~Permissions.manage_guild` permission to
do this.
You must have :attr:`~Permissions.manage_guild` to do this.
Raises
-------
@ -287,8 +284,7 @@ class StreamIntegration(Integration):
This is an alias of :meth:`Integration.delete`.
You must have the :attr:`~Permissions.manage_guild` permission to
do this.
You must have :attr:`~Permissions.manage_guild` to do this.
Parameters
-----------
@ -309,8 +305,7 @@ class StreamIntegration(Integration):
Enables the integration.
You must have the :attr:`~Permissions.manage_guild` permission to
do this.
You must have :attr:`~Permissions.manage_guild` to do this.
Parameters
-----------

2
discord/invite.py
View File

@ -688,7 +688,7 @@ class Invite(Hashable):
Revokes the instant invite.
In a guild context, you must have the :attr:`~Permissions.manage_channels` permission to do this.
In a guild context, you must have :attr:`~Permissions.manage_channels` to do this.
.. versionchanged:: 2.0

10
discord/member.py
View File

@ -898,8 +898,7 @@ class Member(discord.abc.Messageable, discord.abc.Connectable, _UserTag):
Moves a member to a new voice channel (they must be connected first).
You must have the :attr:`~Permissions.move_members` permission to
use this.
You must have :attr:`~Permissions.move_members` to do this.
This raises the same exceptions as :meth:`edit`.
@ -924,8 +923,7 @@ class Member(discord.abc.Messageable, discord.abc.Connectable, _UserTag):
Applies a time out to a member until the specified date time or for the
given :class:`datetime.timedelta`.
You must have the :attr:`~Permissions.moderate_members` permission to
use this.
You must have :attr:`~Permissions.moderate_members` to do this.
This raises the same exceptions as :meth:`edit`.
@ -961,7 +959,7 @@ class Member(discord.abc.Messageable, discord.abc.Connectable, _UserTag):
Gives the member a number of :class:`Role`\s.
You must have the :attr:`~Permissions.manage_roles` permission to
You must have :attr:`~Permissions.manage_roles` to
use this, and the added :class:`Role`\s must appear lower in the list
of roles than the highest role of the member.
@ -1000,7 +998,7 @@ class Member(discord.abc.Messageable, discord.abc.Connectable, _UserTag):
Removes :class:`Role`\s from this member.
You must have the :attr:`~Permissions.manage_roles` permission to
You must have :attr:`~Permissions.manage_roles` to
use this, and the removed :class:`Role`\s must appear lower in the list
of roles than the highest role of the member.

25
discord/message.py
View File

@ -667,8 +667,7 @@ class PartialMessage(Hashable):
Deletes the message.
Your own messages could be deleted without any proper permissions. However to
delete other people's messages, you need the :attr:`~Permissions.manage_messages`
permission.
delete other people's messages, you must have :attr:`~Permissions.manage_messages`.
.. versionchanged:: 1.1
Added the new ``delay`` keyword-only parameter.
@ -810,10 +809,10 @@ class PartialMessage(Hashable):
Publishes this message to your announcement channel.
You must have the :attr:`~Permissions.send_messages` permission to do this.
You must have :attr:`~Permissions.send_messages` to do this.
If the message is not your own then the :attr:`~Permissions.manage_messages`
permission is also needed.
If the message is not your own then :attr:`~Permissions.manage_messages`
is also needed.
Raises
-------
@ -829,7 +828,7 @@ class PartialMessage(Hashable):
Pins the message.
You must have the :attr:`~Permissions.manage_messages` permission to do
You must have :attr:`~Permissions.manage_messages` to do
this in a non-private channel context.
Parameters
@ -858,7 +857,7 @@ class PartialMessage(Hashable):
Unpins the message.
You must have the :attr:`~Permissions.manage_messages` permission to do
You must have :attr:`~Permissions.manage_messages` to do
this in a non-private channel context.
Parameters
@ -888,9 +887,9 @@ class PartialMessage(Hashable):
The emoji may be a unicode emoji or a custom guild :class:`Emoji`.
You must have the :attr:`~Permissions.read_message_history` permission
to use this. If nobody else has reacted to the message using this
emoji, the :attr:`~Permissions.add_reactions` permission is required.
You must have :attr:`~Permissions.read_message_history`
to do this. If nobody else has reacted to the message using this
emoji, :attr:`~Permissions.add_reactions` is required.
.. versionchanged:: 2.0
@ -927,7 +926,7 @@ class PartialMessage(Hashable):
The emoji may be a unicode emoji or a custom guild :class:`Emoji`.
If the reaction is not your own (i.e. ``member`` parameter is not you) then
the :attr:`~Permissions.manage_messages` permission is needed.
:attr:`~Permissions.manage_messages` is needed.
The ``member`` parameter must represent a member and meet
the :class:`abc.Snowflake` abc.
@ -968,7 +967,7 @@ class PartialMessage(Hashable):
The emoji may be a unicode emoji or a custom guild :class:`Emoji`.
You need the :attr:`~Permissions.manage_messages` permission to use this.
You must have :attr:`~Permissions.manage_messages` to do this.
.. versionadded:: 1.3
@ -1000,7 +999,7 @@ class PartialMessage(Hashable):
Removes all the reactions from the message.
You need the :attr:`~Permissions.manage_messages` permission to use this.
You must have :attr:`~Permissions.manage_messages` to do this.
Raises
--------

4
discord/reaction.py
View File

@ -117,7 +117,7 @@ class Reaction:
Remove the reaction by the provided :class:`User` from the message.
If the reaction is not your own (i.e. ``user`` parameter is not you) then
the :attr:`~Permissions.manage_messages` permission is needed.
:attr:`~Permissions.manage_messages` is needed.
The ``user`` parameter must represent a user or member and meet
the :class:`abc.Snowflake` abc.
@ -144,7 +144,7 @@ class Reaction:
Clears this reaction from the message.
You need the :attr:`~Permissions.manage_messages` permission to use this.
You must have :attr:`~Permissions.manage_messages` to do this.
.. versionadded:: 1.3

14
discord/role.py
View File

@ -423,8 +423,8 @@ class Role(Hashable):
Adds a number of :class:`Member`\s to this role.
You must have the :attr:`~Permissions.manage_roles` permission to
use this, and the current :class:`Role` must appear lower in the list
You must have :attr:`~Permissions.manage_roles` to use this,
and the current :class:`Role` must appear lower in the list
of roles than the highest role of the member.
Parameters
@ -465,8 +465,8 @@ class Role(Hashable):
Removes :class:`Member`\s from this role.
You must have the :attr:`~Permissions.manage_roles` permission to
use this, and the current :class:`Role` must appear lower in the list
You must have :attr:`~Permissions.manage_roles` to use this,
and the current :class:`Role` must appear lower in the list
of roles than the highest role of the member.
Parameters
@ -514,8 +514,7 @@ class Role(Hashable):
Edits the role.
You must have the :attr:`~Permissions.manage_roles` permission to
use this.
You must have :attr:`~Permissions.manage_roles` to do this.
All fields are optional.
@ -638,8 +637,7 @@ class Role(Hashable):
Deletes the role.
You must have the :attr:`~Permissions.manage_roles` permission to
use this.
You must have :attr:`~Permissions.manage_roles` to do this.
Parameters
-----------

4
discord/scheduled_event.py
View File

@ -315,7 +315,7 @@ class ScheduledEvent(Hashable):
Edits the scheduled event.
Requires :attr:`~Permissions.manage_events` permissions.
You must have :attr:`~Permissions.manage_events` to do this.
Parameters
-----------
@ -460,7 +460,7 @@ class ScheduledEvent(Hashable):
Deletes the scheduled event.
Requires :attr:`~Permissions.manage_events` permissions.
You must have :attr:`~Permissions.manage_events` to do this.
Parameters
-----------

6
discord/stage_instance.py
View File

@ -140,8 +140,7 @@ class StageInstance(Hashable):
Edits the stage instance.
You must have the :attr:`~Permissions.manage_channels` permission to
use this.
You must have :attr:`~Permissions.manage_channels` to do this.
Parameters
-----------
@ -180,8 +179,7 @@ class StageInstance(Hashable):
Deletes the stage instance.
You must have the :attr:`~Permissions.manage_channels` permission to
use this.
You must have :attr:`~Permissions.manage_channels` to do this.
Parameters
-----------

5
discord/sticker.py
View File

@ -427,7 +427,7 @@ class GuildSticker(Sticker):
The ID of the guild that this sticker is from.
user: Optional[:class:`User`]
The user that created this sticker. This can only be retrieved using :meth:`Guild.fetch_sticker` and
having the :attr:`~Permissions.manage_emojis_and_stickers` permission.
having :attr:`~Permissions.manage_emojis_and_stickers`.
emoji: :class:`str`
The name of a unicode emoji that represents this sticker.
"""
@ -516,8 +516,7 @@ class GuildSticker(Sticker):
Deletes the custom :class:`Sticker` from the guild.
You must have :attr:`~Permissions.manage_emojis_and_stickers` permission to
do this.
You must have :attr:`~Permissions.manage_emojis_and_stickers` to do this.
Parameters
-----------

9
discord/template.py
View File

@ -208,8 +208,7 @@ class Template:
Sync the template to the guild's current state.
You must have the :attr:`~Permissions.manage_guild` permission in the
source guild to do this.
You must have :attr:`~Permissions.manage_guild` in the source guild to do this.
.. versionadded:: 1.7
@ -244,8 +243,7 @@ class Template:
Edit the template metadata.
You must have the :attr:`~Permissions.manage_guild` permission in the
source guild to do this.
You must have :attr:`~Permissions.manage_guild` in the source guild to do this.
.. versionadded:: 1.7
@ -288,8 +286,7 @@ class Template:
Delete the template.
You must have the :attr:`~Permissions.manage_guild` permission in the
source guild to do this.
You must have :attr:`~Permissions.manage_guild` in the source guild to do this.
.. versionadded:: 1.7

15
discord/threads.py
View File

@ -445,8 +445,7 @@ class Thread(Messageable, Hashable):
Deletes a list of messages. This is similar to :meth:`Message.delete`
except it bulk deletes multiple messages.
You must have the :attr:`~Permissions.manage_messages` permission to
use this (unless they're your own).
You must have :attr:`~Permissions.manage_messages` to use this (unless they're your own).
.. note::
Users do not have access to the message bulk-delete endpoint.
@ -492,7 +491,7 @@ class Thread(Messageable, Hashable):
``check``. If a ``check`` is not provided then all messages are deleted
without discrimination.
The :attr:`~Permissions.read_message_history` permission is needed to
Having :attr:`~Permissions.read_message_history` is needed to
retrieve message history.
Examples
@ -639,11 +638,11 @@ class Thread(Messageable, Hashable):
Adds the given forum tags to a thread.
You must have the :attr:`~Permissions.manage_threads` permission to
You must have :attr:`~Permissions.manage_threads` to
use this or the thread must be owned by you.
Tags that have :attr:`ForumTag.moderated` set to ``True`` require the
:attr:`~Permissions.manage_threads` permissions to be added.
Tags that have :attr:`ForumTag.moderated` set to ``True`` require
:attr:`~Permissions.manage_threads` to be added.
The maximum number of tags that can be added to a thread is 5.
@ -677,7 +676,7 @@ class Thread(Messageable, Hashable):
Remove the given forum tags to a thread.
You must have the :attr:`~Permissions.manage_threads` permission to
You must have :attr:`~Permissions.manage_threads` to
use this or the thread must be owned by you.
The parent channel must be a :class:`ForumChannel`.
@ -743,7 +742,7 @@ class Thread(Messageable, Hashable):
Adds a user to this thread.
You must have :attr:`~Permissions.send_messages_in_threads` to add a user to a thread.
If the thread is private then and :attr:`invitable` is ``False`` then :attr:`~Permissions.manage_messages`
If the thread is private and :attr:`invitable` is ``False`` then :attr:`~Permissions.manage_messages`
is required to add a user to the thread.
Parameters

30
discord/welcome_screen.py
View File

@ -62,9 +62,12 @@ class WelcomeChannel:
The emoji shown under the description.
"""
def __init__(self, *, channel: Snowflake, description: str, emoji: Optional[Union[PartialEmoji, Emoji]] = None) -> None:
def __init__(self, *, channel: Snowflake, description: str, emoji: Optional[Union[PartialEmoji, Emoji, str]] = None) -> None:
self.channel = channel
self.description = description
if isinstance(emoji, str):
emoji = PartialEmoji(name=emoji)
self.emoji = emoji
def __repr__(self) -> str:
@ -146,14 +149,33 @@ class WelcomeScreen:
description: str = MISSING,
welcome_channels: List[WelcomeChannel] = MISSING,
enabled: bool = MISSING,
reason: Optional[str] = None,
):
"""|coro|
Edit the welcome screen.
You must have the :attr:`~Permissions.manage_guild` permission to do this.
Welcome channels can only accept custom emojis if :attr:`Guild.premium_tier` is level 2 or above.
You must have :attr:`~Permissions.manage_guild` in the guild to do this.
All parameters are optional.
Usage: ::
rules_channel = guild.get_channel(12345678)
announcements_channel = guild.get_channel(87654321)
custom_emoji = utils.get(guild.emojis, name='loudspeaker')
await welcome_screen.edit(
description='This is a very cool community server!',
welcome_channels=[
WelcomeChannel(channel=rules_channel, description='Read the rules!', emoji='👨‍🏫'),
WelcomeChannel(channel=announcements_channel, description='Watch out for announcements!', emoji=custom_emoji),
]
)
Parameters
------------
enabled: :class:`bool`
@ -162,6 +184,8 @@ class WelcomeScreen:
The welcome screen's description.
welcome_channels: Optional[List[:class:`WelcomeChannel`]]
The welcome channels (in order).
reason: Optional[:class:`str`]
The reason for editing the welcome screen. Shows up on the audit log.
Raises
-------
@ -182,5 +206,5 @@ class WelcomeScreen:
if payload:
guild = self.guild
data = await guild._state.http.edit_welcome_screen(guild.id, payload)
data = await guild._state.http.edit_welcome_screen(guild.id, payload, reason=reason)
self._update(data)

4
docs/api.rst
View File

@ -767,7 +767,7 @@ Guilds
.. function:: on_invite_create(invite)
Called when an :class:`Invite` is created.
You must have the :attr:`~Permissions.manage_channels` permission to receive this.
You must have :attr:`~Permissions.manage_channels` to receive this.
.. versionadded:: 1.3
@ -782,7 +782,7 @@ Guilds
.. function:: on_invite_delete(invite)
Called when an :class:`Invite` is deleted.
You must have the :attr:`~Permissions.manage_channels` permission to receive this.
You must have :attr:`~Permissions.manage_channels` to receive this.
.. versionadded:: 1.3

Write Preview
Loading…
Cancel
Save