mirrors/discord.py
1
0
Fork 0
mirror of https://github.com/Rapptz/discord.py.git synced 2025-04-19 07:26:17 +00:00
Code Issues Projects Releases Wiki Activity

Improve documentation

Browse Source
This commit is contained in:
NCPlayz 2019-05-18 06:04:54 -04:00 committed by Rapptz
parent 2f05436653
commit 3c9bcc2851
48 changed files with 652 additions and 569 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
discord/abc.py
View File

@ -61,7 +61,7 @@ class Snowflake(metaclass=abc.ABCMeta):
@property @property
@abc.abstractmethod @abc.abstractmethod
def created_at(self): def created_at(self):
"""Returns the model's creation time in UTC.""" """:class:`datetime.datetime`: Returns the model's creation time as a naive datetime in UTC."""
raise NotImplementedError raise NotImplementedError
@classmethod @classmethod
@ -82,11 +82,11 @@ class User(metaclass=abc.ABCMeta):
The following implement this ABC: The following implement this ABC:
- :class:`User` - :class:`~discord.User`
- :class:`ClientUser` - :class:`~discord.ClientUser`
- :class:`Member` - :class:`~discord.Member`
This ABC must also implement :class:`abc.Snowflake`. This ABC must also implement :class:`~discord.abc.Snowflake`.
Attributes Attributes
----------- -----------
@ -104,13 +104,13 @@ class User(metaclass=abc.ABCMeta):
@property @property
@abc.abstractmethod @abc.abstractmethod
def display_name(self): def display_name(self):
"""Returns the user's display name.""" """:class:`str`: Returns the user's display name."""
raise NotImplementedError raise NotImplementedError
@property @property
@abc.abstractmethod @abc.abstractmethod
def mention(self): def mention(self):
"""Returns a string that allows you to mention the given user.""" """:class:`str`: Returns a string that allows you to mention the given user."""
raise NotImplementedError raise NotImplementedError
@classmethod @classmethod
@ -134,14 +134,14 @@ class PrivateChannel(metaclass=abc.ABCMeta):
The following implement this ABC: The following implement this ABC:
- :class:`DMChannel` - :class:`~discord.DMChannel`
- :class:`GroupChannel` - :class:`~discord.GroupChannel`
This ABC must also implement :class:`abc.Snowflake`. This ABC must also implement :class:`~discord.abc.Snowflake`.
Attributes Attributes
----------- -----------
me: :class:`ClientUser` me: :class:`~discord.ClientUser`
The user presenting yourself. The user presenting yourself.
""" """
__slots__ = () __slots__ = ()
@ -166,17 +166,17 @@ class GuildChannel:
The following implement this ABC: The following implement this ABC:
- :class:`TextChannel` - :class:`~discord.TextChannel`
- :class:`VoiceChannel` - :class:`~discord.VoiceChannel`
- :class:`CategoryChannel` - :class:`~discord.CategoryChannel`
This ABC must also implement :class:`abc.Snowflake`. This ABC must also implement :class:`~discord.abc.Snowflake`.
Attributes Attributes
----------- -----------
name: :class:`str` name: :class:`str`
The channel name. The channel name.
guild: :class:`Guild` guild: :class:`~discord.Guild`
The guild the channel belongs to. The guild the channel belongs to.
position: :class:`int` position: :class:`int`
The position in the channel list. This is a number that starts at 0. The position in the channel list. This is a number that starts at 0.
@ -288,8 +288,8 @@ class GuildChannel:
@property @property
def changed_roles(self): def changed_roles(self):
"""Returns a :class:`list` of :class:`Roles` that have been overridden from """List[:class:`~discord.Role`]: Returns a list of roles that have been overridden from
their default values in the :attr:`Guild.roles` attribute.""" their default values in the :attr:`~discord.Guild.roles` attribute."""
ret = [] ret = []
g = self.guild g = self.guild
for overwrite in filter(lambda o: o.type == 'role', self._overwrites): for overwrite in filter(lambda o: o.type == 'role', self._overwrites):
@ -309,7 +309,7 @@ class GuildChannel:
@property @property
def created_at(self): def created_at(self):
"""Returns the channel's creation time in UTC.""" """:class:`datetime.datetime`: Returns the channel's creation time in UTC."""
return utils.snowflake_time(self.id) return utils.snowflake_time(self.id)
def overwrites_for(self, obj): def overwrites_for(self, obj):
@ -317,13 +317,13 @@ class GuildChannel:
Parameters Parameters
----------- -----------
obj obj: Union[:class:`~discord.Role`, :class:`~discord.abc.User`]
The :class:`Role` or :class:`abc.User` denoting The role or user denoting
whose overwrite to get. whose overwrite to get.
Returns Returns
--------- ---------
:class:`PermissionOverwrite` :class:`~discord.PermissionOverwrite`
The permission overwrites for this object. The permission overwrites for this object.
""" """
@ -347,12 +347,12 @@ class GuildChannel:
"""Returns all of the channel's overwrites. """Returns all of the channel's overwrites.
This is returned as a dictionary where the key contains the target which This is returned as a dictionary where the key contains the target which
can be either a :class:`Role` or a :class:`Member` and the value is the can be either a :class:`~discord.Role` or a :class:`~discord.Member` and the key is the
overwrite as a :class:`PermissionOverwrite`. overwrite as a :class:`~discord.PermissionOverwrite`.
Returns Returns
-------- --------
Mapping[Union[:class:`Role`, :class:`Member`], :class:`PermissionOverwrite`]: Mapping[Union[:class:`~discord.Role`, :class:`~discord.Member`], :class:`~discord.PermissionOverwrite`]
The channel's permission overwrites. The channel's permission overwrites.
""" """
ret = {} ret = {}
@ -377,14 +377,14 @@ class GuildChannel:
@property @property
def category(self): def category(self):
"""Optional[:class:`CategoryChannel`]: The category this channel belongs to. """Optional[:class:`~discord.CategoryChannel`]: The category this channel belongs to.
If there is no category then this is ``None``. If there is no category then this is ``None``.
""" """
return self.guild.get_channel(self.category_id) return self.guild.get_channel(self.category_id)
def permissions_for(self, member): def permissions_for(self, member):
"""Handles permission resolution for the current :class:`Member`. """Handles permission resolution for the current :class:`~discord.Member`.
This function takes into consideration the following cases: This function takes into consideration the following cases:
@ -395,12 +395,12 @@ class GuildChannel:
Parameters Parameters
---------- ----------
member: :class:`Member` member: :class:`~discord.Member`
The member to resolve permissions for. The member to resolve permissions for.
Returns Returns
------- -------
:class:`Permissions` :class:`~discord.Permissions`
The resolved permissions for the member. The resolved permissions for the member.
""" """
@ -500,11 +500,11 @@ class GuildChannel:
Raises Raises
------- -------
Forbidden :exc:`~discord.Forbidden`
You do not have proper permissions to delete the channel. You do not have proper permissions to delete the channel.
NotFound :exc:`~discord.NotFound`
The channel was not found or was already deleted. The channel was not found or was already deleted.
HTTPException :exc:`~discord.HTTPException`
Deleting the channel failed. Deleting the channel failed.
""" """
await self._state.http.delete_channel(self.id, reason=reason) await self._state.http.delete_channel(self.id, reason=reason)
@ -515,19 +515,19 @@ class GuildChannel:
Sets the channel specific permission overwrites for a target in the Sets the channel specific permission overwrites for a target in the
channel. channel.
The ``target`` parameter should either be a :class:`Member` or a The ``target`` parameter should either be a :class:`~discord.Member` or a
:class:`Role` that belongs to guild. :class:`~discord.Role` that belongs to guild.
The ``overwrite`` parameter, if given, must either be ``None`` or The ``overwrite`` parameter, if given, must either be ``None`` or
:class:`PermissionOverwrite`. For convenience, you can pass in :class:`~discord.PermissionOverwrite`. For convenience, you can pass in
keyword arguments denoting :class:`Permissions` attributes. If this is keyword arguments denoting :class:`~discord.Permissions` attributes. If this is
done, then you cannot mix the keyword arguments with the ``overwrite`` done, then you cannot mix the keyword arguments with the ``overwrite``
parameter. parameter.
If the ``overwrite`` parameter is ``None``, then the permission If the ``overwrite`` parameter is ``None``, then the permission
overwrites are deleted. overwrites are deleted.
You must have the :attr:`~Permissions.manage_roles` permission to use this. You must have the :attr:`~.Permissions.manage_roles` permission to use this.
Examples Examples
---------- ----------
@ -541,7 +541,7 @@ class GuildChannel:
await channel.set_permissions(member, overwrite=None) await channel.set_permissions(member, overwrite=None)
Using :class:`PermissionOverwrite` :: Using :class:`~discord.PermissionOverwrite` ::
overwrite = discord.PermissionOverwrite() overwrite = discord.PermissionOverwrite()
overwrite.send_messages = False overwrite.send_messages = False
@ -550,9 +550,9 @@ class GuildChannel:
Parameters Parameters
----------- -----------
target target: Union[:class:`~discord.Member`, :class:`~discord.Role`]
The :class:`Member` or :class:`Role` to overwrite permissions for. The member or role to overwrite permissions for.
overwrite: :class:`PermissionOverwrite` overwrite: :class:`~discord.PermissionOverwrite`
The permissions to allow and deny to the target. The permissions to allow and deny to the target.
\*\*permissions \*\*permissions
A keyword argument list of permissions to set for ease of use. A keyword argument list of permissions to set for ease of use.
@ -562,15 +562,15 @@ class GuildChannel:
Raises Raises
------- -------
Forbidden :exc:`~discord.Forbidden`
You do not have permissions to edit channel specific permissions. You do not have permissions to edit channel specific permissions.
HTTPException :exc:`~discord.HTTPException`
Editing channel specific permissions failed. Editing channel specific permissions failed.
NotFound :exc:`~discord.NotFound`
The role or member being edited is not part of the guild. The role or member being edited is not part of the guild.
InvalidArgument :exc:`~discord.InvalidArgument`
The overwrite parameter invalid or the target type was not The overwrite parameter invalid or the target type was not
:class:`Role` or :class:`Member`. :class:`~discord.Role` or :class:`~discord.Member`.
""" """
http = self._state.http http = self._state.http
@ -636,9 +636,9 @@ class GuildChannel:
Raises Raises
------- -------
Forbidden :exc:`~discord.Forbidden`
You do not have the proper permissions to create this channel. You do not have the proper permissions to create this channel.
HTTPException :exc:`~discord.HTTPException`
Creating the channel failed. Creating the channel failed.
""" """
raise NotImplementedError raise NotImplementedError
@ -648,7 +648,7 @@ class GuildChannel:
Creates an instant invite. Creates an instant invite.
You must have :attr:`~.Permissions.create_instant_invite` permission to You must have the :attr:`~.Permissions.create_instant_invite` permission to
do this. do this.
Parameters Parameters
@ -661,22 +661,22 @@ class GuildChannel:
are unlimited uses. Defaults to 0. are unlimited uses. Defaults to 0.
temporary: :class:`bool` temporary: :class:`bool`
Denotes that the invite grants temporary membership Denotes that the invite grants temporary membership
(i.e. they get kicked after they disconnect). Defaults to False. (i.e. they get kicked after they disconnect). Defaults to ``False``.
unique: :class:`bool` unique: :class:`bool`
Indicates if a unique invite URL should be created. Defaults to True. Indicates if a unique invite URL should be created. Defaults to True.
If this is set to False then it will return a previously created If this is set to ``False`` then it will return a previously created
invite. invite.
reason: Optional[:class:`str`] reason: Optional[:class:`str`]
The reason for creating this invite. Shows up on the audit log. The reason for creating this invite. Shows up on the audit log.
Raises Raises
------- -------
HTTPException :exc:`~discord.HTTPException`
Invite creation failed. Invite creation failed.
Returns Returns
-------- --------
:class:`Invite` :class:`~discord.Invite`
The invite that was created. The invite that was created.
""" """
@ -692,14 +692,14 @@ class GuildChannel:
Raises Raises
------- -------
Forbidden :exc:`~discord.Forbidden`
You do not have proper permissions to get the information. You do not have proper permissions to get the information.
HTTPException :exc:`~discord.HTTPException`
An error occurred while fetching the information. An error occurred while fetching the information.
Returns Returns
------- -------
List[:class:`Invite`] List[:class:`~discord.Invite`]
The list of invites that are currently active. The list of invites that are currently active.
""" """
@ -719,14 +719,14 @@ class Messageable(metaclass=abc.ABCMeta):
The following implement this ABC: The following implement this ABC:
- :class:`TextChannel` - :class:`~discord.TextChannel`
- :class:`DMChannel` - :class:`~discord.DMChannel`
- :class:`GroupChannel` - :class:`~discord.GroupChannel`
- :class:`User` - :class:`~discord.User`
- :class:`Member` - :class:`~discord.Member`
- :class:`~ext.commands.Context` - :class:`~discord.ext.commands.Context`
This ABC must also implement :class:`abc.Snowflake`. This ABC must also implement :class:`~discord.abc.Snowflake`.
""" """
__slots__ = () __slots__ = ()
@ -745,24 +745,24 @@ class Messageable(metaclass=abc.ABCMeta):
be provided. be provided.
To upload a single file, the ``file`` parameter should be used with a To upload a single file, the ``file`` parameter should be used with a
single :class:`.File` object. To upload multiple files, the ``files`` single :class:`~discord.File` object. To upload multiple files, the ``files``
parameter should be used with a :class:`list` of :class:`.File` objects. parameter should be used with a :class:`list` of :class:`~discord.File` objects.
**Specifying both parameters will lead to an exception**. **Specifying both parameters will lead to an exception**.
If the ``embed`` parameter is provided, it must be of type :class:`.Embed` and If the ``embed`` parameter is provided, it must be of type :class:`~discord.Embed` and
it must be a rich embed type. it must be a rich embed type.
Parameters Parameters
------------ ------------
content content: :class:`str`
The content of the message to send. The content of the message to send.
tts: :class:`bool` tts: :class:`bool`
Indicates if the message should be sent using text-to-speech. Indicates if the message should be sent using text-to-speech.
embed: :class:`.Embed` embed: :class:`~discord.Embed`
The rich embed for the content. The rich embed for the content.
file: :class:`.File` file: :class:`~discord.File`
The file to upload. The file to upload.
files: List[:class:`.File`] files: List[:class:`~discord.File`]
A list of files to upload. Must be a maximum of 10. A list of files to upload. Must be a maximum of 10.
nonce: :class:`int` nonce: :class:`int`
The nonce to use for sending this message. If the message was successfully sent, The nonce to use for sending this message. If the message was successfully sent,
@ -774,17 +774,17 @@ class Messageable(metaclass=abc.ABCMeta):
Raises Raises
-------- --------
:exc:`.HTTPException` :exc:`~discord.HTTPException`
Sending the message failed. Sending the message failed.
:exc:`.Forbidden` :exc:`~discord.Forbidden`
You do not have the proper permissions to send the message. You do not have the proper permissions to send the message.
:exc:`.InvalidArgument` :exc:`~discord.InvalidArgument`
The ``files`` list is not of the appropriate size or The ``files`` list is not of the appropriate size or
you specified both ``file`` and ``files``. you specified both ``file`` and ``files``.
Returns Returns
--------- ---------
:class:`.Message` :class:`~discord.Message`
The message that was sent. The message that was sent.
""" """
@ -860,7 +860,7 @@ class Messageable(metaclass=abc.ABCMeta):
async def fetch_message(self, id): async def fetch_message(self, id):
"""|coro| """|coro|
Retrieves a single :class:`.Message` from the destination. Retrieves a single :class:`~discord.Message` from the destination.
This can only be used by bot accounts. This can only be used by bot accounts.
@ -871,16 +871,16 @@ class Messageable(metaclass=abc.ABCMeta):
Raises Raises
-------- --------
:exc:`.NotFound` :exc:`~discord.NotFound`
The specified message was not found. The specified message was not found.
:exc:`.Forbidden` :exc:`~discord.Forbidden`
You do not have the permissions required to get a message. You do not have the permissions required to get a message.
:exc:`.HTTPException` :exc:`~discord.HTTPException`
Retrieving the message failed. Retrieving the message failed.
Returns Returns
-------- --------
:class:`.Message` :class:`~discord.Message`
The message asked for. The message asked for.
""" """
@ -891,7 +891,7 @@ class Messageable(metaclass=abc.ABCMeta):
async def pins(self): async def pins(self):
"""|coro| """|coro|
Returns a :class:`list` of :class:`.Message` that are currently pinned. Retrieves all messages that are currently pinned in the channel.
.. note:: .. note::
@ -901,8 +901,13 @@ class Messageable(metaclass=abc.ABCMeta):
Raises Raises
------- -------
:exc:`.HTTPException` :exc:`~discord.HTTPException`
Retrieving the pinned messages failed. Retrieving the pinned messages failed.
Returns
--------
List[:class:`~discord.Message`]
The messages that are currently pinned.
""" """
channel = await self._get_channel() channel = await self._get_channel()
@ -911,7 +916,7 @@ class Messageable(metaclass=abc.ABCMeta):
return [state.create_message(channel=channel, data=m) for m in data] return [state.create_message(channel=channel, data=m) for m in data]
def history(self, *, limit=100, before=None, after=None, around=None, oldest_first=None): def history(self, *, limit=100, before=None, after=None, around=None, oldest_first=None):
"""Returns an :class:`.AsyncIterator` that enables receiving the destination's message history. """Returns an :class:`~discord.AsyncIterator` that enables receiving the destination's message history.
You must have :attr:`~.Permissions.read_message_history` permissions to use this. You must have :attr:`~.Permissions.read_message_history` permissions to use this.
@ -938,31 +943,31 @@ class Messageable(metaclass=abc.ABCMeta):
The number of messages to retrieve. The number of messages to retrieve.
If ``None``, retrieves every message in the channel. Note, however, If ``None``, retrieves every message in the channel. Note, however,
that this would make it a slow operation. that this would make it a slow operation.
before: :class:`.Message` or :class:`datetime.datetime` before: Optional[Union[:class:`~discord.abc.Snowflake`, :class:`datetime.datetime`]]
Retrieve messages before this date or message. Retrieve messages before this date or message.
If a date is provided it must be a timezone-naive datetime representing UTC time. If a date is provided it must be a timezone-naive datetime representing UTC time.
after: :class:`.Message` or :class:`datetime.datetime` after: Optional[Union[:class:`~discord.abc.Snowflake`, :class:`datetime.datetime`]]
Retrieve messages after this date or message. Retrieve messages after this date or message.
If a date is provided it must be a timezone-naive datetime representing UTC time. If a date is provided it must be a timezone-naive datetime representing UTC time.
around: :class:`.Message` or :class:`datetime.datetime` around: Optional[Union[:class:`~discord.abc.Snowflake`, :class:`datetime.datetime`]]
Retrieve messages around this date or message. Retrieve messages around this date or message.
If a date is provided it must be a timezone-naive datetime representing UTC time. If a date is provided it must be a timezone-naive datetime representing UTC time.
When using this argument, the maximum limit is 101. Note that if the limit is an When using this argument, the maximum limit is 101. Note that if the limit is an
even number then this will return at most limit + 1 messages. even number then this will return at most limit + 1 messages.
oldest_first: Optional[:class:`bool`] oldest_first: Optional[:class:`bool`]
If set to true, return messages in oldest->newest order. Defaults to True if If set to ``True``, return messages in oldest->newest order. Defaults to ``True`` if
``after`` is specified, otherwise False. ``after`` is specified, otherwise ``False``.
Raises Raises
------ ------
:exc:`.Forbidden` :exc:`~discord.Forbidden`
You do not have permissions to get channel message history. You do not have permissions to get channel message history.
:exc:`.HTTPException` :exc:`~discord.HTTPException`
The request to get message history failed. The request to get message history failed.
Yields Yields
------- -------
:class:`.Message` :class:`~discord.Message`
The message with the message data parsed. The message with the message data parsed.
""" """
return HistoryIterator(self, limit=limit, before=before, after=after, around=around, oldest_first=oldest_first) return HistoryIterator(self, limit=limit, before=before, after=after, around=around, oldest_first=oldest_first)
@ -974,7 +979,7 @@ class Connectable(metaclass=abc.ABCMeta):
The following implement this ABC: The following implement this ABC:
- :class:`VoiceChannel` - :class:`~discord.VoiceChannel`
""" """
__slots__ = () __slots__ = ()
@ -1003,16 +1008,16 @@ class Connectable(metaclass=abc.ABCMeta):
Raises Raises
------- -------
asyncio.TimeoutError :exc:`asyncio.TimeoutError`
Could not connect to the voice channel in time. Could not connect to the voice channel in time.
ClientException :exc:`~discord.ClientException`
You are already connected to a voice channel. You are already connected to a voice channel.
OpusNotLoaded :exc:`~discord.opus.OpusNotLoaded`
The opus library has not been loaded. The opus library has not been loaded.
Returns Returns
------- --------
:class:`VoiceClient` :class:`~discord.VoiceClient`
A voice client that is fully connected to the voice server. A voice client that is fully connected to the voice server.
""" """
key_id, _ = self._get_voice_client_key() key_id, _ = self._get_voice_client_key()

