mirror
/
Rapptz.discord.py
mirror of https://github.com/Rapptz/discord.py
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Add intersphinx

pull/984/merge
Tobotimus 7 years ago
committed by Rapptz
parent
0ef866a704
commit
3112e1c17e
37 changed files with 267 additions and 268 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 22
      discord/abc.py
  2. 4
      discord/audit_logs.py
  3. 6
      discord/calls.py
  4. 40
      discord/channel.py
  5. 22
      discord/client.py
  6. 4
      discord/colour.py
  7. 18
      discord/embeds.py
  8. 16
      discord/emoji.py
  9. 12
      discord/errors.py
  10. 18
      discord/ext/commands/bot.py
  11. 12
      discord/ext/commands/context.py
  12. 6
      discord/ext/commands/converter.py
  13. 30
      discord/ext/commands/core.py
  14. 6
      discord/ext/commands/errors.py
  15. 22
      discord/ext/commands/formatter.py
  16. 4
      discord/file.py
  17. 6
      discord/game.py
  18. 2
      discord/gateway.py
  19. 32
      discord/guild.py
  20. 12
      discord/invite.py
  21. 16
      discord/member.py
  22. 32
      discord/message.py
  23. 2
      discord/object.py
  24. 2
      discord/opus.py
  25. 8
      discord/reaction.py
  26. 14
      discord/role.py
  27. 6
      discord/shard.py
  28. 42
      discord/user.py
  29. 8
      discord/voice_client.py
  30. 16
      discord/webhook.py
  31. 62
      docs/api.rst
  32. 4
      docs/conf.py
  33. 2
      docs/ext/commands/commands.rst
  34. 13
      docs/faq.rst
  35. 8
      docs/logging.rst
  36. 4
      docs/migrating.rst
  37. 2
      docs/migrating_to_async.rst

22
discord/abc.py
View File

