mirrors/discord.py
1
0
Fork 0
mirror of https://github.com/Rapptz/discord.py.git synced 2025-04-16 06:03:11 +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
@abc.abstractmethod
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
@classmethod
@ -82,11 +82,11 @@ class User(metaclass=abc.ABCMeta):
The following implement this ABC:
- :class:`User`
- :class:`ClientUser`
- :class:`Member`
- :class:`~discord.User`
- :class:`~discord.ClientUser`
- :class:`~discord.Member`
This ABC must also implement :class:`abc.Snowflake`.
This ABC must also implement :class:`~discord.abc.Snowflake`.
Attributes
-----------
@ -104,13 +104,13 @@ class User(metaclass=abc.ABCMeta):
@property
@abc.abstractmethod
def display_name(self):
"""Returns the user's display name."""
""":class:`str`: Returns the user's display name."""
raise NotImplementedError
@property
@abc.abstractmethod
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
@classmethod
@ -134,14 +134,14 @@ class PrivateChannel(metaclass=abc.ABCMeta):
The following implement this ABC:
- :class:`DMChannel`
- :class:`GroupChannel`
- :class:`~discord.DMChannel`
- :class:`~discord.GroupChannel`
This ABC must also implement :class:`abc.Snowflake`.
This ABC must also implement :class:`~discord.abc.Snowflake`.
Attributes
-----------
me: :class:`ClientUser`
me: :class:`~discord.ClientUser`
The user presenting yourself.
"""
__slots__ = ()
@ -166,17 +166,17 @@ class GuildChannel:
The following implement this ABC:
- :class:`TextChannel`
- :class:`VoiceChannel`
- :class:`CategoryChannel`
- :class:`~discord.TextChannel`
- :class:`~discord.VoiceChannel`
- :class:`~discord.CategoryChannel`
This ABC must also implement :class:`abc.Snowflake`.
This ABC must also implement :class:`~discord.abc.Snowflake`.
Attributes
-----------
name: :class:`str`
The channel name.
guild: :class:`Guild`
guild: :class:`~discord.Guild`
The guild the channel belongs to.
position: :class:`int`
The position in the channel list. This is a number that starts at 0.
@ -288,8 +288,8 @@ class GuildChannel:
@property
def changed_roles(self):
"""Returns a :class:`list` of :class:`Roles` that have been overridden from
their default values in the :attr:`Guild.roles` attribute."""
"""List[:class:`~discord.Role`]: Returns a list of roles that have been overridden from
their default values in the :attr:`~discord.Guild.roles` attribute."""
ret = []
g = self.guild
for overwrite in filter(lambda o: o.type == 'role', self._overwrites):
@ -309,7 +309,7 @@ class GuildChannel:
@property
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)
def overwrites_for(self, obj):
@ -317,13 +317,13 @@ class GuildChannel:
Parameters
-----------
obj
The :class:`Role` or :class:`abc.User` denoting
obj: Union[:class:`~discord.Role`, :class:`~discord.abc.User`]
The role or user denoting
whose overwrite to get.
Returns
---------
:class:`PermissionOverwrite`
:class:`~discord.PermissionOverwrite`
The permission overwrites for this object.
"""
@ -347,12 +347,12 @@ class GuildChannel:
"""Returns all of the channel's overwrites.
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
overwrite as a :class:`PermissionOverwrite`.
can be either a :class:`~discord.Role` or a :class:`~discord.Member` and the key is the
overwrite as a :class:`~discord.PermissionOverwrite`.
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.
"""
ret = {}
@ -377,14 +377,14 @@ class GuildChannel:
@property
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``.
"""
return self.guild.get_channel(self.category_id)
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:
@ -395,12 +395,12 @@ class GuildChannel:
Parameters
----------
member: :class:`Member`
member: :class:`~discord.Member`
The member to resolve permissions for.
Returns
-------
:class:`Permissions`
:class:`~discord.Permissions`
The resolved permissions for the member.
"""
@ -500,11 +500,11 @@ class GuildChannel:
Raises
-------
Forbidden
:exc:`~discord.Forbidden`
You do not have proper permissions to delete the channel.
NotFound
:exc:`~discord.NotFound`
The channel was not found or was already deleted.
HTTPException
:exc:`~discord.HTTPException`
Deleting the channel failed.
"""
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
channel.
The ``target`` parameter should either be a :class:`Member` or a
:class:`Role` that belongs to guild.
The ``target`` parameter should either be a :class:`~discord.Member` or a
:class:`~discord.Role` that belongs to guild.
The ``overwrite`` parameter, if given, must either be ``None`` or
:class:`PermissionOverwrite`. For convenience, you can pass in
keyword arguments denoting :class:`Permissions` attributes. If this is
:class:`~discord.PermissionOverwrite`. For convenience, you can pass in
keyword arguments denoting :class:`~discord.Permissions` attributes. If this is
done, then you cannot mix the keyword arguments with the ``overwrite``
parameter.
If the ``overwrite`` parameter is ``None``, then the permission
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
----------
@ -541,7 +541,7 @@ class GuildChannel:
await channel.set_permissions(member, overwrite=None)
Using :class:`PermissionOverwrite` ::
Using :class:`~discord.PermissionOverwrite` ::
overwrite = discord.PermissionOverwrite()
overwrite.send_messages = False
@ -550,9 +550,9 @@ class GuildChannel:
Parameters
-----------
target
The :class:`Member` or :class:`Role` to overwrite permissions for.
overwrite: :class:`PermissionOverwrite`
target: Union[:class:`~discord.Member`, :class:`~discord.Role`]
The member or role to overwrite permissions for.
overwrite: :class:`~discord.PermissionOverwrite`
The permissions to allow and deny to the target.
\*\*permissions
A keyword argument list of permissions to set for ease of use.
@ -562,15 +562,15 @@ class GuildChannel:
Raises
-------
Forbidden
:exc:`~discord.Forbidden`
You do not have permissions to edit channel specific permissions.
HTTPException
:exc:`~discord.HTTPException`
Editing channel specific permissions failed.
NotFound
:exc:`~discord.NotFound`
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
:class:`Role` or :class:`Member`.
:class:`~discord.Role` or :class:`~discord.Member`.
"""
http = self._state.http
@ -636,9 +636,9 @@ class GuildChannel:
Raises
-------
Forbidden
:exc:`~discord.Forbidden`
You do not have the proper permissions to create this channel.
HTTPException
:exc:`~discord.HTTPException`
Creating the channel failed.
"""
raise NotImplementedError
@ -648,7 +648,7 @@ class GuildChannel:
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.
Parameters
@ -661,22 +661,22 @@ class GuildChannel:
are unlimited uses. Defaults to 0.
temporary: :class:`bool`
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`
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.
reason: Optional[:class:`str`]
The reason for creating this invite. Shows up on the audit log.
Raises
-------
HTTPException
:exc:`~discord.HTTPException`
Invite creation failed.
Returns
--------
:class:`Invite`
:class:`~discord.Invite`
The invite that was created.
"""
@ -692,14 +692,14 @@ class GuildChannel:
Raises
-------
Forbidden
:exc:`~discord.Forbidden`
You do not have proper permissions to get the information.
HTTPException
:exc:`~discord.HTTPException`
An error occurred while fetching the information.
Returns
-------
List[:class:`Invite`]
List[:class:`~discord.Invite`]
The list of invites that are currently active.
"""
@ -719,14 +719,14 @@ class Messageable(metaclass=abc.ABCMeta):
The following implement this ABC:
- :class:`TextChannel`
- :class:`DMChannel`
- :class:`GroupChannel`
- :class:`User`
- :class:`Member`
- :class:`~ext.commands.Context`
- :class:`~discord.TextChannel`
- :class:`~discord.DMChannel`
- :class:`~discord.GroupChannel`
- :class:`~discord.User`
- :class:`~discord.Member`
- :class:`~discord.ext.commands.Context`
This ABC must also implement :class:`abc.Snowflake`.
This ABC must also implement :class:`~discord.abc.Snowflake`.
"""
__slots__ = ()
@ -745,24 +745,24 @@ class Messageable(metaclass=abc.ABCMeta):
be provided.
To upload a single file, the ``file`` parameter should be used with a
single :class:`.File` object. To upload multiple files, the ``files``
parameter should be used with a :class:`list` of :class:`.File` objects.
single :class:`~discord.File` object. To upload multiple files, the ``files``
parameter should be used with a :class:`list` of :class:`~discord.File` objects.
**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.
Parameters
------------
content
content: :class:`str`
The content of the message to send.
tts: :class:`bool`
Indicates if the message should be sent using text-to-speech.
embed: :class:`.Embed`
embed: :class:`~discord.Embed`
The rich embed for the content.
file: :class:`.File`
file: :class:`~discord.File`
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.
nonce: :class:`int`
The nonce to use for sending this message. If the message was successfully sent,
@ -774,17 +774,17 @@ class Messageable(metaclass=abc.ABCMeta):
Raises
--------
:exc:`.HTTPException`
:exc:`~discord.HTTPException`
Sending the message failed.
:exc:`.Forbidden`
:exc:`~discord.Forbidden`
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
you specified both ``file`` and ``files``.
Returns
---------
:class:`.Message`
:class:`~discord.Message`
The message that was sent.
"""
@ -860,7 +860,7 @@ class Messageable(metaclass=abc.ABCMeta):
async def fetch_message(self, id):
"""|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.
@ -871,16 +871,16 @@ class Messageable(metaclass=abc.ABCMeta):
Raises
--------
:exc:`.NotFound`
:exc:`~discord.NotFound`
The specified message was not found.
:exc:`.Forbidden`
:exc:`~discord.Forbidden`
You do not have the permissions required to get a message.
:exc:`.HTTPException`
:exc:`~discord.HTTPException`
Retrieving the message failed.
Returns
--------
:class:`.Message`
:class:`~discord.Message`
The message asked for.
"""
@ -891,7 +891,7 @@ class Messageable(metaclass=abc.ABCMeta):
async def pins(self):
"""|coro|
Returns a :class:`list` of :class:`.Message` that are currently pinned.
Retrieves all messages that are currently pinned in the channel.
.. note::
@ -901,8 +901,13 @@ class Messageable(metaclass=abc.ABCMeta):
Raises
-------
:exc:`.HTTPException`
:exc:`~discord.HTTPException`
Retrieving the pinned messages failed.
Returns
--------
List[:class:`~discord.Message`]
The messages that are currently pinned.
"""
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]
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.
@ -938,31 +943,31 @@ class Messageable(metaclass=abc.ABCMeta):
The number of messages to retrieve.
If ``None``, retrieves every message in the channel. Note, however,
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.
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.
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.
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
even number then this will return at most limit + 1 messages.
oldest_first: Optional[:class:`bool`]
If set to true, return messages in oldest->newest order. Defaults to True if
``after`` is specified, otherwise False.
If set to ``True``, return messages in oldest->newest order. Defaults to ``True`` if
``after`` is specified, otherwise ``False``.
Raises
------
:exc:`.Forbidden`
:exc:`~discord.Forbidden`
You do not have permissions to get channel message history.
:exc:`.HTTPException`
:exc:`~discord.HTTPException`
The request to get message history failed.
Yields
-------
:class:`.Message`
:class:`~discord.Message`
The message with the message data parsed.
"""
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:
- :class:`VoiceChannel`
- :class:`~discord.VoiceChannel`
"""
__slots__ = ()
@ -1003,16 +1008,16 @@ class Connectable(metaclass=abc.ABCMeta):
Raises
-------
asyncio.TimeoutError
:exc:`asyncio.TimeoutError`
Could not connect to the voice channel in time.
ClientException
:exc:`~discord.ClientException`
You are already connected to a voice channel.
OpusNotLoaded
:exc:`~discord.opus.OpusNotLoaded`
The opus library has not been loaded.
Returns
-------
:class:`VoiceClient`
--------
:class:`~discord.VoiceClient`
A voice client that is fully connected to the voice server.
"""
key_id, _ = self._get_voice_client_key()

