From 6f9793fe5e8090446f7e8fd0d1e0d752cd66fd0f Mon Sep 17 00:00:00 2001 From: Harmon Date: Wed, 22 Jan 2020 22:55:05 -0600 Subject: 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 +++ 12 files changed, 81 insertions(+), 18 deletions(-) (limited to 'discord') diff --git a/discord/activity.py b/discord/activity.py index 01f23347..ddbdc60d 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 4b3c9e94..0a15e1e1 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 2bd5c31c..1879a974 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 fcd8adcb..5feb1c90 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 42cdd929..20dc94de 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 f37262d6..62460098 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 9ee522c4..38c965c9 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 0292e2b4..62585735 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 c7349f6b..d9ce84cd 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 3472820a..39f7f222 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 a172d5f9..2331ff49 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 cc43bbca..efc33bed 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. -- cgit v1.2.3