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

Add intersphinx

Browse Source
This commit is contained in:
Tobotimus 2018-01-06 17:21:56 -05:00 committed by Rapptz
parent 0ef866a704
commit 3112e1c17e
37 changed files with 267 additions and 268 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
discord/abc.py
View File

@ -54,7 +54,7 @@ class Snowflake(metaclass=abc.ABCMeta):
Attributes
-----------
id: int
id: :class:`int`
The model's unique ID.
"""
__slots__ = ()
@ -91,13 +91,13 @@ class User(metaclass=abc.ABCMeta):
Attributes
-----------
name: str
name: :class:`str`
The user's username.
discriminator: str
discriminator: :class:`str`
The user's discriminator.
avatar: Optional[str]
avatar: Optional[:class:`str`]
The avatar hash the user has.
bot: bool
bot: :class:`bool`
If the user is a bot account.
"""
__slots__ = ()
@ -175,11 +175,11 @@ class GuildChannel:
Attributes
-----------
name: str
name: :class:`str`
The channel name.
guild: :class:`Guild`
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.
e.g. the top channel is position 0.
"""
@ -282,7 +282,7 @@ class GuildChannel:
@property
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."""
ret = []
for overwrite in filter(lambda o: o.type == 'role', self._overwrites):
@ -297,7 +297,7 @@ class GuildChannel:
@property
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
@property
@ -688,7 +688,7 @@ class Messageable(metaclass=abc.ABCMeta):
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 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**.
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):
"""|coro|
Returns a list of :class:`Message` that are currently pinned.
Returns a :class:`list` of :class:`Message` that are currently pinned.
Raises
-------

4
discord/audit_logs.py
View File

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

6
discord/calls.py
View File

@ -53,7 +53,7 @@ class CallMessage:
@property
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
@property
@ -87,7 +87,7 @@ class GroupCall:
-----------
call: :class:`CallMessage`
The call message associated with this group call.
unavailable: bool
unavailable: :obj:`bool`
Denotes if this group call is unavailable.
ringing: List[:class:`User`]
A list of users that are currently being rung to join the call.
@ -122,7 +122,7 @@ class GroupCall:
@property
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]
me = self.channel.me
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
-----------
name: str
name: :class:`str`
The channel name.
guild: :class:`Guild`
The guild the channel belongs to.
id: int
id: :class:`int`
The channel ID.
category_id: int
category_id: :class:`int`
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.
position: int
position: :class:`int`
The position in the channel list. This is a number that starts at 0. e.g. the
top channel is position 0.
"""
@ -116,7 +116,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
@property
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]
def is_nsfw(self):
@ -404,20 +404,20 @@ class VoiceChannel(discord.abc.Connectable, discord.abc.GuildChannel, Hashable):
Attributes
-----------
name: str
name: :class:`str`
The channel name.
guild: :class:`Guild`
The guild the channel belongs to.
id: int
id: :class:`int`
The channel ID.
category_id: int
category_id: :class:`int`
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
top channel is position 0.
bitrate: int
bitrate: :class:`int`
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.
"""
@ -521,13 +521,13 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
Attributes
-----------
name: str
name: :class:`str`
The category name.
guild: :class:`Guild`
The guild the category belongs to.
id: int
id: :class:`int`
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
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.
me: :class:`ClientUser`
The user presenting yourself.
id: int
id: :class:`int`
The direct message channel ID.
"""
@ -716,17 +716,17 @@ class GroupChannel(discord.abc.Messageable, Hashable):
Attributes
----------
recipients: list of :class:`User`
recipients: :class:`list` of :class:`User`
The users you are participating with in the group channel.
me: :class:`ClientUser`
The user presenting yourself.
id: int
id: :class:`int`
The group channel ID.
owner: :class:`User`
The user that owns the group channel.
icon: Optional[str]
icon: Optional[:class:`str`]
The group channel's icon hash if provided.
name: Optional[str]
name: Optional[:class:`str`]
The group channel's name if provided.
"""

22
discord/client.py
View File

@ -175,7 +175,7 @@ class Client:
@property
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.
"""
@ -214,7 +214,7 @@ class Client:
return self._connection.voice_clients
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()
@asyncio.coroutine
@ -581,14 +581,14 @@ class Client:
# properties
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()
# helpers/getters
@property
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())
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
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
``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.
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
:ref:`documentation <discord-api-events>` for a list of events and their
parameters.
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
---------
@ -723,7 +721,7 @@ class Client:
parameters of the event being waited for.
timeout: Optional[float]
The number of seconds to wait before timing out and raising
``asyncio.TimeoutError``\.
:exc:`asyncio.TimeoutError`.
Raises
-------
@ -733,7 +731,7 @@ class Client:
Returns
--------
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
:ref:`event reference <discord-api-events>`.
"""
@ -789,7 +787,7 @@ class Client:
return 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):
coro = asyncio.coroutine(coro)

4
discord/colour.py
View File

@ -26,7 +26,7 @@ DEALINGS IN THE SOFTWARE.
class Colour:
"""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.
@ -50,7 +50,7 @@ class Colour:
Attributes
------------
value: int
value: :class:`int`
The raw integer colour value.
"""

18
discord/embeds.py
View File

@ -58,27 +58,27 @@ class Embed:
of the object:
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
is invalid or empty, then a special sentinel value is returned,
:attr:`Embed.Empty`.
For ease of use, all parameters that expect a ``str`` are implicitly
casted to ``str`` for you.
For ease of use, all parameters that expect a :class:`str` are implicitly
casted to :class:`str` for you.
Attributes
-----------
title: str
title: :class:`str`
The title of the embed.
type: str
type: :class:`str`
The type of embed. Usually "rich".
description: str
description: :class:`str`
The description of the embed.
url: str
url: :class:`str`
The URL of the embed.
timestamp: `datetime.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.
Empty
A special sentinel value used by ``EmbedProxy`` and this class
@ -334,7 +334,7 @@ class Embed:
@property
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.

16
discord/emoji.py
View File

@ -58,10 +58,10 @@ class PartialReactionEmoji(namedtuple('PartialReactionEmoji', 'name id')):
Attributes
-----------
name: str
name: :class:`str`
The custom emoji name, if applicable, or the unicode codepoint
of the non-custom emoji.
id: Optional[int]
id: Optional[:class:`int`]
The ID of the custom emoji, if applicable.
"""
@ -116,17 +116,17 @@ class Emoji(Hashable):
Attributes
-----------
name: str
name: :class:`str`
The name of the emoji.
id: int
id: :class:`int`
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).
animated: bool
animated: :class:`bool`
Whether an emoji is animated or not.
managed: bool
managed: :class:`bool`
If this emoji is managed by a Twitch integration.
guild_id: int
guild_id: :class:`int`
The guild ID the emoji belongs to.
"""
__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
text: str
text: :class:`str`
The text of the error. Could be an empty string.
status: int
status: :class:`int`
The status code of the HTTP request.
code: int
code: :class:`int`
The Discord specific error code for the failure.
"""
@ -150,11 +150,11 @@ class ConnectionClosed(ClientException):
Attributes
-----------
code: int
code: :class:`int`
The close code of the websocket.
reason: str
reason: :class:`str`
The reason provided for the closure.
shard_id: Optional[int]
shard_id: Optional[:class:`int`]
The shard ID that got closed if applicable.
"""
def __init__(self, original, *, shard_id):

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

@ -436,7 +436,7 @@ class BotBase(GroupMixin):
Parameters
-----------
func : coroutine
func : :ref:`coroutine <coroutine>`
The extra event to listen to.
name : Optional[str]
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
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
match will be the invocation prefix. You can get this prefix via
:attr:`.Context.prefix`.
description : str
description : :class:`str`
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
than ignoring itself. If ``False`` (the default) then the bot will ignore
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
a call to :meth:`~.Bot.remove_command` with 'help' as the argument would do the
trick.
pm_help : Optional[bool]
pm_help : Optional[:class:`bool`]
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
``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
message becomes too long (dictated by more than 1000 characters).
Defaults to ``False``.
help_attrs : dict
help_attrs : :class:`dict`
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
the implementation of the command. The attributes will be the same as the
ones passed in the :class:`.Command` constructor. Note that ``pass_context``
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
is not found. Useful for i18n. Defaults to ``"No command called {} found."``.
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
subcommand but the command does not have any subcommands. Defaults to
``"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.
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
:meth:`.is_owner` then it is fetched automatically using
: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.
bot: :class:`.Bot`
The bot that contains the command being executed.
args: list
args: :class:`list`
The list of transformed arguments that were passed into the command.
If this is accessed during the :func:`on_command_error` event
then this list could be incomplete.
kwargs: dict
kwargs: :class:`dict`
A dictionary of transformed arguments that were passed into the command.
Similar to :attr:`args`\, if this is accessed in the
: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.
command
The command (i.e. :class:`.Command` or its superclasses) that is being
invoked currently.
invoked_with: str
invoked_with: :class:`str`
The command name that triggered this invocation. Useful for finding out
which alias called the command.
invoked_subcommand
The subcommand (i.e. :class:`.Command` or its superclasses) that was
invoked. If no valid subcommand was invoked then this is equal to
`None`.
subcommand_passed: Optional[str]
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`.
command_failed: bool
command_failed: :class:`bool`
A boolean that indicates if the command failed to be parsed, checked,
or invoked.
"""

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