7
discord/asset.py
View File

@ -163,6 +163,13 @@ class Asset:
.. 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
------
DiscordException

2
discord/audit_logs.py
View File

@ -269,7 +269,7 @@ class AuditLogEntry:
@utils.cached_property
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)
@utils.cached_property

4
discord/backoff.py
View File

@ -42,10 +42,10 @@ class ExponentialBackoff:
Parameters
----------
base: :class:`int`
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.
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.
"""

6
discord/calls.py
View File

@ -38,7 +38,7 @@ class CallMessage:
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.
participants: List[:class:`User`]
The list of users that are participating in this call.
@ -70,7 +70,7 @@ class CallMessage:
Returns
---------
datetime.timedelta
:class:`datetime.timedelta`
The timedelta object representing the duration.
"""
if self.ended_timestamp is None:
@ -122,7 +122,7 @@ class GroupCall:
@property
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]
me = self.channel.me
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
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]
def is_nsfw(self):
@ -313,22 +313,22 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
limit: Optional[:class:`int`]
The number of messages to search through. This is not the number
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.
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`.
after
after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
Same as ``after`` in :meth:`history`.
around
around: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
Same as ``around`` in :meth:`history`.
oldest_first
oldest_first: Optional[:class:`bool`]
Same as ``oldest_first`` in :meth:`history`.
bulk: :class:`bool`
If True, use bulk delete. bulk=False is useful for mass-deleting
a bot's own messages without manage_messages. When True, will fall
back to single delete if current account is a user bot, or if
messages are older than two weeks.
bulk: class:`bool`
If ``True``, use bulk delete. Setting this to ``False`` is useful for mass-deleting
a bot's own messages without :attr:`Permissions.manage_messages`. When ``True``, will
fall back to single delete if current account is a user bot, or if messages are
older than two weeks.
Raises
-------
@ -534,7 +534,7 @@ class VoiceChannel(discord.abc.Connectable, discord.abc.GuildChannel, Hashable):
@property
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 = []
for user_id, state in self.guild._voice_states.items():
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.
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.
- manage_messages: You cannot delete others messages in a DM.
- :attr:`~Permissions.send_tts_messages`: You cannot send TTS messages in a DM.
- :attr:`~Permissions.manage_messages`: You cannot delete others messages in a DM.
Parameters
-----------
@ -988,7 +988,7 @@ class GroupChannel(discord.abc.Messageable, Hashable):
Attributes
----------
recipients: :class:`list` of :class:`User`
recipients: List[:class:`User`]
The users you are participating with in the group channel.
me: :class:`ClientUser`
The user presenting yourself.
@ -1051,7 +1051,7 @@ class GroupChannel(discord.abc.Messageable, Hashable):
@property
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)
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.
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.
- 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`]
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.
loop: Optional[:class:`asyncio.AbstractEventLoop`]
The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations.
@ -135,11 +135,11 @@ class Client:
proxy_auth: Optional[:class:`aiohttp.BasicAuth`]
An object that represents proxy HTTP Basic Authorization.
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`]
The total number of shards.
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
no offline members are received and :meth:`request_offline_members`
must be used to fetch the offline members of the guild.
@ -156,7 +156,7 @@ class Client:
Attributes
-----------
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`
The event loop that the client uses for HTTP requests and websocket operations.
"""
@ -239,7 +239,7 @@ class Client:
@property
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
"""
@ -247,7 +247,7 @@ class Client:
@property
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::
@ -262,7 +262,7 @@ class Client:
return self._connection.voice_clients
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()
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
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)
traceback.print_exc()
@ -348,12 +348,12 @@ class Client:
Parameters
-----------
\*guilds: :class:`Guild`
\*guilds: :class:`.Guild`
An argument list of guilds to request offline members for.
Raises
-------
InvalidArgument
:exc:`.InvalidArgument`
If any guild is unavailable or not large in the collection.
"""
if any(not g.large or g.unavailable for g in guilds):
@ -388,9 +388,9 @@ class Client:
Raises
------
LoginFailure
:exc:`.LoginFailure`
The wrong credentials are passed.
HTTPException
:exc:`.HTTPException`
An unknown HTTP related error occurred,
usually when it isn't 200 or the known incorrect credentials
passing status code.
@ -444,10 +444,10 @@ class Client:
Raises
-------
GatewayNotFound
:exc:`.GatewayNotFound`
If the gateway to connect to discord is not found. Usually if this
is thrown then there is a discord API outage.
ConnectionClosed
:exc:`.ConnectionClosed`
The websocket connection has been terminated.
"""
@ -514,8 +514,8 @@ class Client:
def clear(self):
"""Clears the internal state of the bot.
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
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
cache cleared.
"""
self._closed = False
@ -533,7 +533,6 @@ class Client:
TypeError
An unexpected keyword argument was received.
"""
bot = kwargs.pop('bot', True)
reconnect = kwargs.pop('reconnect', True)
@ -598,12 +597,14 @@ class Client:
# properties
def is_closed(self):
""":class:`bool`: Indicates if the websocket connection is closed."""
"""Indicates if the websocket connection is closed."""
return self._closed
@property
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)
@activity.setter
@ -619,26 +620,36 @@ class Client:
@property
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())
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)
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)
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)
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)
def get_all_channels(self):
@ -669,7 +680,6 @@ class Client:
for guild in client.guilds:
for member in guild.members:
yield member
"""
for guild in self.guilds:
for member in guild.members:
@ -746,7 +756,7 @@ class Client:
event: :class:`str`
The event name, similar to the :ref:`event reference <discord-api-events>`,
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
parameters of the event being waited for.
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>`.
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
---------
@ -835,16 +845,16 @@ class Client:
activity: Optional[Union[:class:`.Game`, :class:`.Streaming`, :class:`.Activity`]]
The activity being done. ``None`` if no currently active activity is done.
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.
afk: :class:`bool`
afk: Optional[:class:`bool`]
Indicates if you are going AFK. This allows the discord
client to know how to handle push notifications better
for you in case you are actually idle and not lying.
Raises
------
InvalidArgument
:exc:`.InvalidArgument`
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.
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
---------
@ -922,6 +906,32 @@ class Client:
guilds = await client.fetch_guilds(limit=150).flatten()
# 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)
@ -932,7 +942,7 @@ class Client:
.. 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`.
.. note::
@ -946,9 +956,9 @@ class Client:
Raises
------
Forbidden
:exc:`.Forbidden`
You do not have access to the guild.
HTTPException
:exc:`.HTTPException`
Getting the guild failed.
Returns
@ -970,7 +980,7 @@ class Client:
----------
name: :class:`str`
The name of the guild.
region: :class:`VoiceRegion`
region: :class:`.VoiceRegion`
The region for the voice communication server.
Defaults to :attr:`.VoiceRegion.us_west`.
icon: :class:`bytes`
@ -979,9 +989,9 @@ class Client:
Raises
------
HTTPException
:exc:`.HTTPException`
Guild creation failed.
InvalidArgument
:exc:`.InvalidArgument`
Invalid icon image format given. Must be PNG or JPG.
Returns
@ -1025,9 +1035,9 @@ class Client:
Raises
-------
NotFound
:exc:`.NotFound`
The invite has expired or is invalid.
HTTPException
:exc:`.HTTPException`
Getting the invite failed.
Returns
@ -1055,11 +1065,11 @@ class Client:
Raises
-------
Forbidden
:exc:`.Forbidden`
You do not have permissions to revoke invites.
NotFound
:exc:`.NotFound`
The invite is invalid or expired.
HTTPException
:exc:`.HTTPException`
Revoking the invite failed.
"""
@ -1084,9 +1094,9 @@ class Client:
Raises
-------
Forbidden
:exc:`.Forbidden`
The widget for this guild is disabled.
HTTPException
:exc:`.HTTPException`
Retrieving the widget failed.
Returns
@ -1101,17 +1111,17 @@ class Client:
async def application_info(self):
"""|coro|
Retrieve's the bot's application information.
Retrieves the bot's application information.
Raises
-------
HTTPException
:exc:`.HTTPException`
Retrieving the information failed somehow.
Returns
--------
:class:`.AppInfo`
A namedtuple representing the application info.
The bot's application information.
"""
data = await self.http.application_info()
if 'rpc_origins' not in data:
@ -1137,9 +1147,9 @@ class Client:
Raises
-------
NotFound
:exc:`.NotFound`
A user with this ID does not exist.
HTTPException
:exc:`.HTTPException`
Fetching the user failed.
Returns
@ -1162,9 +1172,9 @@ class Client:
Raises
-------
Forbidden
:exc:`.Forbidden`
Not allowed to fetch profiles.
HTTPException
:exc:`.HTTPException`
Fetching the profile failed.
Returns
@ -1237,11 +1247,11 @@ class Client:
Raises
--------
HTTPException
:exc:`.HTTPException`
Retrieving the webhook failed.
NotFound
:exc:`.NotFound`
Invalid webhook ID.
Forbidden
:exc:`.Forbidden`
You do not have permission to fetch this webhook.
Returns

8
discord/colour.py
View File

@ -84,21 +84,21 @@ class Colour:
@property
def r(self):
"""Returns the red component of the colour."""
""":class:`int`: Returns the red component of the colour."""
return self._get_byte(2)
@property
def g(self):
"""Returns the green component of the colour."""
""":class:`int`: Returns the green component of the colour."""
return self._get_byte(1)
@property
def b(self):
"""Returns the blue component of the colour."""
""":class:`int`: Returns the blue component of the colour."""
return self._get_byte(0)
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)
@classmethod

5
discord/embeds.py
View File

@ -87,10 +87,9 @@ class Embed:
url: :class:`str`
The URL of the embed.
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.
This can be set during initialisation.
colour: :class:`Colour` or :class:`int`
colour: Union[:class:`Colour`, :class:`int`]
The colour code of the embed. Aliased to ``color`` as well.
This can be set during initialisation.
Empty

4
discord/emoji.py
View File

@ -222,12 +222,12 @@ class Emoji:
@property
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)
@property
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'
url = "https://cdn.discordapp.com/emojis/{0.id}.{1}".format(self, _format)
return Asset(self._state, url)

8
discord/errors.py
View File

@ -72,12 +72,10 @@ class HTTPException(DiscordException):
Attributes
------------
response: aiohttp.ClientResponse
response: :class:`aiohttp.ClientResponse`
The response of the failed HTTP request. This is an
instance of `aiohttp.ClientResponse`__. In some cases
this could also be a ``requests.Response``.
__ http://aiohttp.readthedocs.org/en/stable/client_reference.html#aiohttp.ClientResponse
instance of :class:`aiohttp.ClientResponse`. In some cases
this could also be a :class:`requests.Response`.
text: :class:`str`
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.
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.
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.
call_once: :class:`bool`
If the function should only be called once per
:meth:`.Command.invoke` call.
:meth:`Command.invoke` call.
"""
if call_once:
@ -241,7 +241,7 @@ class BotBase(GroupMixin):
r"""A decorator that adds a "call once" global check to the bot.
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
or :meth:`.Command.can_run` is called. This type of check
@ -288,6 +288,11 @@ class BotBase(GroupMixin):
-----------
user: :class:`.abc.User`
The user to check for.
Returns
--------
:class:`bool`
Whether the user is the owner.
"""
if self.owner_id is None:
@ -314,7 +319,7 @@ class BotBase(GroupMixin):
Parameters
-----------
coro
coro: :ref:`coroutine <coroutine>`
The coroutine to register as the pre-invoke hook.
Raises
@ -347,7 +352,7 @@ class BotBase(GroupMixin):
Parameters
-----------
coro
coro: :ref:`coroutine <coroutine>`
The coroutine to register as the post-invoke hook.
Raises
@ -420,7 +425,7 @@ class BotBase(GroupMixin):
event listener. Basically this allows you to listen to multiple
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
--------

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