@ -54,7 +54,7 @@ class Snowflake(metaclass=abc.ABCMeta):
Attributes Attributes
----------- -----------
id: int id: :class:`int`
The model's unique ID. The model's unique ID.
""" """
__slots__ = () __slots__ = ()
@ -91,13 +91,13 @@ class User(metaclass=abc.ABCMeta):
Attributes Attributes
----------- -----------
name: str name: :class:`str`
The user's username. The user's username.
discriminator: str discriminator: :class:`str`
The user's discriminator. The user's discriminator.
avatar: Optional[str] avatar: Optional[:class:`str`]
The avatar hash the user has. The avatar hash the user has.
bot: bool bot: :class:`bool`
If the user is a bot account. If the user is a bot account.
""" """
__slots__ = () __slots__ = ()
@ -175,11 +175,11 @@ class GuildChannel:
Attributes Attributes
----------- -----------
name: str name: :class:`str`
The channel name. The channel name.
guild: :class:`Guild` guild: :class:`Guild`
The guild the channel belongs to. The guild the channel belongs to.
position: int position: :class:`int`
The position in the channel list. This is a number that starts at 0. The position in the channel list. This is a number that starts at 0.
e.g. the top channel is position 0. e.g. the top channel is position 0.
""" """
@ -282,7 +282,7 @@ class GuildChannel:
@property @property
def changed_roles(self): def changed_roles(self):
"""Returns a list of :class:`Roles` that have been overridden from """Returns a :class:`list` of :class:`Roles` that have been overridden from
their default values in the :attr:`Guild.roles` attribute.""" their default values in the :attr:`Guild.roles` attribute."""
ret = [] ret = []
for overwrite in filter(lambda o: o.type == 'role', self._overwrites): for overwrite in filter(lambda o: o.type == 'role', self._overwrites):
@ -297,7 +297,7 @@ class GuildChannel:
@property @property
def mention(self): def mention(self):
"""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 return '<#%s>' % self.id
@property @property
@ -688,7 +688,7 @@ class Messageable(metaclass=abc.ABCMeta):
To upload a single file, the ``file`` parameter should be used with a To upload a single file, the ``file`` parameter should be used with a
single :class:`File` object. To upload multiple files, the ``files`` single :class:`File` object. To upload multiple files, the ``files``
parameter should be used with a list of :class:`File` objects. parameter should be used with a :class:`list` of :class:`File` objects.
**Specifying both parameters will lead to an exception**. **Specifying both parameters will lead to an exception**.
If the ``embed`` parameter is provided, it must be of type :class:`Embed` and If the ``embed`` parameter is provided, it must be of type :class:`Embed` and
@ -842,7 +842,7 @@ class Messageable(metaclass=abc.ABCMeta):
def pins(self): def pins(self):
"""|coro| """|coro|
Returns a list of :class:`Message` that are currently pinned. Returns a :class:`list` of :class:`Message` that are currently pinned.
Raises Raises
------- -------

4
discord/audit_logs.py
View File

@ -189,12 +189,12 @@ class AuditLogEntry:
user: :class:`abc.User` user: :class:`abc.User`
The user who initiated this action. Usually a :class:`Member`\, unless gone The user who initiated this action. Usually a :class:`Member`\, unless gone
then it's a :class:`User`. then it's a :class:`User`.
id: int id: :class:`int`
The entry ID. The entry ID.
target: Any target: Any
The target that got changed. The exact type of this depends on The target that got changed. The exact type of this depends on
the action being done. the action being done.
reason: Optional[str] reason: Optional[:class:`str`]
The reason this action was done. The reason this action was done.
extra: Any extra: Any
Extra information that this entry has that might be useful. Extra information that this entry has that might be useful.

6
discord/calls.py
View File

@ -53,7 +53,7 @@ class CallMessage:
@property @property
def call_ended(self): def call_ended(self):
"""bool: Indicates if the call has ended.""" """:obj:`bool`: Indicates if the call has ended."""
return self.ended_timestamp is not None return self.ended_timestamp is not None
@property @property
@ -87,7 +87,7 @@ class GroupCall:
----------- -----------
call: :class:`CallMessage` call: :class:`CallMessage`
The call message associated with this group call. The call message associated with this group call.
unavailable: bool unavailable: :obj:`bool`
Denotes if this group call is unavailable. Denotes if this group call is unavailable.
ringing: List[:class:`User`] ringing: List[:class:`User`]
A list of users that are currently being rung to join the call. A list of users that are currently being rung to join the call.
@ -122,7 +122,7 @@ class GroupCall:
@property @property
def connected(self): def connected(self):
"""A property that returns the list of :class:`User` that are currently in this call.""" """A property that returns the :obj:`list` of :class:`User` that are currently in this call."""
ret = [u for u in self.channel.recipients if self.voice_state_for(u) is not None] ret = [u for u in self.channel.recipients if self.voice_state_for(u) is not None]
me = self.channel.me me = self.channel.me
if self.voice_state_for(me) is not None: if self.voice_state_for(me) is not None:

40
discord/channel.py
View File

@ -65,17 +65,17 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
Attributes Attributes
----------- -----------
name: str name: :class:`str`
The channel name. The channel name.
guild: :class:`Guild` guild: :class:`Guild`
The guild the channel belongs to. The guild the channel belongs to.
id: int id: :class:`int`
The channel ID. The channel ID.
category_id: int category_id: :class:`int`
The category channel ID this channel belongs to. The category channel ID this channel belongs to.
topic: Optional[str] topic: Optional[:class:`str`]
The channel's topic. None if it doesn't exist. The channel's topic. None if it doesn't exist.
position: int position: :class:`int`
The position in the channel list. This is a number that starts at 0. e.g. the The position in the channel list. This is a number that starts at 0. e.g. the
top channel is position 0. top channel is position 0.
""" """
@ -116,7 +116,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
@property @property
def members(self): def members(self):
"""Returns a list of :class:`Member` that can see this channel.""" """Returns a :class:`list` of :class:`Member` that can see this channel."""
return [m for m in self.guild.members if self.permissions_for(m).read_messages] return [m for m in self.guild.members if self.permissions_for(m).read_messages]
def is_nsfw(self): def is_nsfw(self):
@ -404,20 +404,20 @@ class VoiceChannel(discord.abc.Connectable, discord.abc.GuildChannel, Hashable):
Attributes Attributes
----------- -----------
name: str name: :class:`str`
The channel name. The channel name.
guild: :class:`Guild` guild: :class:`Guild`
The guild the channel belongs to. The guild the channel belongs to.
id: int id: :class:`int`
The channel ID. The channel ID.
category_id: int category_id: :class:`int`
The category channel ID this channel belongs to. The category channel ID this channel belongs to.
position: int position: :class:`int`
The position in the channel list. This is a number that starts at 0. e.g. the The position in the channel list. This is a number that starts at 0. e.g. the
top channel is position 0. top channel is position 0.
bitrate: int bitrate: :class:`int`
The channel's preferred audio bitrate in bits per second. The channel's preferred audio bitrate in bits per second.
user_limit: int user_limit: :class:`int`
The channel's limit for number of members that can be in a voice channel. The channel's limit for number of members that can be in a voice channel.
""" """
@ -521,13 +521,13 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
Attributes Attributes
----------- -----------
name: str name: :class:`str`
The category name. The category name.
guild: :class:`Guild` guild: :class:`Guild`
The guild the category belongs to. The guild the category belongs to.
id: int id: :class:`int`
The category channel ID. The category channel ID.
position: int position: :class:`int`
The position in the category list. This is a number that starts at 0. e.g. the The position in the category list. This is a number that starts at 0. e.g. the
top category is position 0. top category is position 0.
""" """
@ -637,7 +637,7 @@ class DMChannel(discord.abc.Messageable, Hashable):
The user you are participating with in the direct message channel. The user you are participating with in the direct message channel.
me: :class:`ClientUser` me: :class:`ClientUser`
The user presenting yourself. The user presenting yourself.
id: int id: :class:`int`
The direct message channel ID. The direct message channel ID.
""" """
@ -716,17 +716,17 @@ class GroupChannel(discord.abc.Messageable, Hashable):
Attributes Attributes
---------- ----------
recipients: list of :class:`User` recipients: :class:`list` of :class:`User`
The users you are participating with in the group channel. The users you are participating with in the group channel.
me: :class:`ClientUser` me: :class:`ClientUser`
The user presenting yourself. The user presenting yourself.
id: int id: :class:`int`
The group channel ID. The group channel ID.
owner: :class:`User` owner: :class:`User`
The user that owns the group channel. The user that owns the group channel.
icon: Optional[str] icon: Optional[:class:`str`]
The group channel's icon hash if provided. The group channel's icon hash if provided.
name: Optional[str] name: Optional[:class:`str`]
The group channel's name if provided. The group channel's name if provided.
""" """

22
discord/client.py
View File

@ -175,7 +175,7 @@ class Client:
@property @property
def latency(self): def latency(self):
"""float: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. """:obj:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
This could be referred to as the Discord WebSocket protocol latency. This could be referred to as the Discord WebSocket protocol latency.
""" """
@ -214,7 +214,7 @@ class Client:
return self._connection.voice_clients return self._connection.voice_clients
def is_ready(self): def is_ready(self):
"""bool: Specifies if the client's internal cache is ready for use.""" """:obj:`bool`: Specifies if the client's internal cache is ready for use."""
return self._ready.is_set() return self._ready.is_set()
@asyncio.coroutine @asyncio.coroutine
@ -581,14 +581,14 @@ class Client:
# properties # properties
def is_closed(self): def is_closed(self):
"""bool: Indicates if the websocket connection is closed.""" """:obj:`bool`: Indicates if the websocket connection is closed."""
return self._closed.is_set() return self._closed.is_set()
# helpers/getters # helpers/getters
@property @property
def users(self): def users(self):
"""Returns a list of all the :class:`User` the bot can see.""" """Returns a :obj:`list` of all the :class:`User` the bot can see."""
return list(self._connection._users.values()) return list(self._connection._users.values())
def get_channel(self, id): def get_channel(self, id):
@ -663,20 +663,18 @@ class Client:
or to react to a message, or to edit a message in a self-contained or to react to a message, or to edit a message in a self-contained
way. way.
The ``timeout`` parameter is passed onto `asyncio.wait_for`_. By default, The ``timeout`` parameter is passed onto :func:`asyncio.wait_for`. By default,
it does not timeout. Note that this does propagate the it does not timeout. Note that this does propagate the
``asyncio.TimeoutError`` for you in case of timeout and is provided for :exc:`asyncio.TimeoutError` for you in case of timeout and is provided for
ease of use. ease of use.
In case the event returns multiple arguments, a tuple containing those In case the event returns multiple arguments, a :obj:`tuple` containing those
arguments is returned instead. Please check the arguments is returned instead. Please check the
:ref:`documentation <discord-api-events>` for a list of events and their :ref:`documentation <discord-api-events>` for a list of events and their
parameters. parameters.
This function returns the **first event that meets the requirements**. This function returns the **first event that meets the requirements**.
.. _asyncio.wait_for: https://docs.python.org/3/library/asyncio-task.html#asyncio.wait_for
Examples Examples
--------- ---------
@ -723,7 +721,7 @@ class Client:
parameters of the event being waited for. parameters of the event being waited for.
timeout: Optional[float] timeout: Optional[float]
The number of seconds to wait before timing out and raising The number of seconds to wait before timing out and raising
``asyncio.TimeoutError``\. :exc:`asyncio.TimeoutError`.
Raises Raises
------- -------
@ -733,7 +731,7 @@ class Client:
Returns Returns
-------- --------
Any Any
Returns no arguments, a single argument, or a tuple of multiple Returns no arguments, a single argument, or a :obj:`tuple` of multiple
arguments that mirrors the parameters passed in the arguments that mirrors the parameters passed in the
:ref:`event reference <discord-api-events>`. :ref:`event reference <discord-api-events>`.
""" """
@ -789,7 +787,7 @@ class Client:
return coro return coro
def async_event(self, coro): def async_event(self, coro):
"""A shorthand decorator for ``asyncio.coroutine`` + :meth:`event`.""" """A shorthand decorator for :func:`asyncio.coroutine` + :meth:`event`."""
if not asyncio.iscoroutinefunction(coro): if not asyncio.iscoroutinefunction(coro):
coro = asyncio.coroutine(coro) coro = asyncio.coroutine(coro)

4
discord/colour.py
View File

@ -26,7 +26,7 @@ DEALINGS IN THE SOFTWARE.
class Colour: class Colour:
"""Represents a Discord role colour. This class is similar """Represents a Discord role colour. This class is similar
to an (red, green, blue) tuple. to an (red, green, blue) :class:`tuple`.
There is an alias for this called Color. There is an alias for this called Color.
@ -50,7 +50,7 @@ class Colour:
Attributes Attributes
------------ ------------
value: int value: :class:`int`
The raw integer colour value. The raw integer colour value.
""" """

18
discord/embeds.py
View File

@ -58,27 +58,27 @@ class Embed:
of the object: of the object:
Certain properties return an ``EmbedProxy``. Which is a type Certain properties return an ``EmbedProxy``. Which is a type
that acts similar to a regular `dict` except access the attributes that acts similar to a regular :class:`dict` except access the attributes
via dotted access, e.g. ``embed.author.icon_url``. If the attribute via dotted access, e.g. ``embed.author.icon_url``. If the attribute
is invalid or empty, then a special sentinel value is returned, is invalid or empty, then a special sentinel value is returned,
:attr:`Embed.Empty`. :attr:`Embed.Empty`.
For ease of use, all parameters that expect a ``str`` are implicitly For ease of use, all parameters that expect a :class:`str` are implicitly
casted to ``str`` for you. casted to :class:`str` for you.
Attributes Attributes
----------- -----------
title: str title: :class:`str`
The title of the embed. The title of the embed.
type: str type: :class:`str`
The type of embed. Usually "rich". The type of embed. Usually "rich".
description: str description: :class:`str`
The description of the embed. The description of the embed.
url: str url: :class:`str`
The URL of the embed. The URL of the embed.
timestamp: `datetime.datetime` timestamp: `datetime.datetime`
The timestamp of the embed content. This could be a naive or aware datetime. The timestamp of the embed content. This could be a naive or aware datetime.
colour: :class:`Colour` or int colour: :class:`Colour` or :class:`int`
The colour code of the embed. Aliased to ``color`` as well. The colour code of the embed. Aliased to ``color`` as well.
Empty Empty
A special sentinel value used by ``EmbedProxy`` and this class A special sentinel value used by ``EmbedProxy`` and this class
@ -334,7 +334,7 @@ class Embed:
@property @property
def fields(self): def fields(self):
"""Returns a list of ``EmbedProxy`` denoting the field contents. """Returns a :class:`list` of ``EmbedProxy`` denoting the field contents.
See :meth:`add_field` for possible values you can access. See :meth:`add_field` for possible values you can access.

16
discord/emoji.py
View File

@ -58,10 +58,10 @@ class PartialReactionEmoji(namedtuple('PartialReactionEmoji', 'name id')):
Attributes Attributes
----------- -----------
name: str name: :class:`str`
The custom emoji name, if applicable, or the unicode codepoint The custom emoji name, if applicable, or the unicode codepoint
of the non-custom emoji. of the non-custom emoji.
id: Optional[int] id: Optional[:class:`int`]
The ID of the custom emoji, if applicable. The ID of the custom emoji, if applicable.
""" """
@ -116,17 +116,17 @@ class Emoji(Hashable):
Attributes Attributes
----------- -----------
name: str name: :class:`str`
The name of the emoji. The name of the emoji.
id: int id: :class:`int`
The emoji's ID. The emoji's ID.
require_colons: bool require_colons: :class:`bool`
If colons are required to use this emoji in the client (:PJSalt: vs PJSalt). If colons are required to use this emoji in the client (:PJSalt: vs PJSalt).
animated: bool animated: :class:`bool`
Whether an emoji is animated or not. Whether an emoji is animated or not.
managed: bool managed: :class:`bool`
If this emoji is managed by a Twitch integration. If this emoji is managed by a Twitch integration.
guild_id: int guild_id: :class:`int`
The guild ID the emoji belongs to. The guild ID the emoji belongs to.
""" """
__slots__ = ('require_colons', 'animated', 'managed', 'id', 'name', '_roles', 'guild_id', '_state') __slots__ = ('require_colons', 'animated', 'managed', 'id', 'name', '_roles', 'guild_id', '_state')

12
discord/errors.py
View File

@ -81,11 +81,11 @@ class HTTPException(DiscordException):
__ http://aiohttp.readthedocs.org/en/stable/client_reference.html#aiohttp.ClientResponse __ http://aiohttp.readthedocs.org/en/stable/client_reference.html#aiohttp.ClientResponse
text: str text: :class:`str`
The text of the error. Could be an empty string. The text of the error. Could be an empty string.
status: int status: :class:`int`
The status code of the HTTP request. The status code of the HTTP request.
code: int code: :class:`int`
The Discord specific error code for the failure. The Discord specific error code for the failure.
""" """
@ -150,11 +150,11 @@ class ConnectionClosed(ClientException):
Attributes Attributes
----------- -----------
code: int code: :class:`int`
The close code of the websocket. The close code of the websocket.
reason: str reason: :class:`str`
The reason provided for the closure. The reason provided for the closure.
shard_id: Optional[int] shard_id: Optional[:class:`int`]
The shard ID that got closed if applicable. The shard ID that got closed if applicable.
""" """
def __init__(self, original, *, shard_id): def __init__(self, original, *, shard_id):

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

@ -436,7 +436,7 @@ class BotBase(GroupMixin):
Parameters Parameters
----------- -----------
func : coroutine func : :ref:`coroutine <coroutine>`
The extra event to listen to. The extra event to listen to.
name : Optional[str] name : Optional[str]
The name of the command to use. Defaults to ``func.__name__``. The name of the command to use. Defaults to ``func.__name__``.
@ -943,13 +943,13 @@ class Bot(BotBase, discord.Client):
command prefixes. This callable can be either a regular function or command prefixes. This callable can be either a regular function or
a coroutine. a coroutine.
The command prefix could also be a list or a tuple indicating that The command prefix could also be a :class:`list` or a :class:`tuple` indicating that
multiple checks for the prefix should be used and the first one to multiple checks for the prefix should be used and the first one to
match will be the invocation prefix. You can get this prefix via match will be the invocation prefix. You can get this prefix via
:attr:`.Context.prefix`. :attr:`.Context.prefix`.
description : str description : :class:`str`
The content prefixed into the default help message. The content prefixed into the default help message.
self_bot : bool self_bot : :class:`bool`
If ``True``, the bot will only listen to commands invoked by itself rather If ``True``, the bot will only listen to commands invoked by itself rather
than ignoring itself. If ``False`` (the default) then the bot will ignore than ignoring itself. If ``False`` (the default) then the bot will ignore
itself. This cannot be changed once initialised. itself. This cannot be changed once initialised.
@ -959,29 +959,29 @@ class Bot(BotBase, discord.Client):
If you want to change the help command completely (add aliases, etc) then If you want to change the help command completely (add aliases, etc) then
a call to :meth:`~.Bot.remove_command` with 'help' as the argument would do the a call to :meth:`~.Bot.remove_command` with 'help' as the argument would do the
trick. trick.
pm_help : Optional[bool] pm_help : Optional[:class:`bool`]
A tribool that indicates if the help command should PM the user instead of A tribool that indicates if the help command should PM the user instead of
sending it to the channel it received it from. If the boolean is set to sending it to the channel it received it from. If the boolean is set to
``True``, then all help output is PM'd. If ``False``, none of the help ``True``, then all help output is PM'd. If ``False``, none of the help
output is PM'd. If ``None``, then the bot will only PM when the help output is PM'd. If ``None``, then the bot will only PM when the help
message becomes too long (dictated by more than 1000 characters). message becomes too long (dictated by more than 1000 characters).
Defaults to ``False``. Defaults to ``False``.
help_attrs : dict help_attrs : :class:`dict`
A dictionary of options to pass in for the construction of the help command. A dictionary of options to pass in for the construction of the help command.
This allows you to change the command behaviour without actually changing This allows you to change the command behaviour without actually changing
the implementation of the command. The attributes will be the same as the the implementation of the command. The attributes will be the same as the
ones passed in the :class:`.Command` constructor. Note that ``pass_context`` ones passed in the :class:`.Command` constructor. Note that ``pass_context``
will always be set to ``True`` regardless of what you pass in. will always be set to ``True`` regardless of what you pass in.
command_not_found : str command_not_found : :class:`str`
The format string used when the help command is invoked with a command that The format string used when the help command is invoked with a command that
is not found. Useful for i18n. Defaults to ``"No command called {} found."``. is not found. Useful for i18n. Defaults to ``"No command called {} found."``.
The only format argument is the name of the command passed. The only format argument is the name of the command passed.
command_has_no_subcommands : str command_has_no_subcommands : :class:`str`
The format string used when the help command is invoked with requests for a The format string used when the help command is invoked with requests for a
subcommand but the command does not have any subcommands. Defaults to subcommand but the command does not have any subcommands. Defaults to
``"Command {0.name} has no subcommands."``. The first format argument is the ``"Command {0.name} has no subcommands."``. The first format argument is the
:class:`.Command` attempted to get a subcommand and the second is the name. :class:`.Command` attempted to get a subcommand and the second is the name.
owner_id: Optional[int] owner_id: Optional[:class:`int`]
The ID that owns the bot. If this is not set and is then queried via The ID that owns the bot. If this is not set and is then queried via
:meth:`.is_owner` then it is fetched automatically using :meth:`.is_owner` then it is fetched automatically using
:meth:`~.Bot.application_info`. :meth:`~.Bot.application_info`.

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

@ -42,32 +42,32 @@ class Context(discord.abc.Messageable):
The message that triggered the command being executed. The message that triggered the command being executed.
bot: :class:`.Bot` bot: :class:`.Bot`
The bot that contains the command being executed. The bot that contains the command being executed.
args: list args: :class:`list`
The list of transformed arguments that were passed into the command. The list of transformed arguments that were passed into the command.
If this is accessed during the :func:`on_command_error` event If this is accessed during the :func:`on_command_error` event
then this list could be incomplete. then this list could be incomplete.
kwargs: dict kwargs: :class:`dict`
A dictionary of transformed arguments that were passed into the command. A dictionary of transformed arguments that were passed into the command.
Similar to :attr:`args`\, if this is accessed in the Similar to :attr:`args`\, if this is accessed in the
:func:`on_command_error` event then this dict could be incomplete. :func:`on_command_error` event then this dict could be incomplete.
prefix: str prefix: :class:`str`
The prefix that was used to invoke the command. The prefix that was used to invoke the command.
command command
The command (i.e. :class:`.Command` or its superclasses) that is being The command (i.e. :class:`.Command` or its superclasses) that is being
invoked currently. invoked currently.
invoked_with: str invoked_with: :class:`str`
The command name that triggered this invocation. Useful for finding out The command name that triggered this invocation. Useful for finding out
which alias called the command. which alias called the command.
invoked_subcommand invoked_subcommand
The subcommand (i.e. :class:`.Command` or its superclasses) that was The subcommand (i.e. :class:`.Command` or its superclasses) that was
invoked. If no valid subcommand was invoked then this is equal to invoked. If no valid subcommand was invoked then this is equal to
`None`. `None`.
subcommand_passed: Optional[str] subcommand_passed: Optional[:class:`str`]
The string that was attempted to call a subcommand. This does not have The string that was attempted to call a subcommand. This does not have
to point to a valid registered subcommand and could just point to a to point to a valid registered subcommand and could just point to a
nonsense string. If nothing was passed to attempt a call to a nonsense string. If nothing was passed to attempt a call to a
subcommand then this is set to `None`. subcommand then this is set to `None`.
command_failed: bool command_failed: :class:`bool`
A boolean that indicates if the command failed to be parsed, checked, A boolean that indicates if the command failed to be parsed, checked,
or invoked. or invoked.
""" """

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

@ -405,11 +405,11 @@ class clean_content(Converter):
Attributes Attributes
------------ ------------
fix_channel_mentions: bool fix_channel_mentions: :obj:`bool`
Whether to clean channel mentions. Whether to clean channel mentions.
use_nicknames: bool use_nicknames: :obj:`bool`
Whether to use nicknames when transforming mentions. Whether to use nicknames when transforming mentions.
escape_markdown: bool escape_markdown: :obj:`bool`
Whether to also escape special markdown characters. Whether to also escape special markdown characters.
""" """
def __init__(self, *, fix_channel_mentions=False, use_nicknames=True, escape_markdown=False): def __init__(self, *, fix_channel_mentions=False, use_nicknames=True, escape_markdown=False):

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

@ -91,20 +91,20 @@ class Command:
Attributes Attributes
----------- -----------
name: str name: :class:`str`
The name of the command. The name of the command.
callback: coroutine callback: :ref:`coroutine <coroutine>`
The coroutine that is executed when the command is called. The coroutine that is executed when the command is called.
help: str help: :class:`str`
The long help text for the command. The long help text for the command.
brief: str brief: :class:`str`
The short help text for the command. If this is not specified The short help text for the command. If this is not specified
then the first line of the long help text is used instead. then the first line of the long help text is used instead.
usage: str usage: :class:`str`
A replacement for arguments in the default help text. A replacement for arguments in the default help text.
aliases: list aliases: :class:`list`
The list of aliases the command can be invoked under. The list of aliases the command can be invoked under.
enabled: bool enabled: :class:`bool`
A boolean that indicates if the command is currently enabled. A boolean that indicates if the command is currently enabled.
If the command is invoked while it is disabled, then If the command is invoked while it is disabled, then
:exc:`.DisabledCommand` is raised to the :func:`.on_command_error` :exc:`.DisabledCommand` is raised to the :func:`.on_command_error`
@ -119,19 +119,19 @@ class Command:
:exc:`.CommandError` should be used. Note that if the checks fail then :exc:`.CommandError` should be used. Note that if the checks fail then
:exc:`.CheckFailure` exception is raised to the :func:`.on_command_error` :exc:`.CheckFailure` exception is raised to the :func:`.on_command_error`
event. event.
description: str description: :class:`str`
The message prefixed into the default help command. The message prefixed into the default help command.
hidden: bool hidden: :class:`bool`
If ``True``\, the default help command does not show this in the If ``True``\, the default help command does not show this in the
help output. help output.
rest_is_raw: bool rest_is_raw: :class:`bool`
If ``False`` and a keyword-only argument is provided then the keyword If ``False`` and a keyword-only argument is provided then the keyword
only argument is stripped and handled as if it was a regular argument only argument is stripped and handled as if it was a regular argument
that handles :exc:`.MissingRequiredArgument` and default values in a that handles :exc:`.MissingRequiredArgument` and default values in a
regular matter rather than passing the rest completely raw. If ``True`` regular matter rather than passing the rest completely raw. If ``True``
then the keyword-only argument will pass in the rest of the arguments then the keyword-only argument will pass in the rest of the arguments
in a completely raw matter. Defaults to ``False``. in a completely raw matter. Defaults to ``False``.
ignore_extra: bool ignore_extra: :class:`bool`
If ``True``\, ignores extraneous strings passed to a command if all its If ``True``\, ignores extraneous strings passed to a command if all its
requirements are met (e.g. ``?foo a b c`` when only expecting ``a`` requirements are met (e.g. ``?foo a b c`` when only expecting ``a``
and ``b``). Otherwise :func:`.on_command_error` and local error handlers and ``b``). Otherwise :func:`.on_command_error` and local error handlers
@ -519,7 +519,7 @@ class Command:
Parameters Parameters
----------- -----------
coro coro : :ref:`coroutine <coroutine>`
The coroutine to register as the local error handler. The coroutine to register as the local error handler.
Raises Raises
@ -703,7 +703,7 @@ class GroupMixin:
Attributes Attributes
----------- -----------
all_commands: dict all_commands: :class:`dict`
A mapping of command name to :class:`.Command` or superclass A mapping of command name to :class:`.Command` or superclass
objects. objects.
""" """
@ -861,7 +861,7 @@ class Group(GroupMixin, Command):
Attributes Attributes
----------- -----------
invoke_without_command: bool invoke_without_command: :class:`bool`
Indicates if the group callback should begin parsing and Indicates if the group callback should begin parsing and
invocation only if no subcommand was found. Useful for invocation only if no subcommand was found. Useful for
making it an error handling function to tell the user that making it an error handling function to tell the user that
@ -950,7 +950,7 @@ def command(name=None, cls=None, **attrs):
By default the ``help`` attribute is received automatically from the By default the ``help`` attribute is received automatically from the
docstring of the function and is cleaned up with the use of docstring of the function and is cleaned up with the use of
``inspect.cleandoc``. If the docstring is ``bytes``, then it is decoded ``inspect.cleandoc``. If the docstring is ``bytes``, then it is decoded
into ``str`` using utf-8 encoding. into :class:`str` using utf-8 encoding.
All checks added using the :func:`.check` & co. decorators are added into All checks added using the :func:`.check` & co. decorators are added into
the function. There is no way to supply your own checks through this the function. There is no way to supply your own checks through this

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

@ -130,7 +130,7 @@ class CommandOnCooldown(CommandError):
cooldown: Cooldown cooldown: Cooldown
A class with attributes ``rate``, ``per``, and ``type`` similar to A class with attributes ``rate``, ``per``, and ``type`` similar to
the :func:`.cooldown` decorator. the :func:`.cooldown` decorator.
retry_after: float retry_after: :class:`float`
The amount of seconds to wait before you can retry again. The amount of seconds to wait before you can retry again.
""" """
def __init__(self, cooldown, retry_after): def __init__(self, cooldown, retry_after):
@ -144,7 +144,7 @@ class MissingPermissions(CheckFailure):
Attributes Attributes
----------- -----------
missing_perms: list missing_perms: :class:`list`
The required permissions that are missing. The required permissions that are missing.
""" """
def __init__(self, missing_perms, *args): def __init__(self, missing_perms, *args):
@ -164,7 +164,7 @@ class BotMissingPermissions(CheckFailure):
Attributes Attributes
----------- -----------
missing_perms: list missing_perms: :class:`list`
The required permissions that are missing. The required permissions that are missing.
""" """
def __init__(self, missing_perms, *args): def __init__(self, missing_perms, *args):

22
discord/ext/commands/formatter.py
View File

@ -58,11 +58,11 @@ class Paginator:
Attributes Attributes
----------- -----------
prefix: str prefix: :class:`str`
The prefix inserted to every page. e.g. three backticks. The prefix inserted to every page. e.g. three backticks.
suffix: str suffix: :class:`str`
The suffix appended at the end of every page. e.g. three backticks. The suffix appended at the end of every page. e.g. three backticks.
max_size: int max_size: :class:`int`
The maximum amount of codepoints allowed in a page. The maximum amount of codepoints allowed in a page.
""" """
def __init__(self, prefix='```', suffix='```', max_size=2000): def __init__(self, prefix='```', suffix='```', max_size=2000):
@ -133,13 +133,13 @@ class HelpFormatter:
Attributes Attributes
----------- -----------
show_hidden: bool show_hidden: :class:`bool`
Dictates if hidden commands should be shown in the output. Dictates if hidden commands should be shown in the output.
Defaults to ``False``. Defaults to ``False``.
show_check_failure: bool show_check_failure: :class:`bool`
Dictates if commands that have their :attr:`.Command.checks` failed Dictates if commands that have their :attr:`.Command.checks` failed
shown. Defaults to ``False``. shown. Defaults to ``False``.
width: int width: :class:`int`
The maximum number of characters that fit in a line. The maximum number of characters that fit in a line.
Defaults to 80. Defaults to 80.
""" """
@ -149,15 +149,15 @@ class HelpFormatter:
self.show_check_failure = show_check_failure self.show_check_failure = show_check_failure
def has_subcommands(self): def has_subcommands(self):
"""bool: Specifies if the command has subcommands.""" """:class:`bool`: Specifies if the command has subcommands."""
return isinstance(self.command, GroupMixin) return isinstance(self.command, GroupMixin)
def is_bot(self): def is_bot(self):
"""bool: Specifies if the command being formatted is the bot itself.""" """:class:`bool`: Specifies if the command being formatted is the bot itself."""
return self.command is self.context.bot return self.command is self.context.bot
def is_cog(self): def is_cog(self):
"""bool: Specifies if the command being formatted is actually a cog.""" """:class:`bool`: Specifies if the command being formatted is actually a cog."""
return not self.is_bot() and not isinstance(self.command, Command) return not self.is_bot() and not isinstance(self.command, Command)
def shorten(self, text): def shorten(self, text):
@ -168,7 +168,7 @@ class HelpFormatter:
@property @property
def max_name_size(self): def max_name_size(self):
"""int: Returns the largest name length of a command or if it has subcommands """:class:`int`: Returns the largest name length of a command or if it has subcommands
the largest subcommand name.""" the largest subcommand name."""
try: try:
commands = self.command.all_commands if not self.is_cog() else self.context.bot.all_commands commands = self.command.all_commands if not self.is_cog() else self.context.bot.all_commands
@ -209,7 +209,7 @@ class HelpFormatter:
-------- --------
iterable iterable
An iterable with the filter being applied. The resulting value is An iterable with the filter being applied. The resulting value is
a (key, value) tuple of the command name and the command itself. a (key, value) :class:`tuple` of the command name and the command itself.
""" """
def sane_no_suspension_point_predicate(tup): def sane_no_suspension_point_predicate(tup):

4
discord/file.py
View File

@ -32,7 +32,7 @@ class File:
Attributes Attributes
----------- -----------
fp: Union[str, BinaryIO] fp: Union[:class:`str`, BinaryIO]
A file-like object opened in binary mode and read mode A file-like object opened in binary mode and read mode
or a filename representing a file in the hard drive to or a filename representing a file in the hard drive to
open. open.
@ -44,7 +44,7 @@ class File:
To pass binary data, consider usage of ``io.BytesIO``. To pass binary data, consider usage of ``io.BytesIO``.
filename: Optional[str] filename: Optional[:class:`str`]
The filename to display when uploading to Discord. The filename to display when uploading to Discord.
If this is not given then it defaults to ``fp.name`` or if ``fp`` is If this is not given then it defaults to ``fp.name`` or if ``fp`` is
a string then the ``filename`` will default to the string given. a string then the ``filename`` will default to the string given.

6
discord/game.py
View File

@ -47,11 +47,11 @@ class Game:
Attributes Attributes
----------- -----------
name: str name: :class:`str`
The game's name. The game's name.
url: str url: :class:`str`
The game's URL. Usually used for twitch streaming. The game's URL. Usually used for twitch streaming.
type: int type: :class:`int`
The type of game being played. 1 indicates "Streaming". The type of game being played. 1 indicates "Streaming".
""" """

2
discord/gateway.py
View File

@ -428,7 +428,7 @@ class DiscordWebSocket(websockets.client.WebSocketClientProtocol):
@property @property
def latency(self): def latency(self):
"""float: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.""" """:obj:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds."""
heartbeat = self._keep_alive heartbeat = self._keep_alive
return float('inf') if heartbeat is None else heartbeat._last_ack - heartbeat._last_send return float('inf') if heartbeat is None else heartbeat._last_ack - heartbeat._last_send

32
discord/guild.py
View File

@ -74,32 +74,32 @@ class Guild(Hashable):
Attributes Attributes
---------- ----------
name: str name: :class:`str`
The guild name. The guild name.
roles roles
A list of :class:`Role` that the guild has available. A :class:`list` of :class:`Role` that the guild has available.
emojis emojis
A tuple of :class:`Emoji` that the guild owns. A :class:`tuple` of :class:`Emoji` that the guild owns.
region: :class:`VoiceRegion` region: :class:`VoiceRegion`
The region the guild belongs on. There is a chance that the region The region the guild belongs on. There is a chance that the region
will be a ``str`` if the value is not recognised by the enumerator. will be a :class:`str` if the value is not recognised by the enumerator.
afk_timeout: int afk_timeout: :class:`int`
The timeout to get sent to the AFK channel. The timeout to get sent to the AFK channel.
afk_channel: Optional[:class:`VoiceChannel`] afk_channel: Optional[:class:`VoiceChannel`]
The channel that denotes the AFK channel. None if it doesn't exist. The channel that denotes the AFK channel. None if it doesn't exist.
icon: str icon: :class:`str`
The guild's icon. The guild's icon.
id: int id: :class:`int`
The guild's ID. The guild's ID.
owner_id: int owner_id: :class:`int`
The guild owner's ID. Use :attr:`Guild.owner` instead. The guild owner's ID. Use :attr:`Guild.owner` instead.
unavailable: bool unavailable: :class:`bool`
Indicates if the guild is unavailable. If this is ``True`` then the Indicates if the guild is unavailable. If this is ``True`` then the
reliability of other attributes outside of :meth:`Guild.id` is slim and they might reliability of other attributes outside of :meth:`Guild.id` is slim and they might
all be None. It is best to not do anything with the guild if it is unavailable. all be None. It is best to not do anything with the guild if it is unavailable.
Check the :func:`on_guild_unavailable` and :func:`on_guild_available` events. Check the :func:`on_guild_unavailable` and :func:`on_guild_available` events.
mfa_level: int mfa_level: :class:`int`
Indicates the guild's two factor authorisation level. If this value is 0 then Indicates the guild's two factor authorisation level. If this value is 0 then
the guild does not require 2FA for their administrative members. If the value is the guild does not require 2FA for their administrative members. If the value is
1 then they do. 1 then they do.
@ -107,7 +107,7 @@ class Guild(Hashable):
The guild's verification level. The guild's verification level.
explicit_content_filter: :class:`ContentFilter` explicit_content_filter: :class:`ContentFilter`
The guild's explicit content filter. The guild's explicit content filter.
features: List[str] features: List[:class:`str`]
A list of features that the guild has. They are currently as follows: A list of features that the guild has. They are currently as follows:
- ``VIP_REGIONS``: Guild has VIP voice regions - ``VIP_REGIONS``: Guild has VIP voice regions
@ -116,7 +116,7 @@ class Guild(Hashable):
- ``VERIFIED``: Guild is a "verified" server. - ``VERIFIED``: Guild is a "verified" server.
- ``MORE_EMOJI``: Guild is allowed to have more than 50 custom emoji. - ``MORE_EMOJI``: Guild is allowed to have more than 50 custom emoji.
splash: str splash: :class:`str`
The guild's invite splash. The guild's invite splash.
""" """
@ -264,7 +264,7 @@ class Guild(Hashable):
@property @property
def large(self): def large(self):
"""bool: Indicates if the guild is a 'large' guild. """:class:`bool`: Indicates if the guild is a 'large' guild.
A large guild is defined as having more than ``large_threshold`` count A large guild is defined as having more than ``large_threshold`` count
members, which for this library is set to the maximum of 250. members, which for this library is set to the maximum of 250.
@ -553,7 +553,7 @@ class Guild(Hashable):
Note that you need the proper permissions to create the channel. Note that you need the proper permissions to create the channel.
The ``overwrites`` parameter can be used to create a 'secret' The ``overwrites`` parameter can be used to create a 'secret'
channel upon creation. This parameter expects a `dict` of channel upon creation. This parameter expects a :class:`dict` of
overwrites with the target (either a :class:`Member` or a :class:`Role`) overwrites with the target (either a :class:`Member` or a :class:`Role`)
as the key and a :class:`PermissionOverwrite` as the value. as the key and a :class:`PermissionOverwrite` as the value.
@ -582,7 +582,7 @@ class Guild(Hashable):
name: str name: str
The channel's name. The channel's name.
overwrites overwrites
A `dict` of target (either a role or a member) to A :class:`dict` of target (either a role or a member) to
:class:`PermissionOverwrite` to apply upon creation of a channel. :class:`PermissionOverwrite` to apply upon creation of a channel.
Useful for creating secret channels. Useful for creating secret channels.
category: Optional[:class:`CategoryChannel`] category: Optional[:class:`CategoryChannel`]
@ -807,7 +807,7 @@ class Guild(Hashable):
Retrieves all the users that are banned from the guild. Retrieves all the users that are banned from the guild.
This coroutine returns a list of BanEntry objects. Which is a This coroutine returns a :class:`list` of BanEntry objects. Which is a
namedtuple with a ``user`` field to denote the :class:`User` namedtuple with a ``user`` field to denote the :class:`User`
that got banned along with a ``reason`` field specifying that got banned along with a ``reason`` field specifying
why the user was banned that could be set to ``None``. why the user was banned that could be set to ``None``.

12
discord/invite.py
View File

@ -56,22 +56,22 @@ class Invite(Hashable):
Attributes Attributes
----------- -----------
max_age: int max_age: :class:`int`
How long the before the invite expires in seconds. A value of 0 indicates that it doesn't expire. How long the before the invite expires in seconds. A value of 0 indicates that it doesn't expire.
code: str code: :class:`str`
The URL fragment used for the invite. The URL fragment used for the invite.
guild: :class:`Guild` guild: :class:`Guild`
The guild the invite is for. The guild the invite is for.
revoked: bool revoked: :class:`bool`
Indicates if the invite has been revoked. Indicates if the invite has been revoked.
created_at: `datetime.datetime` created_at: `datetime.datetime`
A datetime object denoting the time the invite was created. A datetime object denoting the time the invite was created.
temporary: bool temporary: :class:`bool`
Indicates that the invite grants temporary membership. Indicates that the invite grants temporary membership.
If True, members who joined via this invite will be kicked upon disconnect. If True, members who joined via this invite will be kicked upon disconnect.
uses: int uses: :class:`int`
How many times the invite has been used. How many times the invite has been used.
max_uses: int max_uses: :class:`int`
How many times the invite can be used. How many times the invite can be used.
inviter: :class:`User` inviter: :class:`User`
The user who created the invite. The user who created the invite.

16
discord/member.py
View File

@ -43,15 +43,15 @@ class VoiceState:
Attributes Attributes
------------ ------------
deaf: bool deaf: :class:`bool`
Indicates if the user is currently deafened by the guild. Indicates if the user is currently deafened by the guild.
mute: bool mute: :class:`bool`
Indicates if the user is currently muted by the guild. Indicates if the user is currently muted by the guild.
self_mute: bool self_mute: :class:`bool`
Indicates if the user is currently muted by their own accord. Indicates if the user is currently muted by their own accord.
self_deaf: bool self_deaf: :class:`bool`
Indicates if the user is currently deafened by their own accord. Indicates if the user is currently deafened by their own accord.
afk: bool afk: :class:`bool`
Indicates if the user is currently in the AFK channel in the guild. Indicates if the user is currently in the AFK channel in the guild.
channel: :class:`VoiceChannel` channel: :class:`VoiceChannel`
The voice channel that the user is currently connected to. None if the user The voice channel that the user is currently connected to. None if the user
@ -138,20 +138,20 @@ class Member(discord.abc.Messageable, _BaseUser):
Attributes Attributes
---------- ----------
roles roles
A list of :class:`Role` that the member belongs to. Note that the first element of this 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. These roles are sorted by their position list is always the default '@everyone' role. These roles are sorted by their position
in the role hierarchy. in the role hierarchy.
joined_at : `datetime.datetime` joined_at : `datetime.datetime`
A datetime object that specifies the date and time in UTC that the member joined the guild for A datetime object that specifies the date and time in UTC that the member joined the guild for
the first time. the first time.
status : :class:`Status` status : :class:`Status`
The member's status. There is a chance that the status will be a ``str`` The member's status. There is a chance that the status will be a :class:`str`
if it is a value that is not recognised by the enumerator. if it is a value that is not recognised by the enumerator.
game : :class:`Game` game : :class:`Game`
The game that the user is currently playing. Could be None if no game is being played. The game that the user is currently playing. Could be None if no game is being played.
guild : :class:`Guild` guild : :class:`Guild`
The guild that the member belongs to. The guild that the member belongs to.
nick : Optional[str] nick : Optional[:class:`str`]
The guild specific nickname of the user. The guild specific nickname of the user.
""" """

32
discord/message.py
View File

@ -40,20 +40,20 @@ class Attachment:
Attributes Attributes
------------ ------------
id: int id: :class:`int`
The attachment ID. The attachment ID.
size: int size: :class:`int`
The attachment size in bytes. The attachment size in bytes.
height: Optional[int] height: Optional[:class:`int`]
The attachment's height, in pixels. Only applicable to images. The attachment's height, in pixels. Only applicable to images.
width: Optional[int] width: Optional[:class:`int`]
The attachment's width, in pixels. Only applicable to images. The attachment's width, in pixels. Only applicable to images.
filename: str filename: :class:`str`
The attachment's filename. The attachment's filename.
url: str url: :class:`str`
The attachment URL. If the message this attachment was attached The attachment URL. If the message this attachment was attached
to is deleted, then this will 404. to is deleted, then this will 404.
proxy_url: str proxy_url: :class:`str`
The proxy URL. This is a cached version of the :attr:`~Attachment.url` in the The proxy URL. This is a cached version of the :attr:`~Attachment.url` in the
case of images. When the message is deleted, this URL might be valid for a few case of images. When the message is deleted, this URL might be valid for a few
minutes or not valid at all. minutes or not valid at all.
@ -111,7 +111,7 @@ class Message:
Attributes Attributes
----------- -----------
tts: bool tts: :class:`bool`
Specifies if the message was done with text-to-speech. Specifies if the message was done with text-to-speech.
type: :class:`MessageType` type: :class:`MessageType`
The type of message. In most cases this should not be checked, but it is helpful The type of message. In most cases this should not be checked, but it is helpful
@ -119,7 +119,7 @@ class Message:
author author
A :class:`Member` that sent the message. If :attr:`channel` is a A :class:`Member` that sent the message. If :attr:`channel` is a
private channel, then it is a :class:`User` instead. private channel, then it is a :class:`User` instead.
content: str content: :class:`str`
The actual contents of the message. The actual contents of the message.
nonce nonce
The value used by the discord guild and the client to verify that the message is successfully sent. The value used by the discord guild and the client to verify that the message is successfully sent.
@ -132,7 +132,7 @@ class Message:
call: Optional[:class:`CallMessage`] call: Optional[:class:`CallMessage`]
The call that the message refers to. This is only applicable to messages of type The call that the message refers to. This is only applicable to messages of type
:attr:`MessageType.call`. :attr:`MessageType.call`.
mention_everyone: bool mention_everyone: :class:`bool`
Specifies if the message mentions everyone. Specifies if the message mentions everyone.
.. note:: .. note::
@ -141,7 +141,7 @@ class Message:
Rather this boolean indicates if the ``@everyone`` text is in the message Rather this boolean indicates if the ``@everyone`` text is in the message
**and** it did end up mentioning everyone. **and** it did end up mentioning everyone.
mentions: list mentions: :class:`list`
A list of :class:`Member` that were mentioned. If the message is in a private message A list of :class:`Member` that were mentioned. If the message is in a private message
then the list will be of :class:`User` instead. For messages that are not of type then the list will be of :class:`User` instead. For messages that are not of type
:attr:`MessageType.default`\, this array can be used to aid in system messages. :attr:`MessageType.default`\, this array can be used to aid in system messages.
@ -152,20 +152,20 @@ class Message:
The order of the mentions list is not in any particular order so you should The order of the mentions list is not in any particular order so you should
not rely on it. This is a discord limitation, not one with the library. not rely on it. This is a discord limitation, not one with the library.
channel_mentions: list channel_mentions: :class:`list`
A list of :class:`abc.GuildChannel` that were mentioned. If the message is in a private message A list of :class:`abc.GuildChannel` that were mentioned. If the message is in a private message
then the list is always empty. then the list is always empty.
role_mentions: list role_mentions: :class:`list`
A list of :class:`Role` that were mentioned. If the message is in a private message A list of :class:`Role` that were mentioned. If the message is in a private message
then the list is always empty. then the list is always empty.
id: int id: :class:`int`
The message ID. The message ID.
webhook_id: Optional[int] webhook_id: Optional[:class:`int`]
If this message was sent by a webhook, then this is the webhook ID's that sent this If this message was sent by a webhook, then this is the webhook ID's that sent this
message. message.
attachments: List[:class:`Attachment`] attachments: List[:class:`Attachment`]
A list of attachments given to a message. A list of attachments given to a message.
pinned: bool pinned: :class:`bool`
Specifies if the message is currently pinned. Specifies if the message is currently pinned.
reactions : List[:class:`Reaction`] reactions : List[:class:`Reaction`]
Reactions to a message. Reactions can be either custom emoji or standard unicode emoji. Reactions to a message. Reactions can be either custom emoji or standard unicode emoji.

2
discord/object.py
View File

@ -56,7 +56,7 @@ class Object(Hashable):
Attributes Attributes
----------- -----------
id : str id : :class:`str`
The ID of the object. The ID of the object.
""" """

2
discord/opus.py
View File

@ -142,7 +142,7 @@ class OpusError(DiscordException):
Attributes Attributes
---------- ----------
code : int code : :class:`int`
The error code returned. The error code returned.
""" """

8
discord/reaction.py
View File

@ -54,11 +54,11 @@ class Reaction:
Attributes Attributes
----------- -----------
emoji: :class:`Emoji` or str emoji: :class:`Emoji` or :class:`str`
The reaction emoji. May be a custom emoji, or a unicode emoji. The reaction emoji. May be a custom emoji, or a unicode emoji.
count: int count: :class:`int`
Number of times this reaction was made Number of times this reaction was made
me: bool me: :class:`bool`
If the user sent this reaction. If the user sent this reaction.
message: :class:`Message` message: :class:`Message`
Message this reaction is for. Message this reaction is for.
@ -73,7 +73,7 @@ class Reaction:
@property @property
def custom_emoji(self): def custom_emoji(self):
"""bool: If this is a custom emoji.""" """:class:`bool`: If this is a custom emoji."""
return not isinstance(self.emoji, str) return not isinstance(self.emoji, str)
def __eq__(self, other): def __eq__(self, other):

14
discord/role.py
View File

@ -71,9 +71,9 @@ class Role(Hashable):
Attributes Attributes
---------- ----------
id: int id: :class:`int`
The ID for the role. The ID for the role.
name: str name: :class:`str`
The name of the role. The name of the role.
permissions: :class:`Permissions` permissions: :class:`Permissions`
Represents the role's permissions. Represents the role's permissions.
@ -81,15 +81,15 @@ class Role(Hashable):
The guild the role belongs to. The guild the role belongs to.
colour: :class:`Colour` colour: :class:`Colour`
Represents the role colour. An alias exists under ``color``. Represents the role colour. An alias exists under ``color``.
hoist: bool hoist: :class:`bool`
Indicates if the role will be displayed separately from other members. Indicates if the role will be displayed separately from other members.
position: int position: :class:`int`
The position of the role. This number is usually positive. The bottom The position of the role. This number is usually positive. The bottom
role has a position of 0. role has a position of 0.
managed: bool managed: :class:`bool`
Indicates if the role is managed by the guild through some form of Indicates if the role is managed by the guild through some form of
integrations such as Twitch. integrations such as Twitch.
mentionable: bool mentionable: :class:`bool`
Indicates if the role can be mentioned by users. Indicates if the role can be mentioned by users.
""" """
@ -164,7 +164,7 @@ class Role(Hashable):
@property @property
def members(self): def members(self):
"""Returns a list of :class:`Member` with this role.""" """Returns a :class:`list` of :class:`Member` with this role."""
all_members = self.guild.members all_members = self.guild.members
if self.is_default(): if self.is_default():
return all_members return all_members

6
discord/shard.py
View File

@ -122,7 +122,7 @@ class AutoShardedClient(Client):
Attributes Attributes
------------ ------------
shard_ids: Optional[List[int]] shard_ids: Optional[List[:class:`int`]]
An optional list of shard_ids to launch the shards with. An optional list of shard_ids to launch the shards with.
""" """
def __init__(self, *args, loop=None, **kwargs): def __init__(self, *args, loop=None, **kwargs):
@ -171,7 +171,7 @@ class AutoShardedClient(Client):
@property @property
def latency(self): def latency(self):
"""float: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
This operates similarly to :meth:`.Client.latency` except it uses the average This operates similarly to :meth:`.Client.latency` except it uses the average
latency of every shard's latency. To get a list of shard latency, check the latency of every shard's latency. To get a list of shard latency, check the
@ -183,7 +183,7 @@ class AutoShardedClient(Client):
@property @property
def latencies(self): def latencies(self):
"""List[Tuple[int, float]]: A list of latencies between a HEARTBEAT and a HEARTBEAT_ACK in seconds. """List[Tuple[:class:`int`, :class:`float`]]: A list of latencies between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
This returns a list of tuples with elements ``(shard_id, latency)``. This returns a list of tuples with elements ``(shard_id, latency)``.
""" """