@ -405,11 +405,11 @@ class clean_content(Converter):
Attributes
------------
fix_channel_mentions: bool
fix_channel_mentions: :obj:`bool`
Whether to clean channel mentions.
use_nicknames: bool
use_nicknames: :obj:`bool`
Whether to use nicknames when transforming mentions.
escape_markdown: bool
escape_markdown: :obj:`bool`
Whether to also escape special markdown characters.
"""
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
-----------
name: str
name: :class:`str`
The name of the command.
callback: coroutine
callback: :ref:`coroutine <coroutine>`
The coroutine that is executed when the command is called.
help: str
help: :class:`str`
The long help text for the command.
brief: str
brief: :class:`str`
The short help text for the command. If this is not specified
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.
aliases: list
aliases: :class:`list`
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.
If the command is invoked while it is disabled, then
: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:`.CheckFailure` exception is raised to the :func:`.on_command_error`
event.
description: str
description: :class:`str`
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
help output.
rest_is_raw: bool
rest_is_raw: :class:`bool`
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
that handles :exc:`.MissingRequiredArgument` and default values in a
regular matter rather than passing the rest completely raw. If ``True``
then the keyword-only argument will pass in the rest of the arguments
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
requirements are met (e.g. ``?foo a b c`` when only expecting ``a``
and ``b``). Otherwise :func:`.on_command_error` and local error handlers
@ -519,7 +519,7 @@ class Command:
Parameters
-----------
coro
coro : :ref:`coroutine <coroutine>`
The coroutine to register as the local error handler.
Raises
@ -703,7 +703,7 @@ class GroupMixin:
Attributes
-----------
all_commands: dict
all_commands: :class:`dict`
A mapping of command name to :class:`.Command` or superclass
objects.
"""
@ -861,7 +861,7 @@ class Group(GroupMixin, Command):
Attributes
-----------
invoke_without_command: bool
invoke_without_command: :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
@ -950,7 +950,7 @@ def command(name=None, cls=None, **attrs):
By default the ``help`` attribute is received automatically from the
docstring of the function and is cleaned up with the use of
``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
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
A class with attributes ``rate``, ``per``, and ``type`` similar to
the :func:`.cooldown` decorator.
retry_after: float
retry_after: :class:`float`
The amount of seconds to wait before you can retry again.
"""
def __init__(self, cooldown, retry_after):
@ -144,7 +144,7 @@ class MissingPermissions(CheckFailure):
Attributes
-----------
missing_perms: list
missing_perms: :class:`list`
The required permissions that are missing.
"""
def __init__(self, missing_perms, *args):
@ -164,7 +164,7 @@ class BotMissingPermissions(CheckFailure):
Attributes
-----------
missing_perms: list
missing_perms: :class:`list`
The required permissions that are missing.
"""
def __init__(self, missing_perms, *args):

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

@ -58,11 +58,11 @@ class Paginator:
Attributes
-----------
prefix: str
prefix: :class:`str`
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.
max_size: int
max_size: :class:`int`
The maximum amount of codepoints allowed in a page.
"""
def __init__(self, prefix='```', suffix='```', max_size=2000):
@ -133,13 +133,13 @@ class HelpFormatter:
Attributes
-----------
show_hidden: bool
show_hidden: :class:`bool`
Dictates if hidden commands should be shown in the output.
Defaults to ``False``.
show_check_failure: bool
show_check_failure: :class:`bool`
Dictates if commands that have their :attr:`.Command.checks` failed
shown. Defaults to ``False``.
width: int
width: :class:`int`
The maximum number of characters that fit in a line.
Defaults to 80.
"""
@ -149,15 +149,15 @@ class HelpFormatter:
self.show_check_failure = show_check_failure
def has_subcommands(self):
"""bool: Specifies if the command has subcommands."""
""":class:`bool`: Specifies if the command has subcommands."""
return isinstance(self.command, GroupMixin)
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
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)
def shorten(self, text):
@ -168,7 +168,7 @@ class HelpFormatter:
@property
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."""
try:
commands = self.command.all_commands if not self.is_cog() else self.context.bot.all_commands
@ -209,7 +209,7 @@ class HelpFormatter:
--------
iterable
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):