@ -34,7 +34,7 @@ __all__ = (
)
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
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
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
-----------
@ -61,12 +61,12 @@ class Context(discord.abc.Messageable):
invoked_subcommand
The subcommand (i.e. :class:`.Command` or its subclasses) that was
invoked. If no valid subcommand was invoked then this is equal to
`None`.
``None``.
subcommand_passed: Optional[:class:`str`]
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
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`
A boolean that indicates if the command failed to be parsed, checked,
or invoked.

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

@ -66,7 +66,7 @@ class Converter:
special cased ``discord`` classes.
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):
@ -96,7 +96,7 @@ class IDConverter(Converter):
return self._id_regex.match(argument)
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
is done by the global cache.
@ -134,7 +134,7 @@ class MemberConverter(IDConverter):
return result
class UserConverter(IDConverter):
"""Converts to a :class:`User`.
"""Converts to a :class:`~discord.User`.
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))
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
is done by the global cache.
@ -249,7 +249,7 @@ class TextChannelConverter(IDConverter):
return result
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
is done by the global cache.
@ -287,7 +287,7 @@ class VoiceChannelConverter(IDConverter):
return result
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
is done by the global cache.
@ -326,7 +326,7 @@ class CategoryChannelConverter(IDConverter):
return result
class ColourConverter(Converter):
"""Converts to a :class:`Colour`.
"""Converts to a :class:`~discord.Colour`.
The following formats are accepted:
@ -355,7 +355,7 @@ class ColourConverter(Converter):
return method()
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
is done by the global cache.
@ -382,12 +382,12 @@ class RoleConverter(IDConverter):
return result
class GameConverter(Converter):
"""Converts to :class:`Game`."""
"""Converts to :class:`~discord.Game`."""
async def convert(self, ctx, argument):
return discord.Game(name=argument)
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`.
"""
@ -399,7 +399,7 @@ class InviteConverter(Converter):
raise BadArgument('Invite is invalid or expired') from exc
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
fails, then it checks the client's global cache.
@ -439,7 +439,7 @@ class EmojiConverter(IDConverter):
return result
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.
"""
@ -460,7 +460,7 @@ class clean_content(Converter):
"""Converts the argument to mention scrubbed version of
said content.
This behaves similarly to :attr:`.Message.clean_content`.
This behaves similarly to :attr:`~discord.Message.clean_content`.
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
:exc:`.DisabledCommand` is raised to the :func:`.on_command_error`
event. Defaults to ``True``.
parent: Optional[command]
parent: Optional[:class:`Command`]
The parent command that this command belongs to. ``None`` if there
isn't one.
checks
checks: List[Callable[..., :class:`bool`]]
A list of predicates that verifies if the command could be executed
with the given :class:`.Context` as the sole parameter. If an exception
is necessary to be thrown to signal failure, then one inherited from
@ -297,7 +297,7 @@ class Command(_BaseCommand):
return other
def copy(self):
"""Creates a copy of this :class:`Command`."""
"""Creates a copy of this command."""
ret = self.__class__(self.callback, **self.__original_kwargs__)
return self._ensure_assignment_on_copy(ret)
@ -505,7 +505,7 @@ class Command(_BaseCommand):
@property
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,
in ``?one two three`` the parent name would be ``one two``.
@ -520,7 +520,7 @@ class Command(_BaseCommand):
@property
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`.
@ -550,7 +550,7 @@ class Command(_BaseCommand):
@property
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.
For example, in ``?one two three`` the qualified name would be
@ -688,7 +688,7 @@ class Command(_BaseCommand):
Parameters
-----------
ctx: :class:`.Context.`
ctx: :class:`.Context`
The invocation context to use when checking the commands cooldown status.
Returns
@ -821,12 +821,12 @@ class Command(_BaseCommand):
@property
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
@property
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.
If that lookup leads to an empty string then the first line of the
@ -851,7 +851,7 @@ class Command(_BaseCommand):
@property
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:
return self.usage
@ -971,7 +971,7 @@ class GroupMixin:
Parameters
-----------
command
command: :class:`Command`
The command to add.
Raises
@ -1107,7 +1107,7 @@ class Group(GroupMixin, Command):
Attributes
-----------
invoke_without_command: :class:`bool`
invoke_without_command: Optional[:class:`bool`]
Indicates if the group callback should begin parsing and
invocation only if no subcommand was found. Useful for
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
that the checks and the parsing dictated by its parameters
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.
Defaults to ``False``.
"""
@ -1301,7 +1301,7 @@ def check(predicate):
Parameters
-----------
predicate: Callable[:class:`Context`, :class:`bool`]
predicate: Callable[[:class:`Context`], :class:`bool`]
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)
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.
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)
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.

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

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