42
discord/user.py
View File

@ -100,7 +100,7 @@ class BaseUser(_BaseUser):
return self.avatar_url_as(format=None, size=1024) return self.avatar_url_as(format=None, size=1024)
def is_avatar_animated(self): def is_avatar_animated(self):
"""bool: Returns True if the user has an animated avatar.""" """:class:`bool`: Returns True if the user has an animated avatar."""
return bool(self.avatar and self.avatar.startswith('a_')) return bool(self.avatar and self.avatar.startswith('a_'))
def avatar_url_as(self, *, format=None, static_format='webp', size=1024): def avatar_url_as(self, *, format=None, static_format='webp', size=1024):
@ -249,23 +249,23 @@ class ClientUser(BaseUser):
Attributes Attributes
----------- -----------
name: str name: :class:`str`
The user's username. The user's username.
id: int id: :class:`int`
The user's unique ID. The user's unique ID.
discriminator: str discriminator: :class:`str`
The user's discriminator. This is given when the username has conflicts. The user's discriminator. This is given when the username has conflicts.
avatar: Optional[str] avatar: Optional[:class:`str`]
The avatar hash the user has. Could be None. The avatar hash the user has. Could be None.
bot: bool bot: :class:`bool`
Specifies if the user is a bot account. Specifies if the user is a bot account.
verified: bool verified: :class:`bool`
Specifies if the user is a verified account. Specifies if the user is a verified account.
email: Optional[str] email: Optional[:class:`str`]
The email the user used when registering. The email the user used when registering.
mfa_enabled: bool mfa_enabled: :class:`bool`
Specifies if the user has MFA turned on and working. Specifies if the user has MFA turned on and working.
premium: bool premium: :class:`bool`
Specifies if the user is a premium user (e.g. has Discord Nitro). Specifies if the user is a premium user (e.g. has Discord Nitro).
""" """
__slots__ = ('email', 'verified', 'mfa_enabled', 'premium', '_relationships') __slots__ = ('email', 'verified', 'mfa_enabled', 'premium', '_relationships')
@ -300,17 +300,17 @@ class ClientUser(BaseUser):
@property @property
def relationships(self): def relationships(self):
"""Returns a list of :class:`Relationship` that the user has.""" """Returns a :class:`list` of :class:`Relationship` that the user has."""
return list(self._relationships.values()) return list(self._relationships.values())
@property @property
def friends(self): def friends(self):
"""Returns a list of :class:`User`\s that the user is friends with.""" """Returns a :class:`list` of :class:`User`\s that the user is friends with."""
return [r.user for r in self._relationships.values() if r.type is RelationshipType.friend] return [r.user for r in self._relationships.values() if r.type is RelationshipType.friend]
@property @property
def blocked(self): def blocked(self):
"""Returns a list of :class:`User`\s that the user has blocked.""" """Returns a :class:`list` of :class:`User`\s that the user has blocked."""
return [r.user for r in self._relationships.values() if r.type is RelationshipType.blocked] return [r.user for r in self._relationships.values() if r.type is RelationshipType.blocked]
@asyncio.coroutine @asyncio.coroutine
@ -411,7 +411,7 @@ class ClientUser(BaseUser):
Parameters Parameters
----------- -----------
\*recipients \*recipients
An argument list of :class:`User` to have in An argument :class:`list` of :class:`User` to have in
your group. your group.
Return Return
@ -460,15 +460,15 @@ class User(BaseUser, discord.abc.Messageable):
Attributes Attributes
----------- -----------
name: str name: :class:`str`
The user's username. The user's username.
id: int id: :class:`int`
The user's unique ID. The user's unique ID.
discriminator: str discriminator: :class:`str`
The user's discriminator. This is given when the username has conflicts. The user's discriminator. This is given when the username has conflicts.
avatar: Optional[str] avatar: Optional[:class:`str`]
The avatar hash the user has. Could be None. The avatar hash the user has. Could be None.
bot: bool bot: :class:`bool`
Specifies if the user is a bot account. Specifies if the user is a bot account.
""" """
@ -512,14 +512,14 @@ class User(BaseUser, discord.abc.Messageable):
return self._state.user.get_relationship(self.id) return self._state.user.get_relationship(self.id)
def is_friend(self): def is_friend(self):
"""bool: Checks if the user is your friend.""" """:class:`bool`: Checks if the user is your friend."""
r = self.relationship r = self.relationship
if r is None: if r is None:
return False return False
return r.type is RelationshipType.friend return r.type is RelationshipType.friend
def is_blocked(self): def is_blocked(self):
"""bool: Checks if the user is blocked.""" """:class:`bool`: Checks if the user is blocked."""
r = self.relationship r = self.relationship
if r is None: if r is None:
return False return False