4
discord/file.py
View File

@ -32,7 +32,7 @@ class File:
Attributes
-----------
fp: Union[str, BinaryIO]
fp: Union[:class:`str`, BinaryIO]
A file-like object opened in binary mode and read mode
or a filename representing a file in the hard drive to
open.
@ -44,7 +44,7 @@ class File:
To pass binary data, consider usage of ``io.BytesIO``.
filename: Optional[str]
filename: Optional[:class:`str`]
The filename to display when uploading to Discord.
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.

6
discord/game.py
View File

@ -47,11 +47,11 @@ class Game:
Attributes
-----------
name: str
name: :class:`str`
The game's name.
url: str
url: :class:`str`
The game's URL. Usually used for twitch streaming.
type: int
type: :class:`int`
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
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
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
----------
name: str
name: :class:`str`
The guild name.
roles
A list of :class:`Role` that the guild has available.
A :class:`list` of :class:`Role` that the guild has available.
emojis
A tuple of :class:`Emoji` that the guild owns.
A :class:`tuple` of :class:`Emoji` that the guild owns.
region: :class:`VoiceRegion`
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.
afk_timeout: int
will be a :class:`str` if the value is not recognised by the enumerator.
afk_timeout: :class:`int`
The timeout to get sent to the AFK channel.
afk_channel: Optional[:class:`VoiceChannel`]
The channel that denotes the AFK channel. None if it doesn't exist.
icon: str
icon: :class:`str`
The guild's icon.
id: int
id: :class:`int`
The guild's ID.
owner_id: int
owner_id: :class:`int`
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
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.
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
the guild does not require 2FA for their administrative members. If the value is
1 then they do.
@ -107,7 +107,7 @@ class Guild(Hashable):
The guild's verification level.
explicit_content_filter: :class:`ContentFilter`
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:
- ``VIP_REGIONS``: Guild has VIP voice regions
@ -116,7 +116,7 @@ class Guild(Hashable):
- ``VERIFIED``: Guild is a "verified" server.
- ``MORE_EMOJI``: Guild is allowed to have more than 50 custom emoji.
splash: str
splash: :class:`str`
The guild's invite splash.
"""
@ -264,7 +264,7 @@ class Guild(Hashable):
@property
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
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.
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`)
as the key and a :class:`PermissionOverwrite` as the value.
@ -582,7 +582,7 @@ class Guild(Hashable):
name: str
The channel's name.
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.
Useful for creating secret channels.
category: Optional[:class:`CategoryChannel`]
@ -807,7 +807,7 @@ class Guild(Hashable):
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`
that got banned along with a ``reason`` field specifying
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
-----------
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.
code: str
code: :class:`str`
The URL fragment used for the invite.
guild: :class:`Guild`
The guild the invite is for.
revoked: bool
revoked: :class:`bool`
Indicates if the invite has been revoked.
created_at: `datetime.datetime`
A datetime object denoting the time the invite was created.
temporary: bool
temporary: :class:`bool`
Indicates that the invite grants temporary membership.
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.
max_uses: int
max_uses: :class:`int`
How many times the invite can be used.
inviter: :class:`User`
The user who created the invite.

16
discord/member.py
View File

@ -43,15 +43,15 @@ class VoiceState:
Attributes
------------
deaf: bool
deaf: :class:`bool`
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.
self_mute: bool
self_mute: :class:`bool`
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.
afk: bool
afk: :class:`bool`
Indicates if the user is currently in the AFK channel in the guild.
channel: :class:`VoiceChannel`
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
----------
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
in the role hierarchy.
joined_at : `datetime.datetime`
A datetime object that specifies the date and time in UTC that the member joined the guild for
the first time.
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.
game : :class:`Game`
The game that the user is currently playing. Could be None if no game is being played.
guild : :class:`Guild`
The guild that the member belongs to.
nick : Optional[str]
nick : Optional[:class:`str`]
The guild specific nickname of the user.
"""