2
discord/file.py
View File

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

26
discord/guild.py
View File

@ -191,8 +191,8 @@ class Guild(Hashable):
----------
name: :class:`str`
The guild name.
emojis
A :class:`tuple` of :class:`Emoji` that the guild owns.
emojis: Tuple[:class:`Emoji`, ...]
All emojis that the guild owns.
region: :class:`VoiceRegion`
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.
@ -586,7 +586,7 @@ class Guild(Hashable):
return bool(self.icon and self.icon.startswith('a_'))
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
'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()
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
size must be a power of 2 between 16 and 4096.
@ -652,7 +652,7 @@ class Guild(Hashable):
return self.splash_url_as()
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
size must be a power of 2 between 16 and 4096.
@ -698,7 +698,7 @@ class Guild(Hashable):
@property
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
if count is None:
return None
@ -706,7 +706,7 @@ class Guild(Hashable):
@property
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)
def get_member_named(self, name):
@ -1483,10 +1483,10 @@ class Guild(Hashable):
This is aliased to ``color`` as well.
hoist: :class:`bool`
Indicates if the role should be shown separately in the member list.
Defaults to False.
Defaults to ``False``.
mentionable: :class:`bool`
Indicates if the role should be mentionable by others.
Defaults to False.
Defaults to ``False``.
reason: Optional[:class:`str`]
The reason for creating this role. Shows up on the audit log.
@ -1697,15 +1697,15 @@ class Guild(Hashable):
-----------
limit: Optional[:class:`int`]
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.
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.
If a date is provided it must be a timezone-naive datetime representing UTC time.
oldest_first: :class:`bool`
If set to true, return entries in oldest->newest order. Defaults to True if
``after`` is specified, otherwise False.
If set to ``True``, return entries in oldest->newest order. Defaults to True if
``after`` is specified, otherwise ``False``.
user: :class:`abc.Snowflake`
The moderator to filter entries from.
action: :class:`AuditLogAction`

20
discord/invite.py
View File

