diff --git a/discord/abc.py b/discord/abc.py index beeebf959..88aa372c4 100644 --- a/discord/abc.py +++ b/discord/abc.py @@ -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 --------- diff --git a/discord/automod.py b/discord/automod.py index 5c406299e..07eca44ab 100644 --- a/discord/automod.py +++ b/discord/automod.py @@ -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 ------- diff --git a/discord/channel.py b/discord/channel.py index 6dac6f734..b39ac0ffa 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -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 ------------- diff --git a/discord/client.py b/discord/client.py index fae23a859..b65d263af 100644 --- a/discord/client.py +++ b/discord/client.py @@ -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 diff --git a/discord/emoji.py b/discord/emoji.py index 89b2dfe98..f564a8f24 100644 --- a/discord/emoji.py +++ b/discord/emoji.py @@ -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. diff --git a/discord/guild.py b/discord/guild.py index 2f37e8253..04dbd665f 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -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 diff --git a/discord/http.py b/discord/http.py index 88384872e..e4e1a7f84 100644 --- a/discord/http.py +++ b/discord/http.py @@ -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 diff --git a/discord/integrations.py b/discord/integrations.py index a36ba8383..70b69e68b 100644 --- a/discord/integrations.py +++ b/discord/integrations.py @@ -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 ----------- diff --git a/discord/invite.py b/discord/invite.py index 835a13a34..4123c7853 100644 --- a/discord/invite.py +++ b/discord/invite.py @@ -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 diff --git a/discord/member.py b/discord/member.py index f6b3f6dbe..aa8ef5a8b 100644 --- a/discord/member.py +++ b/discord/member.py @@ -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. diff --git a/discord/message.py b/discord/message.py index 32798b74a..93d0b5db4 100644 --- a/discord/message.py +++ b/discord/message.py @@ -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 -------- diff --git a/discord/reaction.py b/discord/reaction.py index 302358880..e93f323e9 100644 --- a/discord/reaction.py +++ b/discord/reaction.py @@ -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 diff --git a/discord/role.py b/discord/role.py index 33b8e5b99..fcd9f4e3c 100644 --- a/discord/role.py +++ b/discord/role.py @@ -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 ----------- diff --git a/discord/scheduled_event.py b/discord/scheduled_event.py index f65c20f22..51eef2745 100644 --- a/discord/scheduled_event.py +++ b/discord/scheduled_event.py @@ -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 ----------- diff --git a/discord/stage_instance.py b/discord/stage_instance.py index 4f3b5b58f..ae40c73b8 100644 --- a/discord/stage_instance.py +++ b/discord/stage_instance.py @@ -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 ----------- diff --git a/discord/sticker.py b/discord/sticker.py index 516cdb8fe..168fcda13 100644 --- a/discord/sticker.py +++ b/discord/sticker.py @@ -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 ----------- diff --git a/discord/template.py b/discord/template.py index b18eb16bd..b05a23ff9 100644 --- a/discord/template.py +++ b/discord/template.py @@ -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 diff --git a/discord/threads.py b/discord/threads.py index c22740831..d2106dcd2 100644 --- a/discord/threads.py +++ b/discord/threads.py @@ -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 diff --git a/discord/welcome_screen.py b/discord/welcome_screen.py index 130e6a8e2..1a2413a12 100644 --- a/discord/welcome_screen.py +++ b/discord/welcome_screen.py @@ -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) diff --git a/docs/api.rst b/docs/api.rst index e6535f377..804cc665a 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -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