32
discord/message.py
View File

@ -40,20 +40,20 @@ class Attachment:
Attributes
------------
id: int
id: :class:`int`
The attachment ID.
size: int
size: :class:`int`
The attachment size in bytes.
height: Optional[int]
height: Optional[:class:`int`]
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.
filename: str
filename: :class:`str`
The attachment's filename.
url: str
url: :class:`str`
The attachment URL. If the message this attachment was attached
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
case of images. When the message is deleted, this URL might be valid for a few
minutes or not valid at all.
@ -111,7 +111,7 @@ class Message:
Attributes
-----------
tts: bool
tts: :class:`bool`
Specifies if the message was done with text-to-speech.
type: :class:`MessageType`
The type of message. In most cases this should not be checked, but it is helpful
@ -119,7 +119,7 @@ class Message:
author
A :class:`Member` that sent the message. If :attr:`channel` is a
private channel, then it is a :class:`User` instead.
content: str
content: :class:`str`
The actual contents of the message.
nonce
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`]
The call that the message refers to. This is only applicable to messages of type
:attr:`MessageType.call`.
mention_everyone: bool
mention_everyone: :class:`bool`
Specifies if the message mentions everyone.
.. note::
@ -141,7 +141,7 @@ class Message:
Rather this boolean indicates if the ``@everyone`` text is in the message
**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
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.
@ -152,20 +152,20 @@ 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: list
channel_mentions: :class:`list`
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: list
role_mentions: :class:`list`
A list of :class:`Role` that were mentioned. If the message is in a private message
then the list is always empty.
id: int
id: :class:`int`
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
message.
attachments: List[:class:`Attachment`]
A list of attachments given to a message.
pinned: bool
pinned: :class:`bool`
Specifies if the message is currently pinned.
reactions : List[:class:`Reaction`]
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
-----------
id : str
id : :class:`str`
The ID of the object.
"""

2
discord/opus.py
View File

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

8
discord/reaction.py
View File

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

14
discord/role.py
View File

@ -71,9 +71,9 @@ class Role(Hashable):
Attributes
----------
id: int
id: :class:`int`
The ID for the role.
name: str
name: :class:`str`
The name of the role.
permissions: :class:`Permissions`
Represents the role's permissions.
@ -81,15 +81,15 @@ class Role(Hashable):
The guild the role belongs to.
colour: :class:`Colour`
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.
position: int
position: :class:`int`
The position of the role. This number is usually positive. The bottom
role has a position of 0.
managed: bool
managed: :class:`bool`
Indicates if the role is managed by the guild through some form of
integrations such as Twitch.
mentionable: bool
mentionable: :class:`bool`
Indicates if the role can be mentioned by users.
"""
@ -164,7 +164,7 @@ class Role(Hashable):
@property
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
if self.is_default():
return all_members

6
discord/shard.py
View File

@ -122,7 +122,7 @@ class AutoShardedClient(Client):
Attributes
------------
shard_ids: Optional[List[int]]
shard_ids: Optional[List[:class:`int`]]
An optional list of shard_ids to launch the shards with.
"""
def __init__(self, *args, loop=None, **kwargs):
@ -171,7 +171,7 @@ class AutoShardedClient(Client):
@property
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
latency of every shard's latency. To get a list of shard latency, check the
@ -183,7 +183,7 @@ class AutoShardedClient(Client):
@property
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)``.
"""

42
discord/user.py
View File

@ -100,7 +100,7 @@ class BaseUser(_BaseUser):
return self.avatar_url_as(format=None, size=1024)
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_'))
def avatar_url_as(self, *, format=None, static_format='webp', size=1024):
@ -249,23 +249,23 @@ class ClientUser(BaseUser):
Attributes
-----------
name: str
name: :class:`str`
The user's username.
id: int
id: :class:`int`
The user's unique ID.
discriminator: str
discriminator: :class:`str`
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.
bot: bool
bot: :class:`bool`
Specifies if the user is a bot account.
verified: bool
verified: :class:`bool`
Specifies if the user is a verified account.
email: Optional[str]
email: Optional[:class:`str`]
The email the user used when registering.
mfa_enabled: bool
mfa_enabled: :class:`bool`
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).
"""
__slots__ = ('email', 'verified', 'mfa_enabled', 'premium', '_relationships')
@ -300,17 +300,17 @@ class ClientUser(BaseUser):
@property
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())
@property
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]
@property
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]
@asyncio.coroutine
@ -411,7 +411,7 @@ class ClientUser(BaseUser):
Parameters
-----------
\*recipients
An argument list of :class:`User` to have in
An argument :class:`list` of :class:`User` to have in
your group.
Return
@ -460,15 +460,15 @@ class User(BaseUser, discord.abc.Messageable):
Attributes
-----------
name: str
name: :class:`str`
The user's username.
id: int
id: :class:`int`
The user's unique ID.
discriminator: str
discriminator: :class:`str`
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.
bot: bool
bot: :class:`bool`
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)
def is_friend(self):
"""bool: Checks if the user is your friend."""
""":class:`bool`: Checks if the user is your friend."""
r = self.relationship
if r is None:
return False
return r.type is RelationshipType.friend
def is_blocked(self):
"""bool: Checks if the user is blocked."""
""":class:`bool`: Checks if the user is blocked."""
r = self.relationship
if r is None:
return False

8
discord/voice_client.py
View File

@ -75,11 +75,11 @@ class VoiceClient:
Attributes
-----------
session_id: str
session_id: :class:`str`
The voice connection session ID.
token: str
token: :class:`str`
The voice connection token.
endpoint: str
endpoint: :class:`str`
The endpoint we are connecting to.
channel: :class:`abc.Connectable`
The voice channel connected to.
@ -288,7 +288,7 @@ class VoiceClient:
yield from self.main_ws.voice_state(guild_id, channel.id)
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()
# audio related

16
discord/webhook.py
View File

@ -68,7 +68,7 @@ class WebhookAdapter:
multipart: Optional[dict]
A dict containing multipart form data to send with
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)``.
payload: Optional[dict]
The JSON to send with the request, if any.
@ -320,20 +320,20 @@ class Webhook:
Attributes
------------
id: int
id: :class:`int`
The webhook's ID
token: str
token: :class:`str`
The authentication token of the webhook.
guild_id: Optional[int]
guild_id: Optional[:class:`int`]
The guild ID this webhook is for.
channel_id: Optional[int]
channel_id: Optional[:class:`int`]
The channel ID this webhook is for.
user: Optional[:class:`abc.User`]
The user this webhook was created by. If the webhook was
received without authentication then this will be ``None``.
name: Optional[str]
name: Optional[:class:`str`]
The default name of the webhook.
avatar: Optional[str]
avatar: Optional[:class:`str`]
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
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
------------

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
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: ::
@ -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.
: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.
.. 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.
:param payload: The message that is about to be passed on to the
WebSocket library. It can be ``bytes`` to denote a binary
message or ``str`` to denote a regular text message.
WebSocket library. It can be :class:`bytes` to denote a binary
message or :class:`str` to denote a regular text message.
.. function:: on_typing(channel, user, when)
@ -1359,14 +1359,14 @@ Certain utilities make working with async iterators easier, detailed below.
|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.
:rtype: list
.. 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
every element it is iterating over. This function can either be a
regular function or a coroutine.
@ -1384,7 +1384,7 @@ Certain utilities make working with async iterators easier, detailed below.
.. 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
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
*str* – A name of something.
:class:`str` – A name of something.
.. 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
*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
@ -1512,15 +1512,15 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. 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
*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
*bool* – The guild's widget has been enabled or disabled.
:class:`bool` – The guild's widget has been enabled or disabled.
.. 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
*int* – The guild's default message notification setting.
:class:`int` – The guild's default message notification setting.
.. 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`.
.. 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
*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.
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'``.
.. attribute:: topic
*str* – The topic of a :class:`TextChannel`.
:class:`str` – The topic of a :class:`TextChannel`.
See also :attr:`TextChannel.topic`.
.. attribute:: bitrate
*int* – The bitrate of a :class:`VoiceChannel`.
:class:`int` – The bitrate of a :class:`VoiceChannel`.
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
*bool* – Whether the member is being server deafened.
:class:`bool` – Whether the member is being server deafened.
See also :attr:`VoiceState.deaf`.
.. attribute:: mute
*bool* – Whether the member is being server muted.
:class:`bool` – Whether the member is being server muted.
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
*bool* – Whether the role is being hoisted or not.
:class:`bool` – Whether the role is being hoisted or not.
See also :attr:`Role.hoist`
.. attribute:: mentionable
*bool* – Whether the role is mentionable or not.
:class:`bool` – Whether the role is mentionable or not.
See also :attr:`Role.mentionable`
.. attribute:: code
*str* – The invite's code.
:class:`str` – The invite's 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
*int* – The invite's max uses.
:class:`int` – The invite's max uses.
See also :attr:`Invite.max_uses`.
.. attribute:: uses
*int* – The invite's current uses.
:class:`int` – The invite's current uses.
See also :attr:`Invite.uses`.
.. 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`.
.. attribute:: temporary
*bool* – If the invite is a temporary invite.
:class:`bool` – If the invite is a temporary invite.
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
*int* – The ID of the object being changed.
:class:`int` – The ID of the object being changed.
.. attribute:: avatar
*str* – The avatar hash of a member.
:class:`str` – The avatar hash of a member.
See also :attr:`User.avatar`.

4
docs/conf.py
View File

@ -35,6 +35,7 @@ sys.path.append(os.path.abspath('extensions'))
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.extlinks',
'sphinx.ext.intersphinx',
'sphinxcontrib.asyncio',
'details'
]
@ -50,6 +51,9 @@ extlinks = {
'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 = """
.. |coro| replace:: This function is 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.
- 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`.

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?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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``.
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
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: ::
# bad
@ -69,7 +69,7 @@ instead. Similar to this example: ::
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 ``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.
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)
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
@ -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
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``
`function <https://docs.python.org/3.5/library/asyncio-task.html#asyncio.run_coroutine_threadsafe>`_ that allows us to call
us, :mod:`asyncio` comes with a :func:`asyncio.run_coroutine_threadsafe` function that allows us to call
a coroutine from another thread.
.. 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
``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: ::
def my_after(error):

8
docs/logging.rst
View File

@ -4,7 +4,7 @@
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
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::
@ -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
``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
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
`logging`_ module.
.. _logging: https://docs.python.org/2/library/logging.html
:mod:`logging` module.

4
docs/migrating.rst
View File

@ -22,7 +22,7 @@ Below are major model changes that have happened in v1.0
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: ::
@ -657,7 +657,7 @@ For example, to wait for a 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:
.. 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":
# 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.
.. code-block:: python3