@ -71,12 +71,12 @@ class PartialInviteChannel(namedtuple('PartialInviteChannel', 'id name type')):
@property
def mention(self):
""":class:`str` : The string that allows you to mention the channel."""
""":class:`str`: The string that allows you to mention the channel."""
return '<#%s>' % self.id
@property
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)
class PartialInviteGuild:
@ -146,7 +146,7 @@ class PartialInviteGuild:
@property
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)
@property
@ -155,7 +155,7 @@ class PartialInviteGuild:
return self.icon_url_as()
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)
@property
@ -164,7 +164,7 @@ class PartialInviteGuild:
return self.banner_url_as()
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)
@property
@ -173,7 +173,7 @@ class PartialInviteGuild:
return self.splash_url_as()
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)
class Invite(Hashable):
@ -232,11 +232,11 @@ class Invite(Hashable):
The guild the invite is for.
revoked: :class:`bool`
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.
temporary: :class:`bool`
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`
How many times the invite has been used.
max_uses: :class:`int`
@ -303,12 +303,12 @@ class Invite(Hashable):
@property
def id(self):
"""Returns the proper code portion of the invite."""
""":class:`str`: Returns the proper code portion of the invite."""
return self.code
@property
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
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.
limit: :class:`int`
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.
after: :class:`abc.Snowflake`
after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
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
limit is an even number, this will return at most limit+1 messages.
oldest_first: :class:`bool`
If set to true, return messages in oldest->newest order. Defaults to
True if ``after`` is specified, otherwise False.
oldest_first: Optional[:class:`bool`]
If set to ``True``, return messages in oldest->newest order. Defaults to
True if ``after`` is specified, otherwise ``False``.
"""
def __init__(self, messageable, limit,
@ -482,9 +482,9 @@ class GuildIterator(_AsyncIterator):
The client to retrieve the guilds from.
limit: :class:`int`
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.
after: :class:`Snowflake`
after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
Object after which all guilds must be.
"""
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'))
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
@property
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
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
@ -309,11 +309,19 @@ class Member(discord.abc.Messageable, _BaseUser):
return role.colour
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
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'
role.
@ -331,14 +339,14 @@ class Member(discord.abc.Messageable, _BaseUser):
@property
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:
return '<@!%s>' % self.id
return '<@%s>' % self.id
@property
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
if they have a guild specific nickname then that
@ -348,7 +356,7 @@ class Member(discord.abc.Messageable, _BaseUser):
@property
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.
.. note::
@ -394,7 +402,7 @@ class Member(discord.abc.Messageable, _BaseUser):
@property
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
hierarchy chain.
@ -435,21 +443,21 @@ class Member(discord.abc.Messageable, _BaseUser):
async def ban(self, **kwargs):
"""|coro|
Bans this member. Equivalent to :meth:`Guild.ban`
Bans this member. Equivalent to :meth:`Guild.ban`.
"""
await self.guild.ban(self, **kwargs)
async def unban(self, *, reason=None):
"""|coro|
Unbans this member. Equivalent to :meth:`Guild.unban`
Unbans this member. Equivalent to :meth:`Guild.unban`.
"""
await self.guild.unban(self, reason=reason)
async def kick(self, *, reason=None):
"""|coro|
Kicks this member. Equivalent to :meth:`Guild.kick`
Kicks this member. Equivalent to :meth:`Guild.kick`.
"""
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.
deafen: :class:`bool`
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.
voice_channel: Optional[:class:`VoiceChannel`]
The voice channel to move the member to.
@ -577,12 +585,12 @@ class Member(discord.abc.Messageable, _BaseUser):
Parameters
-----------
\*roles: :class:`Snowflake`
\*roles: :class:`abc.Snowflake`
An argument list of :class:`abc.Snowflake` representing a :class:`Role`
to give to the member.
reason: Optional[:class:`str`]
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
operations will always be applied regardless of the current
state of the cache.
@ -615,7 +623,7 @@ class Member(discord.abc.Messageable, _BaseUser):
Parameters
-----------
\*roles: :class:`Snowflake`
\*roles: :class:`abc.Snowflake`
An argument list of :class:`abc.Snowflake` representing a :class:`Role`
to remove from the member.
reason: Optional[:class:`str`]

30
discord/message.py
View File

@ -88,7 +88,7 @@ class Attachment:
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
to use. If a filename is passed then a file is created with that
filename and used instead.
@ -175,7 +175,7 @@ class Message:
type: :class:`MessageType`
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`.
author
author: :class:`abc.User`
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.
content: :class:`str`
@ -185,7 +185,7 @@ class Message:
This is typically non-important.
embeds: List[:class:`Embed`]
A list of embeds the message has.
channel
channel: Union[:class:`abc.Messageable`]
The :class:`TextChannel` that the message was sent from.
Could be a :class:`DMChannel` or :class:`GroupChannel` if it's a private message.
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.
Rather this boolean indicates if either the ``@everyone`` or the ``@here`` text is in the message
**and** it did end up mentioning.
mentions: :class:`list`
mentions: List[:class:`abc.User`]
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
: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
not rely on it. This is a discord limitation, not one with the library.
channel_mentions: :class:`list`
channel_mentions: List[:class:`abc.GuildChannel`]
A list of :class:`abc.GuildChannel` that were mentioned. If the message is in a private message
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
then the list is always empty.
id: :class:`int`
@ -408,8 +406,8 @@ class Message:
@utils.cached_slot_property('_cs_raw_mentions')
def raw_mentions(self):
"""A property that returns an array of user IDs matched with
the syntax of <@user_id> in the message content.
"""List[:class:`int`]: A property that returns an array of user IDs matched with
the syntax of ``<@user_id>`` in the message content.
This allows you to receive the user IDs of mentioned users
even in a private message context.
@ -418,15 +416,15 @@ class Message:
@utils.cached_slot_property('_cs_raw_channel_mentions')
def raw_channel_mentions(self):
"""A property that returns an array of channel IDs matched with
the syntax of <#channel_id> in the message content.
"""List[:class:`int`]: A property that returns an array of channel IDs matched with
the syntax of ``<#channel_id>`` in the message content.
"""
return [int(x) for x in re.findall(r'<#([0-9]+)>', self.content)]
@utils.cached_slot_property('_cs_raw_role_mentions')
def raw_role_mentions(self):
"""A property that returns an array of role IDs matched with
the syntax of <@&role_id> in the message content.
"""List[:class:`int`]: A property that returns an array of role IDs matched with
the syntax of ``<@&role_id>`` in the message content.
"""
return [int(x) for x in re.findall(r'<@&([0-9]+)>', self.content)]
@ -499,12 +497,12 @@ class Message:
@property
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)
@property
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
@property

2
discord/object.py
View File

@ -69,5 +69,5 @@ class Object(Hashable):
@property
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)

19
discord/opus.py
View File

@ -115,21 +115,13 @@ def load_opus(name):
"""Loads the libopus shared library for use with voice.
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.
.. _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.
This function propagates the exceptions thrown.
.. note::
On Windows, this function should not need to be called as the binaries
are automatically loaded.
.. warning::
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
the load will throw an exception.
.. note::
On Windows, this function should not need to be called as the binaries
are automatically loaded.
.. note::
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``.
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.
Parameters
@ -154,7 +151,7 @@ def load_opus(name):
def is_loaded():
"""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.

86
discord/permissions.py
View File