7
discord/asset.py
View File

@ -163,6 +163,13 @@ class Asset:
.. versionadded:: 1.1.0 .. versionadded:: 1.1.0
Parameters
-----------
fp: Union[:class:`io.BufferedIOBase`, :class:`os.PathLike`]
Same as in :meth:`Attachment.save`.
seek_begin: :class:`bool`
Same as in :meth:`Attachment.save`.
Raises Raises
------ ------
DiscordException DiscordException

2
discord/audit_logs.py
View File

@ -269,7 +269,7 @@ class AuditLogEntry:
@utils.cached_property @utils.cached_property
def created_at(self): def created_at(self):
"""Returns the entry's creation time in UTC.""" """:class:`datetime.datetime`: Returns the entry's creation time in UTC."""
return utils.snowflake_time(self.id) return utils.snowflake_time(self.id)
@utils.cached_property @utils.cached_property

2
discord/backoff.py
View File

@ -45,7 +45,7 @@ class ExponentialBackoff:
The base delay in seconds. The first retry-delay will be up to The base delay in seconds. The first retry-delay will be up to
this many seconds. this many seconds.
integral: :class:`bool` integral: :class:`bool`
Set to True if whole periods of base is desirable, otherwise any Set to ``True`` if whole periods of base is desirable, otherwise any
number in between may be returned. number in between may be returned.
""" """

6
discord/calls.py
View File

@ -38,7 +38,7 @@ class CallMessage:
Attributes Attributes
----------- -----------
ended_timestamp: Optional[datetime.datetime] ended_timestamp: Optional[:class:`datetime.datetime`]
A naive UTC datetime object that represents the time that the call has ended. A naive UTC datetime object that represents the time that the call has ended.
participants: List[:class:`User`] participants: List[:class:`User`]
The list of users that are participating in this call. The list of users that are participating in this call.
@ -70,7 +70,7 @@ class CallMessage:
Returns Returns
--------- ---------
datetime.timedelta :class:`datetime.timedelta`
The timedelta object representing the duration. The timedelta object representing the duration.
""" """
if self.ended_timestamp is None: if self.ended_timestamp is None:
@ -122,7 +122,7 @@ class GroupCall:
@property @property
def connected(self): def connected(self):
"""A property that returns the :class:`list` of :class:`User` that are currently in this call.""" """List[:class:`User`]: A property that returns all users that are currently in this call."""
ret = [u for u in self.channel.recipients if self.voice_state_for(u) is not None] ret = [u for u in self.channel.recipients if self.voice_state_for(u) is not None]
me = self.channel.me me = self.channel.me
if self.voice_state_for(me) is not None: if self.voice_state_for(me) is not None:

36
discord/channel.py
View File

@ -149,7 +149,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
@property @property
def members(self): def members(self):
"""Returns a :class:`list` of :class:`Member` that can see this channel.""" """List[:class:`Member`]: Returns all members that can see this channel."""
return [m for m in self.guild.members if self.permissions_for(m).read_messages] return [m for m in self.guild.members if self.permissions_for(m).read_messages]
def is_nsfw(self): def is_nsfw(self):
@ -313,22 +313,22 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
limit: Optional[:class:`int`] limit: Optional[:class:`int`]
The number of messages to search through. This is not the number The number of messages to search through. This is not the number
of messages that will be deleted, though it can be. of messages that will be deleted, though it can be.
check: predicate check: Callable[[:class:`Message`], :class:`bool`]
The function used to check if a message should be deleted. The function used to check if a message should be deleted.
It must take a :class:`Message` as its sole parameter. It must take a :class:`Message` as its sole parameter.
before before: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
Same as ``before`` in :meth:`history`. Same as ``before`` in :meth:`history`.
after after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
Same as ``after`` in :meth:`history`. Same as ``after`` in :meth:`history`.
around around: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
Same as ``around`` in :meth:`history`. Same as ``around`` in :meth:`history`.
oldest_first oldest_first: Optional[:class:`bool`]
Same as ``oldest_first`` in :meth:`history`. Same as ``oldest_first`` in :meth:`history`.
bulk: :class:`bool` bulk: class:`bool`
If True, use bulk delete. bulk=False is useful for mass-deleting If ``True``, use bulk delete. Setting this to ``False`` is useful for mass-deleting
a bot's own messages without manage_messages. When True, will fall a bot's own messages without :attr:`Permissions.manage_messages`. When ``True``, will
back to single delete if current account is a user bot, or if fall back to single delete if current account is a user bot, or if messages are
messages are older than two weeks. older than two weeks.
Raises Raises
------- -------
@ -534,7 +534,7 @@ class VoiceChannel(discord.abc.Connectable, discord.abc.GuildChannel, Hashable):
@property @property
def members(self): def members(self):
"""Returns a list of :class:`Member` that are currently inside this voice channel.""" """List[:class:`Member`]: Returns all members that are currently inside this voice channel."""
ret = [] ret = []
for user_id, state in self.guild._voice_states.items(): for user_id, state in self.guild._voice_states.items():
if state.channel.id == self.id: if state.channel.id == self.id:
@ -943,10 +943,10 @@ class DMChannel(discord.abc.Messageable, Hashable):
Actual direct messages do not really have the concept of permissions. Actual direct messages do not really have the concept of permissions.
This returns all the Text related permissions set to true except: This returns all the Text related permissions set to ``True`` except:
- send_tts_messages: You cannot send TTS messages in a DM. - :attr:`~Permissions.send_tts_messages`: You cannot send TTS messages in a DM.
- manage_messages: You cannot delete others messages in a DM. - :attr:`~Permissions.manage_messages`: You cannot delete others messages in a DM.
Parameters Parameters
----------- -----------
@ -988,7 +988,7 @@ class GroupChannel(discord.abc.Messageable, Hashable):
Attributes Attributes
---------- ----------
recipients: :class:`list` of :class:`User` recipients: List[:class:`User`]
The users you are participating with in the group channel. The users you are participating with in the group channel.
me: :class:`ClientUser` me: :class:`ClientUser`
The user presenting yourself. The user presenting yourself.
@ -1051,7 +1051,7 @@ class GroupChannel(discord.abc.Messageable, Hashable):
@property @property
def created_at(self): def created_at(self):
"""Returns the channel's creation time in UTC.""" """:class:`datetime.datetime`: Returns the channel's creation time in UTC."""
return utils.snowflake_time(self.id) return utils.snowflake_time(self.id)
def permissions_for(self, user): def permissions_for(self, user):
@ -1061,7 +1061,7 @@ class GroupChannel(discord.abc.Messageable, Hashable):
Actual direct messages do not really have the concept of permissions. Actual direct messages do not really have the concept of permissions.
This returns all the Text related permissions set to true except: This returns all the Text related permissions set to ``True`` except:
- send_tts_messages: You cannot send TTS messages in a DM. - send_tts_messages: You cannot send TTS messages in a DM.
- manage_messages: You cannot delete others messages in a DM. - manage_messages: You cannot delete others messages in a DM.

170
discord/client.py
View File

@ -122,7 +122,7 @@ class Client:
----------- -----------
max_messages: Optional[:class:`int`] max_messages: Optional[:class:`int`]
The maximum number of messages to store in the internal message cache. The maximum number of messages to store in the internal message cache.
This defaults to 5000. Passing in `None` or a value less than 100 This defaults to 5000. Passing in ``None`` or a value less than 100
will use the default instead of the passed in value. will use the default instead of the passed in value.
loop: Optional[:class:`asyncio.AbstractEventLoop`] loop: Optional[:class:`asyncio.AbstractEventLoop`]
The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations. The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations.
@ -135,11 +135,11 @@ class Client:
proxy_auth: Optional[:class:`aiohttp.BasicAuth`] proxy_auth: Optional[:class:`aiohttp.BasicAuth`]
An object that represents proxy HTTP Basic Authorization. An object that represents proxy HTTP Basic Authorization.
shard_id: Optional[:class:`int`] shard_id: Optional[:class:`int`]
Integer starting at 0 and less than shard_count. Integer starting at 0 and less than :attr:`.shard_count`.
shard_count: Optional[:class:`int`] shard_count: Optional[:class:`int`]
The total number of shards. The total number of shards.
fetch_offline_members: :class:`bool` fetch_offline_members: :class:`bool`
Indicates if :func:`on_ready` should be delayed to fetch all offline Indicates if :func:`.on_ready` should be delayed to fetch all offline
members from the guilds the bot belongs to. If this is ``False``\, then members from the guilds the bot belongs to. If this is ``False``\, then
no offline members are received and :meth:`request_offline_members` no offline members are received and :meth:`request_offline_members`
must be used to fetch the offline members of the guild. must be used to fetch the offline members of the guild.
@ -156,7 +156,7 @@ class Client:
Attributes Attributes
----------- -----------
ws ws
The websocket gateway the client is currently connected to. Could be None. The websocket gateway the client is currently connected to. Could be ``None``.
loop: :class:`asyncio.AbstractEventLoop` loop: :class:`asyncio.AbstractEventLoop`
The event loop that the client uses for HTTP requests and websocket operations. The event loop that the client uses for HTTP requests and websocket operations.
""" """
@ -239,7 +239,7 @@ class Client:
@property @property
def cached_messages(self): def cached_messages(self):
"""Sequence[:class:`~discord.Message`]: Read-only list of messages the connected client has cached. """Sequence[:class:`.Message`]: Read-only list of messages the connected client has cached.
.. versionadded:: 1.1.0 .. versionadded:: 1.1.0
""" """
@ -247,7 +247,7 @@ class Client:
@property @property
def private_channels(self): def private_channels(self):
"""List[:class:`abc.PrivateChannel`]: The private channels that the connected client is participating on. """List[:class:`.abc.PrivateChannel`]: The private channels that the connected client is participating on.
.. note:: .. note::
@ -262,7 +262,7 @@ class Client:
return self._connection.voice_clients return self._connection.voice_clients
def is_ready(self): def is_ready(self):
""":class:`bool`: Specifies if the client's internal cache is ready for use.""" """Specifies if the client's internal cache is ready for use."""
return self._ready.is_set() return self._ready.is_set()
async def _run_event(self, coro, event_name, *args, **kwargs): async def _run_event(self, coro, event_name, *args, **kwargs):
@ -328,7 +328,7 @@ class Client:
By default this prints to :data:`sys.stderr` however it could be By default this prints to :data:`sys.stderr` however it could be
overridden to have a different implementation. overridden to have a different implementation.
Check :func:`discord.on_error` for more details. Check :func:`~discord.on_error` for more details.
""" """
print('Ignoring exception in {}'.format(event_method), file=sys.stderr) print('Ignoring exception in {}'.format(event_method), file=sys.stderr)
traceback.print_exc() traceback.print_exc()
@ -348,12 +348,12 @@ class Client:
Parameters Parameters
----------- -----------
\*guilds: :class:`Guild` \*guilds: :class:`.Guild`
An argument list of guilds to request offline members for. An argument list of guilds to request offline members for.
Raises Raises
------- -------
InvalidArgument :exc:`.InvalidArgument`
If any guild is unavailable or not large in the collection. If any guild is unavailable or not large in the collection.
""" """
if any(not g.large or g.unavailable for g in guilds): if any(not g.large or g.unavailable for g in guilds):
@ -388,9 +388,9 @@ class Client:
Raises Raises
------ ------
LoginFailure :exc:`.LoginFailure`
The wrong credentials are passed. The wrong credentials are passed.
HTTPException :exc:`.HTTPException`
An unknown HTTP related error occurred, An unknown HTTP related error occurred,
usually when it isn't 200 or the known incorrect credentials usually when it isn't 200 or the known incorrect credentials
passing status code. passing status code.
@ -444,10 +444,10 @@ class Client:
Raises Raises
------- -------
GatewayNotFound :exc:`.GatewayNotFound`
If the gateway to connect to discord is not found. Usually if this If the gateway to connect to discord is not found. Usually if this
is thrown then there is a discord API outage. is thrown then there is a discord API outage.
ConnectionClosed :exc:`.ConnectionClosed`
The websocket connection has been terminated. The websocket connection has been terminated.
""" """
@ -514,8 +514,8 @@ class Client:
def clear(self): def clear(self):
"""Clears the internal state of the bot. """Clears the internal state of the bot.
After this, the bot can be considered "re-opened", i.e. :meth:`.is_closed` After this, the bot can be considered "re-opened", i.e. :meth:`is_closed`
and :meth:`.is_ready` both return ``False`` along with the bot's internal and :meth:`is_ready` both return ``False`` along with the bot's internal
cache cleared. cache cleared.
""" """
self._closed = False self._closed = False
@ -533,7 +533,6 @@ class Client:
TypeError TypeError
An unexpected keyword argument was received. An unexpected keyword argument was received.
""" """
bot = kwargs.pop('bot', True) bot = kwargs.pop('bot', True)
reconnect = kwargs.pop('reconnect', True) reconnect = kwargs.pop('reconnect', True)
@ -598,12 +597,14 @@ class Client:
# properties # properties
def is_closed(self): def is_closed(self):
""":class:`bool`: Indicates if the websocket connection is closed.""" """Indicates if the websocket connection is closed."""
return self._closed return self._closed
@property @property
def activity(self): def activity(self):
"""Optional[Union[:class:`.Activity`, :class:`.Game`, :class:`.Streaming`]]: The activity being used upon logging in.""" """Optional[Union[:class:`.Activity`, :class:`.Game`, :class:`.Streaming`]]: The activity being used upon
logging in.
"""
return create_activity(self._connection._activity) return create_activity(self._connection._activity)
@activity.setter @activity.setter
@ -619,26 +620,36 @@ class Client:
@property @property
def users(self): def users(self):
"""Returns a :class:`list` of all the :class:`User` the bot can see.""" """List[:class:`~discord.User`]: Returns a list of all the users the bot can see."""
return list(self._connection._users.values()) return list(self._connection._users.values())
def get_channel(self, id): def get_channel(self, id):
"""Returns a :class:`.abc.GuildChannel` or :class:`.abc.PrivateChannel` with the following ID. """Optional[Union[:class:`.abc.GuildChannel`, :class:`.abc.PrivateChannel`]]: Returns a channel with the
given ID.
If not found, returns None. If not found, returns ``None``.
""" """
return self._connection.get_channel(id) return self._connection.get_channel(id)
def get_guild(self, id): def get_guild(self, id):
"""Returns a :class:`.Guild` with the given ID. If not found, returns None.""" """Optional[:class:`.Guild`]: Returns a guild with the given ID.
If not found, returns ``None``.
"""
return self._connection._get_guild(id) return self._connection._get_guild(id)
def get_user(self, id): def get_user(self, id):
"""Returns a :class:`~discord.User` with the given ID. If not found, returns None.""" """Optional[:class:`~discord.User`]: Returns a user with the given ID.
If not found, returns ``None``.
"""
return self._connection.get_user(id) return self._connection.get_user(id)
def get_emoji(self, id): def get_emoji(self, id):
"""Returns a :class:`.Emoji` with the given ID. If not found, returns None.""" """Optional[:class:`.Emoji`]: Returns an emoji with the given ID.
If not found, returns ``None``.
"""
return self._connection.get_emoji(id) return self._connection.get_emoji(id)
def get_all_channels(self): def get_all_channels(self):
@ -669,7 +680,6 @@ class Client:
for guild in client.guilds: for guild in client.guilds:
for member in guild.members: for member in guild.members:
yield member yield member
""" """
for guild in self.guilds: for guild in self.guilds:
for member in guild.members: for member in guild.members:
@ -746,7 +756,7 @@ class Client:
event: :class:`str` event: :class:`str`
The event name, similar to the :ref:`event reference <discord-api-events>`, The event name, similar to the :ref:`event reference <discord-api-events>`,
but without the ``on_`` prefix, to wait for. but without the ``on_`` prefix, to wait for.
check: Optional[predicate] check: Optional[Callable[..., :class:`bool`]]
A predicate to check what to wait for. The arguments must meet the A predicate to check what to wait for. The arguments must meet the
parameters of the event being waited for. parameters of the event being waited for.
timeout: Optional[:class:`float`] timeout: Optional[:class:`float`]
@ -789,7 +799,7 @@ class Client:
You can find more info about the events on the :ref:`documentation below <discord-api-events>`. You can find more info about the events on the :ref:`documentation below <discord-api-events>`.
The events must be a |corourl|_, if not, :exc:`TypeError` is raised. The events must be a :ref:`coroutine <coroutine>`, if not, :exc:`TypeError` is raised.
Example Example
--------- ---------
@ -835,16 +845,16 @@ class Client:
activity: Optional[Union[:class:`.Game`, :class:`.Streaming`, :class:`.Activity`]] activity: Optional[Union[:class:`.Game`, :class:`.Streaming`, :class:`.Activity`]]
The activity being done. ``None`` if no currently active activity is done. The activity being done. ``None`` if no currently active activity is done.
status: Optional[:class:`.Status`] status: Optional[:class:`.Status`]
Indicates what status to change to. If None, then Indicates what status to change to. If ``None``, then
:attr:`.Status.online` is used. :attr:`.Status.online` is used.
afk: :class:`bool` afk: Optional[:class:`bool`]
Indicates if you are going AFK. This allows the discord Indicates if you are going AFK. This allows the discord
client to know how to handle push notifications better client to know how to handle push notifications better
for you in case you are actually idle and not lying. for you in case you are actually idle and not lying.
Raises Raises
------ ------
InvalidArgument :exc:`.InvalidArgument`
If the ``activity`` parameter is not the proper type. If the ``activity`` parameter is not the proper type.
""" """
@ -884,32 +894,6 @@ class Client:
This method is an API call. For general usage, consider :attr:`guilds` instead. This method is an API call. For general usage, consider :attr:`guilds` instead.
All parameters are optional.
Parameters
-----------
limit: Optional[:class:`int`]
The number of guilds to retrieve.
If ``None``, it retrieves every guild you have access to. Note, however,
that this would make it a slow operation.
Defaults to 100.
before: :class:`.abc.Snowflake` or :class:`datetime.datetime`
Retrieves guilds before this date or object.
If a date is provided it must be a timezone-naive datetime representing UTC time.
after: :class:`.abc.Snowflake` or :class:`datetime.datetime`
Retrieve guilds after this date or object.
If a date is provided it must be a timezone-naive datetime representing UTC time.
Raises
------
HTTPException
Getting the guilds failed.
Yields
--------
:class:`.Guild`
The guild with the guild data parsed.
Examples Examples
--------- ---------
@ -922,6 +906,32 @@ class Client:
guilds = await client.fetch_guilds(limit=150).flatten() guilds = await client.fetch_guilds(limit=150).flatten()
# guilds is now a list of Guild... # guilds is now a list of Guild...
All parameters are optional.
Parameters
-----------
limit: Optional[:class:`int`]
The number of guilds to retrieve.
If ``None``, it retrieves every guild you have access to. Note, however,
that this would make it a slow operation.
Defaults to 100.
before: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]
Retrieves guilds before this date or object.
If a date is provided it must be a timezone-naive datetime representing UTC time.
after: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]
Retrieve guilds after this date or object.
If a date is provided it must be a timezone-naive datetime representing UTC time.
Raises
------
:exc:`.HTTPException`
Getting the guilds failed.
Yields
--------
:class:`.Guild`
The guild with the guild data parsed.
""" """
return GuildIterator(self, limit=limit, before=before, after=after) return GuildIterator(self, limit=limit, before=before, after=after)
@ -932,7 +942,7 @@ class Client:
.. note:: .. note::
Using this, you will not receive :attr:`.Guild.channels`, :class:`.Guild.members`, Using this, you will **not** receive :attr:`.Guild.channels`, :class:`.Guild.members`,
:attr:`.Member.activity` and :attr:`.Member.voice` per :class:`.Member`. :attr:`.Member.activity` and :attr:`.Member.voice` per :class:`.Member`.
.. note:: .. note::
@ -946,9 +956,9 @@ class Client:
Raises Raises
------ ------
Forbidden :exc:`.Forbidden`
You do not have access to the guild. You do not have access to the guild.
HTTPException :exc:`.HTTPException`
Getting the guild failed. Getting the guild failed.
Returns Returns
@ -970,7 +980,7 @@ class Client:
---------- ----------
name: :class:`str` name: :class:`str`
The name of the guild. The name of the guild.
region: :class:`VoiceRegion` region: :class:`.VoiceRegion`
The region for the voice communication server. The region for the voice communication server.
Defaults to :attr:`.VoiceRegion.us_west`. Defaults to :attr:`.VoiceRegion.us_west`.
icon: :class:`bytes` icon: :class:`bytes`
@ -979,9 +989,9 @@ class Client:
Raises Raises
------ ------
HTTPException :exc:`.HTTPException`
Guild creation failed. Guild creation failed.
InvalidArgument :exc:`.InvalidArgument`
Invalid icon image format given. Must be PNG or JPG. Invalid icon image format given. Must be PNG or JPG.
Returns Returns
@ -1025,9 +1035,9 @@ class Client:
Raises Raises
------- -------
NotFound :exc:`.NotFound`
The invite has expired or is invalid. The invite has expired or is invalid.
HTTPException :exc:`.HTTPException`
Getting the invite failed. Getting the invite failed.
Returns Returns
@ -1055,11 +1065,11 @@ class Client:
Raises Raises
------- -------
Forbidden :exc:`.Forbidden`
You do not have permissions to revoke invites. You do not have permissions to revoke invites.
NotFound :exc:`.NotFound`
The invite is invalid or expired. The invite is invalid or expired.
HTTPException :exc:`.HTTPException`
Revoking the invite failed. Revoking the invite failed.
""" """
@ -1084,9 +1094,9 @@ class Client:
Raises Raises
------- -------
Forbidden :exc:`.Forbidden`
The widget for this guild is disabled. The widget for this guild is disabled.
HTTPException :exc:`.HTTPException`
Retrieving the widget failed. Retrieving the widget failed.
Returns Returns
@ -1101,17 +1111,17 @@ class Client:
async def application_info(self): async def application_info(self):
"""|coro| """|coro|
Retrieve's the bot's application information. Retrieves the bot's application information.
Raises Raises
------- -------
HTTPException :exc:`.HTTPException`
Retrieving the information failed somehow. Retrieving the information failed somehow.
Returns Returns
-------- --------
:class:`.AppInfo` :class:`.AppInfo`
A namedtuple representing the application info. The bot's application information.
""" """
data = await self.http.application_info() data = await self.http.application_info()
if 'rpc_origins' not in data: if 'rpc_origins' not in data:
@ -1137,9 +1147,9 @@ class Client:
Raises Raises
------- -------
NotFound :exc:`.NotFound`
A user with this ID does not exist. A user with this ID does not exist.
HTTPException :exc:`.HTTPException`
Fetching the user failed. Fetching the user failed.
Returns Returns
@ -1162,9 +1172,9 @@ class Client:
Raises Raises
------- -------
Forbidden :exc:`.Forbidden`
Not allowed to fetch profiles. Not allowed to fetch profiles.
HTTPException :exc:`.HTTPException`
Fetching the profile failed. Fetching the profile failed.
Returns Returns
@ -1237,11 +1247,11 @@ class Client:
Raises Raises
-------- --------
HTTPException :exc:`.HTTPException`
Retrieving the webhook failed. Retrieving the webhook failed.
NotFound :exc:`.NotFound`
Invalid webhook ID. Invalid webhook ID.
Forbidden :exc:`.Forbidden`
You do not have permission to fetch this webhook. You do not have permission to fetch this webhook.
Returns Returns