8
discord/voice_client.py
View File

@ -75,11 +75,11 @@ class VoiceClient:
Attributes Attributes
----------- -----------
session_id: str session_id: :class:`str`
The voice connection session ID. The voice connection session ID.
token: str token: :class:`str`
The voice connection token. The voice connection token.
endpoint: str endpoint: :class:`str`
The endpoint we are connecting to. The endpoint we are connecting to.
channel: :class:`abc.Connectable` channel: :class:`abc.Connectable`
The voice channel connected to. The voice channel connected to.
@ -288,7 +288,7 @@ class VoiceClient:
yield from self.main_ws.voice_state(guild_id, channel.id) yield from self.main_ws.voice_state(guild_id, channel.id)
def is_connected(self): def is_connected(self):
"""bool: Indicates if the voice client is connected to voice.""" """:class:`bool`: Indicates if the voice client is connected to voice."""
return self._connected.is_set() return self._connected.is_set()
# audio related # audio related

16
discord/webhook.py
View File

@ -68,7 +68,7 @@ class WebhookAdapter:
multipart: Optional[dict] multipart: Optional[dict]
A dict containing multipart form data to send with A dict containing multipart form data to send with
the request. If a filename is being uploaded, then it will the request. If a filename is being uploaded, then it will
be under a ``file`` key which will have a 3-element tuple be under a ``file`` key which will have a 3-element :class:`tuple`
denoting ``(filename, file, content_type)``. denoting ``(filename, file, content_type)``.
payload: Optional[dict] payload: Optional[dict]
The JSON to send with the request, if any. The JSON to send with the request, if any.
@ -320,20 +320,20 @@ class Webhook:
Attributes Attributes
------------ ------------
id: int id: :class:`int`
The webhook's ID The webhook's ID
token: str token: :class:`str`
The authentication token of the webhook. The authentication token of the webhook.
guild_id: Optional[int] guild_id: Optional[:class:`int`]
The guild ID this webhook is for. The guild ID this webhook is for.
channel_id: Optional[int] channel_id: Optional[:class:`int`]
The channel ID this webhook is for. The channel ID this webhook is for.
user: Optional[:class:`abc.User`] user: Optional[:class:`abc.User`]
The user this webhook was created by. If the webhook was The user this webhook was created by. If the webhook was
received without authentication then this will be ``None``. received without authentication then this will be ``None``.
name: Optional[str] name: Optional[:class:`str`]
The default name of the webhook. The default name of the webhook.
avatar: Optional[str] avatar: Optional[:class:`str`]
The default avatar of the webhook. The default avatar of the webhook.
""" """
@ -581,7 +581,7 @@ class Webhook:
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:`Embed` and
it must be a rich embed type. You cannot mix the ``embed`` parameter with the it must be a rich embed type. You cannot mix the ``embed`` parameter with the
``embeds`` parameter, which must be a list of :class:`Embed` objects to send. ``embeds`` parameter, which must be a :class:`list` of :class:`Embed` objects to send.
Parameters Parameters
------------ ------------