@ -97,25 +97,25 @@ class Permissions:
return self._perm_iterator()
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):
return (self.value & other.value) == self.value
else:
raise TypeError("cannot compare {} with {}".format(self.__class__.__name__, other.__class__.__name__))
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):
return (self.value | other.value) == self.value
else:
raise TypeError("cannot compare {} with {}".format(self.__class__.__name__, other.__class__.__name__))
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
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
__le__ = is_subset
@ -126,7 +126,7 @@ class Permissions:
@classmethod
def none(cls):
"""A factory method that creates a :class:`Permissions` with all
permissions set to False."""
permissions set to ``False``."""
return cls(0)
@classmethod
@ -138,7 +138,7 @@ class Permissions:
@classmethod
def all_channel(cls):
"""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:
- manage_guild
@ -153,21 +153,22 @@ class Permissions:
@classmethod
def general(cls):
"""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)
@classmethod
def text(cls):
"""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)
@classmethod
def voice(cls):
"""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)
def update(self, **kwargs):
r"""Bulk updates this permission object.
@ -217,7 +218,7 @@ class Permissions:
@property
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)
@create_instant_invite.setter
@ -226,7 +227,7 @@ class Permissions:
@property
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)
@kick_members.setter
@ -235,7 +236,7 @@ class Permissions:
@property
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)
@ban_members.setter
@ -244,7 +245,7 @@ class Permissions:
@property
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.
"""
@ -256,7 +257,7 @@ class Permissions:
@property
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."""
return self._bit(4)
@ -267,7 +268,7 @@ class Permissions:
@property
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)
@manage_guild.setter
@ -276,7 +277,7 @@ class Permissions:
@property
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)
@add_reactions.setter
@ -285,7 +286,7 @@ class Permissions:
@property
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)
@view_audit_log.setter
@ -294,7 +295,7 @@ class Permissions:
@property
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)
@priority_speaker.setter
@ -303,7 +304,7 @@ class Permissions:
@property
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)
@stream.setter
@ -312,7 +313,7 @@ class Permissions:
@property
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)
@read_messages.setter
@ -321,7 +322,7 @@ class Permissions:
@property
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)
@send_messages.setter
@ -330,7 +331,7 @@ class Permissions:
@property
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)
@send_tts_messages.setter
@ -339,7 +340,12 @@ class Permissions:
@property
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)
@manage_messages.setter
@ -348,7 +354,7 @@ class Permissions:
@property
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)
@embed_links.setter
@ -357,7 +363,7 @@ class Permissions:
@property
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)
@attach_files.setter
@ -366,7 +372,7 @@ class Permissions:
@property
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)
@read_message_history.setter
@ -375,7 +381,7 @@ class Permissions:
@property
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)
@mention_everyone.setter
@ -384,7 +390,7 @@ class Permissions:
@property
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)
@external_emojis.setter
@ -395,7 +401,7 @@ class Permissions:
@property
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)
@connect.setter
@ -404,7 +410,7 @@ class Permissions:
@property
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)
@speak.setter
@ -413,7 +419,7 @@ class Permissions:
@property
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)
@mute_members.setter
@ -422,7 +428,7 @@ class Permissions:
@property
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)
@deafen_members.setter
@ -431,7 +437,7 @@ class Permissions:
@property
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)
@move_members.setter
@ -440,7 +446,7 @@ class Permissions:
@property
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)
@use_voice_activation.setter
@ -449,7 +455,7 @@ class Permissions:
@property
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)
@change_nickname.setter
@ -458,7 +464,7 @@ class Permissions:
@property
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)
@manage_nicknames.setter
@ -467,7 +473,7 @@ class Permissions:
@property
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.
"""
@ -479,7 +485,7 @@ class Permissions:
@property
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)
@manage_webhooks.setter
@ -488,7 +494,7 @@ class Permissions:
@property
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)
@manage_emojis.setter
@ -604,7 +610,7 @@ class PermissionOverwrite:
"""Checks if the permission overwrite is currently empty.
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())

15
discord/player.py
View File

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

3
discord/raw_models.py
View File

@ -90,8 +90,7 @@ class RawMessageUpdateEvent(_RawReprMixin):
message_id: :class:`int`
The message ID that got updated.
data: :class:`dict`
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>`_
cached_message: Optional[:class:`Message`]
The cached message, if found in the internal message cache.
"""

6
discord/reaction.py
View File

@ -54,7 +54,7 @@ class Reaction:
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.
count: :class:`int`
Number of times this reaction was made
@ -99,7 +99,7 @@ class Reaction:
Remove the reaction by the provided :class:`User` from the message.
If the reaction is not your own (i.e. ``user`` parameter is not you) then
the :attr:`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 :class:`abc.Snowflake` abc.
@ -139,7 +139,7 @@ class Reaction:
Flattening into a list: ::
users = await reaction.users().flatten()
# users is now a list...
# users is now a list of User...
winner = random.choice(users)
await channel.send('{} has won the raffle.'.format(winner))

6
discord/role.py
View File