8
discord/colour.py
View File

@ -84,21 +84,21 @@ class Colour:
@property @property
def r(self): def r(self):
"""Returns the red component of the colour.""" """:class:`int`: Returns the red component of the colour."""
return self._get_byte(2) return self._get_byte(2)
@property @property
def g(self): def g(self):
"""Returns the green component of the colour.""" """:class:`int`: Returns the green component of the colour."""
return self._get_byte(1) return self._get_byte(1)
@property @property
def b(self): def b(self):
"""Returns the blue component of the colour.""" """:class:`int`: Returns the blue component of the colour."""
return self._get_byte(0) return self._get_byte(0)
def to_rgb(self): def to_rgb(self):
"""Returns an (r, g, b) tuple representing the colour.""" """Tuple[:class:`int`, :class:`int`, :class:`int`]: Returns an (r, g, b) tuple representing the colour."""
return (self.r, self.g, self.b) return (self.r, self.g, self.b)
@classmethod @classmethod

5
discord/embeds.py
View File

@ -87,10 +87,9 @@ class Embed:
url: :class:`str` url: :class:`str`
The URL of the embed. The URL of the embed.
This can be set during initialisation. This can be set during initialisation.
timestamp: `datetime.datetime` timestamp: :class:`datetime.datetime`
The timestamp of the embed content. This could be a naive or aware datetime. The timestamp of the embed content. This could be a naive or aware datetime.
This can be set during initialisation. colour: Union[:class:`Colour`, :class:`int`]
colour: :class:`Colour` or :class:`int`
The colour code of the embed. Aliased to ``color`` as well. The colour code of the embed. Aliased to ``color`` as well.
This can be set during initialisation. This can be set during initialisation.
Empty Empty

4
discord/emoji.py
View File

@ -222,12 +222,12 @@ class Emoji:
@property @property
def created_at(self): def created_at(self):
"""Returns the emoji's creation time in UTC.""" """:class:`datetime.datetime`: Returns the emoji's creation time in UTC."""
return utils.snowflake_time(self.id) return utils.snowflake_time(self.id)
@property @property
def url(self): def url(self):
"""Returns a URL version of the emoji.""" """:class:`Asset`: Returns the asset of the emoji."""
_format = 'gif' if self.animated else 'png' _format = 'gif' if self.animated else 'png'
url = "https://cdn.discordapp.com/emojis/{0.id}.{1}".format(self, _format) url = "https://cdn.discordapp.com/emojis/{0.id}.{1}".format(self, _format)
return Asset(self._state, url) return Asset(self._state, url)

8
discord/errors.py
View File

@ -72,12 +72,10 @@ class HTTPException(DiscordException):
Attributes Attributes
------------ ------------
response: aiohttp.ClientResponse response: :class:`aiohttp.ClientResponse`
The response of the failed HTTP request. This is an The response of the failed HTTP request. This is an
instance of `aiohttp.ClientResponse`__. In some cases instance of :class:`aiohttp.ClientResponse`. In some cases
this could also be a ``requests.Response``. this could also be a :class:`requests.Response`.
__ http://aiohttp.readthedocs.org/en/stable/client_reference.html#aiohttp.ClientResponse
text: :class:`str` text: :class:`str`
The text of the error. Could be an empty string. The text of the error. Could be an empty string.

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

@ -147,7 +147,7 @@ class BotBase(GroupMixin):
The default command error handler provided by the bot. The default command error handler provided by the bot.
By default this prints to ``sys.stderr`` however it could be By default this prints to :data:`sys.stderr` however it could be
overridden to have a different implementation. overridden to have a different implementation.
This only fires if you do not specify any listeners for command error. This only fires if you do not specify any listeners for command error.
@ -208,7 +208,7 @@ class BotBase(GroupMixin):
The function that was used as a global check. The function that was used as a global check.
call_once: :class:`bool` call_once: :class:`bool`
If the function should only be called once per If the function should only be called once per
:meth:`.Command.invoke` call. :meth:`Command.invoke` call.
""" """
if call_once: if call_once:
@ -241,7 +241,7 @@ class BotBase(GroupMixin):
r"""A decorator that adds a "call once" global check to the bot. r"""A decorator that adds a "call once" global check to the bot.
Unlike regular global checks, this one is called only once Unlike regular global checks, this one is called only once
per :meth:`.Command.invoke` call. per :meth:`Command.invoke` call.
Regular global checks are called whenever a command is called Regular global checks are called whenever a command is called
or :meth:`.Command.can_run` is called. This type of check or :meth:`.Command.can_run` is called. This type of check
@ -288,6 +288,11 @@ class BotBase(GroupMixin):
----------- -----------
user: :class:`.abc.User` user: :class:`.abc.User`
The user to check for. The user to check for.
Returns
--------
:class:`bool`
Whether the user is the owner.
""" """
if self.owner_id is None: if self.owner_id is None:
@ -314,7 +319,7 @@ class BotBase(GroupMixin):
Parameters Parameters
----------- -----------
coro coro: :ref:`coroutine <coroutine>`
The coroutine to register as the pre-invoke hook. The coroutine to register as the pre-invoke hook.
Raises Raises
@ -347,7 +352,7 @@ class BotBase(GroupMixin):
Parameters Parameters
----------- -----------
coro coro: :ref:`coroutine <coroutine>`
The coroutine to register as the post-invoke hook. The coroutine to register as the post-invoke hook.
Raises Raises
@ -420,7 +425,7 @@ class BotBase(GroupMixin):
event listener. Basically this allows you to listen to multiple event listener. Basically this allows you to listen to multiple
events from different places e.g. such as :func:`.on_ready` events from different places e.g. such as :func:`.on_ready`
The functions being listened to must be a coroutine. The functions being listened to must be a :ref:`coroutine <coroutine>`.
Example Example
-------- --------

2
discord/ext/commands/cog.py
View File

@ -34,7 +34,7 @@ __all__ = (
) )
class CogMeta(type): class CogMeta(type):
"""A　metaclass for defining a cog. """A metaclass for defining a cog.
Note that you should probably not use this directly. It is exposed Note that you should probably not use this directly. It is exposed
purely for documentation purposes along with making custom metaclasses to intermix purely for documentation purposes along with making custom metaclasses to intermix

6
discord/ext/commands/context.py
View File

@ -34,7 +34,7 @@ class Context(discord.abc.Messageable):
the invocation context. This class is not created manually and is instead the invocation context. This class is not created manually and is instead
passed around to commands as the first parameter. passed around to commands as the first parameter.
This class implements the :class:`abc.Messageable` ABC. This class implements the :class:`~discord.abc.Messageable` ABC.
Attributes Attributes
----------- -----------
@ -61,12 +61,12 @@ class Context(discord.abc.Messageable):
invoked_subcommand invoked_subcommand
The subcommand (i.e. :class:`.Command` or its subclasses) that was The subcommand (i.e. :class:`.Command` or its subclasses) that was
invoked. If no valid subcommand was invoked then this is equal to invoked. If no valid subcommand was invoked then this is equal to
`None`. ``None``.
subcommand_passed: Optional[:class:`str`] subcommand_passed: Optional[:class:`str`]
The string that was attempted to call a subcommand. This does not have The string that was attempted to call a subcommand. This does not have
to point to a valid registered subcommand and could just point to a to point to a valid registered subcommand and could just point to a
nonsense string. If nothing was passed to attempt a call to a nonsense string. If nothing was passed to attempt a call to a
subcommand then this is set to `None`. subcommand then this is set to ``None``.
command_failed: :class:`bool` command_failed: :class:`bool`
A boolean that indicates if the command failed to be parsed, checked, A boolean that indicates if the command failed to be parsed, checked,
or invoked. or invoked.

26
discord/ext/commands/converter.py
View File

@ -66,7 +66,7 @@ class Converter:
special cased ``discord`` classes. special cased ``discord`` classes.
Classes that derive from this should override the :meth:`~.Converter.convert` Classes that derive from this should override the :meth:`~.Converter.convert`
method to do its conversion logic. This method must be a coroutine. method to do its conversion logic. This method must be a :ref:`coroutine <coroutine>`.
""" """
async def convert(self, ctx, argument): async def convert(self, ctx, argument):
@ -96,7 +96,7 @@ class IDConverter(Converter):
return self._id_regex.match(argument) return self._id_regex.match(argument)
class MemberConverter(IDConverter): class MemberConverter(IDConverter):
"""Converts to a :class:`Member`. """Converts to a :class:`~discord.Member`.
All lookups are via the local guild. If in a DM context, then the lookup All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache. is done by the global cache.
@ -134,7 +134,7 @@ class MemberConverter(IDConverter):
return result return result
class UserConverter(IDConverter): class UserConverter(IDConverter):
"""Converts to a :class:`User`. """Converts to a :class:`~discord.User`.
All lookups are via the global user cache. All lookups are via the global user cache.
@ -210,7 +210,7 @@ class MessageConverter(Converter):
raise BadArgument("Can't read messages in {channel}".format(channel=channel.mention)) raise BadArgument("Can't read messages in {channel}".format(channel=channel.mention))
class TextChannelConverter(IDConverter): class TextChannelConverter(IDConverter):
"""Converts to a :class:`TextChannel`. """Converts to a :class:`~discord.TextChannel`.
All lookups are via the local guild. If in a DM context, then the lookup All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache. is done by the global cache.
@ -249,7 +249,7 @@ class TextChannelConverter(IDConverter):
return result return result
class VoiceChannelConverter(IDConverter): class VoiceChannelConverter(IDConverter):
"""Converts to a :class:`VoiceChannel`. """Converts to a :class:`~discord.VoiceChannel`.
All lookups are via the local guild. If in a DM context, then the lookup All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache. is done by the global cache.
@ -287,7 +287,7 @@ class VoiceChannelConverter(IDConverter):
return result return result
class CategoryChannelConverter(IDConverter): class CategoryChannelConverter(IDConverter):
"""Converts to a :class:`CategoryChannel`. """Converts to a :class:`~discord.CategoryChannel`.
All lookups are via the local guild. If in a DM context, then the lookup All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache. is done by the global cache.
@ -326,7 +326,7 @@ class CategoryChannelConverter(IDConverter):
return result return result
class ColourConverter(Converter): class ColourConverter(Converter):
"""Converts to a :class:`Colour`. """Converts to a :class:`~discord.Colour`.
The following formats are accepted: The following formats are accepted:
@ -355,7 +355,7 @@ class ColourConverter(Converter):
return method() return method()
class RoleConverter(IDConverter): class RoleConverter(IDConverter):
"""Converts to a :class:`Role`. """Converts to a :class:`~discord.Role`.
All lookups are via the local guild. If in a DM context, then the lookup All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache. is done by the global cache.
@ -382,12 +382,12 @@ class RoleConverter(IDConverter):
return result return result
class GameConverter(Converter): class GameConverter(Converter):
"""Converts to :class:`Game`.""" """Converts to :class:`~discord.Game`."""
async def convert(self, ctx, argument): async def convert(self, ctx, argument):
return discord.Game(name=argument) return discord.Game(name=argument)
class InviteConverter(Converter): class InviteConverter(Converter):
"""Converts to a :class:`Invite`. """Converts to a :class:`~discord.Invite`.
This is done via an HTTP request using :meth:`.Bot.fetch_invite`. This is done via an HTTP request using :meth:`.Bot.fetch_invite`.
""" """
@ -399,7 +399,7 @@ class InviteConverter(Converter):
raise BadArgument('Invite is invalid or expired') from exc raise BadArgument('Invite is invalid or expired') from exc
class EmojiConverter(IDConverter): class EmojiConverter(IDConverter):
"""Converts to a :class:`Emoji`. """Converts to a :class:`~discord.Emoji`.
All lookups are done for the local guild first, if available. If that lookup All lookups are done for the local guild first, if available. If that lookup
fails, then it checks the client's global cache. fails, then it checks the client's global cache.
@ -439,7 +439,7 @@ class EmojiConverter(IDConverter):
return result return result
class PartialEmojiConverter(Converter): class PartialEmojiConverter(Converter):
"""Converts to a :class:`PartialEmoji`. """Converts to a :class:`~discord.PartialEmoji`.
This is done by extracting the animated flag, name and ID from the emoji. This is done by extracting the animated flag, name and ID from the emoji.
""" """
@ -460,7 +460,7 @@ class clean_content(Converter):
"""Converts the argument to mention scrubbed version of """Converts the argument to mention scrubbed version of
said content. said content.
This behaves similarly to :attr:`.Message.clean_content`. This behaves similarly to :attr:`~discord.Message.clean_content`.
Attributes Attributes
------------ ------------

28
discord/ext/commands/core.py
View File

@ -145,10 +145,10 @@ class Command(_BaseCommand):
If the command is invoked while it is disabled, then If the command is invoked while it is disabled, then
:exc:`.DisabledCommand` is raised to the :func:`.on_command_error` :exc:`.DisabledCommand` is raised to the :func:`.on_command_error`
event. Defaults to ``True``. event. Defaults to ``True``.
parent: Optional[command] parent: Optional[:class:`Command`]
The parent command that this command belongs to. ``None`` if there The parent command that this command belongs to. ``None`` if there
isn't one. isn't one.
checks checks: List[Callable[..., :class:`bool`]]
A list of predicates that verifies if the command could be executed A list of predicates that verifies if the command could be executed
with the given :class:`.Context` as the sole parameter. If an exception with the given :class:`.Context` as the sole parameter. If an exception
is necessary to be thrown to signal failure, then one inherited from is necessary to be thrown to signal failure, then one inherited from
@ -297,7 +297,7 @@ class Command(_BaseCommand):
return other return other
def copy(self): def copy(self):
"""Creates a copy of this :class:`Command`.""" """Creates a copy of this command."""
ret = self.__class__(self.callback, **self.__original_kwargs__) ret = self.__class__(self.callback, **self.__original_kwargs__)
return self._ensure_assignment_on_copy(ret) return self._ensure_assignment_on_copy(ret)
@ -505,7 +505,7 @@ class Command(_BaseCommand):
@property @property
def full_parent_name(self): def full_parent_name(self):
"""Retrieves the fully qualified parent command name. """:class:`str`: Retrieves the fully qualified parent command name.
This the base command name required to execute it. For example, This the base command name required to execute it. For example,
in ``?one two three`` the parent name would be ``one two``. in ``?one two three`` the parent name would be ``one two``.
@ -520,7 +520,7 @@ class Command(_BaseCommand):
@property @property
def parents(self): def parents(self):
"""Retrieves the parents of this command. """:class:`Command`: Retrieves the parents of this command.
If the command has no parents then it returns an empty :class:`list`. If the command has no parents then it returns an empty :class:`list`.
@ -550,7 +550,7 @@ class Command(_BaseCommand):
@property @property
def qualified_name(self): def qualified_name(self):
"""Retrieves the fully qualified command name. """:class:`str`: Retrieves the fully qualified command name.
This is the full parent name with the command name as well. This is the full parent name with the command name as well.
For example, in ``?one two three`` the qualified name would be For example, in ``?one two three`` the qualified name would be
@ -688,7 +688,7 @@ class Command(_BaseCommand):
Parameters Parameters
----------- -----------
ctx: :class:`.Context.` ctx: :class:`.Context`
The invocation context to use when checking the commands cooldown status. The invocation context to use when checking the commands cooldown status.
Returns Returns
@ -821,12 +821,12 @@ class Command(_BaseCommand):
@property @property
def cog_name(self): def cog_name(self):
"""The name of the cog this command belongs to. None otherwise.""" """:class:`str`: The name of the cog this command belongs to. None otherwise."""
return type(self.cog).__cog_name__ if self.cog is not None else None return type(self.cog).__cog_name__ if self.cog is not None else None
@property @property
def short_doc(self): def short_doc(self):
"""Gets the "short" documentation of a command. """:class:`str`: Gets the "short" documentation of a command.
By default, this is the :attr:`brief` attribute. By default, this is the :attr:`brief` attribute.
If that lookup leads to an empty string then the first line of the If that lookup leads to an empty string then the first line of the
@ -851,7 +851,7 @@ class Command(_BaseCommand):
@property @property
def signature(self): def signature(self):
"""Returns a POSIX-like signature useful for help command output.""" """:class:`str`: Returns a POSIX-like signature useful for help command output."""
if self.usage is not None: if self.usage is not None:
return self.usage return self.usage
@ -971,7 +971,7 @@ class GroupMixin:
Parameters Parameters
----------- -----------
command command: :class:`Command`
The command to add. The command to add.
Raises Raises
@ -1107,7 +1107,7 @@ class Group(GroupMixin, Command):
Attributes Attributes
----------- -----------
invoke_without_command: :class:`bool` invoke_without_command: Optional[:class:`bool`]
Indicates if the group callback should begin parsing and Indicates if the group callback should begin parsing and
invocation only if no subcommand was found. Useful for invocation only if no subcommand was found. Useful for
making it an error handling function to tell the user that making it an error handling function to tell the user that
@ -1116,7 +1116,7 @@ class Group(GroupMixin, Command):
the group callback will always be invoked first. This means the group callback will always be invoked first. This means
that the checks and the parsing dictated by its parameters that the checks and the parsing dictated by its parameters
will be executed. Defaults to ``False``. will be executed. Defaults to ``False``.
case_insensitive: :class:`bool` case_insensitive: Optional[:class:`bool`]
Indicates if the group's commands should be case insensitive. Indicates if the group's commands should be case insensitive.
Defaults to ``False``. Defaults to ``False``.
""" """
@ -1301,7 +1301,7 @@ def check(predicate):
Parameters Parameters
----------- -----------
predicate: Callable[:class:`Context`, :class:`bool`] predicate: Callable[[:class:`Context`], :class:`bool`]
The predicate to check if the command should be invoked. The predicate to check if the command should be invoked.
""" """

2
discord/ext/commands/errors.py
View File

@ -374,7 +374,7 @@ class BotMissingPermissions(CheckFailure):
super().__init__(message, *args) super().__init__(message, *args)
class BadUnionArgument(UserInputError): class BadUnionArgument(UserInputError):
"""Exception raised when a :class:`typing.Union` converter fails for all """Exception raised when a :data:`typing.Union` converter fails for all
its associated types. its associated types.
This inherits from :exc:`UserInputError` This inherits from :exc:`UserInputError`

2
discord/ext/commands/help.py
View File

@ -550,7 +550,7 @@ class HelpCommand:
return max(as_lengths, default=0) return max(as_lengths, default=0)
def get_destination(self): def get_destination(self):
"""Returns the :class:`abc.Messageable` where the help command will be output. """Returns the :class:`~discord.abc.Messageable` where the help command will be output.
You can override this method to customise the behaviour. You can override this method to customise the behaviour.

2
discord/ext/tasks/__init__.py
View File