62
docs/api.rst
View File

@ -94,7 +94,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
All the events must be a |corourl|_. If they aren't, then you might get unexpected All the events must be a |corourl|_. If they aren't, then you might get unexpected
errors. In order to turn a function into a coroutine they must either be ``async def`` errors. In order to turn a function into a coroutine they must either be ``async def``
functions or in 3.4 decorated with ``@asyncio.coroutine``. functions or in 3.4 decorated with :func:`asyncio.coroutine`.
The following two functions are examples of coroutine functions: :: The following two functions are examples of coroutine functions: ::
@ -172,7 +172,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
WebSocket. The voice WebSocket will not trigger this event. WebSocket. The voice WebSocket will not trigger this event.
:param msg: The message passed in from the WebSocket library. :param msg: The message passed in from the WebSocket library.
Could be ``bytes`` for a binary message or ``str`` Could be :class:`bytes` for a binary message or :class:`str`
for a regular message. for a regular message.
.. function:: on_socket_raw_send(payload) .. function:: on_socket_raw_send(payload)
@ -190,8 +190,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
WebSocket. The voice WebSocket will not trigger this event. WebSocket. The voice WebSocket will not trigger this event.
:param payload: The message that is about to be passed on to the :param payload: The message that is about to be passed on to the
WebSocket library. It can be ``bytes`` to denote a binary WebSocket library. It can be :class:`bytes` to denote a binary
message or ``str`` to denote a regular text message. message or :class:`str` to denote a regular text message.
.. function:: on_typing(channel, user, when) .. function:: on_typing(channel, user, when)
@ -1359,14 +1359,14 @@ Certain utilities make working with async iterators easier, detailed below.
|coro| |coro|
Flattens the async iterator into a ``list`` with all the elements. Flattens the async iterator into a :class:`list` with all the elements.
:return: A list of every element in the async iterator. :return: A list of every element in the async iterator.
:rtype: list :rtype: list
.. method:: map(func) .. method:: map(func)
This is similar to the built-in ``map`` function. Another This is similar to the built-in :func:`map <python:map>` function. Another
:class:`AsyncIterator` is returned that executes the function on :class:`AsyncIterator` is returned that executes the function on
every element it is iterating over. This function can either be a every element it is iterating over. This function can either be a
regular function or a coroutine. regular function or a coroutine.
@ -1384,7 +1384,7 @@ Certain utilities make working with async iterators easier, detailed below.
.. method:: filter(predicate) .. method:: filter(predicate)
This is similar to the built-in ``filter`` function. Another This is similar to the built-in :func:`filter <python:filter>` function. Another
:class:`AsyncIterator` is returned that filters over the original :class:`AsyncIterator` is returned that filters over the original
async iterator. This predicate can be a regular function or a coroutine. async iterator. This predicate can be a regular function or a coroutine.
@ -1474,15 +1474,15 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: name .. attribute:: name
*str* – A name of something. :class:`str` – A name of something.
.. attribute:: icon .. attribute:: icon
*str* – A guild's icon hash. See also :attr:`Guild.icon`. :class:`str` – A guild's icon hash. See also :attr:`Guild.icon`.
.. attribute:: splash .. attribute:: splash
*str* – The guild's invite splash hash. See also :attr:`Guild.splash`. :class:`str` – The guild's invite splash hash. See also :attr:`Guild.splash`.
.. attribute:: owner .. attribute:: owner
@ -1512,15 +1512,15 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: afk_timeout .. attribute:: afk_timeout
*int* – The guild's AFK timeout. See :attr:`Guild.afk_timeout`. :class:`int` – The guild's AFK timeout. See :attr:`Guild.afk_timeout`.
.. attribute:: mfa_level .. attribute:: mfa_level
*int* - The guild's MFA level. See :attr:`Guild.mfa_level`. :class:`int` - The guild's MFA level. See :attr:`Guild.mfa_level`.
.. attribute:: widget_enabled .. attribute:: widget_enabled
*bool* – The guild's widget has been enabled or disabled. :class:`bool` – The guild's widget has been enabled or disabled.
.. attribute:: widget_channel .. attribute:: widget_channel
@ -1543,37 +1543,37 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: default_message_notifications .. attribute:: default_message_notifications
*int* – The guild's default message notification setting. :class:`int` – The guild's default message notification setting.
.. attribute:: vanity_url_code .. attribute:: vanity_url_code
*str* – The guild's vanity URL. :class:`str` – The guild's vanity URL.
See also :meth:`Guild.vanity_invite` and :meth:`Guild.change_vanity_invite`. See also :meth:`Guild.vanity_invite` and :meth:`Guild.change_vanity_invite`.
.. attribute:: position .. attribute:: position
*int* – The position of a :class:`Role` or :class:`abc.GuildChannel`. :class:`int` – The position of a :class:`Role` or :class:`abc.GuildChannel`.
.. attribute:: type .. attribute:: type
*Union[int, str]* – The type of channel or channel permission overwrite. *Union[int, str]* – The type of channel or channel permission overwrite.
If the type is an ``int``, then it is a type of channel which can be either If the type is an :class:`int`, then it is a type of channel which can be either
``0`` to indicate a text channel or ``1`` to indicate a voice channel. ``0`` to indicate a text channel or ``1`` to indicate a voice channel.
If the type is a ``str``, then it is a type of permission overwrite which If the type is a :class:`str`, then it is a type of permission overwrite which
can be either ``'role'`` or ``'member'``. can be either ``'role'`` or ``'member'``.
.. attribute:: topic .. attribute:: topic
*str* – The topic of a :class:`TextChannel`. :class:`str` – The topic of a :class:`TextChannel`.
See also :attr:`TextChannel.topic`. See also :attr:`TextChannel.topic`.
.. attribute:: bitrate .. attribute:: bitrate
*int* – The bitrate of a :class:`VoiceChannel`. :class:`int` – The bitrate of a :class:`VoiceChannel`.
See also :attr:`VoiceChannel.bitrate`. See also :attr:`VoiceChannel.bitrate`.
@ -1605,13 +1605,13 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: deaf .. attribute:: deaf
*bool* – Whether the member is being server deafened. :class:`bool` – Whether the member is being server deafened.
See also :attr:`VoiceState.deaf`. See also :attr:`VoiceState.deaf`.
.. attribute:: mute .. attribute:: mute
*bool* – Whether the member is being server muted. :class:`bool` – Whether the member is being server muted.
See also :attr:`VoiceState.mute`. See also :attr:`VoiceState.mute`.
@ -1630,19 +1630,19 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: hoist .. attribute:: hoist
*bool* – Whether the role is being hoisted or not. :class:`bool` – Whether the role is being hoisted or not.
See also :attr:`Role.hoist` See also :attr:`Role.hoist`
.. attribute:: mentionable .. attribute:: mentionable
*bool* – Whether the role is mentionable or not. :class:`bool` – Whether the role is mentionable or not.
See also :attr:`Role.mentionable` See also :attr:`Role.mentionable`
.. attribute:: code .. attribute:: code
*str* – The invite's code. :class:`str` – The invite's code.
See also :attr:`Invite.code` See also :attr:`Invite.code`
@ -1661,25 +1661,25 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: max_uses .. attribute:: max_uses
*int* – The invite's max uses. :class:`int` – The invite's max uses.
See also :attr:`Invite.max_uses`. See also :attr:`Invite.max_uses`.
.. attribute:: uses .. attribute:: uses
*int* – The invite's current uses. :class:`int` – The invite's current uses.
See also :attr:`Invite.uses`. See also :attr:`Invite.uses`.
.. attribute:: max_age .. attribute:: max_age
*int* – The invite's max age in seconds. :class:`int` – The invite's max age in seconds.
See also :attr:`Invite.max_age`. See also :attr:`Invite.max_age`.
.. attribute:: temporary .. attribute:: temporary
*bool* – If the invite is a temporary invite. :class:`bool` – If the invite is a temporary invite.
See also :attr:`Invite.temporary`. See also :attr:`Invite.temporary`.
@ -1690,11 +1690,11 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: id .. attribute:: id
*int* – The ID of the object being changed. :class:`int` – The ID of the object being changed.
.. attribute:: avatar .. attribute:: avatar
*str* – The avatar hash of a member. :class:`str` – The avatar hash of a member.
See also :attr:`User.avatar`. See also :attr:`User.avatar`.