@ -158,17 +158,17 @@ class Role(Hashable):
@property
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)
@property
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
@property
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
if self.is_default():
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
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.
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
0 to ``shard_count - 1``.
@ -163,7 +163,7 @@ class AutoShardedClient(Client):
def latency(self):
""":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
: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`]]
The activity being done. ``None`` if no currently active activity is done.
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.
afk: :class:`bool`
Indicates if you are going AFK. This allows the discord

59
discord/user.py
View File

@ -114,7 +114,7 @@ class BaseUser(_BaseUser):
@property
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
the default avatar is returned instead.
@ -125,11 +125,11 @@ class BaseUser(_BaseUser):
return self.avatar_url_as(format=None, size=1024)
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_'))
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
the default avatar is returned instead.
@ -166,28 +166,35 @@ class BaseUser(_BaseUser):
@property
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))
@property
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))
@property
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`.
There is an alias for this under ``color``.
There is an alias for this named :meth:`color`.
"""
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
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)
def permissions_in(self, channel):
@ -208,14 +215,14 @@ class BaseUser(_BaseUser):
@property
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."""
return snowflake_time(self.id)
@property
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
if they have a guild specific nickname then that
@ -324,13 +331,13 @@ class ClientUser(BaseUser):
Returns
--------
Optional[:class:`Relationship`]
The relationship if available or ``None``
The relationship if available or ``None``.
"""
return self._relationships.get(user_id)
@property
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::
@ -340,7 +347,7 @@ class ClientUser(BaseUser):
@property
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::
@ -350,7 +357,7 @@ class ClientUser(BaseUser):
@property
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::
@ -366,14 +373,14 @@ class ClientUser(BaseUser):
If a bot account is used then a password field is optional,
otherwise it is required.
Note
-----
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
then the file must be opened via ``open('some_filename', 'rb')`` and
the :term:`py:bytes-like object` is given through the use of ``fp.read()``.
.. note::
The only image formats supported for uploading is JPEG and PNG.
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
then the file must be opened via ``open('some_filename', 'rb')`` and
the :term:`py:bytes-like object` is given through the use of ``fp.read()``.
The only image formats supported for uploading is JPEG and PNG.
Parameters
-----------
@ -542,7 +549,7 @@ class ClientUser(BaseUser):
inline_embed_media: :class:`bool`
Whether or not to display videos and images from links posted in chat.
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.
message_display_compact: :class:`bool`
Whether or not to use the compact Discord display mode.
@ -654,7 +661,7 @@ class User(BaseUser, discord.abc.Messageable):
@property
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
: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]
def is_friend(self):
""":class:`bool`: Checks if the user is your friend.
"""Checks if the user is your friend.
.. note::
@ -723,7 +730,7 @@ class User(BaseUser, discord.abc.Messageable):
return r.type is RelationshipType.friend
def is_blocked(self):
""":class:`bool`: Checks if the user is blocked.
"""Checks if the user is blocked.
.. 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`
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
permissions.
guild: :class:`Guild`
guild: :class:`~discord.Guild`
The guild to pre-select in the authorization screen, if available.
redirect_uri: :class:`str`
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):
"""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)
def time_snowflake(datetime_obj, high=False):
"""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 higher end of a range, use time_snowflake(high=True) + 1 to be inclusive, high=False 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
Parameters
-----------
datetime_obj
datetime_obj: :class:`datetime.datetime`
A timezone-naive datetime object representing UTC time.
high: :class:`bool`
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)
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.
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.
.. _filter: https://docs.python.org/3.6/library/functions.html#filter
Parameters
-----------
predicate
@ -207,7 +204,7 @@ def find(predicate, seq):
def get(iterable, **attrs):
r"""A helper that returns the first element in the iterable that meets
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
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):
"""
Resolves an invite from a :class:`Invite`, URL or ID
Resolves an invite from a :class:`~discord.Invite`, URL or ID
Parameters
-----------
invite: Union[:class:`Invite`, :class:`Object`, :class:`str`]
invite: Union[:class:`~discord.Invite`, :class:`~discord.Object`, :class:`str`]
The invite.
Returns

12
discord/voice_client.py
View File

@ -84,7 +84,7 @@ class VoiceClient:
The endpoint we are connecting to.
channel: :class:`abc.Connectable`
The voice channel connected to.
loop
loop: :class:`asyncio.AbstractEventLoop`
The event loop that the voice client is running on.
"""
def __init__(self, state, timeout, channel):
@ -301,7 +301,7 @@ class VoiceClient:
await self.main_ws.voice_state(guild_id, channel.id)
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()
# audio related
@ -345,7 +345,7 @@ class VoiceClient:
-----------
source: :class:`AudioSource`
The audio source we're reading from.
after
after: Callable[[:class:`Exception`], Any]
The finalizer that is called after the stream is exhausted.
All exceptions it throws are silently discarded. This function
must have a single parameter, ``error``, that denotes an
@ -420,16 +420,16 @@ class VoiceClient:
Parameters
----------
data: bytes
data: :class:`bytes`
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.
Raises
-------
ClientException
You are not connected.
OpusError
opus.OpusError
Encoding the data failed.
"""

24
discord/webhook.py
View File

@ -164,7 +164,7 @@ class AsyncWebhookAdapter(WebhookAdapter):
Parameters
-----------
session: aiohttp.ClientSession
session: :class:`aiohttp.ClientSession`
The session to use to send requests.
"""
@ -235,7 +235,7 @@ class AsyncWebhookAdapter(WebhookAdapter):
class RequestsWebhookAdapter(WebhookAdapter):
"""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
-----------
@ -369,9 +369,9 @@ class Webhook:
it bound to a websocket connection using the :meth:`~.Webhook.from_url` or
: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
``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
@ -383,7 +383,7 @@ class Webhook:
webhook = Webhook.from_url('url-here', adapter=AsyncWebhookAdapter(session))
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
@ -456,8 +456,8 @@ class Webhook:
The authentication token of the webhook.
adapter: :class:`WebhookAdapter`
The webhook adapter to use when sending requests. This is
typically :class:`AsyncWebhookAdapter` for ``aiohttp`` or
:class:`RequestsWebhookAdapter` for ``requests``.
typically :class:`AsyncWebhookAdapter` for :doc:`aiohttp <aio:index>` or
:class:`RequestsWebhookAdapter` for :doc:`req:index`.
"""
if not isinstance(adapter, WebhookAdapter):
@ -480,8 +480,8 @@ class Webhook:
The URL of the webhook.
adapter: :class:`WebhookAdapter`
The webhook adapter to use when sending requests. This is
typically :class:`AsyncWebhookAdapter` for ``aiohttp`` or
:class:`RequestsWebhookAdapter` for ``requests``.
typically :class:`AsyncWebhookAdapter` for :doc:`aiohttp <aio:index>` or
:class:`RequestsWebhookAdapter` for :doc:`req:index`.
Raises
-------
@ -518,12 +518,12 @@ class Webhook:
@property
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)
@property
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
the default avatar is returned instead.
@ -534,7 +534,7 @@ class Webhook:
return self.avatar_url_as()
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
the default avatar is returned instead.

4
discord/widget.py
View File

@ -73,7 +73,7 @@ class WidgetChannel(namedtuple('WidgetChannel', 'id name position')):
@property
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)
class WidgetMember(BaseUser):
@ -229,7 +229,7 @@ class Widget:
"""|coro|
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.
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__
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
-------
@ -94,7 +94,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
.. 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``
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.
:param shard_id: The shard ID that is ready.
:type shard_id: :class:`int`
.. 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.
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
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`.
: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
exception.
: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.
Could be :class:`bytes` for a binary message or :class:`str`
for a regular message.
:type msg: Union[:class:`bytes`, :class:`str`]
.. 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`.
:param channel: The location where the typing originated from.
:type channel: :class:`abc.Messageable`
: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)
@ -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
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)
@ -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.
:param message: A :class:`Message` of the deleted message.
:param message: The deleted message.
:type message: :class:`Message`
.. 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.
: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)
@ -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.
:param before: A :class:`Message` of the previous version of the message.
:param after: A :class:`Message` of the current version of the message.
:param before: The previous 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)
@ -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`
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.
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`.
:param reaction: A :class:`Reaction` showing the current state of the reaction.
:param user: A :class:`User` or :class:`Member` of the user who added the reaction.
:param reaction: The current state of 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)
@ -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`.
:param reaction: A :class:`Reaction` showing the current state of the reaction.
:param user: A :class:`User` or :class:`Member` of the user whose reaction was removed.
:param reaction: The current state of 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_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
will not be called.
:param message: The :class:`Message` that had its reactions cleared.
:param reactions: A list of :class:`Reaction`\s that were removed.
:param message: The message that had its reactions cleared.
:type message: :class:`Message`
:param reactions: The reactions that were removed.
:type reactions: List[:class:`Reaction`]
.. 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.
: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)
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 after: The :class:`GroupChannel` that got updated with the updated info.
:param before: The updated group channel's old 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)
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 last_pin: A ``datetime.datetime`` object representing when the latest message
was pinned or ``None`` if there are no pins.
:param channel: The private channel that had its pins updated.
:type channel: :class:`abc.PrivateChannel`
: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)
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`.
: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)
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 after: The :class:`abc.GuildChannel` that got updated with the updated info.
:param before: The updated guild channel's old 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)
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 last_pin: A ``datetime.datetime`` object representing when the latest message
was pinned or ``None`` if there are no pins.
:param channel: The guild channel that had its pins updated.
:type channel: :class:`abc.GuildChannel`
: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)
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)
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)
on_member_remove(member)
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)
@ -445,8 +474,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- nickname
- roles
:param before: The :class:`Member` that updated their profile with the old info.
:param after: The :class:`Member` that updated their profile with the updated info.
:param before: The updated member's old info.
:type before: :class:`Member`
:param after: The updated member's updated info.
:type after: :class:`Member`
.. function:: on_user_update(before, after)
@ -458,15 +489,18 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- username
- discriminator
:param before: The :class:`User` that updated their profile with the old info.
:param after: The :class:`User` that updated their profile with the updated info.
:param before: The updated user's old info.
:type before: :class:`User`
:param after: The updated user's updated info.
:type after: :class:`User`
.. function:: on_guild_join(guild)
Called when a :class:`Guild` is either created by the :class:`Client` or when the
: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)
@ -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
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)
@ -493,8 +528,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- Changed AFK timeout
- etc
:param before: The :class:`Guild` prior to being updated.
:param after: The :class:`Guild` after being updated.
:param before: The guild prior to being updated.
:type before: :class:`Guild`
:param after: The guild after being updated.
:type after: :class:`Guild`
.. function:: on_guild_role_create(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`.
: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)
Called when a :class:`Role` is changed guild-wide.
:param before: The :class:`Role` that updated with the old info.
:param after: The :class:`Role` that updated with the updated info.
:param before: The updated role's old 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)
Called when a :class:`Guild` adds or removes :class:`Emoji`.
:param guild: The :class:`Guild` who got their emojis updated.
:param before: A list of :class:`Emoji` before the update.
:param after: A list of :class:`Emoji` after the update.
:param guild: The guild who got their emojis updated.
:type guild: :class:`Guild`
: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)
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 a guild administrator.
:param member: The :class:`Member` whose voice states changed.
:param before: The :class:`VoiceState` prior to the changes.
:param after: The :class:`VoiceState` after to the changes.
:param member: The member whose voice states changed.
:type member: :class:`Member`
: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)
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.
Can be either :class:`User` or :class:`Member` depending if
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)
Called when a :class:`User` gets unbanned from a :class:`Guild`.
:param guild: The :class:`Guild` the user got unbanned from.
:param user: The :class:`User` that got unbanned.
:param guild: The guild the user got unbanned from.
:type guild: :class:`Guild`
:param user: The user that got unbanned.
:type user: :class:`User`
.. function:: on_group_join(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`.
:param channel: The group that the user joined or left.
:type channel: :class:`GroupChannel`
:param user: The user that joined or left.
:type user: :class:`User`
.. function:: on_relationship_add(relationship)
on_relationship_remove(relationship)
@ -574,6 +626,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
:class:`ClientUser`.
:param relationship: The relationship that was added or removed.
:type relationship: :class:`Relationship`
.. 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.
:param before: The previous relationship status.
:type before: :class:`Relationship`
:param after: The updated relationship status.
:type after: :class:`Relationship`
.. _discord-api-utils:
@ -600,6 +655,8 @@ Utility Functions
.. autofunction:: discord.utils.escape_mentions
.. autofunction:: discord.utils.resolve_invite
Profile
---------
@ -659,9 +716,7 @@ Enumerations
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.
All enumerations are subclasses of `enum`_.
.. _enum: https://docs.python.org/3/library/enum.html
All enumerations are subclasses of :class:`enum.Enum`.
.. class:: ChannelType
@ -1114,7 +1169,7 @@ All enumerations are subclasses of `enum`_.
A member prune was triggered.
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
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
capable of being used in an `async for <https://docs.python.org/3/reference/compound_stmts.html#the-async-for-statement>`_
statement.
capable of being used in an :ref:`async for statement <py:async for>`.
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.
Unlike :func:`utils.find`\, the predicate provided can be a
coroutine.
|coroutine_link|_.
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)
: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``.
.. comethod:: flatten()
@ -1554,10 +1608,10 @@ Certain utilities make working with async iterators easier, detailed below.
.. 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
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: ::
@ -1567,14 +1621,14 @@ Certain utilities make working with async iterators easier, detailed below.
async for content in channel.history().map(transform):
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.
.. 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
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: ::
@ -1584,7 +1638,7 @@ Certain utilities make working with async iterators easier, detailed below.
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.
@ -1678,7 +1732,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. 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
@ -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.
See also :meth:`Guild.vanity_invite` and :meth:`Guild.change_vanity_invite`.
See also :meth:`Guild.vanity_invite` and :meth:`Guild.edit`.
.. 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
*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
``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
*Optional[str]* – The nickname of a member.
Optional[:class:`str`] – The nickname of a member.
See also :attr:`Member.nick`
@ -1930,12 +1984,12 @@ interface, :meth:`WebhookAdapter.request`.
Abstract Base Classes
-----------------------
An 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
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 :doc:`abc <py:library/abc>` is
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.
.. autoclass:: discord.abc.Snowflake
@ -1985,12 +2039,9 @@ the user of the library.
.. 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.
More information about ``__slots__`` can be found
`in the official python documentation <https://docs.python.org/3/reference/datamodel.html#slots>`_.
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
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.
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.
More information about ``__slots__`` can be found
`in the official python documentation <https://docs.python.org/3/reference/datamodel.html#slots>`_.
Object
~~~~~~~