@ -245,7 +245,7 @@ class Loop:
return self._task return self._task
def is_being_cancelled(self): def is_being_cancelled(self):
""":class:`bool`: Whether the task is being cancelled.""" """Whether the task is being cancelled."""
return self._is_being_cancelled return self._is_being_cancelled
def failed(self): def failed(self):

2
discord/file.py
View File

@ -33,7 +33,7 @@ class File:
Attributes Attributes
----------- -----------
fp: Union[:class:`str`, BinaryIO] fp: Union[:class:`str`, :class:`io.BufferedIOBase`]
A file-like object opened in binary mode and read mode A file-like object opened in binary mode and read mode
or a filename representing a file in the hard drive to or a filename representing a file in the hard drive to
open. open.

2
discord/gateway.py
View File

@ -269,7 +269,7 @@ class DiscordWebSocket(websockets.client.WebSocketClientProtocol):
properties. The data parameter is the 'd' key in the JSON message. properties. The data parameter is the 'd' key in the JSON message.
result result
A function that takes the same data parameter and executes to send A function that takes the same data parameter and executes to send
the result to the future. If None, returns the data. the result to the future. If ``None``, returns the data.
Returns Returns
-------- --------

26
discord/guild.py
View File

@ -191,8 +191,8 @@ class Guild(Hashable):
---------- ----------
name: :class:`str` name: :class:`str`
The guild name. The guild name.
emojis emojis: Tuple[:class:`Emoji`, ...]
A :class:`tuple` of :class:`Emoji` that the guild owns. All emojis that the guild owns.
region: :class:`VoiceRegion` region: :class:`VoiceRegion`
The region the guild belongs on. There is a chance that the region The region the guild belongs on. There is a chance that the region
will be a :class:`str` if the value is not recognised by the enumerator. will be a :class:`str` if the value is not recognised by the enumerator.
@ -586,7 +586,7 @@ class Guild(Hashable):
return bool(self.icon and self.icon.startswith('a_')) return bool(self.icon and self.icon.startswith('a_'))
def icon_url_as(self, *, format=None, static_format='webp', size=1024): def icon_url_as(self, *, format=None, static_format='webp', size=1024):
"""Returns a :class:`Asset` for the guild's icon. """Returns an :class:`Asset` for the guild's icon.
The format must be one of 'webp', 'jpeg', 'jpg', 'png' or 'gif', and The format must be one of 'webp', 'jpeg', 'jpg', 'png' or 'gif', and
'gif' is only valid for animated avatars. The size must be a power of 2 'gif' is only valid for animated avatars. The size must be a power of 2
@ -622,7 +622,7 @@ class Guild(Hashable):
return self.banner_url_as() return self.banner_url_as()
def banner_url_as(self, *, format='webp', size=2048): def banner_url_as(self, *, format='webp', size=2048):
"""Returns a :class:`Asset` for the guild's banner. """Returns an :class:`Asset` for the guild's banner.
The format must be one of 'webp', 'jpeg', or 'png'. The The format must be one of 'webp', 'jpeg', or 'png'. The
size must be a power of 2 between 16 and 4096. size must be a power of 2 between 16 and 4096.
@ -652,7 +652,7 @@ class Guild(Hashable):
return self.splash_url_as() return self.splash_url_as()
def splash_url_as(self, *, format='webp', size=2048): def splash_url_as(self, *, format='webp', size=2048):
"""Returns a :class:`Asset` for the guild's invite splash. """Returns an :class:`Asset` for the guild's invite splash.
The format must be one of 'webp', 'jpeg', 'jpg', or 'png'. The The format must be one of 'webp', 'jpeg', 'jpg', or 'png'. The
size must be a power of 2 between 16 and 4096. size must be a power of 2 between 16 and 4096.
@ -698,7 +698,7 @@ class Guild(Hashable):
@property @property
def shard_id(self): def shard_id(self):
"""Returns the shard ID for this guild if applicable.""" """:class:`int`: Returns the shard ID for this guild if applicable."""
count = self._state.shard_count count = self._state.shard_count
if count is None: if count is None:
return None return None
@ -706,7 +706,7 @@ class Guild(Hashable):
@property @property
def created_at(self): def created_at(self):
"""Returns the guild's creation time in UTC.""" """:class:`datetime.datetime`: Returns the guild's creation time in UTC."""
return utils.snowflake_time(self.id) return utils.snowflake_time(self.id)
def get_member_named(self, name): def get_member_named(self, name):
@ -1483,10 +1483,10 @@ class Guild(Hashable):
This is aliased to ``color`` as well. This is aliased to ``color`` as well.
hoist: :class:`bool` hoist: :class:`bool`
Indicates if the role should be shown separately in the member list. Indicates if the role should be shown separately in the member list.
Defaults to False. Defaults to ``False``.
mentionable: :class:`bool` mentionable: :class:`bool`
Indicates if the role should be mentionable by others. Indicates if the role should be mentionable by others.
Defaults to False. Defaults to ``False``.
reason: Optional[:class:`str`] reason: Optional[:class:`str`]
The reason for creating this role. Shows up on the audit log. The reason for creating this role. Shows up on the audit log.
@ -1697,15 +1697,15 @@ class Guild(Hashable):
----------- -----------
limit: Optional[:class:`int`] limit: Optional[:class:`int`]
The number of entries to retrieve. If ``None`` retrieve all entries. The number of entries to retrieve. If ``None`` retrieve all entries.
before: Union[:class:`abc.Snowflake`, datetime] before: Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]
Retrieve entries before this date or entry. Retrieve entries before this date or entry.
If a date is provided it must be a timezone-naive datetime representing UTC time. If a date is provided it must be a timezone-naive datetime representing UTC time.
after: Union[:class:`abc.Snowflake`, datetime] after: Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]
Retrieve entries after this date or entry. Retrieve entries after this date or entry.
If a date is provided it must be a timezone-naive datetime representing UTC time. If a date is provided it must be a timezone-naive datetime representing UTC time.
oldest_first: :class:`bool` oldest_first: :class:`bool`
If set to true, return entries in oldest->newest order. Defaults to True if If set to ``True``, return entries in oldest->newest order. Defaults to True if
``after`` is specified, otherwise False. ``after`` is specified, otherwise ``False``.
user: :class:`abc.Snowflake` user: :class:`abc.Snowflake`
The moderator to filter entries from. The moderator to filter entries from.
action: :class:`AuditLogAction` action: :class:`AuditLogAction`

18
discord/invite.py
View File

@ -76,7 +76,7 @@ class PartialInviteChannel(namedtuple('PartialInviteChannel', 'id name type')):
@property @property
def created_at(self): def created_at(self):
"""Returns the channel's creation time in UTC.""" """:class:`datetime.datetime`: Returns the channel's creation time in UTC."""
return snowflake_time(self.id) return snowflake_time(self.id)
class PartialInviteGuild: class PartialInviteGuild:
@ -146,7 +146,7 @@ class PartialInviteGuild:
@property @property
def created_at(self): def created_at(self):
"""Returns the guild's creation time in UTC.""" """:class:`datetime.datetime`: Returns the guild's creation time in UTC."""
return snowflake_time(self.id) return snowflake_time(self.id)
@property @property
@ -155,7 +155,7 @@ class PartialInviteGuild:
return self.icon_url_as() return self.icon_url_as()
def icon_url_as(self, *, format='webp', size=1024): def icon_url_as(self, *, format='webp', size=1024):
""":class:`Asset`: The same operation as :meth:`Guild.icon_url_as`.""" """The same operation as :meth:`Guild.icon_url_as`."""
return Asset._from_guild_image(self._state, self.id, self.icon, 'icons', format=format, size=size) return Asset._from_guild_image(self._state, self.id, self.icon, 'icons', format=format, size=size)
@property @property
@ -164,7 +164,7 @@ class PartialInviteGuild:
return self.banner_url_as() return self.banner_url_as()
def banner_url_as(self, *, format='webp', size=2048): def banner_url_as(self, *, format='webp', size=2048):
""":class:`Asset`: The same operation as :meth:`Guild.banner_url_as`.""" """The same operation as :meth:`Guild.banner_url_as`."""
return Asset._from_guild_image(self._state, self.id, self.banner, 'banners', format=format, size=size) return Asset._from_guild_image(self._state, self.id, self.banner, 'banners', format=format, size=size)
@property @property
@ -173,7 +173,7 @@ class PartialInviteGuild:
return self.splash_url_as() return self.splash_url_as()
def splash_url_as(self, *, format='webp', size=2048): def splash_url_as(self, *, format='webp', size=2048):
""":class:`Asset`: The same operation as :meth:`Guild.splash_url_as`.""" """The same operation as :meth:`Guild.splash_url_as`."""
return Asset._from_guild_image(self._state, self.id, self.splash, 'splashes', format=format, size=size) return Asset._from_guild_image(self._state, self.id, self.splash, 'splashes', format=format, size=size)
class Invite(Hashable): class Invite(Hashable):
@ -232,11 +232,11 @@ class Invite(Hashable):
The guild the invite is for. The guild the invite is for.
revoked: :class:`bool` revoked: :class:`bool`
Indicates if the invite has been revoked. Indicates if the invite has been revoked.
created_at: `datetime.datetime` created_at: :class:`datetime.datetime`
A datetime object denoting the time the invite was created. A datetime object denoting the time the invite was created.
temporary: :class:`bool` temporary: :class:`bool`
Indicates that the invite grants temporary membership. Indicates that the invite grants temporary membership.
If True, members who joined via this invite will be kicked upon disconnect. If ``True``, members who joined via this invite will be kicked upon disconnect.
uses: :class:`int` uses: :class:`int`
How many times the invite has been used. How many times the invite has been used.
max_uses: :class:`int` max_uses: :class:`int`
@ -303,12 +303,12 @@ class Invite(Hashable):
@property @property
def id(self): def id(self):
"""Returns the proper code portion of the invite.""" """:class:`str`: Returns the proper code portion of the invite."""
return self.code return self.code
@property @property
def url(self): def url(self):
"""A property that retrieves the invite URL.""" """:class:`str`: A property that retrieves the invite URL."""
return 'http://discord.gg/' + self.code return 'http://discord.gg/' + self.code
async def delete(self, *, reason=None): async def delete(self, *, reason=None):

16
discord/iterators.py
View File