4
docs/conf.py
View File

@ -35,6 +35,7 @@ sys.path.append(os.path.abspath('extensions'))
extensions = [ extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
'sphinx.ext.extlinks', 'sphinx.ext.extlinks',
'sphinx.ext.intersphinx',
'sphinxcontrib.asyncio', 'sphinxcontrib.asyncio',
'details' 'details'
] ]
@ -50,6 +51,9 @@ extlinks = {
'issue': ('https://github.com/Rapptz/discord.py/issues/%s', 'issue '), 'issue': ('https://github.com/Rapptz/discord.py/issues/%s', 'issue '),
} }
# Links used for cross-referencing stuff in other documentation
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
rst_prolog = """ rst_prolog = """
.. |coro| replace:: This function is a |corourl|_. .. |coro| replace:: This function is a |corourl|_.
.. |maybecoro| replace:: This function *could be a* |corourl|_. .. |maybecoro| replace:: This function *could be a* |corourl|_.

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

@ -189,7 +189,7 @@ Converters come in a few flavours:
- A regular callable object that takes an argument as a sole parameter and returns a different type. - A regular callable object that takes an argument as a sole parameter and returns a different type.
- These range from your own function, to something like ``bool`` or ``int``. - These range from your own function, to something like :class:`bool` or :class:`int`.
- A custom class that inherits from :class:`~ext.commands.Converter`. - A custom class that inherits from :class:`~ext.commands.Converter`.