11
docs/conf.py
View File

@ -49,14 +49,15 @@ extlinks = {
# Links used for cross-referencing stuff in other documentation
intersphinx_mapping = {
'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 = """
.. |coro| replace:: This function is a |corourl|_.
.. |maybecoro| replace:: This function *could be a* |corourl|_.
.. |corourl| replace:: *coroutine*
.. _corourl: https://docs.python.org/3/library/asyncio-task.html#coroutine
.. |coro| replace:: This function is a |coroutine_link|_.
.. |maybecoro| replace:: This function *could be a* |coroutine_link|_.
.. |coroutine_link| replace:: *coroutine*
.. _coroutine_link: https://docs.python.org/3/library/asyncio-task.html#coroutine
"""
# 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`).
:param ctx: The invocation context.
:type ctx: :class:`Context`
:type ctx: :class:`.Context`
:param error: The error that was raised.
:type error: :class:`CommandError` derived
:type error: :class:`.CommandError` derived
.. function:: on_command(ctx)
@ -50,7 +50,7 @@ are custom to the command extension module.
error or completes.
:param ctx: The invocation context.
:type ctx: :class:`Context`
:type ctx: :class:`.Context`
.. function:: on_command_completion(ctx)
@ -60,7 +60,7 @@ are custom to the command extension module.
passed and the user input it correctly.
:param ctx: The invocation context.
:type ctx: :class:`Context`
:type ctx: :class:`.Context`
.. _ext_commands_api_command:

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

@ -129,7 +129,7 @@ at all:
.. 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.
Keyword-Only Arguments

11
docs/faq.rst
View File

@ -18,7 +18,7 @@ Questions regarding coroutines and asyncio belong here.
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.
This allows for your program to be doing multiple things at the same time without using threads or complicated
multiprocessing.
@ -51,9 +51,10 @@ instead. Similar to this example: ::
# good
await asyncio.sleep(10)
Another common source of blocking for too long is using HTTP requests with the famous module ``requests``. While ``requests``
is an amazing module for non-asynchronous programming, it is not a good choice for :mod:`asyncio` because certain requests can
block the event loop too long. Instead, use the ``aiohttp`` library which is installed on the side with this library.
Another common source of blocking for too long is using HTTP requests with the famous module :doc:`req:index`.
While :doc:`req:index` is an amazing module for non-asynchronous programming, it is not a good choice for
: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: ::
@ -128,7 +129,7 @@ To upload multiple files, you can use the ``files`` keyword argument instead of
]
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:
.. 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
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:
@ -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:
- libffi
- libnacl
- python3-dev
- `libffi <https://github.com/libffi/libffi>`_
- `libnacl <https://github.com/saltstack/libnacl>`_
- `python3-dev <https://packages.debian.org/python3-dev>`_
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
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:

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"
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
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:`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`:
@ -382,8 +382,8 @@ They will be enumerated here.
**Changed**
- :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.attachments` is now a list of :class:`Attachment` instead of ``dict`` object.
- :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 :class:`dict` object.
- :attr:`Guild.roles` is now sorted through hierarchy. The first element is always the ``@everyone`` role.
**Added**
@ -701,12 +701,12 @@ when reached instead of setting the return to ``None``. For example:
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
`changes <http://aiohttp.readthedocs.io/en/stable/changes.html#rc1-2017-03-15>`_ and the
`migrating <http://aiohttp.readthedocs.io/en/stable/migration.html>`_ pages for details on the breaking changes in
``aiohttp``.
`changes <http://aiohttp.readthedocs.io/en/stable/changes.html#rc1-2017-03-15>`_
and the :doc:`aio:migration_to_2xx` pages for details on the breaking changes in
:doc:`aiohttp <aio:index>`.
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:
- 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
~~~~~~~~~~~~~~~
@ -949,7 +949,7 @@ and commands.
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``.

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.
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
**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`
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
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
`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.

BIN
docs/requests.inv Normal file
View File

Binary file not shown.