@ -191,16 +191,16 @@ class HistoryIterator(_AsyncIterator):
Messageable class to retrieve message history from. Messageable class to retrieve message history from.
limit: :class:`int` limit: :class:`int`
Maximum number of messages to retrieve Maximum number of messages to retrieve
before: :class:`abc.Snowflake` before: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
Message before which all messages must be. Message before which all messages must be.
after: :class:`abc.Snowflake` after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
Message after which all messages must be. Message after which all messages must be.
around: :class:`abc.Snowflake` around: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
Message around which all messages must be. Limit max 101. Note that if Message around which all messages must be. Limit max 101. Note that if
limit is an even number, this will return at most limit+1 messages. limit is an even number, this will return at most limit+1 messages.
oldest_first: :class:`bool` oldest_first: Optional[:class:`bool`]
If set to true, return messages in oldest->newest order. Defaults to If set to ``True``, return messages in oldest->newest order. Defaults to
True if ``after`` is specified, otherwise False. True if ``after`` is specified, otherwise ``False``.
""" """
def __init__(self, messageable, limit, def __init__(self, messageable, limit,
@ -482,9 +482,9 @@ class GuildIterator(_AsyncIterator):
The client to retrieve the guilds from. The client to retrieve the guilds from.
limit: :class:`int` limit: :class:`int`
Maximum number of guilds to retrieve. Maximum number of guilds to retrieve.
before: :class:`Snowflake` before: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
Object before which all guilds must be. Object before which all guilds must be.
after: :class:`Snowflake` after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
Object after which all guilds must be. Object after which all guilds must be.
""" """
def __init__(self, bot, limit, before=None, after=None): def __init__(self, bot, limit, before=None, after=None):

40
discord/member.py
View File

@ -287,16 +287,16 @@ class Member(discord.abc.Messageable, _BaseUser):
return try_enum(Status, self._client_status.get('web', 'offline')) return try_enum(Status, self._client_status.get('web', 'offline'))
def is_on_mobile(self): def is_on_mobile(self):
""":class:`bool`: A helper function that determines if a member is active on a mobile device.""" """A helper function that determines if a member is active on a mobile device."""
return 'mobile' in self._client_status return 'mobile' in self._client_status
@property @property
def colour(self): def colour(self):
"""A property that returns a :class:`Colour` denoting the rendered colour """:class:`Colour`: A property that returns a colour denoting the rendered colour
for the member. If the default colour is the one rendered then an instance for the member. If the default colour is the one rendered then an instance
of :meth:`Colour.default` is returned. of :meth:`Colour.default` is returned.
There is an alias for this under ``color``. There is an alias for this named :meth:`color`.
""" """
roles = self.roles[1:] # remove @everyone roles = self.roles[1:] # remove @everyone
@ -309,11 +309,19 @@ class Member(discord.abc.Messageable, _BaseUser):
return role.colour return role.colour
return Colour.default() return Colour.default()
color = colour @property
def color(self):
""":class:`Colour`: A property that returns a color denoting the rendered color for
the member. If the default color is the one rendered then an instance of :meth:`Colour.default`
is returned.
There is an alias for this named :meth:`colour`.
"""
return self.colour
@property @property
def roles(self): def roles(self):
"""A :class:`list` of :class:`Role` that the member belongs to. Note """List[:class:`Role`]: A :class:`list` of :class:`Role` that the member belongs to. Note
that the first element of this list is always the default '@everyone' that the first element of this list is always the default '@everyone'
role. role.
@ -331,14 +339,14 @@ class Member(discord.abc.Messageable, _BaseUser):
@property @property
def mention(self): def mention(self):
"""Returns a string that mentions the member.""" """:class:`str`: Returns a string that allows you to mention the member."""
if self.nick: if self.nick:
return '<@!%s>' % self.id return '<@!%s>' % self.id
return '<@%s>' % self.id return '<@%s>' % self.id
@property @property
def display_name(self): def display_name(self):
"""Returns the user's display name. """:class:`str`: Returns the user's display name.
For regular users this is just their username, but For regular users this is just their username, but
if they have a guild specific nickname then that if they have a guild specific nickname then that
@ -348,7 +356,7 @@ class Member(discord.abc.Messageable, _BaseUser):
@property @property
def activity(self): def activity(self):
"""Returns a class Union[:class:`Game`, :class:`Streaming`, :class:`Spotify`, :class:`Activity`] for the primary """Union[:class:`Game`, :class:`Streaming`, :class:`Spotify`, :class:`Activity`]: Returns the primary
activity the user is currently doing. Could be None if no activity is being done. activity the user is currently doing. Could be None if no activity is being done.
.. note:: .. note::
@ -394,7 +402,7 @@ class Member(discord.abc.Messageable, _BaseUser):
@property @property
def top_role(self): def top_role(self):
"""Returns the member's highest role. """:class:`Role`: Returns the member's highest role.
This is useful for figuring where a member stands in the role This is useful for figuring where a member stands in the role
hierarchy chain. hierarchy chain.
@ -435,21 +443,21 @@ class Member(discord.abc.Messageable, _BaseUser):
async def ban(self, **kwargs): async def ban(self, **kwargs):
"""|coro| """|coro|
Bans this member. Equivalent to :meth:`Guild.ban` Bans this member. Equivalent to :meth:`Guild.ban`.
""" """
await self.guild.ban(self, **kwargs) await self.guild.ban(self, **kwargs)
async def unban(self, *, reason=None): async def unban(self, *, reason=None):
"""|coro| """|coro|
Unbans this member. Equivalent to :meth:`Guild.unban` Unbans this member. Equivalent to :meth:`Guild.unban`.
""" """
await self.guild.unban(self, reason=reason) await self.guild.unban(self, reason=reason)
async def kick(self, *, reason=None): async def kick(self, *, reason=None):
"""|coro| """|coro|
Kicks this member. Equivalent to :meth:`Guild.kick` Kicks this member. Equivalent to :meth:`Guild.kick`.
""" """
await self.guild.kick(self, reason=reason) await self.guild.kick(self, reason=reason)
@ -487,7 +495,7 @@ class Member(discord.abc.Messageable, _BaseUser):
Indicates if the member should be guild muted or un-muted. Indicates if the member should be guild muted or un-muted.
deafen: :class:`bool` deafen: :class:`bool`
Indicates if the member should be guild deafened or un-deafened. Indicates if the member should be guild deafened or un-deafened.
roles: List[:class:`Roles`] roles: Optional[List[:class:`Role`]]
The member's new list of roles. This *replaces* the roles. The member's new list of roles. This *replaces* the roles.
voice_channel: Optional[:class:`VoiceChannel`] voice_channel: Optional[:class:`VoiceChannel`]
The voice channel to move the member to. The voice channel to move the member to.
@ -577,12 +585,12 @@ class Member(discord.abc.Messageable, _BaseUser):
Parameters Parameters
----------- -----------
\*roles: :class:`Snowflake` \*roles: :class:`abc.Snowflake`
An argument list of :class:`abc.Snowflake` representing a :class:`Role` An argument list of :class:`abc.Snowflake` representing a :class:`Role`
to give to the member. to give to the member.
reason: Optional[:class:`str`] reason: Optional[:class:`str`]
The reason for adding these roles. Shows up on the audit log. The reason for adding these roles. Shows up on the audit log.
atomic: bool atomic: :class:`bool`
Whether to atomically add roles. This will ensure that multiple Whether to atomically add roles. This will ensure that multiple
operations will always be applied regardless of the current operations will always be applied regardless of the current
state of the cache. state of the cache.
@ -615,7 +623,7 @@ class Member(discord.abc.Messageable, _BaseUser):
Parameters Parameters
----------- -----------
\*roles: :class:`Snowflake` \*roles: :class:`abc.Snowflake`
An argument list of :class:`abc.Snowflake` representing a :class:`Role` An argument list of :class:`abc.Snowflake` representing a :class:`Role`
to remove from the member. to remove from the member.
reason: Optional[:class:`str`] reason: Optional[:class:`str`]

30
discord/message.py
View File

@ -88,7 +88,7 @@ class Attachment:
Parameters Parameters
----------- -----------
fp: Union[BinaryIO, :class:`os.PathLike`] fp: Union[:class:`io.BufferedIOBase`, :class:`os.PathLike`]
The file-like object to save this attachment to or the filename The file-like object to save this attachment to or the filename
to use. If a filename is passed then a file is created with that to use. If a filename is passed then a file is created with that
filename and used instead. filename and used instead.
@ -175,7 +175,7 @@ class Message:
type: :class:`MessageType` type: :class:`MessageType`
The type of message. In most cases this should not be checked, but it is helpful The type of message. In most cases this should not be checked, but it is helpful
in cases where it might be a system message for :attr:`system_content`. in cases where it might be a system message for :attr:`system_content`.
author author: :class:`abc.User`
A :class:`Member` that sent the message. If :attr:`channel` is a A :class:`Member` that sent the message. If :attr:`channel` is a
private channel or the user has the left the guild, then it is a :class:`User` instead. private channel or the user has the left the guild, then it is a :class:`User` instead.
content: :class:`str` content: :class:`str`
@ -185,7 +185,7 @@ class Message:
This is typically non-important. This is typically non-important.
embeds: List[:class:`Embed`] embeds: List[:class:`Embed`]
A list of embeds the message has. A list of embeds the message has.
channel channel: Union[:class:`abc.Messageable`]
The :class:`TextChannel` that the message was sent from. The :class:`TextChannel` that the message was sent from.
Could be a :class:`DMChannel` or :class:`GroupChannel` if it's a private message. Could be a :class:`DMChannel` or :class:`GroupChannel` if it's a private message.
call: Optional[:class:`CallMessage`] call: Optional[:class:`CallMessage`]
@ -199,8 +199,7 @@ class Message:
This does not check if the ``@everyone`` or the ``@here`` text is in the message itself. This does not check if the ``@everyone`` or the ``@here`` text is in the message itself.
Rather this boolean indicates if either the ``@everyone`` or the ``@here`` text is in the message Rather this boolean indicates if either the ``@everyone`` or the ``@here`` text is in the message
**and** it did end up mentioning. **and** it did end up mentioning.
mentions: List[:class:`abc.User`]
mentions: :class:`list`
A list of :class:`Member` that were mentioned. If the message is in a private message A list of :class:`Member` that were mentioned. If the message is in a private message
then the list will be of :class:`User` instead. For messages that are not of type then the list will be of :class:`User` instead. For messages that are not of type
:attr:`MessageType.default`\, this array can be used to aid in system messages. :attr:`MessageType.default`\, this array can be used to aid in system messages.
@ -210,11 +209,10 @@ class Message:
The order of the mentions list is not in any particular order so you should The order of the mentions list is not in any particular order so you should
not rely on it. This is a discord limitation, not one with the library. not rely on it. This is a discord limitation, not one with the library.
channel_mentions: List[:class:`abc.GuildChannel`]
channel_mentions: :class:`list`
A list of :class:`abc.GuildChannel` that were mentioned. If the message is in a private message A list of :class:`abc.GuildChannel` that were mentioned. If the message is in a private message
then the list is always empty. then the list is always empty.
role_mentions: :class:`list` role_mentions: List[:class:`Role`]
A list of :class:`Role` that were mentioned. If the message is in a private message A list of :class:`Role` that were mentioned. If the message is in a private message
then the list is always empty. then the list is always empty.
id: :class:`int` id: :class:`int`
@ -408,8 +406,8 @@ class Message:
@utils.cached_slot_property('_cs_raw_mentions') @utils.cached_slot_property('_cs_raw_mentions')
def raw_mentions(self): def raw_mentions(self):
"""A property that returns an array of user IDs matched with """List[:class:`int`]: A property that returns an array of user IDs matched with
the syntax of <@user_id> in the message content. the syntax of ``<@user_id>`` in the message content.
This allows you to receive the user IDs of mentioned users This allows you to receive the user IDs of mentioned users
even in a private message context. even in a private message context.
@ -418,15 +416,15 @@ class Message:
@utils.cached_slot_property('_cs_raw_channel_mentions') @utils.cached_slot_property('_cs_raw_channel_mentions')
def raw_channel_mentions(self): def raw_channel_mentions(self):
"""A property that returns an array of channel IDs matched with """List[:class:`int`]: A property that returns an array of channel IDs matched with
the syntax of <#channel_id> in the message content. the syntax of ``<#channel_id>`` in the message content.
""" """
return [int(x) for x in re.findall(r'<#([0-9]+)>', self.content)] return [int(x) for x in re.findall(r'<#([0-9]+)>', self.content)]
@utils.cached_slot_property('_cs_raw_role_mentions') @utils.cached_slot_property('_cs_raw_role_mentions')
def raw_role_mentions(self): def raw_role_mentions(self):
"""A property that returns an array of role IDs matched with """List[:class:`int`]: A property that returns an array of role IDs matched with
the syntax of <@&role_id> in the message content. the syntax of ``<@&role_id>`` in the message content.
""" """
return [int(x) for x in re.findall(r'<@&([0-9]+)>', self.content)] return [int(x) for x in re.findall(r'<@&([0-9]+)>', self.content)]
@ -499,12 +497,12 @@ class Message:
@property @property
def created_at(self): def created_at(self):
"""datetime.datetime: The message's creation time in UTC.""" """:class:`datetime.datetime`: The message's creation time in UTC."""
return utils.snowflake_time(self.id) return utils.snowflake_time(self.id)
@property @property
def edited_at(self): def edited_at(self):
"""Optional[datetime.datetime]: A naive UTC datetime object containing the edited time of the message.""" """Optional[:class:`datetime.datetime`]: A naive UTC datetime object containing the edited time of the message."""
return self._edited_timestamp return self._edited_timestamp
@property @property

2
discord/object.py
View File

@ -69,5 +69,5 @@ class Object(Hashable):
@property @property
def created_at(self): def created_at(self):
"""Returns the snowflake's creation time in UTC.""" """:class:`datetime.datetime`: Returns the snowflake's creation time in UTC."""
return utils.snowflake_time(self.id) return utils.snowflake_time(self.id)

19
discord/opus.py
View File

@ -115,21 +115,13 @@ def load_opus(name):
"""Loads the libopus shared library for use with voice. """Loads the libopus shared library for use with voice.
If this function is not called then the library uses the function If this function is not called then the library uses the function
`ctypes.util.find_library`__ and then loads that one :func:`ctypes.util.find_library` and then loads that one
if available. if available.
.. _find library: https://docs.python.org/3.5/library/ctypes.html#finding-shared-libraries
__ `find library`_
Not loading a library leads to voice not working. Not loading a library leads to voice not working.
This function propagates the exceptions thrown. This function propagates the exceptions thrown.
.. note::
On Windows, this function should not need to be called as the binaries
are automatically loaded.
.. warning:: .. warning::
The bitness of the library must match the bitness of your python The bitness of the library must match the bitness of your python
@ -137,11 +129,16 @@ def load_opus(name):
must be 64-bit as well. Usually if there's a mismatch in bitness then must be 64-bit as well. Usually if there's a mismatch in bitness then
the load will throw an exception. the load will throw an exception.
.. note::
On Windows, this function should not need to be called as the binaries
are automatically loaded.
.. note:: .. note::
On Windows, the .dll extension is not necessary. However, on Linux On Windows, the .dll extension is not necessary. However, on Linux
the full extension is required to load the library, e.g. ``libopus.so.1``. the full extension is required to load the library, e.g. ``libopus.so.1``.
On Linux however, `find library`_ will usually find the library automatically On Linux however, :func:`ctypes.util.find_library` will usually find the library automatically
without you having to call this. without you having to call this.
Parameters Parameters
@ -154,7 +151,7 @@ def load_opus(name):
def is_loaded(): def is_loaded():
"""Function to check if opus lib is successfully loaded either """Function to check if opus lib is successfully loaded either
via the ``ctypes.util.find_library`` call of :func:`load_opus`. via the :func:`ctypes.util.find_library` call of :func:`load_opus`.
This must return ``True`` for voice to work. This must return ``True`` for voice to work.

86
discord/permissions.py
View File

@ -97,25 +97,25 @@ class Permissions:
return self._perm_iterator() return self._perm_iterator()
def is_subset(self, other): def is_subset(self, other):
"""Returns True if self has the same or fewer permissions as other.""" """Returns ``True`` if self has the same or fewer permissions as other."""
if isinstance(other, Permissions): if isinstance(other, Permissions):
return (self.value & other.value) == self.value return (self.value & other.value) == self.value
else: else:
raise TypeError("cannot compare {} with {}".format(self.__class__.__name__, other.__class__.__name__)) raise TypeError("cannot compare {} with {}".format(self.__class__.__name__, other.__class__.__name__))
def is_superset(self, other): def is_superset(self, other):
"""Returns True if self has the same or more permissions as other.""" """Returns ``True`` if self has the same or more permissions as other."""
if isinstance(other, Permissions): if isinstance(other, Permissions):
return (self.value | other.value) == self.value return (self.value | other.value) == self.value
else: else:
raise TypeError("cannot compare {} with {}".format(self.__class__.__name__, other.__class__.__name__)) raise TypeError("cannot compare {} with {}".format(self.__class__.__name__, other.__class__.__name__))
def is_strict_subset(self, other): def is_strict_subset(self, other):
"""Returns True if the permissions on other are a strict subset of those on self.""" """Returns ``True`` if the permissions on other are a strict subset of those on self."""
return self.is_subset(other) and self != other return self.is_subset(other) and self != other
def is_strict_superset(self, other): def is_strict_superset(self, other):
"""Returns True if the permissions on other are a strict superset of those on self.""" """Returns ``True`` if the permissions on other are a strict superset of those on self."""
return self.is_superset(other) and self != other return self.is_superset(other) and self != other
__le__ = is_subset __le__ = is_subset
@ -126,7 +126,7 @@ class Permissions:
@classmethod @classmethod
def none(cls): def none(cls):
"""A factory method that creates a :class:`Permissions` with all """A factory method that creates a :class:`Permissions` with all
permissions set to False.""" permissions set to ``False``."""
return cls(0) return cls(0)
@classmethod @classmethod
@ -138,7 +138,7 @@ class Permissions:
@classmethod @classmethod
def all_channel(cls): def all_channel(cls):
"""A :class:`Permissions` with all channel-specific permissions set to """A :class:`Permissions` with all channel-specific permissions set to
True and the guild-specific ones set to False. The guild-specific ``True`` and the guild-specific ones set to ``False``. The guild-specific
permissions are currently: permissions are currently:
- manage_guild - manage_guild
@ -153,21 +153,22 @@ class Permissions:
@classmethod @classmethod
def general(cls): def general(cls):
"""A factory method that creates a :class:`Permissions` with all """A factory method that creates a :class:`Permissions` with all
"General" permissions from the official Discord UI set to True.""" "General" permissions from the official Discord UI set to ``True``."""
return cls(0b01111100000000000000000010111111) return cls(0b01111100000000000000000010111111)
@classmethod @classmethod
def text(cls): def text(cls):
"""A factory method that creates a :class:`Permissions` with all """A factory method that creates a :class:`Permissions` with all
"Text" permissions from the official Discord UI set to True.""" "Text" permissions from the official Discord UI set to ``True``."""
return cls(0b00000000000001111111110001000000) return cls(0b00000000000001111111110001000000)
@classmethod @classmethod
def voice(cls): def voice(cls):
"""A factory method that creates a :class:`Permissions` with all """A factory method that creates a :class:`Permissions` with all
"Voice" permissions from the official Discord UI set to True.""" "Voice" permissions from the official Discord UI set to ``True``."""
return cls(0b00000011111100000000001100000000) return cls(0b00000011111100000000001100000000)
def update(self, **kwargs): def update(self, **kwargs):
r"""Bulk updates this permission object. r"""Bulk updates this permission object.
@ -217,7 +218,7 @@ class Permissions:
@property @property
def create_instant_invite(self): def create_instant_invite(self):
"""Returns True if the user can create instant invites.""" """:class:`bool`: Returns ``True`` if the user can create instant invites."""
return self._bit(0) return self._bit(0)
@create_instant_invite.setter @create_instant_invite.setter
@ -226,7 +227,7 @@ class Permissions:
@property @property
def kick_members(self): def kick_members(self):
"""Returns True if the user can kick users from the guild.""" """:class:`bool`: Returns ``True`` if the user can kick users from the guild."""
return self._bit(1) return self._bit(1)
@kick_members.setter @kick_members.setter
@ -235,7 +236,7 @@ class Permissions:
@property @property
def ban_members(self): def ban_members(self):
"""Returns True if a user can ban users from the guild.""" """:class:`bool`: Returns ``True`` if a user can ban users from the guild."""
return self._bit(2) return self._bit(2)
@ban_members.setter @ban_members.setter
@ -244,7 +245,7 @@ class Permissions:
@property @property
def administrator(self): def administrator(self):
"""Returns True if a user is an administrator. This role overrides all other permissions. """:class:`bool`: Returns ``True`` if a user is an administrator. This role overrides all other permissions.
This also bypasses all channel-specific overrides. This also bypasses all channel-specific overrides.
""" """
@ -256,7 +257,7 @@ class Permissions:
@property @property
def manage_channels(self): def manage_channels(self):
"""Returns True if a user can edit, delete, or create channels in the guild. """:class:`bool`: Returns ``True`` if a user can edit, delete, or create channels in the guild.
This also corresponds to the "Manage Channel" channel-specific override.""" This also corresponds to the "Manage Channel" channel-specific override."""
return self._bit(4) return self._bit(4)
@ -267,7 +268,7 @@ class Permissions:
@property @property
def manage_guild(self): def manage_guild(self):
"""Returns True if a user can edit guild properties.""" """:class:`bool`: Returns ``True`` if a user can edit guild properties."""
return self._bit(5) return self._bit(5)
@manage_guild.setter @manage_guild.setter
@ -276,7 +277,7 @@ class Permissions:
@property @property
def add_reactions(self): def add_reactions(self):
"""Returns True if a user can add reactions to messages.""" """:class:`bool`: Returns ``True`` if a user can add reactions to messages."""
return self._bit(6) return self._bit(6)
@add_reactions.setter @add_reactions.setter
@ -285,7 +286,7 @@ class Permissions:
@property @property
def view_audit_log(self): def view_audit_log(self):
"""Returns True if a user can view the guild's audit log.""" """:class:`bool`: Returns ``True`` if a user can view the guild's audit log."""
return self._bit(7) return self._bit(7)
@view_audit_log.setter @view_audit_log.setter
@ -294,7 +295,7 @@ class Permissions:
@property @property
def priority_speaker(self): def priority_speaker(self):
"""Returns True if a user can be more easily heard while talking.""" """:class:`bool`: Returns ``True`` if a user can be more easily heard while talking."""
return self._bit(8) return self._bit(8)
@priority_speaker.setter @priority_speaker.setter
@ -303,7 +304,7 @@ class Permissions:
@property @property
def stream(self): def stream(self):
"""Returns ``True`` if a user can stream in a voice channel.""" """:class:`bool`: Returns ``True`` if a user can stream in a voice channel."""
return self._bit(9) return self._bit(9)
@stream.setter @stream.setter
@ -312,7 +313,7 @@ class Permissions:
@property @property
def read_messages(self): def read_messages(self):
"""Returns True if a user can read messages from all or specific text channels.""" """:class:`bool`: Returns ``True`` if a user can read messages from all or specific text channels."""
return self._bit(10) return self._bit(10)
@read_messages.setter @read_messages.setter
@ -321,7 +322,7 @@ class Permissions:
@property @property
def send_messages(self): def send_messages(self):
"""Returns True if a user can send messages from all or specific text channels.""" """:class:`bool`: Returns ``True`` if a user can send messages from all or specific text channels."""
return self._bit(11) return self._bit(11)
@send_messages.setter @send_messages.setter
@ -330,7 +331,7 @@ class Permissions:
@property @property
def send_tts_messages(self): def send_tts_messages(self):
"""Returns True if a user can send TTS messages from all or specific text channels.""" """:class:`bool`: Returns ``True`` if a user can send TTS messages from all or specific text channels."""
return self._bit(12) return self._bit(12)
@send_tts_messages.setter @send_tts_messages.setter
@ -339,7 +340,12 @@ class Permissions:
@property @property
def manage_messages(self): def manage_messages(self):
"""Returns True if a user can delete or pin messages in a text channel. Note that there are currently no ways to edit other people's messages.""" """:class:`bool`: Returns ``True`` if a user can delete or pin messages in a text channel.
.. note::
Note that there are currently no ways to edit other people's messages.
"""
return self._bit(13) return self._bit(13)
@manage_messages.setter @manage_messages.setter
@ -348,7 +354,7 @@ class Permissions:
@property @property
def embed_links(self): def embed_links(self):
"""Returns True if a user's messages will automatically be embedded by Discord.""" """:class:`bool`: Returns ``True`` if a user's messages will automatically be embedded by Discord."""
return self._bit(14) return self._bit(14)
@embed_links.setter @embed_links.setter
@ -357,7 +363,7 @@ class Permissions:
@property @property
def attach_files(self): def attach_files(self):
"""Returns True if a user can send files in their messages.""" """:class:`bool`: Returns ``True`` if a user can send files in their messages."""
return self._bit(15) return self._bit(15)
@attach_files.setter @attach_files.setter
@ -366,7 +372,7 @@ class Permissions:
@property @property
def read_message_history(self): def read_message_history(self):
"""Returns True if a user can read a text channel's previous messages.""" """:class:`bool`: Returns ``True`` if a user can read a text channel's previous messages."""
return self._bit(16) return self._bit(16)
@read_message_history.setter @read_message_history.setter
@ -375,7 +381,7 @@ class Permissions:
@property @property
def mention_everyone(self): def mention_everyone(self):
"""Returns True if a user's @everyone or @here will mention everyone in the text channel.""" """:class:`bool`: Returns ``True`` if a user's @everyone or @here will mention everyone in the text channel."""
return self._bit(17) return self._bit(17)
@mention_everyone.setter @mention_everyone.setter
@ -384,7 +390,7 @@ class Permissions:
@property @property
def external_emojis(self): def external_emojis(self):
"""Returns True if a user can use emojis from other guilds.""" """:class:`bool`: Returns ``True`` if a user can use emojis from other guilds."""
return self._bit(18) return self._bit(18)
@external_emojis.setter @external_emojis.setter
@ -395,7 +401,7 @@ class Permissions:
@property @property
def connect(self): def connect(self):
"""Returns True if a user can connect to a voice channel.""" """:class:`bool`: Returns ``True`` if a user can connect to a voice channel."""
return self._bit(20) return self._bit(20)
@connect.setter @connect.setter
@ -404,7 +410,7 @@ class Permissions:
@property @property
def speak(self): def speak(self):
"""Returns True if a user can speak in a voice channel.""" """:class:`bool`: Returns ``True`` if a user can speak in a voice channel."""
return self._bit(21) return self._bit(21)
@speak.setter @speak.setter
@ -413,7 +419,7 @@ class Permissions:
@property @property
def mute_members(self): def mute_members(self):
"""Returns True if a user can mute other users.""" """:class:`bool`: Returns ``True`` if a user can mute other users."""
return self._bit(22) return self._bit(22)
@mute_members.setter @mute_members.setter
@ -422,7 +428,7 @@ class Permissions:
@property @property
def deafen_members(self): def deafen_members(self):
"""Returns True if a user can deafen other users.""" """:class:`bool`: Returns ``True`` if a user can deafen other users."""
return self._bit(23) return self._bit(23)
@deafen_members.setter @deafen_members.setter
@ -431,7 +437,7 @@ class Permissions:
@property @property
def move_members(self): def move_members(self):
"""Returns True if a user can move users between other voice channels.""" """:class:`bool`: Returns ``True`` if a user can move users between other voice channels."""
return self._bit(24) return self._bit(24)
@move_members.setter @move_members.setter
@ -440,7 +446,7 @@ class Permissions:
@property @property
def use_voice_activation(self): def use_voice_activation(self):
"""Returns True if a user can use voice activation in voice channels.""" """:class:`bool`: Returns ``True`` if a user can use voice activation in voice channels."""
return self._bit(25) return self._bit(25)
@use_voice_activation.setter @use_voice_activation.setter
@ -449,7 +455,7 @@ class Permissions:
@property @property
def change_nickname(self): def change_nickname(self):
"""Returns True if a user can change their nickname in the guild.""" """:class:`bool`: Returns ``True`` if a user can change their nickname in the guild."""
return self._bit(26) return self._bit(26)
@change_nickname.setter @change_nickname.setter
@ -458,7 +464,7 @@ class Permissions:
@property @property
def manage_nicknames(self): def manage_nicknames(self):
"""Returns True if a user can change other user's nickname in the guild.""" """:class:`bool`: Returns ``True`` if a user can change other user's nickname in the guild."""
return self._bit(27) return self._bit(27)
@manage_nicknames.setter @manage_nicknames.setter
@ -467,7 +473,7 @@ class Permissions:
@property @property
def manage_roles(self): def manage_roles(self):
"""Returns True if a user can create or edit roles less than their role's position. """:class:`bool`: Returns ``True`` if a user can create or edit roles less than their role's position.
This also corresponds to the "Manage Permissions" channel-specific override. This also corresponds to the "Manage Permissions" channel-specific override.
""" """
@ -479,7 +485,7 @@ class Permissions:
@property @property
def manage_webhooks(self): def manage_webhooks(self):
"""Returns True if a user can create, edit, or delete webhooks.""" """:class:`bool`: Returns ``True`` if a user can create, edit, or delete webhooks."""
return self._bit(29) return self._bit(29)
@manage_webhooks.setter @manage_webhooks.setter
@ -488,7 +494,7 @@ class Permissions:
@property @property
def manage_emojis(self): def manage_emojis(self):
"""Returns True if a user can create, edit, or delete emojis.""" """:class:`bool`: Returns ``True`` if a user can create, edit, or delete emojis."""
return self._bit(30) return self._bit(30)
@manage_emojis.setter @manage_emojis.setter
@ -604,7 +610,7 @@ class PermissionOverwrite:
"""Checks if the permission overwrite is currently empty. """Checks if the permission overwrite is currently empty.
An empty permission overwrite is one that has no overwrites set An empty permission overwrite is one that has no overwrites set
to True or False. to ``True`` or ``False``.
""" """
return all(x is None for x in self._values.values()) return all(x is None for x in self._values.values())

15
discord/player.py
View File

@ -76,10 +76,7 @@ class AudioSource:
raise NotImplementedError raise NotImplementedError
def is_opus(self): def is_opus(self):
"""Checks if the audio source is already encoded in Opus. """Checks if the audio source is already encoded in Opus."""
Defaults to ``False``.
"""
return False return False
def cleanup(self): def cleanup(self):
@ -98,7 +95,7 @@ class PCMAudio(AudioSource):
Attributes Attributes
----------- -----------
stream: file-like object stream: :term:`py:file object`
A file-like object that reads byte data representing raw PCM. A file-like object that reads byte data representing raw PCM.
""" """
def __init__(self, stream): def __init__(self, stream):
@ -122,16 +119,16 @@ class FFmpegPCMAudio(AudioSource):
Parameters Parameters
------------ ------------
source: Union[:class:`str`, BinaryIO] source: Union[:class:`str`, :class:`io.BufferedIOBase`]
The input that ffmpeg will take and convert to PCM bytes. The input that ffmpeg will take and convert to PCM bytes.
If ``pipe`` is True then this is a file-like object that is If ``pipe`` is True then this is a file-like object that is
passed to the stdin of ffmpeg. passed to the stdin of ffmpeg.
executable: :class:`str` executable: :class:`str`
The executable name (and path) to use. Defaults to ``ffmpeg``. The executable name (and path) to use. Defaults to ``ffmpeg``.
pipe: :class:`bool` pipe: :class:`bool`
If true, denotes that ``source`` parameter will be passed If ``True``, denotes that ``source`` parameter will be passed
to the stdin of ffmpeg. Defaults to ``False``. to the stdin of ffmpeg. Defaults to ``False``.
stderr: Optional[BinaryIO] stderr: Optional[:term:`py:file object`]
A file-like object to pass to the Popen constructor. A file-like object to pass to the Popen constructor.
Could also be an instance of ``subprocess.PIPE``. Could also be an instance of ``subprocess.PIPE``.
options: Optional[:class:`str`] options: Optional[:class:`str`]
@ -203,7 +200,7 @@ class PCMVolumeTransformer(AudioSource):
------------ ------------
original: :class:`AudioSource` original: :class:`AudioSource`
The original AudioSource to transform. The original AudioSource to transform.
volume: float volume: :class:`float`
The initial volume to set it to. The initial volume to set it to.
See :attr:`volume` for more info. See :attr:`volume` for more info.

3
discord/raw_models.py
View File

@ -90,8 +90,7 @@ class RawMessageUpdateEvent(_RawReprMixin):
message_id: :class:`int` message_id: :class:`int`
The message ID that got updated. The message ID that got updated.
data: :class:`dict` data: :class:`dict`
The raw data given by the The raw data given by the `gateway <https://discordapp.com/developers/docs/topics/gateway#message-update>`_
`gateway <https://discordapp.com/developers/docs/topics/gateway#message-update>`
cached_message: Optional[:class:`Message`] cached_message: Optional[:class:`Message`]
The cached message, if found in the internal message cache. The cached message, if found in the internal message cache.
""" """

6
discord/reaction.py
View File

@ -54,7 +54,7 @@ class Reaction:
Attributes Attributes
----------- -----------
emoji: :class:`Emoji` or :class:`str` emoji: Union[:class:`Emoji`, :class:`str`]
The reaction emoji. May be a custom emoji, or a unicode emoji. The reaction emoji. May be a custom emoji, or a unicode emoji.
count: :class:`int` count: :class:`int`
Number of times this reaction was made Number of times this reaction was made
@ -99,7 +99,7 @@ class Reaction:
Remove the reaction by the provided :class:`User` from the message. 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 If the reaction is not your own (i.e. ``user`` parameter is not you) then
the :attr:`discord.permissions.Permissions.manage_messages` permission is needed. the :attr:`~Permissions.manage_messages` permission is needed.
The ``user`` parameter must represent a user or member and meet The ``user`` parameter must represent a user or member and meet
the :class:`abc.Snowflake` abc. the :class:`abc.Snowflake` abc.
@ -139,7 +139,7 @@ class Reaction:
Flattening into a list: :: Flattening into a list: ::
users = await reaction.users().flatten() users = await reaction.users().flatten()
# users is now a list... # users is now a list of User...
winner = random.choice(users) winner = random.choice(users)
await channel.send('{} has won the raffle.'.format(winner)) await channel.send('{} has won the raffle.'.format(winner))

6
discord/role.py
View File

@ -158,17 +158,17 @@ class Role(Hashable):
@property @property
def created_at(self): def created_at(self):
"""Returns the role's creation time in UTC.""" """:class:`datetime.datetime`: Returns the role's creation time in UTC."""
return snowflake_time(self.id) return snowflake_time(self.id)
@property @property
def mention(self): def mention(self):
"""Returns a string that allows you to mention a role.""" """:class:`str`: Returns a string that allows you to mention a role."""
return '<@&%s>' % self.id return '<@&%s>' % self.id
@property @property
def members(self): def members(self):
"""Returns a :class:`list` of :class:`Member` with this role.""" """List[:class:`Member`]: Returns all the members with this role."""
all_members = self.guild.members all_members = self.guild.members
if self.is_default(): if self.is_default():
return all_members return all_members

8
discord/shard.py
View File

@ -102,11 +102,11 @@ class AutoShardedClient(Client):
It is recommended to use this client only if you have surpassed at least It is recommended to use this client only if you have surpassed at least
1000 guilds. 1000 guilds.
If no :attr:`shard_count` is provided, then the library will use the If no :attr:`.shard_count` is provided, then the library will use the
Bot Gateway endpoint call to figure out how many shards to use. Bot Gateway endpoint call to figure out how many shards to use.
If a ``shard_ids`` parameter is given, then those shard IDs will be used If a ``shard_ids`` parameter is given, then those shard IDs will be used
to launch the internal shards. Note that :attr:`shard_count` must be provided to launch the internal shards. Note that :attr:`.shard_count` must be provided
if this is used. By default, when omitted, the client will launch shards from if this is used. By default, when omitted, the client will launch shards from
0 to ``shard_count - 1``. 0 to ``shard_count - 1``.
@ -163,7 +163,7 @@ class AutoShardedClient(Client):
def latency(self): def latency(self):
""":class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
This operates similarly to :meth:`.Client.latency` except it uses the average This operates similarly to :meth:`Client.latency` except it uses the average
latency of every shard's latency. To get a list of shard latency, check the latency of every shard's latency. To get a list of shard latency, check the
:attr:`latencies` property. Returns ``nan`` if there are no shards ready. :attr:`latencies` property. Returns ``nan`` if there are no shards ready.
""" """
@ -314,7 +314,7 @@ class AutoShardedClient(Client):
activity: Optional[Union[:class:`Game`, :class:`Streaming`, :class:`Activity`]] activity: Optional[Union[:class:`Game`, :class:`Streaming`, :class:`Activity`]]
The activity being done. ``None`` if no currently active activity is done. The activity being done. ``None`` if no currently active activity is done.
status: Optional[:class:`Status`] status: Optional[:class:`Status`]
Indicates what status to change to. If None, then Indicates what status to change to. If ``None``, then
:attr:`Status.online` is used. :attr:`Status.online` is used.
afk: :class:`bool` afk: :class:`bool`
Indicates if you are going AFK. This allows the discord Indicates if you are going AFK. This allows the discord

49
discord/user.py
View File

@ -114,7 +114,7 @@ class BaseUser(_BaseUser):
@property @property
def avatar_url(self): def avatar_url(self):
"""Returns a :class:`Asset` for the avatar the user has. """Returns an :class:`Asset` for the avatar the user has.
If the user does not have a traditional avatar, an asset for If the user does not have a traditional avatar, an asset for
the default avatar is returned instead. the default avatar is returned instead.
@ -125,11 +125,11 @@ class BaseUser(_BaseUser):
return self.avatar_url_as(format=None, size=1024) return self.avatar_url_as(format=None, size=1024)
def is_avatar_animated(self): def is_avatar_animated(self):
""":class:`bool`: Returns True if the user has an animated avatar.""" """Indicates if the user has an animated avatar."""
return bool(self.avatar and self.avatar.startswith('a_')) return bool(self.avatar and self.avatar.startswith('a_'))
def avatar_url_as(self, *, format=None, static_format='webp', size=1024): def avatar_url_as(self, *, format=None, static_format='webp', size=1024):
"""Returns a :class:`Asset` for the avatar the user has. """Returns an :class:`Asset` for the avatar the user has.
If the user does not have a traditional avatar, an asset for If the user does not have a traditional avatar, an asset for
the default avatar is returned instead. the default avatar is returned instead.
@ -166,28 +166,35 @@ class BaseUser(_BaseUser):
@property @property
def default_avatar(self): def default_avatar(self):
"""Returns the default avatar for a given user. This is calculated by the user's discriminator""" """class:`DefaultAvatar`: Returns the default avatar for a given user. This is calculated by the user's discriminator."""
return try_enum(DefaultAvatar, int(self.discriminator) % len(DefaultAvatar)) return try_enum(DefaultAvatar, int(self.discriminator) % len(DefaultAvatar))
@property @property
def default_avatar_url(self): def default_avatar_url(self):
"""Returns a URL for a user's default avatar.""" """:class:`Asset`: Returns a URL for a user's default avatar."""
return Asset(self._state, 'https://cdn.discordapp.com/embed/avatars/{}.png'.format(self.default_avatar.value)) return Asset(self._state, 'https://cdn.discordapp.com/embed/avatars/{}.png'.format(self.default_avatar.value))
@property @property
def colour(self): def colour(self):
"""A property that returns a :class:`Colour` denoting the rendered colour """:class:`Colour`: A property that returns a colour denoting the rendered colour
for the user. This always returns :meth:`Colour.default`. for the user. This always returns :meth:`Colour.default`.
There is an alias for this under ``color``. There is an alias for this named :meth:`color`.
""" """
return Colour.default() return Colour.default()
color = colour @property
def color(self):
""":class:`Colour`: A property that returns a color denoting the rendered color
for the user. This always returns :meth:`Colour.default`.
There is an alias for this named :meth:`colour`.
"""
return self.colour
@property @property
def mention(self): def mention(self):
"""Returns a string that allows you to mention the given user.""" """:class:`str`: Returns a string that allows you to mention the given user."""
return '<@{0.id}>'.format(self) return '<@{0.id}>'.format(self)
def permissions_in(self, channel): def permissions_in(self, channel):
@ -208,14 +215,14 @@ class BaseUser(_BaseUser):
@property @property
def created_at(self): def created_at(self):
"""Returns the user's creation time in UTC. """:class:`datetime.datetime`: Returns the user's creation time in UTC.
This is when the user's discord account was created.""" This is when the user's discord account was created."""
return snowflake_time(self.id) return snowflake_time(self.id)
@property @property
def display_name(self): def display_name(self):
"""Returns the user's display name. """:class:`str`: Returns the user's display name.
For regular users this is just their username, but For regular users this is just their username, but
if they have a guild specific nickname then that if they have a guild specific nickname then that
@ -324,13 +331,13 @@ class ClientUser(BaseUser):
Returns Returns
-------- --------
Optional[:class:`Relationship`] Optional[:class:`Relationship`]
The relationship if available or ``None`` The relationship if available or ``None``.
""" """
return self._relationships.get(user_id) return self._relationships.get(user_id)
@property @property
def relationships(self): def relationships(self):
"""Returns a :class:`list` of :class:`Relationship` that the user has. """List[:class:`User`]: Returns all the relationships that the user has.
.. note:: .. note::
@ -340,7 +347,7 @@ class ClientUser(BaseUser):
@property @property
def friends(self): def friends(self):
r"""Returns a :class:`list` of :class:`User`\s that the user is friends with. r"""List[:class:`User`]: Returns all the users that the user is friends with.
.. note:: .. note::
@ -350,7 +357,7 @@ class ClientUser(BaseUser):
@property @property
def blocked(self): def blocked(self):
r"""Returns a :class:`list` of :class:`User`\s that the user has blocked. r"""List[:class:`User`]: Returns all the users that the user has blocked.
.. note:: .. note::
@ -366,8 +373,8 @@ class ClientUser(BaseUser):
If a bot account is used then a password field is optional, If a bot account is used then a password field is optional,
otherwise it is required. otherwise it is required.
Note .. note::
-----
To upload an avatar, a :term:`py:bytes-like object` must be passed in that To upload an avatar, a :term:`py:bytes-like object` must be passed in that
represents the image being uploaded. If this is done through a file represents the image being uploaded. If this is done through a file
then the file must be opened via ``open('some_filename', 'rb')`` and then the file must be opened via ``open('some_filename', 'rb')`` and
@ -542,7 +549,7 @@ class ClientUser(BaseUser):
inline_embed_media: :class:`bool` inline_embed_media: :class:`bool`
Whether or not to display videos and images from links posted in chat. Whether or not to display videos and images from links posted in chat.
locale: :class:`str` locale: :class:`str`
The RFC 3066 language identifier of the locale to use for the language The :rfc:`3066` language identifier of the locale to use for the language
of the Discord client. of the Discord client.
message_display_compact: :class:`bool` message_display_compact: :class:`bool`
Whether or not to use the compact Discord display mode. Whether or not to use the compact Discord display mode.
@ -654,7 +661,7 @@ class User(BaseUser, discord.abc.Messageable):
@property @property
def dm_channel(self): def dm_channel(self):
"""Returns the :class:`DMChannel` associated with this user if it exists. """Optional[:class:`DMChannel`]: Returns the channel associated with this user if it exists.
If this returns ``None``, you can create a DM channel by calling the If this returns ``None``, you can create a DM channel by calling the
:meth:`create_dm` coroutine function. :meth:`create_dm` coroutine function.
@ -711,7 +718,7 @@ class User(BaseUser, discord.abc.Messageable):
return [User(state=state, data=friend) for friend in mutuals] return [User(state=state, data=friend) for friend in mutuals]
def is_friend(self): def is_friend(self):
""":class:`bool`: Checks if the user is your friend. """Checks if the user is your friend.
.. note:: .. note::
@ -723,7 +730,7 @@ class User(BaseUser, discord.abc.Messageable):
return r.type is RelationshipType.friend return r.type is RelationshipType.friend
def is_blocked(self): def is_blocked(self):
""":class:`bool`: Checks if the user is blocked. """Checks if the user is blocked.
.. note:: .. note::

25
discord/utils.py
View File

@ -135,10 +135,10 @@ def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None):
----------- -----------
client_id: :class:`str` client_id: :class:`str`
The client ID for your bot. The client ID for your bot.
permissions: :class:`Permissions` permissions: :class:`~discord.Permissions`
The permissions you're requesting. If not given then you won't be requesting any The permissions you're requesting. If not given then you won't be requesting any
permissions. permissions.
guild: :class:`Guild` guild: :class:`~discord.Guild`
The guild to pre-select in the authorization screen, if available. The guild to pre-select in the authorization screen, if available.
redirect_uri: :class:`str` redirect_uri: :class:`str`
An optional valid redirect URI. An optional valid redirect URI.
@ -155,18 +155,18 @@ def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None):
def snowflake_time(id): def snowflake_time(id):
"""Returns the creation date in UTC of a discord id.""" """Returns the creation date in UTC of a Discord snowflake ID."""
return datetime.datetime.utcfromtimestamp(((id >> 22) + DISCORD_EPOCH) / 1000) return datetime.datetime.utcfromtimestamp(((id >> 22) + DISCORD_EPOCH) / 1000)
def time_snowflake(datetime_obj, high=False): def time_snowflake(datetime_obj, high=False):
"""Returns a numeric snowflake pretending to be created at the given date. """Returns a numeric snowflake pretending to be created at the given date.
When using as the lower end of a range, use time_snowflake(high=False) - 1 to be inclusive, high=True to be exclusive When using as the lower end of a range, use ``time_snowflake(high=False) - 1`` to be inclusive, ``high=True`` to be exclusive
When using as the higher end of a range, use time_snowflake(high=True) + 1 to be inclusive, high=False to be exclusive When using as the higher end of a range, use ``time_snowflake(high=True)`` + 1 to be inclusive, ``high=False`` to be exclusive
Parameters Parameters
----------- -----------
datetime_obj datetime_obj: :class:`datetime.datetime`
A timezone-naive datetime object representing UTC time. A timezone-naive datetime object representing UTC time.
high: :class:`bool` high: :class:`bool`
Whether or not to set the lower 22 bit to high or low. Whether or not to set the lower 22 bit to high or low.
@ -182,15 +182,12 @@ def find(predicate, seq):
member = find(lambda m: m.name == 'Mighty', channel.guild.members) member = find(lambda m: m.name == 'Mighty', channel.guild.members)
would find the first :class:`Member` whose name is 'Mighty' and return it. would find the first :class:`~discord.Member` whose name is 'Mighty' and return it.
If an entry is not found, then ``None`` is returned. If an entry is not found, then ``None`` is returned.
This is different from `filter`_ due to the fact it stops the moment it finds This is different from :func:`py:filter` due to the fact it stops the moment it finds
a valid entry. a valid entry.
.. _filter: https://docs.python.org/3.6/library/functions.html#filter
Parameters Parameters
----------- -----------
predicate predicate
@ -207,7 +204,7 @@ def find(predicate, seq):
def get(iterable, **attrs): def get(iterable, **attrs):
r"""A helper that returns the first element in the iterable that meets r"""A helper that returns the first element in the iterable that meets
all the traits passed in ``attrs``. This is an alternative for all the traits passed in ``attrs``. This is an alternative for
:func:`discord.utils.find`. :func:`~discord.utils.find`.
When multiple attributes are specified, they are checked using When multiple attributes are specified, they are checked using
logical AND, not logical OR. Meaning they have to meet every logical AND, not logical OR. Meaning they have to meet every
@ -381,11 +378,11 @@ def _string_width(string, *, _IS_ASCII=_IS_ASCII):
def resolve_invite(invite): def resolve_invite(invite):
""" """
Resolves an invite from a :class:`Invite`, URL or ID Resolves an invite from a :class:`~discord.Invite`, URL or ID
Parameters Parameters
----------- -----------
invite: Union[:class:`Invite`, :class:`Object`, :class:`str`] invite: Union[:class:`~discord.Invite`, :class:`~discord.Object`, :class:`str`]
The invite. The invite.
Returns Returns