13
docs/faq.rst
View File

@ -18,7 +18,7 @@ Questions regarding coroutines and asyncio belong here.
I get a SyntaxError around the word ``async``\! What should I do? I get a SyntaxError around the word ``async``\! What should I do?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This ``SyntaxError`` happens because you're using a Python version lower than 3.5. Python 3.4 uses ``@asyncio.coroutine`` and This :exc:`SyntaxError` happens because you're using a Python version lower than 3.5. Python 3.4 uses ``@asyncio.coroutine`` and
``yield from`` instead of ``async def`` and ``await``. ``yield from`` instead of ``async def`` and ``await``.
Thus you must do the following instead: :: Thus you must do the following instead: ::
@ -59,7 +59,7 @@ despair however, because not all forms of blocking are bad! Using blocking calls
sure that you don't excessively block functions. Remember, if you block for too long then your bot will freeze since it has sure that you don't excessively block functions. Remember, if you block for too long then your bot will freeze since it has
not stopped the function's execution at that point to do other things. not stopped the function's execution at that point to do other things.
A common source of blocking for too long is something like ``time.sleep(n)``. Don't do that. Use ``asyncio.sleep(n)`` A common source of blocking for too long is something like :func:`time.sleep`. Don't do that. Use :func:`asyncio.sleep`
instead. Similar to this example: :: instead. Similar to this example: ::
# bad # bad
@ -69,7 +69,7 @@ instead. Similar to this example: ::
await asyncio.sleep(10) await asyncio.sleep(10)
Another common source of blocking for too long is using HTTP requests with the famous module ``requests``. While ``requests`` Another common source of blocking for too long is using HTTP requests with the famous module ``requests``. While ``requests``
is an amazing module for non-asynchronous programming, it is not a good choice for ``asyncio`` because certain requests can 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. block the event loop too long. Instead, use the ``aiohttp`` library which is installed on the side with this library.
Consider the following example: :: Consider the following example: ::
@ -135,7 +135,7 @@ To upload multiple files, you can use the ``files`` keyword argument instead of
await channel.send(files=my_files) await channel.send(files=my_files)
If you want to upload something from a URL, you will have to use an HTTP request using ``aiohttp`` If you want to upload something from a URL, you will have to use an HTTP request using ``aiohttp``
and then pass an ``io.BytesIO`` instance to :class:`File` like so: and then pass an :class:`io.BytesIO` instance to :class:`File` like so:
.. code-block:: python3 .. code-block:: python3
@ -192,8 +192,7 @@ that wraps up a couple of aspects.
The first gotcha that you must be aware of is that calling a coroutine is not a thread-safe operation. Since we are The first gotcha that you must be aware of is that calling a coroutine is not a thread-safe operation. Since we are
technically in another thread, we must take caution in calling thread-safe operations so things do not bug out. Luckily for technically in another thread, we must take caution in calling thread-safe operations so things do not bug out. Luckily for
us, ``asyncio`` comes with a ``asyncio.run_coroutine_threadsafe`` us, :mod:`asyncio` comes with a :func:`asyncio.run_coroutine_threadsafe` function that allows us to call
`function <https://docs.python.org/3.5/library/asyncio-task.html#asyncio.run_coroutine_threadsafe>`_ that allows us to call
a coroutine from another thread. a coroutine from another thread.
.. warning:: .. warning::
@ -201,7 +200,7 @@ a coroutine from another thread.
This function is only part of 3.5.1+ and 3.4.4+. If you are not using these Python versions then use This function is only part of 3.5.1+ and 3.4.4+. If you are not using these Python versions then use
``discord.compat.run_coroutine_threadsafe``. ``discord.compat.run_coroutine_threadsafe``.
However, this function returns a ``concurrent.Future`` and to actually call it we have to fetch its result. Putting all of However, this function returns a :class:`concurrent.Future` and to actually call it we have to fetch its result. Putting all of
this together we can do the following: :: this together we can do the following: ::
def my_after(error): def my_after(error):

