matthew/enhanced-discord.py
1
0
Fork 0
Code Issues 4 Pull Requests 21 Projects Releases Wiki Activity

Fixes and improvements for v1.3 documentation

Browse Source 
* 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
This commit is contained in:
Harmon 2020-01-22 22:55:05 -06:00 committed by Danny
parent 03d9005eec
commit 6f9793fe5e
14 changed files with 122 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
discord/activity.py
View File

@ -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`

35
discord/appinfo.py
View File

@ -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))

15
discord/channel.py
View File

@ -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

5
discord/emoji.py
View File

@ -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:

7
discord/ext/commands/bot.py
View File

@ -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

2
discord/flags.py
View File

@ -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`

2
discord/guild.py
View File

@ -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',

6
discord/message.py
View File

@ -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`]

11
discord/raw_models.py
View File

@ -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 <https://discordapp.com/developers/docs/topics/gateway#message-update>`_
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',

4
discord/team.py
View File

@ -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`

3
discord/user.py
View File

@ -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`]

3
discord/webhook.py
View File

@ -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.

43
docs/api.rst
View File

@ -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.

8
docs/whats_new.rst
View File

@ -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`)