12
discord/voice_client.py
View File

@ -84,7 +84,7 @@ class VoiceClient:
The endpoint we are connecting to. The endpoint we are connecting to.
channel: :class:`abc.Connectable` channel: :class:`abc.Connectable`
The voice channel connected to. The voice channel connected to.
loop loop: :class:`asyncio.AbstractEventLoop`
The event loop that the voice client is running on. The event loop that the voice client is running on.
""" """
def __init__(self, state, timeout, channel): def __init__(self, state, timeout, channel):
@ -301,7 +301,7 @@ class VoiceClient:
await self.main_ws.voice_state(guild_id, channel.id) await self.main_ws.voice_state(guild_id, channel.id)
def is_connected(self): def is_connected(self):
""":class:`bool`: Indicates if the voice client is connected to voice.""" """Indicates if the voice client is connected to voice."""
return self._connected.is_set() return self._connected.is_set()
# audio related # audio related
@ -345,7 +345,7 @@ class VoiceClient:
----------- -----------
source: :class:`AudioSource` source: :class:`AudioSource`
The audio source we're reading from. The audio source we're reading from.
after after: Callable[[:class:`Exception`], Any]
The finalizer that is called after the stream is exhausted. The finalizer that is called after the stream is exhausted.
All exceptions it throws are silently discarded. This function All exceptions it throws are silently discarded. This function
must have a single parameter, ``error``, that denotes an must have a single parameter, ``error``, that denotes an
@ -420,16 +420,16 @@ class VoiceClient:
Parameters Parameters
---------- ----------
data: bytes data: :class:`bytes`
The :term:`py:bytes-like object` denoting PCM or Opus voice data. The :term:`py:bytes-like object` denoting PCM or Opus voice data.
encode: bool encode: :class:`bool`
Indicates if ``data`` should be encoded into Opus. Indicates if ``data`` should be encoded into Opus.
Raises Raises
------- -------
ClientException ClientException
You are not connected. You are not connected.
OpusError opus.OpusError
Encoding the data failed. Encoding the data failed.
""" """

24
discord/webhook.py
View File

@ -164,7 +164,7 @@ class AsyncWebhookAdapter(WebhookAdapter):
Parameters Parameters
----------- -----------
session: aiohttp.ClientSession session: :class:`aiohttp.ClientSession`
The session to use to send requests. The session to use to send requests.
""" """
@ -235,7 +235,7 @@ class AsyncWebhookAdapter(WebhookAdapter):
class RequestsWebhookAdapter(WebhookAdapter): class RequestsWebhookAdapter(WebhookAdapter):
"""A webhook adapter suited for use with ``requests``. """A webhook adapter suited for use with ``requests``.
Only versions of requests higher than 2.13.0 are supported. Only versions of :doc:`req:index` higher than 2.13.0 are supported.
Parameters Parameters
----------- -----------
@ -369,9 +369,9 @@ class Webhook:
it bound to a websocket connection using the :meth:`~.Webhook.from_url` or it bound to a websocket connection using the :meth:`~.Webhook.from_url` or
:meth:`~.Webhook.partial` classmethods. This form allows finer grained control :meth:`~.Webhook.partial` classmethods. This form allows finer grained control
over how requests are done, allowing you to mix async and sync code using either over how requests are done, allowing you to mix async and sync code using either
``aiohttp`` or ``requests``. :doc:`aiohttp <aio:index>` or :doc:`req:index`.
For example, creating a webhook from a URL and using ``aiohttp``: For example, creating a webhook from a URL and using :doc:`aiohttp <aio:index>`:
.. code-block:: python3 .. code-block:: python3
@ -383,7 +383,7 @@ class Webhook:
webhook = Webhook.from_url('url-here', adapter=AsyncWebhookAdapter(session)) webhook = Webhook.from_url('url-here', adapter=AsyncWebhookAdapter(session))
await webhook.send('Hello World', username='Foo') await webhook.send('Hello World', username='Foo')
Or creating a webhook from an ID and token and using ``requests``: Or creating a webhook from an ID and token and using :doc:`req:index`:
.. code-block:: python3 .. code-block:: python3
@ -456,8 +456,8 @@ class Webhook:
The authentication token of the webhook. The authentication token of the webhook.
adapter: :class:`WebhookAdapter` adapter: :class:`WebhookAdapter`
The webhook adapter to use when sending requests. This is The webhook adapter to use when sending requests. This is
typically :class:`AsyncWebhookAdapter` for ``aiohttp`` or typically :class:`AsyncWebhookAdapter` for :doc:`aiohttp <aio:index>` or
:class:`RequestsWebhookAdapter` for ``requests``. :class:`RequestsWebhookAdapter` for :doc:`req:index`.
""" """
if not isinstance(adapter, WebhookAdapter): if not isinstance(adapter, WebhookAdapter):
@ -480,8 +480,8 @@ class Webhook:
The URL of the webhook. The URL of the webhook.
adapter: :class:`WebhookAdapter` adapter: :class:`WebhookAdapter`
The webhook adapter to use when sending requests. This is The webhook adapter to use when sending requests. This is
typically :class:`AsyncWebhookAdapter` for ``aiohttp`` or typically :class:`AsyncWebhookAdapter` for :doc:`aiohttp <aio:index>` or
:class:`RequestsWebhookAdapter` for ``requests``. :class:`RequestsWebhookAdapter` for :doc:`req:index`.
Raises Raises
------- -------
@ -518,12 +518,12 @@ class Webhook:
@property @property
def created_at(self): def created_at(self):
"""Returns the webhook's creation time in UTC.""" """:class:`datetime.datetime`: Returns the webhook's creation time in UTC."""
return utils.snowflake_time(self.id) return utils.snowflake_time(self.id)
@property @property
def avatar_url(self): def avatar_url(self):
"""Returns a :class:`Asset` for the avatar the webhook has. """Returns an :class:`Asset` for the avatar the webhook has.
If the webhook does not have a traditional avatar, an asset for If the webhook does not have a traditional avatar, an asset for
the default avatar is returned instead. the default avatar is returned instead.
@ -534,7 +534,7 @@ class Webhook:
return self.avatar_url_as() return self.avatar_url_as()
def avatar_url_as(self, *, format=None, size=1024): def avatar_url_as(self, *, format=None, size=1024):
"""Returns a :class:`Asset` for the avatar the webhook has. """Returns an :class:`Asset` for the avatar the webhook has.
If the webhook does not have a traditional avatar, an asset for If the webhook does not have a traditional avatar, an asset for
the default avatar is returned instead. the default avatar is returned instead.