8
docs/logging.rst
View File

@ -4,7 +4,7 @@
Setting Up Logging Setting Up Logging
=================== ===================
*discord.py* logs errors and debug information via the `logging`_ python *discord.py* logs errors and debug information via the :mod:`logging` python
module. It is strongly recommended that the logging module is module. It is strongly recommended that the logging module is
configured, as no errors or warnings will be output if it is not set up. configured, as no errors or warnings will be output if it is not set up.
Configuration of the ``logging`` module can be as simple as:: Configuration of the ``logging`` module can be as simple as::
@ -21,7 +21,7 @@ The optional ``level`` argument specifies what level of events to log
out and can any of ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, and out and can any of ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, and
``DEBUG`` and if not specified defaults to ``WARNING``. ``DEBUG`` and if not specified defaults to ``WARNING``.
More advance setups are possible with the ``logging`` module. To for More advance setups are possible with the :mod:`logging` module. To for
example write the logs to a file called ``discord.log`` instead of example write the logs to a file called ``discord.log`` instead of
outputting them to to the console the following snippet can be used:: outputting them to to the console the following snippet can be used::
@ -41,6 +41,4 @@ stdout of your program.
For more information, check the documentation and tutorial of the For more information, check the documentation and tutorial of the
`logging`_ module. :mod:`logging` module.
.. _logging: https://docs.python.org/2/library/logging.html

4
docs/migrating.rst
View File

@ -22,7 +22,7 @@ Below are major model changes that have happened in v1.0
Snowflakes are int Snowflakes are int
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
Before v1.0, all snowflakes (the ``id`` attribute) were strings. This has been changed to ``int``. Before v1.0, all snowflakes (the ``id`` attribute) were strings. This has been changed to :class:`int`.
Quick example: :: Quick example: ::
@ -657,7 +657,7 @@ For example, to wait for a reaction: ::
# use user and reaction # use user and reaction
Since this function now can return multiple arguments, the ``timeout`` parameter will now raise a ``asyncio.TimeoutError`` Since this function now can return multiple arguments, the ``timeout`` parameter will now raise a :exc:`asyncio.TimeoutError`
when reached instead of setting the return to ``None``. For example: when reached instead of setting the return to ``None``. For example:
.. code-block:: python3 .. code-block:: python3

2
docs/migrating_to_async.rst
View File

@ -142,7 +142,7 @@ Some examples of previously valid behaviour that is now invalid
if client.servers[0].name == "test": if client.servers[0].name == "test":
# do something # do something
Since they are no longer ``list``\s, they no longer support indexing or any operation other than iterating. Since they are no longer :obj:`list`\s, they no longer support indexing or any operation other than iterating.
In order to get the old behaviour you should explicitly cast it to a list. In order to get the old behaviour you should explicitly cast it to a list.
.. code-block:: python3 .. code-block:: python3

Write Preview
Loading…
Cancel
Save