From 6f9793fe5e8090446f7e8fd0d1e0d752cd66fd0f Mon Sep 17 00:00:00 2001 From: Harmon Date: Wed, 22 Jan 2020 22:55:05 -0600 Subject: [PATCH] Fixes and improvements for v1.3 documentation * Add missing versionadded strings for v1.3 * Add missing versionchanged string for Message.edit * Consistently use versionadded for attributes * Consistently use versionchanged for parameters * Use versionchanged for Bot.is_owner * Fix references in v1.3 changelog * Improve grammar in v1.3 changelog --- discord/activity.py | 6 ++++++ discord/appinfo.py | 35 +++++++++++++++++++++++++++--- discord/channel.py | 15 +++++++------ discord/emoji.py | 5 ++++- discord/ext/commands/bot.py | 7 ++++-- discord/flags.py | 2 ++ discord/guild.py | 2 ++ discord/message.py | 6 ++++++ discord/raw_models.py | 11 +++++----- discord/team.py | 4 ++++ discord/user.py | 3 +++ discord/webhook.py | 3 +++ docs/api.rst | 43 +++++++++++++++++++++++++++++++------ docs/whats_new.rst | 8 +++---- 14 files changed, 122 insertions(+), 28 deletions(-) diff --git a/discord/activity.py b/discord/activity.py index 01f23347f..ddbdc60db 100644 --- a/discord/activity.py +++ b/discord/activity.py @@ -414,12 +414,18 @@ class Streaming(BaseActivity): ----------- platform: :class:`str` Where the user is streaming from (ie. YouTube, Twitch). + + .. versionadded:: 1.3 + name: Optional[:class:`str`] The stream's name. details: Optional[:class:`str`] Same as :attr:`name` game: Optional[:class:`str`] The game being streamed. + + .. versionadded:: 1.3 + url: :class:`str` The stream's URL. assets: :class:`dict` diff --git a/discord/appinfo.py b/discord/appinfo.py index 4b3c9e941..0a15e1e10 100644 --- a/discord/appinfo.py +++ b/discord/appinfo.py @@ -44,6 +44,9 @@ class AppInfo: The application owner. team: Optional[:class:`Team`] The application's team. + + .. versionadded:: 1.3 + icon: Optional[:class:`str`] The icon hash, if it exists. description: Optional[:class:`str`] @@ -59,20 +62,37 @@ class AppInfo: summary: :class:`str` If this application is a game sold on Discord, this field will be the summary field for the store page of its primary SKU + + .. versionadded:: 1.3 + verify_key: :class:`str` The base64 encoded key for the GameSDK's GetTicket + + .. versionadded:: 1.3 + guild_id: Optional[:class:`int`] If this application is a game sold on Discord, this field will be the guild to which it has been linked + + .. versionadded:: 1.3 + primary_sku_id: Optional[:class:`int`] If this application is a game sold on Discord, this field will be the id of the "Game SKU" that is created, if exists + + .. versionadded:: 1.3 + slug: Optional[:class:`str`] If this application is a game sold on Discord, this field will be the URL slug that links to the store page + + .. versionadded:: 1.3 + cover_image: Optional[:class:`str`] If this application is a game sold on Discord, this field will be the hash of the image on store embeds + + .. versionadded:: 1.3 """ __slots__ = ('_state', 'description', 'id', 'name', 'rpc_origins', 'bot_public', 'bot_require_code_grant', 'owner', 'icon', @@ -109,16 +129,25 @@ class AppInfo: @property def icon_url(self): - """:class:`.Asset`: Retrieves the application's icon asset.""" + """:class:`.Asset`: Retrieves the application's icon asset. + + .. versionadded:: 1.3 + """ return Asset._from_icon(self._state, self, 'app') @property def cover_image_url(self): - """:class:`.Asset`: Retrieves the cover image on a store embed.""" + """:class:`.Asset`: Retrieves the cover image on a store embed. + + .. versionadded:: 1.3 + """ return Asset._from_cover_image(self._state, self) @property def guild(self): """Optional[:class:`Guild`]: If this application is a game sold on Discord, - this field will be the guild to which it has been linked""" + this field will be the guild to which it has been linked + + .. versionadded:: 1.3 + """ return self._state._get_guild(int(self.guild_id)) diff --git a/discord/channel.py b/discord/channel.py index 2bd5c31cb..1879a974d 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -194,6 +194,9 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable): You must have the :attr:`~Permissions.manage_channels` permission to use this. + .. versionchanged:: 1.3 + The ``overwrites`` keyword-only parameter was added. + Parameters ---------- name: :class:`str` @@ -219,8 +222,6 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable): A :class:`dict` of target (either a role or a member) to :class:`PermissionOverwrite` to apply to the channel. - .. versionadded:: 1.3 - Raises ------ InvalidArgument @@ -644,6 +645,9 @@ class VoiceChannel(discord.abc.Connectable, discord.abc.GuildChannel, Hashable): You must have the :attr:`~Permissions.manage_channels` permission to use this. + .. versionchanged:: 1.3 + The ``overwrites`` keyword-only parameter was added. + Parameters ---------- name: :class:`str` @@ -666,8 +670,6 @@ class VoiceChannel(discord.abc.Connectable, discord.abc.GuildChannel, Hashable): A :class:`dict` of target (either a role or a member) to :class:`PermissionOverwrite` to apply to the channel. - .. versionadded:: 1.3 - Raises ------ InvalidArgument @@ -762,6 +764,9 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable): You must have the :attr:`~Permissions.manage_channels` permission to use this. + .. versionchanged:: 1.3 + The ``overwrites`` keyword-only parameter was added. + Parameters ---------- name: :class:`str` @@ -776,8 +781,6 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable): A :class:`dict` of target (either a role or a member) to :class:`PermissionOverwrite` to apply to the channel. - .. versionadded:: 1.3 - Raises ------ InvalidArgument diff --git a/discord/emoji.py b/discord/emoji.py index fcd8adcb4..5feb1c904 100644 --- a/discord/emoji.py +++ b/discord/emoji.py @@ -154,7 +154,10 @@ class Emoji(_EmojiTag): return self._state._get_guild(self.guild_id) def is_usable(self): - """:class:`bool`: Whether the bot can use this emoji.""" + """:class:`bool`: Whether the bot can use this emoji. + + .. versionadded:: 1.3 + """ if not self.available: return False if not self._roles: diff --git a/discord/ext/commands/bot.py b/discord/ext/commands/bot.py index 42cdd929e..20dc94de1 100644 --- a/discord/ext/commands/bot.py +++ b/discord/ext/commands/bot.py @@ -293,8 +293,9 @@ class BotBase(GroupMixin): If an :attr:`owner_id` is not set, it is fetched automatically through the use of :meth:`~.Bot.application_info`. - The function also checks if the application is team-owned if - :attr:`owner_ids` is not set. + .. versionchanged:: 1.3 + The function also checks if the application is team-owned if + :attr:`owner_ids` is not set. Parameters ----------- @@ -993,6 +994,8 @@ class Bot(BotBase, discord.Client): fetched automatically using :meth:`~.Bot.application_info`. For performance reasons it is recommended to use a :class:`set` for the collection. You cannot set both `owner_id` and `owner_ids`. + + .. versionadded:: 1.3 """ pass diff --git a/discord/flags.py b/discord/flags.py index f37262d68..624600983 100644 --- a/discord/flags.py +++ b/discord/flags.py @@ -187,6 +187,8 @@ class MessageFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. + .. versionadded:: 1.3 + Attributes ----------- value: :class:`int` diff --git a/discord/guild.py b/discord/guild.py index 9ee522c49..38c965c93 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -146,6 +146,8 @@ class Guild(Hashable): results to a specific language. discovery_splash: :class:`str` The guild's discovery splash. + + .. versionadded:: 1.3 """ __slots__ = ('afk_timeout', 'afk_channel', '_members', '_channels', 'icon', diff --git a/discord/message.py b/discord/message.py index 0292e2b4c..62585735f 100644 --- a/discord/message.py +++ b/discord/message.py @@ -269,6 +269,9 @@ class Message: Specifies if the message is currently pinned. flags: :class:`MessageFlags` Extra features of the message. + + .. versionadded:: 1.3 + reactions : List[:class:`Reaction`] Reactions to a message. Reactions can be either custom emoji or standard unicode emoji. activity: Optional[:class:`dict`] @@ -764,6 +767,9 @@ class Message: The content must be able to be transformed into a string via ``str(content)``. + .. versionchanged:: 1.3 + The ``suppress`` keyword-only parameter was added. + Parameters ----------- content: Optional[:class:`str`] diff --git a/discord/raw_models.py b/discord/raw_models.py index c7349f6b8..d9ce84cdc 100644 --- a/discord/raw_models.py +++ b/discord/raw_models.py @@ -85,15 +85,15 @@ class RawBulkMessageDeleteEvent(_RawReprMixin): class RawMessageUpdateEvent(_RawReprMixin): """Represents the payload for a :func:`on_raw_message_edit` event. - .. versionchanged:: 1.3 - The ``channel_id`` attribute was added. - Attributes ----------- message_id: :class:`int` The message ID that got updated. channel_id: :class:`int` The channel ID where the update took place. + + .. versionadded:: 1.3 + data: :class:`dict` The raw data given by the `gateway `_ cached_message: Optional[:class:`Message`] @@ -112,9 +112,6 @@ class RawReactionActionEvent(_RawReprMixin): """Represents the payload for a :func:`on_raw_reaction_add` or :func:`on_raw_reaction_remove` event. - .. versionchanged:: 1.3 - The ``event_type`` attribute was added. - Attributes ----------- message_id: :class:`int` @@ -136,6 +133,8 @@ class RawReactionActionEvent(_RawReprMixin): The event type that triggered this action. Can be ``REACTION_ADD`` for reaction addition or ``REACTION_REMOVE`` for reaction removal. + + .. versionadded:: 1.3 """ __slots__ = ('message_id', 'user_id', 'channel_id', 'guild_id', 'emoji', diff --git a/discord/team.py b/discord/team.py index 3472820a8..39f7f222e 100644 --- a/discord/team.py +++ b/discord/team.py @@ -49,6 +49,8 @@ class Team: The team's owner ID. members: List[:class:`TeamMember`] A list of the members in the team + + .. versionadded:: 1.3 """ __slots__ = ('_state', 'id', 'name', 'icon', 'owner_id', 'members') @@ -95,6 +97,8 @@ class TeamMember(BaseUser): Returns the team member's name with discriminator. + .. versionadded:: 1.3 + Attributes ------------- name: :class:`str` diff --git a/discord/user.py b/discord/user.py index a172d5f9d..2331ff498 100644 --- a/discord/user.py +++ b/discord/user.py @@ -301,6 +301,9 @@ class ClientUser(BaseUser): Specifies if the user is a bot account. system: :class:`bool` Specifies if the user is a system user (i.e. represents Discord officially). + + .. versionadded:: 1.3 + verified: :class:`bool` Specifies if the user is a verified account. email: Optional[:class:`str`] diff --git a/discord/webhook.py b/discord/webhook.py index cc43bbca8..efc33beda 100644 --- a/discord/webhook.py +++ b/discord/webhook.py @@ -404,6 +404,9 @@ class Webhook: The webhook's ID type: :class:`WebhookType` The type of the webhook. + + .. versionadded:: 1.3 + token: Optional[:class:`str`] The authentication token of the webhook. If this is ``None`` then the webhook cannot be used to make requests. diff --git a/docs/api.rst b/docs/api.rst index 02ba215eb..54ba123af 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -768,9 +768,15 @@ Profile .. attribute:: team_user A boolean indicating if the user is in part of a team. + + .. versionadded:: 1.3 + .. attribute:: system A boolean indicating if the user is officially part of the Discord urgent message system. + + .. versionadded:: 1.3 + .. attribute:: mutual_guilds A list of :class:`Guild` that the :class:`ClientUser` shares with this @@ -914,12 +920,6 @@ of :class:`enum.Enum`. Specifies the region a voice server belongs to. - .. versionchanged:: 1.2 - The ``india`` region was added. - - .. versionchanged:: 1.3 - The ``europe`` and ``dubai`` regions were added. - .. attribute:: amsterdam The Amsterdam region. @@ -929,6 +929,9 @@ of :class:`enum.Enum`. .. attribute:: dubai The Dubai region. + + .. versionadded:: 1.3 + .. attribute:: eu_central The EU Central region. @@ -938,6 +941,9 @@ of :class:`enum.Enum`. .. attribute:: europe The Europe region. + + .. versionadded:: 1.3 + .. attribute:: frankfurt The Frankfurt region. @@ -947,6 +953,9 @@ of :class:`enum.Enum`. .. attribute:: india The India region. + + .. versionadded:: 1.2 + .. attribute:: japan The Japan region. @@ -1332,6 +1341,8 @@ of :class:`enum.Enum`. - ``channel``: A :class:`TextChannel` or :class:`Object` with the channel ID where the members were moved. - ``count``: An integer specifying how many members were moved. + .. versionadded:: 1.3 + .. attribute:: member_disconnect A member's voice state has changed. This triggers when a @@ -1342,6 +1353,8 @@ of :class:`enum.Enum`. - ``count``: An integer specifying how many members were disconnected. + .. versionadded:: 1.3 + .. attribute:: bot_add A bot was added to the guild. @@ -1349,6 +1362,8 @@ of :class:`enum.Enum`. When this is the action, the type of :attr:`~AuditLogEntry.target` is the :class:`Member` or :class:`User` which was added to the guild. + .. versionadded:: 1.3 + .. attribute:: role_create A new role was created. @@ -1540,6 +1555,8 @@ of :class:`enum.Enum`. - ``count``: An integer specifying how many messages were deleted. + .. versionadded:: 1.3 + .. attribute:: message_pin A message was pinned in a channel. @@ -1553,6 +1570,8 @@ of :class:`enum.Enum`. - ``channel``: A :class:`TextChannel` or :class:`Object` with the channel ID where the message was pinned. - ``message_id``: the ID of the message which was pinned. + .. versionadded:: 1.3 + .. attribute:: message_unpin A message was unpinned in a channel. @@ -1566,6 +1585,8 @@ of :class:`enum.Enum`. - ``channel``: A :class:`TextChannel` or :class:`Object` with the channel ID where the message was unpinned. - ``message_id``: the ID of the message which was unpinned. + .. versionadded:: 1.3 + .. attribute:: integration_create A guild integration was created. @@ -1573,6 +1594,8 @@ of :class:`enum.Enum`. When this is the action, the type of :attr:`~AuditLogEntry.target` is the :class:`Object` with the integration ID of the integration which was created. + .. versionadded:: 1.3 + .. attribute:: integration_update A guild integration was updated. @@ -1580,6 +1603,8 @@ of :class:`enum.Enum`. When this is the action, the type of :attr:`~AuditLogEntry.target` is the :class:`Object` with the integration ID of the integration which was updated. + .. versionadded:: 1.3 + .. attribute:: integration_delete A guild integration was deleted. @@ -1587,6 +1612,8 @@ of :class:`enum.Enum`. When this is the action, the type of :attr:`~AuditLogEntry.target` is the :class:`Object` with the integration ID of the integration which was deleted. + .. versionadded:: 1.3 + .. class:: AuditLogActionCategory Represents the category that the :class:`AuditLogAction` belongs to. @@ -1721,6 +1748,8 @@ of :class:`enum.Enum`. Represents the membership state of a team member retrieved through :func:`Bot.application_info`. + .. versionadded:: 1.3 + .. attribute:: invited Represents an invited member. @@ -1733,6 +1762,8 @@ of :class:`enum.Enum`. Represents the type of webhook that can be received. + .. versionadded:: 1.3 + .. attribute:: incoming Represents a webhook that can post messages to channels with a token. diff --git a/docs/whats_new.rst b/docs/whats_new.rst index 8ae0cfed3..86d9d06bb 100644 --- a/docs/whats_new.rst +++ b/docs/whats_new.rst @@ -25,7 +25,7 @@ New Features - Add :meth:`Guild.fetch_roles` to fetch roles from the HTTP API. (:issue:`2208`) - Add support for teams via :class:`Team` when fetching with :meth:`Client.application_info`. (:issue:`2239`) - Add support for suppressing embeds via :meth:`Message.edit` -- Add support for guild subscriptions, see the :class:`Client` documentation for more details. +- Add support for guild subscriptions. See the :class:`Client` documentation for more details. - Add :attr:`VoiceChannel.voice_states` to get voice states without relying on member cache. - Add :meth:`Guild.query_members` to request members from the gateway. - Add :class:`FFmpegOpusAudio` and other voice improvements. (:issue:`2258`) @@ -56,7 +56,7 @@ New Features - Add :attr:`User.system` and :attr:`Profile.system` to know whether a user is an official Discord Trust and Safety account. - Add :attr:`Profile.team_user` to check whether a user is a member of a team. - Add :meth:`Attachment.to_file` to easily convert attachments to :class:`File` for sending. -- Add certain aliases to :class:`Permission` to match the UI better. (:issue:`2496`) +- Add certain aliases to :class:`Permissions` to match the UI better. (:issue:`2496`) - :attr:`Permissions.manage_permissions` - :attr:`Permissions.view_channel` - :attr:`Permissions.use_external_emojis` @@ -66,11 +66,11 @@ New Features - Add support for :func:`on_invite_create` and :func:`on_invite_delete` events. - Add support for clearing a specific reaction emoji from a message. - - :meth:`Message.clear_reaction` and :class:`Reaction.clear` methods. + - :meth:`Message.clear_reaction` and :meth:`Reaction.clear` methods. - :func:`on_raw_reaction_clear_emoji` and :func:`on_reaction_clear_emoji` events. - Add :func:`utils.sleep_until` helper to sleep until a specific datetime. (:issue:`2517`, :issue:`2519`) -- |commands| Add support for teams and :attr:`Bot.owner_ids` to have multiple bot owners. (:issue:`2239`) +- |commands| Add support for teams and :attr:`Bot.owner_ids <.ext.commands.Bot.owner_ids>` to have multiple bot owners. (:issue:`2239`) - |commands| Add new :attr:`BucketType.role <.ext.commands.BucketType.role>` bucket type. (:issue:`2201`) - |commands| Expose :attr:`Command.cog <.ext.commands.Command.cog>` property publicly. (:issue:`2360`) - |commands| Add non-decorator interface for adding checks to commands via :meth:`Command.add_check <.ext.commands.Command.add_check>` and :meth:`Command.remove_check <.ext.commands.Command.remove_check>`. (:issue:`2411`)