4
discord/widget.py
View File

@ -73,7 +73,7 @@ class WidgetChannel(namedtuple('WidgetChannel', 'id name position')):
@property @property
def created_at(self): def created_at(self):
"""Returns the channel's creation time in UTC.""" """:class:`datetime.datetime`: Returns the channel's creation time in UTC."""
return snowflake_time(self.id) return snowflake_time(self.id)
class WidgetMember(BaseUser): class WidgetMember(BaseUser):
@ -229,7 +229,7 @@ class Widget:
"""|coro| """|coro|
Retrieves an :class:`Invite` from a invite URL or ID. Retrieves an :class:`Invite` from a invite URL or ID.
This is the same as :meth:`Client.get_invite`; the invite This is the same as :meth:`Client.fetch_invite`; the invite
code is abstracted away. code is abstracted away.
Parameters Parameters

214
docs/api.rst
View File

@ -28,7 +28,7 @@ There are two main ways to query version information about the library. For guar
.. data:: __version__ .. data:: __version__
A string representation of the version. e.g. ``'1.0.0rc1'``. This is based A string representation of the version. e.g. ``'1.0.0rc1'``. This is based
off of `PEP-440 <https://www.python.org/dev/peps/pep-0440/>`_. off of :pep:`440`.
Client Client
------- -------
@ -94,7 +94,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
.. warning:: .. warning::
All the events must be a |corourl|_. If they aren't, then you might get unexpected All the events must be a |coroutine_link|_. If they aren't, then you might get unexpected
errors. In order to turn a function into a coroutine they must be ``async def`` errors. In order to turn a function into a coroutine they must be ``async def``
functions. functions.
@ -131,6 +131,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
to denote when a particular shard ID has become ready. to denote when a particular shard ID has become ready.
:param shard_id: The shard ID that is ready. :param shard_id: The shard ID that is ready.
:type shard_id: :class:`int`
.. function:: on_resumed() .. function:: on_resumed()
@ -145,14 +146,16 @@ to handle it, which defaults to print a traceback and ignoring the exception.
suppress the default action of printing the traceback. suppress the default action of printing the traceback.
The information of the exception raised and the exception itself can The information of the exception raised and the exception itself can
be retrieved with a standard call to ``sys.exc_info()``. be retrieved with a standard call to :func:`sys.exc_info`.
If you want exception to propagate out of the :class:`Client` class If you want exception to propagate out of the :class:`Client` class
you can define an ``on_error`` handler consisting of a single empty you can define an ``on_error`` handler consisting of a single empty
``raise`` statement. Exceptions raised by ``on_error`` will not be :ref:`py:raise`. Exceptions raised by ``on_error`` will not be
handled in any way by :class:`Client`. handled in any way by :class:`Client`.
:param event: The name of the event that raised the exception. :param event: The name of the event that raised the exception.
:type event: :class:`str`
:param args: The positional arguments for the event that raised the :param args: The positional arguments for the event that raised the
exception. exception.
:param kwargs: The keyword arguments for the event that raised the :param kwargs: The keyword arguments for the event that raised the
@ -175,6 +178,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
:param msg: The message passed in from the WebSocket library. :param msg: The message passed in from the WebSocket library.
Could be :class:`bytes` for a binary message or :class:`str` Could be :class:`bytes` for a binary message or :class:`str`
for a regular message. for a regular message.
:type msg: Union[:class:`bytes`, :class:`str`]
.. function:: on_socket_raw_send(payload) .. function:: on_socket_raw_send(payload)
@ -206,8 +210,11 @@ to handle it, which defaults to print a traceback and ignoring the exception.
is a :class:`Member`, otherwise it is a :class:`User`. is a :class:`Member`, otherwise it is a :class:`User`.
:param channel: The location where the typing originated from. :param channel: The location where the typing originated from.
:type channel: :class:`abc.Messageable`
:param user: The user that started typing. :param user: The user that started typing.
:param when: A ``datetime.datetime`` object representing when typing started. :type user: Union[:class:`User`, :class:`Member`]
:param when: When the typing started as a naive datetime in UTC.
:type when: :class:`datetime.datetime`
.. function:: on_message(message) .. function:: on_message(message)
@ -221,7 +228,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
checking the user IDs. Note that :class:`~ext.commands.Bot` does not checking the user IDs. Note that :class:`~ext.commands.Bot` does not
have this problem. have this problem.
:param message: A :class:`Message` of the current message. :param message: The current message.
:type message: :class:`Message`
.. function:: on_message_delete(message) .. function:: on_message_delete(message)
@ -232,7 +240,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
If this occurs increase the :attr:`Client.max_messages` attribute. If this occurs increase the :attr:`Client.max_messages` attribute.
:param message: A :class:`Message` of the deleted message. :param message: The deleted message.
:type message: :class:`Message`
.. function:: on_bulk_message_delete(messages) .. function:: on_bulk_message_delete(messages)
@ -245,7 +254,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
If this occurs increase the :attr:`Client.max_messages` attribute. If this occurs increase the :attr:`Client.max_messages` attribute.
:param messages: A :class:`list` of :class:`Message` that have been deleted. :param messages: The messages that have been deleted.
:type messages: List[:class:`Message`]
.. function:: on_raw_message_delete(payload) .. function:: on_raw_message_delete(payload)
@ -288,8 +298,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- A call message has received an update to its participants or ending time. - A call message has received an update to its participants or ending time.
:param before: A :class:`Message` of the previous version of the message. :param before: The previous version of the message.
:param after: A :class:`Message` of the current version of the message. :type before: :class:`Message`
:param after: The current version of the message.
:type after: :class:`Message`
.. function:: on_raw_message_edit(payload) .. function:: on_raw_message_edit(payload)
@ -300,7 +312,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
it can be accessed via :attr:`RawMessageUpdateEvent.cached_message` it can be accessed via :attr:`RawMessageUpdateEvent.cached_message`
Due to the inherently raw nature of this event, the data parameter coincides with Due to the inherently raw nature of this event, the data parameter coincides with
the raw data given by the `gateway <https://discordapp.com/developers/docs/topics/gateway#message-update>`_ the raw data given by the `gateway <https://discordapp.com/developers/docs/topics/gateway#message-update>`_.
Since the data payload can be partial, care must be taken when accessing stuff in the dictionary. Since the data payload can be partial, care must be taken when accessing stuff in the dictionary.
One example of a common case of partial data is when the ``'content'`` key is inaccessible. This One example of a common case of partial data is when the ``'content'`` key is inaccessible. This
@ -320,8 +332,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
To get the :class:`Message` being reacted, access it via :attr:`Reaction.message`. To get the :class:`Message` being reacted, access it via :attr:`Reaction.message`.
:param reaction: A :class:`Reaction` showing the current state of the reaction. :param reaction: The current state of the reaction.
:param user: A :class:`User` or :class:`Member` of the user who added the reaction. :type reaction: :class:`Reaction`
:param user: The user who added the reaction.
:type user: Union[:class:`Member`, :class:`User`]
.. function:: on_raw_reaction_add(payload) .. function:: on_raw_reaction_add(payload)
@ -341,8 +355,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
To get the message being reacted, access it via :attr:`Reaction.message`. To get the message being reacted, access it via :attr:`Reaction.message`.
:param reaction: A :class:`Reaction` showing the current state of the reaction. :param reaction: The current state of the reaction.
:param user: A :class:`User` or :class:`Member` of the user whose reaction was removed. :type reaction: :class:`Reaction`
:param user: The user who added the reaction.
:type user: Union[:class:`Member`, :class:`User`]
.. function:: on_raw_reaction_remove(payload) .. function:: on_raw_reaction_remove(payload)
@ -358,8 +374,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
if the message is not found in the internal message cache, then this event if the message is not found in the internal message cache, then this event
will not be called. will not be called.
:param message: The :class:`Message` that had its reactions cleared. :param message: The message that had its reactions cleared.
:param reactions: A list of :class:`Reaction`\s that were removed. :type message: :class:`Message`
:param reactions: The reactions that were removed.
:type reactions: List[:class:`Reaction`]
.. function:: on_raw_reaction_clear(payload) .. function:: on_raw_reaction_clear(payload)
@ -374,22 +392,26 @@ to handle it, which defaults to print a traceback and ignoring the exception.
Called whenever a private channel is deleted or created. Called whenever a private channel is deleted or created.
:param channel: The :class:`abc.PrivateChannel` that got created or deleted. :param channel: The private channel that got created or deleted.
:type channel: :class:`abc.PrivateChannel`
.. function:: on_private_channel_update(before, after) .. function:: on_private_channel_update(before, after)
Called whenever a private group DM is updated. e.g. changed name or topic. Called whenever a private group DM is updated. e.g. changed name or topic.
:param before: The :class:`GroupChannel` that got updated with the old info. :param before: The updated group channel's old info.
:param after: The :class:`GroupChannel` that got updated with the updated info. :type before: :class:`GroupChannel`
:param after: The updated group channel's new info.
:type after: :class:`GroupChannel`
.. function:: on_private_channel_pins_update(channel, last_pin) .. function:: on_private_channel_pins_update(channel, last_pin)
Called whenever a message is pinned or unpinned from a private channel. Called whenever a message is pinned or unpinned from a private channel.
:param channel: The :class:`abc.PrivateChannel` that had it's pins updated. :param channel: The private channel that had its pins updated.
:param last_pin: A ``datetime.datetime`` object representing when the latest message :type channel: :class:`abc.PrivateChannel`
was pinned or ``None`` if there are no pins. :param last_pin: The latest message that was pinned as a naive datetime in UTC. Could be ``None``.
:type last_pin: Optional[:class:`datetime.datetime`]
.. function:: on_guild_channel_delete(channel) .. function:: on_guild_channel_delete(channel)
on_guild_channel_create(channel) on_guild_channel_create(channel)
@ -398,41 +420,48 @@ to handle it, which defaults to print a traceback and ignoring the exception.
Note that you can get the guild from :attr:`~abc.GuildChannel.guild`. Note that you can get the guild from :attr:`~abc.GuildChannel.guild`.
:param channel: The :class:`abc.GuildChannel` that got created or deleted. :param channel: The guild channel that got created or deleted.
:type channel: :class:`abc.GuildChannel`
.. function:: on_guild_channel_update(before, after) .. function:: on_guild_channel_update(before, after)
Called whenever a guild channel is updated. e.g. changed name, topic, permissions. Called whenever a guild channel is updated. e.g. changed name, topic, permissions.
:param before: The :class:`abc.GuildChannel` that got updated with the old info. :param before: The updated guild channel's old info.
:param after: The :class:`abc.GuildChannel` that got updated with the updated info. :type before: :class:`abc.GuildChannel`
:param after: The updated guild channel's new info.
:type after: :class:`abc.GuildChannel`
.. function:: on_guild_channel_pins_update(channel, last_pin) .. function:: on_guild_channel_pins_update(channel, last_pin)
Called whenever a message is pinned or unpinned from a guild channel. Called whenever a message is pinned or unpinned from a guild channel.
:param channel: The :class:`abc.GuildChannel` that had it's pins updated. :param channel: The guild channel that had its pins updated.
:param last_pin: A ``datetime.datetime`` object representing when the latest message :type channel: :class:`abc.GuildChannel`
was pinned or ``None`` if there are no pins. :param last_pin: The latest message that was pinned as a naive datetime in UTC. Could be ``None``.
:type last_pin: Optional[:class:`datetime.datetime`]
.. function:: on_guild_integrations_update(guild) .. function:: on_guild_integrations_update(guild)
Called whenever an integration is created, modified, or removed from a guild. Called whenever an integration is created, modified, or removed from a guild.
:param guild: The :class:`Guild` that had its integrations updated. :param guild: The guild that had its integrations updated.
:type guild: :class:`Guild`
.. function:: on_webhooks_update(channel) .. function:: on_webhooks_update(channel)
Called whenever a webhook is created, modified, or removed from a guild channel. Called whenever a webhook is created, modified, or removed from a guild channel.
:param channel: The :class:`abc.GuildChannel` that had its webhooks updated. :param channel: The channel that had its webhooks updated.
:type channel: :class:`abc.GuildChannel`
.. function:: on_member_join(member) .. function:: on_member_join(member)
on_member_remove(member) on_member_remove(member)
Called when a :class:`Member` leaves or joins a :class:`Guild`. Called when a :class:`Member` leaves or joins a :class:`Guild`.
:param member: The :class:`Member` that joined or left. :param member: The member who joined or left.
:type member: :class:`Member`
.. function:: on_member_update(before, after) .. function:: on_member_update(before, after)
@ -445,8 +474,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- nickname - nickname
- roles - roles
:param before: The :class:`Member` that updated their profile with the old info. :param before: The updated member's old info.
:param after: The :class:`Member` that updated their profile with the updated info. :type before: :class:`Member`
:param after: The updated member's updated info.
:type after: :class:`Member`
.. function:: on_user_update(before, after) .. function:: on_user_update(before, after)
@ -458,15 +489,18 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- username - username
- discriminator - discriminator
:param before: The :class:`User` that updated their profile with the old info. :param before: The updated user's old info.
:param after: The :class:`User` that updated their profile with the updated info. :type before: :class:`User`
:param after: The updated user's updated info.
:type after: :class:`User`
.. function:: on_guild_join(guild) .. function:: on_guild_join(guild)
Called when a :class:`Guild` is either created by the :class:`Client` or when the Called when a :class:`Guild` is either created by the :class:`Client` or when the
:class:`Client` joins a guild. :class:`Client` joins a guild.
:param guild: The :class:`Guild` that was joined. :param guild: The guild that was joined.
:type guild: :class:`Guild`
.. function:: on_guild_remove(guild) .. function:: on_guild_remove(guild)
@ -482,7 +516,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
In order for this event to be invoked then the :class:`Client` must have In order for this event to be invoked then the :class:`Client` must have
been part of the guild to begin with. (i.e. it is part of :attr:`Client.guilds`) been part of the guild to begin with. (i.e. it is part of :attr:`Client.guilds`)
:param guild: The :class:`Guild` that got removed. :param guild: The guild that got removed.
:type guild: :class:`Guild`
.. function:: on_guild_update(before, after) .. function:: on_guild_update(before, after)
@ -493,8 +528,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- Changed AFK timeout - Changed AFK timeout
- etc - etc
:param before: The :class:`Guild` prior to being updated. :param before: The guild prior to being updated.
:param after: The :class:`Guild` after being updated. :type before: :class:`Guild`
:param after: The guild after being updated.
:type after: :class:`Guild`
.. function:: on_guild_role_create(role) .. function:: on_guild_role_create(role)
on_guild_role_delete(role) on_guild_role_delete(role)
@ -503,22 +540,28 @@ to handle it, which defaults to print a traceback and ignoring the exception.
To get the guild it belongs to, use :attr:`Role.guild`. To get the guild it belongs to, use :attr:`Role.guild`.
:param role: The :class:`Role` that was created or deleted. :param role: The role that was created or deleted.
:type role: :class:`Role`
.. function:: on_guild_role_update(before, after) .. function:: on_guild_role_update(before, after)
Called when a :class:`Role` is changed guild-wide. Called when a :class:`Role` is changed guild-wide.
:param before: The :class:`Role` that updated with the old info. :param before: The updated role's old info.
:param after: The :class:`Role` that updated with the updated info. :type before: :class:`Role`
:param after: The updated role's updated info.
:type after: :class:`Role`
.. function:: on_guild_emojis_update(guild, before, after) .. function:: on_guild_emojis_update(guild, before, after)
Called when a :class:`Guild` adds or removes :class:`Emoji`. Called when a :class:`Guild` adds or removes :class:`Emoji`.
:param guild: The :class:`Guild` who got their emojis updated. :param guild: The guild who got their emojis updated.
:param before: A list of :class:`Emoji` before the update. :type guild: :class:`Guild`
:param after: A list of :class:`Emoji` after the update. :param before: A list of emojis before the update.
:type before: List[:class:`Emoji`]
:param after: A list of emojis after the update.
:type after: List[:class:`Emoji`]
.. function:: on_guild_available(guild) .. function:: on_guild_available(guild)
on_guild_unavailable(guild) on_guild_unavailable(guild)
@ -539,25 +582,32 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- A member is muted or deafened by their own accord. - A member is muted or deafened by their own accord.
- A member is muted or deafened by a guild administrator. - A member is muted or deafened by a guild administrator.
:param member: The :class:`Member` whose voice states changed. :param member: The member whose voice states changed.
:param before: The :class:`VoiceState` prior to the changes. :type member: :class:`Member`
:param after: The :class:`VoiceState` after to the changes. :param before: The voice state prior to the changes.
:type before: :class:`VoiceState`
:param after: The voice state after to the changes.
:type after: :class:`VoiceState`
.. function:: on_member_ban(guild, user) .. function:: on_member_ban(guild, user)
Called when user gets banned from a :class:`Guild`. Called when user gets banned from a :class:`Guild`.
:param guild: The :class:`Guild` the user got banned from. :param guild: The guild the user got banned from.
:type guild: :class:`Guild`
:param user: The user that got banned. :param user: The user that got banned.
Can be either :class:`User` or :class:`Member` depending if Can be either :class:`User` or :class:`Member` depending if
the user was in the guild or not at the time of removal. the user was in the guild or not at the time of removal.
:type user: Union[:class:`User`, :class:`Member`]
.. function:: on_member_unban(guild, user) .. function:: on_member_unban(guild, user)
Called when a :class:`User` gets unbanned from a :class:`Guild`. Called when a :class:`User` gets unbanned from a :class:`Guild`.
:param guild: The :class:`Guild` the user got unbanned from. :param guild: The guild the user got unbanned from.
:param user: The :class:`User` that got unbanned. :type guild: :class:`Guild`
:param user: The user that got unbanned.
:type user: :class:`User`
.. function:: on_group_join(channel, user) .. function:: on_group_join(channel, user)
on_group_remove(channel, user) on_group_remove(channel, user)
@ -565,7 +615,9 @@ to handle it, which defaults to print a traceback and ignoring the exception.
Called when someone joins or leaves a :class:`GroupChannel`. Called when someone joins or leaves a :class:`GroupChannel`.
:param channel: The group that the user joined or left. :param channel: The group that the user joined or left.
:type channel: :class:`GroupChannel`
:param user: The user that joined or left. :param user: The user that joined or left.
:type user: :class:`User`
.. function:: on_relationship_add(relationship) .. function:: on_relationship_add(relationship)
on_relationship_remove(relationship) on_relationship_remove(relationship)
@ -574,6 +626,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
:class:`ClientUser`. :class:`ClientUser`.
:param relationship: The relationship that was added or removed. :param relationship: The relationship that was added or removed.
:type relationship: :class:`Relationship`
.. function:: on_relationship_update(before, after) .. function:: on_relationship_update(before, after)
@ -581,7 +634,9 @@ to handle it, which defaults to print a traceback and ignoring the exception.
block a friend or a friendship is accepted. block a friend or a friendship is accepted.
:param before: The previous relationship status. :param before: The previous relationship status.
:type before: :class:`Relationship`
:param after: The updated relationship status. :param after: The updated relationship status.
:type after: :class:`Relationship`
.. _discord-api-utils: .. _discord-api-utils:
@ -600,6 +655,8 @@ Utility Functions
.. autofunction:: discord.utils.escape_mentions .. autofunction:: discord.utils.escape_mentions
.. autofunction:: discord.utils.resolve_invite
Profile Profile
--------- ---------
@ -659,9 +716,7 @@ Enumerations
The API provides some enumerations for certain types of strings to avoid the API The API provides some enumerations for certain types of strings to avoid the API
from being stringly typed in case the strings change in the future. from being stringly typed in case the strings change in the future.
All enumerations are subclasses of `enum`_. All enumerations are subclasses of :class:`enum.Enum`.
.. _enum: https://docs.python.org/3/library/enum.html
.. class:: ChannelType .. class:: ChannelType
@ -1114,7 +1169,7 @@ All enumerations are subclasses of `enum`_.
A member prune was triggered. A member prune was triggered.
When this is the action, the type of :attr:`~AuditLogEntry.target` is When this is the action, the type of :attr:`~AuditLogEntry.target` is
set to `None`. set to ``None``.
When this is the action, the type of :attr:`~AuditLogEntry.extra` is When this is the action, the type of :attr:`~AuditLogEntry.extra` is
set to an unspecified proxy object with two attributes: set to an unspecified proxy object with two attributes:
@ -1485,8 +1540,7 @@ Async Iterator
---------------- ----------------
Some API functions return an "async iterator". An async iterator is something that is Some API functions return an "async iterator". An async iterator is something that is
capable of being used in an `async for <https://docs.python.org/3/reference/compound_stmts.html#the-async-for-statement>`_ capable of being used in an :ref:`async for statement <py:async for>`.
statement.
These async iterators can be used as follows: :: These async iterators can be used as follows: ::
@ -1531,7 +1585,7 @@ Certain utilities make working with async iterators easier, detailed below.
Similar to :func:`utils.find` except run over the async iterator. Similar to :func:`utils.find` except run over the async iterator.
Unlike :func:`utils.find`\, the predicate provided can be a Unlike :func:`utils.find`\, the predicate provided can be a
coroutine. |coroutine_link|_.
Getting the last audit log with a reason or ``None``: :: Getting the last audit log with a reason or ``None``: ::
@ -1540,7 +1594,7 @@ Certain utilities make working with async iterators easier, detailed below.
event = await guild.audit_logs().find(predicate) event = await guild.audit_logs().find(predicate)
:param predicate: The predicate to use. Can be a coroutine. :param predicate: The predicate to use. Could be a |coroutine_link|_.
:return: The first element that returns ``True`` for the predicate or ``None``. :return: The first element that returns ``True`` for the predicate or ``None``.
.. comethod:: flatten() .. comethod:: flatten()
@ -1554,10 +1608,10 @@ Certain utilities make working with async iterators easier, detailed below.
.. method:: map(func) .. method:: map(func)
This is similar to the built-in :func:`map <python:map>` function. Another This is similar to the built-in :func:`map <py:map>` function. Another
:class:`AsyncIterator` is returned that executes the function on :class:`AsyncIterator` is returned that executes the function on
every element it is iterating over. This function can either be a every element it is iterating over. This function can either be a
regular function or a coroutine. regular function or a |coroutine_link|_.
Creating a content iterator: :: Creating a content iterator: ::
@ -1567,14 +1621,14 @@ Certain utilities make working with async iterators easier, detailed below.
async for content in channel.history().map(transform): async for content in channel.history().map(transform):
message_length = len(content) message_length = len(content)
:param func: The function to call on every element. Could be a coroutine. :param func: The function to call on every element. Could be a |coroutine_link|_.
:return: An async iterator. :return: An async iterator.
.. method:: filter(predicate) .. method:: filter(predicate)
This is similar to the built-in :func:`filter <python:filter>` function. Another This is similar to the built-in :func:`filter <py:filter>` function. Another
:class:`AsyncIterator` is returned that filters over the original :class:`AsyncIterator` is returned that filters over the original
async iterator. This predicate can be a regular function or a coroutine. async iterator. This predicate can be a regular function or a |coroutine_link|_.
Getting messages by non-bot accounts: :: Getting messages by non-bot accounts: ::
@ -1584,7 +1638,7 @@ Certain utilities make working with async iterators easier, detailed below.
async for elem in channel.history().filter(predicate): async for elem in channel.history().filter(predicate):
... ...
:param predicate: The predicate to call on every element. Could be a coroutine. :param predicate: The predicate to call on every element. Could be a |coroutine_link|_.
:return: An async iterator. :return: An async iterator.
@ -1678,7 +1732,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: region .. attribute:: region
:class:`GuildRegion` – The guild's voice region. See also :attr:`Guild.region`. :class:`VoiceRegion` – The guild's voice region. See also :attr:`Guild.region`.
.. attribute:: afk_channel .. attribute:: afk_channel
@ -1743,7 +1797,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
:class:`str` – The guild's vanity URL. :class:`str` – The guild's vanity URL.
See also :meth:`Guild.vanity_invite` and :meth:`Guild.change_vanity_invite`. See also :meth:`Guild.vanity_invite` and :meth:`Guild.edit`.
.. attribute:: position .. attribute:: position
@ -1751,7 +1805,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: type .. attribute:: type
*Union[int, str]* – The type of channel or channel permission overwrite. Union[:class:`int`, :class:`str`] – The type of channel or channel permission overwrite.
If the type is an :class:`int`, then it is a type of channel which can be either If the type is an :class:`int`, then it is a type of channel which can be either
``0`` to indicate a text channel or ``1`` to indicate a voice channel. ``0`` to indicate a text channel or ``1`` to indicate a voice channel.
@ -1793,7 +1847,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: nick .. attribute:: nick
*Optional[str]* – The nickname of a member. Optional[:class:`str`] – The nickname of a member.
See also :attr:`Member.nick` See also :attr:`Member.nick`
@ -1930,12 +1984,12 @@ interface, :meth:`WebhookAdapter.request`.
Abstract Base Classes Abstract Base Classes
----------------------- -----------------------
An abstract base class (also known as an ``abc``) is a class that models can inherit An :term:`py:abstract base class` (also known as an ``abc``) is a class that models can inherit
to get their behaviour. The Python implementation of an `abc <https://docs.python.org/3/library/abc.html>`_ is to get their behaviour. The Python implementation of an :doc:`abc <py:library/abc>` is
slightly different in that you can register them at run-time. **Abstract base classes cannot be instantiated**. slightly different in that you can register them at run-time. **Abstract base classes cannot be instantiated**.
They are mainly there for usage with ``isinstance`` and ``issubclass``\. They are mainly there for usage with :func:`py:isinstance` and :func:`py:issubclass`\.
This library has a module related to abstract base classes, some of which are actually from the ``abc`` standard This library has a module related to abstract base classes, some of which are actually from the :doc:`abc <py:library/abc>` standard
module, others which are not. module, others which are not.
.. autoclass:: discord.abc.Snowflake .. autoclass:: discord.abc.Snowflake
@ -1985,12 +2039,9 @@ the user of the library.
.. note:: .. note::
Nearly all classes here have ``__slots__`` defined which means that it is Nearly all classes here have :ref:`py:slots` defined which means that it is
impossible to have dynamic attributes to the data classes. impossible to have dynamic attributes to the data classes.
More information about ``__slots__`` can be found
`in the official python documentation <https://docs.python.org/3/reference/datamodel.html#slots>`_.
ClientUser ClientUser
~~~~~~~~~~~~ ~~~~~~~~~~~~
@ -2247,15 +2298,12 @@ Some classes are just there to be data containers, this lists them.
Unlike :ref:`models <discord_api_models>` you are allowed to create Unlike :ref:`models <discord_api_models>` you are allowed to create
these yourself, even if they can also be used to hold attributes. these yourself, even if they can also be used to hold attributes.
Nearly all classes here have ``__slots__`` defined which means that it is Nearly all classes here have :ref:`py:slots` defined which means that it is
impossible to have dynamic attributes to the data classes. impossible to have dynamic attributes to the data classes.
The only exception to this rule is :class:`Object`, which is made with The only exception to this rule is :class:`abc.Snowflake`, which is made with
dynamic attributes in mind. dynamic attributes in mind.
More information about ``__slots__`` can be found
`in the official python documentation <https://docs.python.org/3/reference/datamodel.html#slots>`_.
Object Object
~~~~~~~ ~~~~~~~

11
docs/conf.py
View File

@ -49,14 +49,15 @@ extlinks = {
# Links used for cross-referencing stuff in other documentation # Links used for cross-referencing stuff in other documentation
intersphinx_mapping = { intersphinx_mapping = {
'py': ('https://docs.python.org/3', None), 'py': ('https://docs.python.org/3', None),
'aio': ('https://aiohttp.readthedocs.io/en/stable/', None) 'aio': ('https://aiohttp.readthedocs.io/en/stable/', None),
'req': ('http://docs.python-requests.org/en/latest/', 'requests.inv')
} }
rst_prolog = """ rst_prolog = """
.. |coro| replace:: This function is a |corourl|_. .. |coro| replace:: This function is a |coroutine_link|_.
.. |maybecoro| replace:: This function *could be a* |corourl|_. .. |maybecoro| replace:: This function *could be a* |coroutine_link|_.
.. |corourl| replace:: *coroutine* .. |coroutine_link| replace:: *coroutine*
.. _corourl: https://docs.python.org/3/library/asyncio-task.html#coroutine .. _coroutine_link: https://docs.python.org/3/library/asyncio-task.html#coroutine
""" """
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.

8
docs/ext/commands/api.rst
View File

@ -38,9 +38,9 @@ are custom to the command extension module.
A default one is provided (:meth:`.Bot.on_command_error`). A default one is provided (:meth:`.Bot.on_command_error`).
:param ctx: The invocation context. :param ctx: The invocation context.
:type ctx: :class:`Context` :type ctx: :class:`.Context`
:param error: The error that was raised. :param error: The error that was raised.
:type error: :class:`CommandError` derived :type error: :class:`.CommandError` derived
.. function:: on_command(ctx) .. function:: on_command(ctx)
@ -50,7 +50,7 @@ are custom to the command extension module.
error or completes. error or completes.
:param ctx: The invocation context. :param ctx: The invocation context.
:type ctx: :class:`Context` :type ctx: :class:`.Context`
.. function:: on_command_completion(ctx) .. function:: on_command_completion(ctx)
@ -60,7 +60,7 @@ are custom to the command extension module.
passed and the user input it correctly. passed and the user input it correctly.
:param ctx: The invocation context. :param ctx: The invocation context.
:type ctx: :class:`Context` :type ctx: :class:`.Context`
.. _ext_commands_api_command: .. _ext_commands_api_command:

2
docs/ext/commands/commands.rst
View File

@ -129,7 +129,7 @@ at all:
.. image:: /images/commands/variable3.png .. image:: /images/commands/variable3.png
Since the ``args`` variable is a `tuple <https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range>`_, Since the ``args`` variable is a :class:`py:tuple`,
you can do anything you would usually do with one. you can do anything you would usually do with one.
Keyword-Only Arguments Keyword-Only Arguments

11
docs/faq.rst
View File

@ -18,7 +18,7 @@ Questions regarding coroutines and asyncio belong here.
What is a coroutine? What is a coroutine?
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
A coroutine is a function that must be invoked with ``await`` or ``yield from``. When Python encounters an ``await`` it stops A |coroutine_link|_ is a function that must be invoked with ``await`` or ``yield from``. When Python encounters an ``await`` it stops
the function's execution at that point and works on other things until it comes back to that point and finishes off its work. the function's execution at that point and works on other things until it comes back to that point and finishes off its work.
This allows for your program to be doing multiple things at the same time without using threads or complicated This allows for your program to be doing multiple things at the same time without using threads or complicated
multiprocessing. multiprocessing.
@ -51,9 +51,10 @@ instead. Similar to this example: ::
# good # good
await asyncio.sleep(10) await asyncio.sleep(10)
Another common source of blocking for too long is using HTTP requests with the famous module ``requests``. While ``requests`` Another common source of blocking for too long is using HTTP requests with the famous module :doc:`req:index`.
is an amazing module for non-asynchronous programming, it is not a good choice for :mod:`asyncio` because certain requests can While :doc:`req:index` is an amazing module for non-asynchronous programming, it is not a good choice for
block the event loop too long. Instead, use the ``aiohttp`` library which is installed on the side with this library. :mod:`asyncio` because certain requests can block the event loop too long. Instead, use the :doc:`aiohttp <aio:index>` library which
is installed on the side with this library.
Consider the following example: :: Consider the following example: ::
@ -128,7 +129,7 @@ To upload multiple files, you can use the ``files`` keyword argument instead of
] ]
await channel.send(files=my_files) await channel.send(files=my_files)
If you want to upload something from a URL, you will have to use an HTTP request using ``aiohttp`` If you want to upload something from a URL, you will have to use an HTTP request using :doc:`aiohttp <aio:index>`
and then pass an :class:`io.BytesIO` instance to :class:`File` like so: and then pass an :class:`io.BytesIO` instance to :class:`File` like so:
.. code-block:: python3 .. code-block:: python3

10
docs/intro.rst
View File

@ -13,7 +13,7 @@ Prerequisites
discord.py works with Python 3.5.3 or higher. Support for earlier versions of Python discord.py works with Python 3.5.3 or higher. Support for earlier versions of Python
is not provided. Python 2.7 or lower is not supported. Python 3.4 or lower is not supported is not provided. Python 2.7 or lower is not supported. Python 3.4 or lower is not supported
due to one of the dependencies (``aiohttp``) not supporting Python 3.4. due to one of the dependencies (:doc:`aiohttp <aio:index>`) not supporting Python 3.4.
.. _installing: .. _installing:
@ -36,9 +36,9 @@ To get voice support, you should use ``discord.py[voice]`` instead of ``discord.
On Linux environments, installing voice requires getting the following dependencies: On Linux environments, installing voice requires getting the following dependencies:
- libffi - `libffi <https://github.com/libffi/libffi>`_
- libnacl - `libnacl <https://github.com/saltstack/libnacl>`_
- python3-dev - `python3-dev <https://packages.debian.org/python3-dev>`_
For a Debian-based system, the following command will get these dependencies: For a Debian-based system, the following command will get these dependencies:
@ -56,7 +56,7 @@ libraries than the ones installed on the system. You might also not have permiss
For this purpose, the standard library as of Python 3.3 comes with a concept called "Virtual Environment"s to For this purpose, the standard library as of Python 3.3 comes with a concept called "Virtual Environment"s to
help maintain these separate versions. help maintain these separate versions.
A more in-depth tutorial is found on `the official documentation. <https://docs.python.org/3/tutorial/venv.html>`_ A more in-depth tutorial is found on :doc:`py:tutorial/venv`.
However, for the quick and dirty: However, for the quick and dirty:

22
docs/migrating.rst
View File

@ -268,7 +268,7 @@ User and Member Type Split
In v1.0 to save memory, :class:`User` and :class:`Member` are no longer inherited. Instead, they are "flattened" In v1.0 to save memory, :class:`User` and :class:`Member` are no longer inherited. Instead, they are "flattened"
by having equivalent properties that map out to the functional underlying :class:`User`. Thus, there is no functional by having equivalent properties that map out to the functional underlying :class:`User`. Thus, there is no functional
change in how they are used. However this breaks ``isinstance`` checks and thus is something to keep in mind. change in how they are used. However this breaks :func:`isinstance` checks and thus is something to keep in mind.
These memory savings were accomplished by having a global :class:`User` cache, and as a positive consequence you These memory savings were accomplished by having a global :class:`User` cache, and as a positive consequence you
can now easily fetch a :class:`User` by their ID by using the new :meth:`Client.get_user`. You can also get a list can now easily fetch a :class:`User` by their ID by using the new :meth:`Client.get_user`. You can also get a list
@ -289,7 +289,7 @@ In order to save memory the channels have been split into 4 different types:
- :class:`DMChannel` for DM channels with members. - :class:`DMChannel` for DM channels with members.
- :class:`GroupChannel` for Group DM channels with members. - :class:`GroupChannel` for Group DM channels with members.
With this split came the removal of the ``is_private`` attribute. You should now use ``isinstance``. With this split came the removal of the ``is_private`` attribute. You should now use :func:`isinstance`.
The types are split into two different :ref:`discord_api_abcs`: The types are split into two different :ref:`discord_api_abcs`:
@ -382,8 +382,8 @@ They will be enumerated here.
**Changed** **Changed**
- :attr:`Member.avatar_url` and :attr:`User.avatar_url` now return the default avatar if a custom one is not set. - :attr:`Member.avatar_url` and :attr:`User.avatar_url` now return the default avatar if a custom one is not set.
- :attr:`Message.embeds` is now a list of :class:`Embed` instead of ``dict`` objects. - :attr:`Message.embeds` is now a list of :class:`Embed` instead of :class:`dict` objects.
- :attr:`Message.attachments` is now a list of :class:`Attachment` instead of ``dict`` object. - :attr:`Message.attachments` is now a list of :class:`Attachment` instead of :class:`dict` object.
- :attr:`Guild.roles` is now sorted through hierarchy. The first element is always the ``@everyone`` role. - :attr:`Guild.roles` is now sorted through hierarchy. The first element is always the ``@everyone`` role.
**Added** **Added**
@ -701,12 +701,12 @@ when reached instead of setting the return to ``None``. For example:
Upgraded Dependencies Upgraded Dependencies
----------------------- -----------------------
Following v1.0 of the library, we've updated our requirements to ``aiohttp`` v2.0 or higher. Following v1.0 of the library, we've updated our requirements to :doc:`aiohttp <aio:index>` v2.0 or higher.
Since this is a backwards incompatible change, it is recommended that you see the Since this is a backwards incompatible change, it is recommended that you see the
`changes <http://aiohttp.readthedocs.io/en/stable/changes.html#rc1-2017-03-15>`_ and the `changes <http://aiohttp.readthedocs.io/en/stable/changes.html#rc1-2017-03-15>`_
`migrating <http://aiohttp.readthedocs.io/en/stable/migration.html>`_ pages for details on the breaking changes in and the :doc:`aio:migration_to_2xx` pages for details on the breaking changes in
``aiohttp``. :doc:`aiohttp <aio:index>`.
Of the most significant for common users is the removal of helper functions such as: Of the most significant for common users is the removal of helper functions such as:
@ -899,9 +899,9 @@ Command instances have gained new attributes and properties:
For :class:`~ext.commands.Group` and :class:`~ext.commands.Bot` the following changed: For :class:`~ext.commands.Group` and :class:`~ext.commands.Bot` the following changed:
- Changed :attr:`~.GroupMixin.commands` to be a ``set`` without aliases. - Changed :attr:`~.GroupMixin.commands` to be a :class:`set` without aliases.
- Use :attr:`~.GroupMixin.all_commands` to get the old ``dict`` with all commands. - Use :attr:`~.GroupMixin.all_commands` to get the old :class:`dict` with all commands.
Check Changes Check Changes
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
@ -949,7 +949,7 @@ and commands.
HelpFormatter and Help Command Changes HelpFormatter and Help Command Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :class:`~.commands.HelpFormatter` class has been removed. It has been replaced with a :class:`~.commands.HelpCommand` class. This class now stores all the command handling and processing of the help command. The ``HelpFormatter`` class has been removed. It has been replaced with a :class:`~.commands.HelpCommand` class. This class now stores all the command handling and processing of the help command.
The help command is now stored in the :attr:`.Bot.help_command` attribute. As an added extension, you can disable the help command completely by assigning the attribute to ``None`` or passing it at ``__init__`` as ``help_command=None``. The help command is now stored in the :attr:`.Bot.help_command` attribute. As an added extension, you can disable the help command completely by assigning the attribute to ``None`` or passing it at ``__init__`` as ``help_command=None``.

6
docs/migrating_to_async.rst
View File

@ -11,7 +11,7 @@ v0.10.0 is one of the biggest breaking changes in the library due to massive
fundamental changes in how the library operates. fundamental changes in how the library operates.
The biggest major change is that the library has dropped support to all versions prior to The biggest major change is that the library has dropped support to all versions prior to
Python 3.4.2. This was made to support ``asyncio``, in which more detail can be seen Python 3.4.2. This was made to support :mod:`asyncio`, in which more detail can be seen
:issue:`in the corresponding issue <50>`. To reiterate this, the implication is that :issue:`in the corresponding issue <50>`. To reiterate this, the implication is that
**python version 2.7 and 3.3 are no longer supported**. **python version 2.7 and 3.3 are no longer supported**.
@ -98,7 +98,7 @@ Coroutines
----------- -----------
The biggest change that the library went through is that almost every function in :class:`Client` The biggest change that the library went through is that almost every function in :class:`Client`
was changed to be a `coroutine <https://docs.python.org/3/library/asyncio-task.html>`_. Functions was changed to be a `coroutine <py:library/asyncio-task.html>`_. Functions
that are marked as a coroutine in the documentation must be awaited from or yielded from in order that are marked as a coroutine in the documentation must be awaited from or yielded from in order
for the computation to be done. For example... for the computation to be done. For example...
@ -159,7 +159,7 @@ Enumerations
------------ ------------
Due to dropping support for versions lower than Python 3.4.2, the library can now use Due to dropping support for versions lower than Python 3.4.2, the library can now use
`enumerations <https://docs.python.org/3/library/enum.html>`_ in places where it makes sense. :doc:`py:library/enum` in places where it makes sense.
The common places where this was changed was in the server region, member status, and channel type. The common places where this was changed was in the server region, member status, and channel type.

BIN
docs/requests.inv Normal file
View File

Binary file not shown.