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

First pass at documentation reform.

Browse Source
This commit is contained in:
Rapptz
2017-05-12 20:14:34 -04:00
parent be2e706b2a
commit b44bba6ee6
35 changed files with 2558 additions and 682 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
discord/abc.py
View File

@ -47,11 +47,22 @@ class _Undefined:
_undefined = _Undefined()
class Snowflake(metaclass=abc.ABCMeta):
"""An ABC that details the common operations on a Discord model.
Almost all :ref:`Discord models <discord_api_models>` meet this
abstract base class.
Attributes
-----------
id: int
The model's unique ID.
"""
__slots__ = ()
@property
@abc.abstractmethod
def created_at(self):
"""Returns the model's creation time in UTC."""
raise NotImplementedError
@classmethod
@ -68,16 +79,39 @@ class Snowflake(metaclass=abc.ABCMeta):
return NotImplemented
class User(metaclass=abc.ABCMeta):
"""An ABC that details the common operations on a Discord user.
The following implement this ABC:
- :class:`User`
- :class:`ClientUser`
- :class:`Member`
This ABC must also implement :class:`abc.Snowflake`.
Attributes
-----------
name: str
The user's username.
discriminator: str
The user's discriminator.
avatar: Optional[str]
The avatar hash the user has.
bot: bool
If the user is a bot account.
"""
__slots__ = ()
@property
@abc.abstractmethod
def display_name(self):
"""Returns the user's display name."""
raise NotImplementedError
@property
@abc.abstractmethod
def mention(self):
"""Returns a string that allows you to mention the given user."""
raise NotImplementedError
@classmethod
@ -97,6 +131,20 @@ class User(metaclass=abc.ABCMeta):
return NotImplemented
class PrivateChannel(metaclass=abc.ABCMeta):
"""An ABC that details the common operations on a private Discord channel.
The follow implement this ABC:
- :class:`DMChannel`
- :class:`GroupChannel`
This ABC must also implement :class:`abc.Snowflake`.
Attributes
-----------
me: :class:`ClientUser`
The user presenting yourself.
"""
__slots__ = ()
@classmethod
@ -115,6 +163,25 @@ class PrivateChannel(metaclass=abc.ABCMeta):
_Overwrites = namedtuple('_Overwrites', 'id allow deny type')
class GuildChannel:
"""An ABC that details the common operations on a Discord guild channel.
The follow implement this ABC:
- :class:`TextChannel`
- :class:`VoiceChannel`
This ABC must also implement :class:`abc.Snowflake`.
Attributes
-----------
name: str
The channel name.
guild: :class:`Guild`
The guild the channel belongs to.
position: int
The position in the channel list. This is a number that starts at 0.
e.g. the top channel is position 0.
"""
__slots__ = ()
def __str__(self):
@ -539,6 +606,20 @@ class GuildChannel:
return result
class Messageable(metaclass=abc.ABCMeta):
"""An ABC that details the common operations on a model that can send messages.
The follow implement this ABC:
- :class:`TextChannel`
- :class:`DMChannel`
- :class:`GroupChannel`
- :class:`User`
- :class:`Member`
- :class:`~ext.commands.Context`
This ABC must also implement :class:`abc.Snowflake`.
"""
__slots__ = ()
@asyncio.coroutine
@ -728,7 +809,7 @@ class Messageable(metaclass=abc.ABCMeta):
def history(self, *, limit=100, before=None, after=None, around=None, reverse=None):
"""Return an :class:`AsyncIterator` that enables receiving the destination's message history.
You must have Read Message History permissions to use this.
You must have :attr:`~Permissions.read_message_history` permissions to use this.
All parameters are optional.
@ -799,6 +880,13 @@ class Messageable(metaclass=abc.ABCMeta):
class Connectable(metaclass=abc.ABCMeta):
"""An ABC that details the common operations on a channel that can
connect to a voice server.
The follow implement this ABC:
- :class:`VoiceChannel`
"""
__slots__ = ()
@abc.abstractmethod

4
discord/channel.py
View File

@ -428,7 +428,7 @@ class DMChannel(discord.abc.Messageable, Hashable):
----------
recipient: :class:`User`
The user you are participating with in the direct message channel.
me: :class:`User`
me: :class:`ClientUser`
The user presenting yourself.
id: int
The direct message channel ID.
@ -507,7 +507,7 @@ class GroupChannel(discord.abc.Messageable, Hashable):
----------
recipients: list of :class:`User`
The users you are participating with in the group channel.
me: :class:`User`
me: :class:`ClientUser`
The user presenting yourself.
id: int
The group channel ID.

4
discord/emoji.py
View File

@ -123,7 +123,7 @@ class Emoji(Hashable):
Deletes the custom emoji.
You must have :attr:`Permissions.manage_emojis` permission to
You must have :attr:`~Permissions.manage_emojis` permission to
do this.
Guild local emotes can only be deleted by user bots.
@ -149,7 +149,7 @@ class Emoji(Hashable):
Edits the custom emoji.
You must have :attr:`Permissions.manage_emojis` permission to
You must have :attr:`~Permissions.manage_emojis` permission to
do this.
Guild local emotes can only be edited by user bots.

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

@ -55,7 +55,7 @@ def when_mentioned_or(*prefixes):
See Also
----------
:func:`when_mentioned`
:func:`.when_mentioned`
"""
def inner(bot, msg):
r = list(prefixes)
@ -212,17 +212,17 @@ class BotBase(GroupMixin):
def check(self, func):
"""A decorator that adds a global check to the bot.
A global check is similar to a :func:`check` that is applied
A global check is similar to a :func:`.check` that is applied
on a per command basis except it is run before any command checks
have been verified and applies to every command the bot has.
.. info::
.. note::
This function can either be a regular function or a coroutine.
Similar to a command :func:`check`\, this takes a single parameter
of type :class:`Context` and can only raise exceptions derived from
:exc:`CommandError`.
Similar to a command :func:`.check`\, this takes a single parameter
of type :class:`.Context` and can only raise exceptions derived from
:exc:`.CommandError`.
Example
---------
@ -240,7 +240,7 @@ class BotBase(GroupMixin):
def add_check(self, func):
"""Adds a global check to the bot.
This is the non-decorator interface to :meth:`check`.
This is the non-decorator interface to :meth:`.check`.
Parameters
-----------
@ -275,15 +275,15 @@ class BotBase(GroupMixin):
@asyncio.coroutine
def is_owner(self, user):
"""Checks if a :class:`User` or :class:`Member` is the owner of
"""Checks if a :class:`.User` or :class:`.Member` is the owner of
this bot.
If an :attr:`owner_id` is not set, it is fetched automatically
through the use of :meth:`application_info`.
through the use of :meth:`~.Bot.application_info`.
Parameters
-----------
user: :class:`abc.User`
user: :class:`.abc.User`
The user to check for.
"""
@ -300,11 +300,11 @@ class BotBase(GroupMixin):
called. This makes it a useful function to set up database
connections or any type of set up required.
This pre-invoke hook takes a sole parameter, a :class:`Context`.
This pre-invoke hook takes a sole parameter, a :class:`.Context`.
.. note::
The :meth:`before_invoke` and :meth:`after_invoke` hooks are
The :meth:`~.Bot.before_invoke` and :meth:`~.Bot.after_invoke` hooks are
only called if all checks and argument parsing procedures pass
without error. If any check or argument parsing procedures fail
then the hooks are not called.
@ -316,7 +316,7 @@ class BotBase(GroupMixin):
Raises
-------
discord.ClientException
:exc:`.ClientException`
The coroutine is not actually a coroutine.
"""
if not asyncio.iscoroutinefunction(coro):
@ -332,14 +332,14 @@ class BotBase(GroupMixin):
called. This makes it a useful function to clean-up database
connections or any type of clean up required.
This post-invoke hook takes a sole parameter, a :class:`Context`.
This post-invoke hook takes a sole parameter, a :class:`.Context`.
.. note::
Similar to :meth:`before_invoke`\, this is not called unless
Similar to :meth:`~.Bot.before_invoke`\, this is not called unless
checks and argument parsing procedures succeed. This hook is,
however, **always** called regardless of the internal command
callback raising an error (i.e. :exc:`CommandInvokeError`\).
callback raising an error (i.e. :exc:`.CommandInvokeError`\).
This makes it ideal for clean-up scenarios.
Parameters
@ -349,7 +349,7 @@ class BotBase(GroupMixin):
Raises
-------
discord.ClientException
:exc:`.ClientException`
The coroutine is not actually a coroutine.
"""
if not asyncio.iscoroutinefunction(coro):
@ -361,7 +361,7 @@ class BotBase(GroupMixin):
# listener registration
def add_listener(self, func, name=None):
"""The non decorator alternative to :meth:`listen`.
"""The non decorator alternative to :meth:`.listen`.
Parameters
-----------
@ -415,7 +415,7 @@ class BotBase(GroupMixin):
def listen(self, name=None):
"""A decorator that registers another function as an external
event listener. Basically this allows you to listen to multiple
events from different places e.g. such as :func:`discord.on_ready`
events from different places e.g. such as :func:`.on_ready`
The functions being listened to must be a coroutine.
@ -438,7 +438,7 @@ class BotBase(GroupMixin):
Raises
-------
discord.ClientException
:exc:`.ClientException`
The function being listened to is not a coroutine.
"""
@ -459,7 +459,7 @@ class BotBase(GroupMixin):
into a singular class that shares some state or no state at all.
The cog can also have a ``__global_check`` member function that allows
you to define a global check. See :meth:`check` for more info.
you to define a global check. See :meth:`.check` for more info.
More information will be documented soon.
@ -515,7 +515,7 @@ class BotBase(GroupMixin):
Returns
---------
Set[:class:`Command`]
Set[:class:`.Command`]
A unique set of commands without aliases that belong
to the cog.
"""
@ -675,27 +675,27 @@ class BotBase(GroupMixin):
Returns the invocation context from the message.
This is a more low-level counter-part for :meth:`process_message`
This is a more low-level counter-part for :meth:`.process_commands`
to allow users more fine grained control over the processing.
The returned context is not guaranteed to be a valid invocation
context, :attr:`Context.valid` must be checked to make sure it is.
context, :attr:`.Context.valid` must be checked to make sure it is.
If the context is not valid then it is not a valid candidate to be
invoked under :meth:`invoke`.
invoked under :meth:`~.Bot.invoke`.
Parameters
-----------
message: :class:`discord.Message`
The message to get the invocation context from.
cls: type
cls
The factory class that will be used to create the context.
By default, this is :class:`Context`. Should a custom
class be provided, it must be similar enough to :class:`Context`\'s
By default, this is :class:`.Context`. Should a custom
class be provided, it must be similar enough to :class:`.Context`\'s
interface.
Returns
--------
:class:`Context`
:class:`.Context`
The invocation context. The type of this can change via the
``cls`` parameter.
"""
@ -732,7 +732,7 @@ class BotBase(GroupMixin):
Parameters
-----------
ctx: :class:`Context`
ctx: :class:`.Context`
The invocation context to invoke.
"""
if ctx.command is not None:
@ -756,12 +756,12 @@ class BotBase(GroupMixin):
to the bot and other groups. Without this coroutine, none of the
commands will be triggered.
By default, this coroutine is called inside the :func:`on_message`
event. If you choose to override the :func:`on_message` event, then
By default, this coroutine is called inside the :func:`.on_message`
event. If you choose to override the :func:`.on_message` event, then
you should invoke this coroutine as well.
This is built using other low level tools, and is equivalent to a
call to :meth:`get_context` followed by a call to :meth:`invoke`.
call to :meth:`~.Bot.get_context` followed by a call to :meth:`~.Bot.invoke`.
Parameters
-----------
@ -782,7 +782,10 @@ class Bot(BotBase, discord.Client):
anything that you can do with a :class:`discord.Client` you can do with
this bot.
This class also subclasses :class:`GroupMixin` to provide the functionality
.. _deque: https://docs.python.org/3.4/library/collections.html#collections.deque
.. _event loop: https://docs.python.org/3/library/asyncio-eventloops.html
This class also subclasses :class:`.GroupMixin` to provide the functionality
to manage commands.
Attributes
@ -799,18 +802,18 @@ class Bot(BotBase, discord.Client):
The command prefix could also be a list or a 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`.
:attr:`.Context.prefix`.
description : str
The content prefixed into the default help message.
self_bot : 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.
formatter : :class:`HelpFormatter`
formatter : :class:`.HelpFormatter`
The formatter used to format the help message. By default, it uses a
the :class:`HelpFormatter`. Check it for more info on how to override it.
the :class:`.HelpFormatter`. Check it for more info on how to override it.
If you want to change the help command completely (add aliases, etc) then
a call to :meth:`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.
pm_help : Optional[bool]
A tribool that indicates if the help command should PM the user instead of
@ -823,7 +826,7 @@ class Bot(BotBase, discord.Client):
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``
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
The format string used when the help command is invoked with a command that
@ -833,16 +836,16 @@ class Bot(BotBase, discord.Client):
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.
:class:`.Command` attempted to get a subcommand and the second is the name.
owner_id: Optional[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:`application_info`.
:meth:`.is_owner` then it is fetched automatically using
:meth:`~.Bot.application_info`.
"""
pass
class AutoShardedBot(BotBase, discord.AutoShardedClient):
"""This is similar to :class:`Bot` except that it is derived from
"""This is similar to :class:`.Bot` except that it is derived from
:class:`discord.AutoShardedClient` instead.
"""
pass

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

@ -40,7 +40,7 @@ class Context(discord.abc.Messageable):
-----------
message: :class:`discord.Message`
The message that triggered the command being executed.
bot: :class:`Bot`
bot: :class:`.Bot`
The bot that contains the command being executed.
args: list
The list of transformed arguments that were passed into the command.
@ -53,13 +53,13 @@ class Context(discord.abc.Messageable):
prefix: str
The prefix that was used to invoke the 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_with: 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
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]
@ -93,7 +93,7 @@ class Context(discord.abc.Messageable):
Calls a command with the arguments given.
This is useful if you want to just call the callback that a
:class:`Command` holds internally.
:class:`.Command` holds internally.
Note
------
@ -101,7 +101,7 @@ class Context(discord.abc.Messageable):
Parameters
-----------
command : :class:`Command`
command : :class:`.Command`
A command or superclass of a command that is going to be called.
\*args
The arguments to to use.

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

@ -46,14 +46,14 @@ def _get_from_guilds(bot, getter, argument):
return result
class Converter:
"""The base class of custom converters that require the :class:`Context`
"""The base class of custom converters that require the :class:`.Context`
to be passed to be useful.
This allows you to implement converters that function similar to the
special cased ``discord`` classes.
Classes that derive from this should override the :meth:`convert` method
to do its conversion logic. This method must be a coroutine.
Classes that derive from this should override the :meth:`~.Converter.convert`
method to do its conversion logic. This method must be a coroutine.
"""
@asyncio.coroutine
@ -62,15 +62,13 @@ class Converter:
The method to override to do conversion logic.
This can either be a coroutine or a regular function.
If an error is found while converting, it is recommended to
raise a :class:`CommandError` derived exception as it will
raise a :exc:`.CommandError` derived exception as it will
properly propagate to the error handlers.
Parameters
-----------
ctx: :class:`Context`
ctx: :class:`.Context`
The invocation context that the argument is being used in.
argument: str
The argument that is being converted.
@ -86,6 +84,20 @@ class IDConverter(Converter):
return self._id_regex.match(argument)
class MemberConverter(IDConverter):
"""Converts to a :class:`Member`.
All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache.
The lookup strategy is as follows (in order):
1. Lookup by ID.
2. Lookup by mention.
3. Lookup by name#discrim
4. Lookup by name
5. Lookup by nickname
"""
@asyncio.coroutine
def convert(self, ctx, argument):
message = ctx.message
@ -112,6 +124,17 @@ class MemberConverter(IDConverter):
return result
class UserConverter(IDConverter):
"""Converts to a :class:`User`.
All lookups are via the global user cache.
The lookup strategy is as follows (in order):
1. Lookup by ID.
2. Lookup by mention.
3. Lookup by name#discrim
4. Lookup by name
"""
@asyncio.coroutine
def convert(self, ctx, argument):
match = self._get_id_match(argument) or re.match(r'<@!?([0-9]+)>$', argument)
@ -141,6 +164,17 @@ class UserConverter(IDConverter):
return result
class TextChannelConverter(IDConverter):
"""Converts to a :class:`TextChannel`.
All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache.
The lookup strategy is as follows (in order):
1. Lookup by ID.
2. Lookup by mention.
3. Lookup by name
"""
@asyncio.coroutine
def convert(self, ctx, argument):
bot = ctx.bot
@ -170,6 +204,17 @@ class TextChannelConverter(IDConverter):
return result
class VoiceChannelConverter(IDConverter):
"""Converts to a :class:`VoiceChannel`.
All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache.
The lookup strategy is as follows (in order):
1. Lookup by ID.
2. Lookup by mention.
3. Lookup by name
"""
@asyncio.coroutine
def convert(self, ctx, argument):
bot = ctx.bot
@ -198,6 +243,17 @@ class VoiceChannelConverter(IDConverter):
return result
class ColourConverter(Converter):
"""Converts to a :class:`Colour`.
The following formats are accepted:
- ``0x<hex>``
- ``#<hex>``
- ``0x#<hex>``
- Any of the ``classmethod`` in :class:`Colour`
- The ``_`` in the name can be optionally replaced with spaces.
"""
@asyncio.coroutine
def convert(self, ctx, argument):
arg = argument.replace('0x', '').lower()
@ -208,12 +264,24 @@ class ColourConverter(Converter):
value = int(arg, base=16)
return discord.Colour(value=value)
except ValueError:
method = getattr(discord.Colour, arg, None)
method = getattr(discord.Colour, arg.replace(' ', '_'), None)
if method is None or not inspect.ismethod(method):
raise BadArgument('Colour "{}" is invalid.'.format(arg))
return method()
class RoleConverter(IDConverter):
"""Converts to a :class:`Role`.
All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache.
The lookup strategy is as follows (in order):
1. Lookup by ID.
2. Lookup by mention.
3. Lookup by name
"""
@asyncio.coroutine
def convert(self, ctx, argument):
guild = ctx.message.guild
@ -228,11 +296,16 @@ class RoleConverter(IDConverter):
return result
class GameConverter(Converter):
"""Converts to :class:`Game`."""
@asyncio.coroutine
def convert(self, ctx, argument):
return discord.Game(name=argument)
class InviteConverter(Converter):
"""Converts to a :class:`Invite`.
This is done via an HTTP request using :meth:`.Bot.get_invite`.
"""
@asyncio.coroutine
def convert(self, ctx, argument):
try:
@ -242,6 +315,18 @@ class InviteConverter(Converter):
raise BadArgument('Invite is invalid or expired') from e
class EmojiConverter(IDConverter):
"""Converts to a :class:`Emoji`.
All lookups are via the local guild. If in a DM context, then the lookup
is done by the global cache.
The lookup strategy is as follows (in order):
1. Lookup by ID.
2. Lookup by extracting ID from the emoji.
3. Lookup by name
"""
@asyncio.coroutine
def convert(self, ctx, argument):
match = self._get_id_match(argument) or re.match(r'<:[a-zA-Z0-9]+:([0-9]+)>$', argument)
@ -272,6 +357,18 @@ class EmojiConverter(IDConverter):
return result
class clean_content(Converter):
"""Converts the argument to mention scrubbed version of
said content.
This behaves similarly to :attr:`.Message.clean_content`.
Attributes
------------
fix_channel_mentions: bool
Whether to clean channel mentions.
use_nicknames: bool
Whether to use nicknames when transforming mentions.
"""
def __init__(self, *, fix_channel_mentions=False, use_nicknames=True):
self.fix_channel_mentions = fix_channel_mentions
self.use_nicknames = use_nicknames

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

@ -88,54 +88,54 @@ class Command:
Attributes
-----------
name : str
name: str
The name of the command.
callback : coroutine
callback: coroutine
The coroutine that is executed when the command is called.
help : str
help: str
The long help text for the command.
brief : str
brief: 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: str
A replacement for arguments in the default help text.
aliases : list
aliases: list
The list of aliases the command can be invoked under.
pass_context : bool
A boolean that indicates that the current :class:`Context` should
pass_context: bool
A boolean that indicates that the current :class:`.Context` should
be passed as the **first parameter**. Defaults to `True`.
enabled : bool
enabled: 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`
:exc:`.DisabledCommand` is raised to the :func:`.on_command_error`
event. Defaults to ``True``.
parent : Optional[command]
parent: Optional[command]
The parent command that this command belongs to. ``None`` is there
isn't one.
checks
A list of predicates that verifies if the command could be executed
with the given :class:`Context` as the sole parameter. If an exception
with the given :class:`.Context` as the sole parameter. If an exception
is necessary to be thrown to signal failure, then one derived from
:exc:`CommandError` should be used. Note that if the checks fail then
:exc:`CheckFailure` exception is raised to the :func:`on_command_error`
: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: str
The message prefixed into the default help command.
hidden : bool
hidden: bool
If ``True``\, the default help command does not show this in the
help output.
rest_is_raw : bool
rest_is_raw: 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
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: 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
are called with :exc:`TooManyArguments`. Defaults to ``True``.
and ``b``). Otherwise :func:`.on_command_error` and local error handlers
are called with :exc:`.TooManyArguments`. Defaults to ``True``.
"""
def __init__(self, name, callback, **kwargs):
self.name = name
@ -418,7 +418,7 @@ class Command:
Parameters
-----------
ctx: :class:`Context`
ctx: :class:`.Context`
The invocation context to reset the cooldown under.
"""
if self._buckets.valid:
@ -439,8 +439,8 @@ class Command:
def error(self, coro):
"""A decorator that registers a coroutine as a local error handler.
A local error handler is an :func:`on_command_error` event limited to
a single command. However, the :func:`on_command_error` is still
A local error handler is an :func:`.on_command_error` event limited to
a single command. However, the :func:`.on_command_error` is still
invoked afterwards as the catch-all.
Parameters
@ -463,13 +463,13 @@ class Command:
def before_invoke(self, coro):
"""A decorator that registers a coroutine as a pre-invoke hook.
A pre-invoke hook is called directly before :meth:`invoke` is
A pre-invoke hook is called directly before the command is
called. This makes it a useful function to set up database
connections or any type of set up required.
This pre-invoke hook takes a sole parameter, a :class:`Context`.
This pre-invoke hook takes a sole parameter, a :class:`.Context`.
See :meth:`Bot.before_invoke` for more info.
See :meth:`.Bot.before_invoke` for more info.
Parameters
-----------
@ -478,7 +478,7 @@ class Command:
Raises
-------
discord.ClientException
:exc:`.ClientException`
The coroutine is not actually a coroutine.
"""
if not asyncio.iscoroutinefunction(coro):
@ -490,13 +490,13 @@ class Command:
def after_invoke(self, coro):
"""A decorator that registers a coroutine as a post-invoke hook.
A post-invoke hook is called directly after :meth:`invoke` is
A post-invoke hook is called directly after the command is
called. This makes it a useful function to clean-up database
connections or any type of clean up required.
This post-invoke hook takes a sole parameter, a :class:`Context`.
This post-invoke hook takes a sole parameter, a :class:`.Context`.
See :meth:`Bot.after_invoke` for more info.
See :meth:`.Bot.after_invoke` for more info.
Parameters
-----------
@ -505,7 +505,7 @@ class Command:
Raises
-------
discord.ClientException
:exc:`.ClientException`
The coroutine is not actually a coroutine.
"""
if not asyncio.iscoroutinefunction(coro):
@ -577,11 +577,11 @@ class Command:
"""|coro|
Checks if the command can be executed by checking all the predicates
inside the :attr:`checks` attribute.
inside the :attr:`.checks` attribute.
Parameters
-----------
ctx: :class:`Context`
ctx: :class:`.Context`
The ctx of the command currently being invoked.
Returns
@ -613,12 +613,12 @@ class Command:
class GroupMixin:
"""A mixin that implements common functionality for classes that behave
similar to :class:`Group` and are allowed to register commands.
similar to :class:`.Group` and are allowed to register commands.
Attributes
-----------
all_commands: dict
A mapping of command name to :class:`Command` or superclass
A mapping of command name to :class:`.Command` or superclass
objects.
"""
def __init__(self, **kwargs):
@ -627,7 +627,7 @@ class GroupMixin:
@property
def commands(self):
"""Set[:class:`Command`]: A unique set of commands without aliases that are registered."""
"""Set[:class:`.Command`]: A unique set of commands without aliases that are registered."""
return set(self.all_commands.values())
def recursively_remove_all_commands(self):
@ -637,11 +637,11 @@ class GroupMixin:
self.remove_command(command.name)
def add_command(self, command):
"""Adds a :class:`Command` or its superclasses into the internal list
"""Adds a :class:`.Command` or its superclasses into the internal list
of commands.
This is usually not called, instead the :meth:`command` or
:meth:`group` shortcut decorators are used instead.
This is usually not called, instead the :meth:`~.GroupMixin.command` or
:meth:`~.GroupMixin.group` shortcut decorators are used instead.
Parameters
-----------
@ -650,10 +650,10 @@ class GroupMixin:
Raises
-------
discord.ClientException
:exc:`.ClientException`
If the command is already registered.
TypeError
If the command passed is not a subclass of :class:`Command`.
If the command passed is not a subclass of :class:`.Command`.
"""
if not isinstance(command, Command):
@ -672,19 +672,19 @@ class GroupMixin:
self.all_commands[alias] = command
def remove_command(self, name):
"""Remove a :class:`Command` or subclasses from the internal list
"""Remove a :class:`.Command` or subclasses from the internal list
of commands.
This could also be used as a way to remove aliases.
Parameters
-----------
name : str
name: str
The name of the command to remove.
Returns
--------
Command or subclass
:class:`.Command` or subclass
The command that was removed. If the name is not valid then
`None` is returned instead.
"""
@ -711,7 +711,7 @@ class GroupMixin:
yield from command.walk_commands()
def get_command(self, name):
"""Get a :class:`Command` or subclasses from the internal list
"""Get a :class:`.Command` or subclasses from the internal list
of commands.
This could also be used as a way to get aliases.
@ -745,8 +745,8 @@ class GroupMixin:
return obj
def command(self, *args, **kwargs):
"""A shortcut decorator that invokes :func:`command` and adds it to
the internal command list via :meth:`add_command`.
"""A shortcut decorator that invokes :func:`.command` and adds it to
the internal command list via :meth:`~.GroupMixin.add_command`.
"""
def decorator(func):
result = command(*args, **kwargs)(func)
@ -756,8 +756,8 @@ class GroupMixin:
return decorator
def group(self, *args, **kwargs):
"""A shortcut decorator that invokes :func:`group` and adds it to
the internal command list via :meth:`add_command`.
"""A shortcut decorator that invokes :func:`.group` and adds it to
the internal command list via :meth:`~.GroupMixin.add_command`.
"""
def decorator(func):
result = group(*args, **kwargs)(func)
@ -770,12 +770,12 @@ class Group(GroupMixin, Command):
"""A class that implements a grouping protocol for commands to be
executed as subcommands.
This class is a subclass of :class:`Command` and thus all options
valid in :class:`Command` are valid in here as well.
This class is a subclass of :class:`.Command` and thus all options
valid in :class:`.Command` are valid in here as well.
Attributes
-----------
invoke_without_command : bool
invoke_without_command: 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
@ -820,25 +820,25 @@ class Group(GroupMixin, Command):
# Decorators
def command(name=None, cls=None, **attrs):
"""A decorator that transforms a function into a :class:`Command`
or if called with :func:`group`, :class:`Group`.
"""A decorator that transforms a function into a :class:`.Command`
or if called with :func:`.group`, :class:`.Group`.
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.
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
decorator.
Parameters
-----------
name : str
name: str
The name to create the command with. By default this uses the
function name unchanged.
cls
The class to construct with. By default this is :class:`Command`.
The class to construct with. By default this is :class:`.Command`.
You usually do not change this.
attrs
Keyword arguments to pass into the construction of the class denoted
@ -886,28 +886,28 @@ def command(name=None, cls=None, **attrs):
return decorator
def group(name=None, **attrs):
"""A decorator that transforms a function into a :class:`Group`.
"""A decorator that transforms a function into a :class:`.Group`.
This is similar to the :func:`command` decorator but creates a
:class:`Group` instead of a :class:`Command`.
This is similar to the :func:`.command` decorator but creates a
:class:`.Group` instead of a :class:`.Command`.
"""
return command(name=name, cls=Group, **attrs)
def check(predicate):
"""A decorator that adds a check to the :class:`Command` or its
subclasses. These checks could be accessed via :attr:`Command.checks`.
"""A decorator that adds a check to the :class:`.Command` or its
subclasses. These checks could be accessed via :attr:`.Command.checks`.
These checks should be predicates that take in a single parameter taking
a :class:`Context`. If the check returns a ``False``\-like value then
during invocation a :exc:`CheckFailure` exception is raised and sent to
the :func:`on_command_error` event.
a :class:`.Context`. If the check returns a ``False``\-like value then
during invocation a :exc:`.CheckFailure` exception is raised and sent to
the :func:`.on_command_error` event.
If an exception should be thrown in the predicate then it should be a
subclass of :exc:`CommandError`. Any exception not subclassed from it
subclass of :exc:`.CommandError`. Any exception not subclassed from it
will be propagated while those subclassed will be sent to
:func:`on_command_error`.
:func:`.on_command_error`.
.. info::
.. note::
These functions can either be regular functions or coroutines.
@ -960,7 +960,7 @@ def check(predicate):
return decorator
def has_role(name):
"""A :func:`check` that is added that checks if the member invoking the
"""A :func:`.check` that is added that checks if the member invoking the
command has the role specified via the name specified.
The name is case sensitive and must be exact. No normalisation is done in
@ -971,7 +971,7 @@ def has_role(name):
Parameters
-----------
name : str
name: str
The name of the role to check.
"""
@ -985,11 +985,11 @@ def has_role(name):
return check(predicate)
def has_any_role(*names):
"""A :func:`check` that is added that checks if the member invoking the
"""A :func:`.check` that is added that checks if the member invoking the
command has **any** of the roles specified. This means that if they have
one out of the three roles specified, then this check will return `True`.
Similar to :func:`has_role`\, the names passed in must be exact.
Similar to :func:`.has_role`\, the names passed in must be exact.
Parameters
-----------
@ -1015,11 +1015,11 @@ def has_any_role(*names):
return check(predicate)
def has_permissions(**perms):
"""A :func:`check` that is added that checks if the member has any of
"""A :func:`.check` that is added that checks if the member has any of
the permissions necessary.
The permissions passed in must be exactly like the properties shown under
:class:`discord.Permissions`.
:class:`.discord.Permissions`.
Parameters
------------
@ -1045,7 +1045,7 @@ def has_permissions(**perms):
return check(predicate)
def bot_has_role(name):
"""Similar to :func:`has_role` except checks if the bot itself has the
"""Similar to :func:`.has_role` except checks if the bot itself has the
role.
"""
@ -1059,7 +1059,7 @@ def bot_has_role(name):
return check(predicate)
def bot_has_any_role(*names):
"""Similar to :func:`has_any_role` except checks if the bot itself has
"""Similar to :func:`.has_any_role` except checks if the bot itself has
any of the roles listed.
"""
def predicate(ctx):
@ -1072,7 +1072,7 @@ def bot_has_any_role(*names):
return check(predicate)
def bot_has_permissions(**perms):
"""Similar to :func:`has_permissions` except checks if the bot itself has
"""Similar to :func:`.has_permissions` except checks if the bot itself has
the permissions listed.
"""
def predicate(ctx):
@ -1083,12 +1083,12 @@ def bot_has_permissions(**perms):
return check(predicate)
def guild_only():
"""A :func:`check` that indicates this command must only be used in a
"""A :func:`.check` that indicates this command must only be used in a
guild context only. Basically, no private messages are allowed when
using the command.
This check raises a special exception, :exc:`NoPrivateMessage`
that is derived from :exc:`CheckFailure`.
This check raises a special exception, :exc:`.NoPrivateMessage`
that is derived from :exc:`.CheckFailure`.
"""
def predicate(ctx):
@ -1099,13 +1099,13 @@ def guild_only():
return check(predicate)
def is_owner():
"""A :func:`check` that checks if the person invoking this command is the
"""A :func:`.check` that checks if the person invoking this command is the
owner of the bot.
This is powered by :meth:`Bot.is_owner`.
This is powered by :meth:`.Bot.is_owner`.
This check raises a special exception, :exc:`NotOwner` that is derived
from :exc:`CheckFailure`.
This check raises a special exception, :exc:`.NotOwner` that is derived
from :exc:`.CheckFailure`.
"""
@asyncio.coroutine
@ -1117,13 +1117,13 @@ def is_owner():
return check(predicate)
def is_nsfw():
"""A :func:`check` that checks if the channel is a NSFW channel."""
"""A :func:`.check` that checks if the channel is a NSFW channel."""
def pred(ctx):
return isinstance(ctx.channel, discord.TextChannel) and ctx.channel.is_nsfw()
return check(pred)
def cooldown(rate, per, type=BucketType.default):
"""A decorator that adds a cooldown to a :class:`Command`
"""A decorator that adds a cooldown to a :class:`.Command`
or its subclasses.
A cooldown allows a command to only be used a specific amount
@ -1137,8 +1137,8 @@ def cooldown(rate, per, type=BucketType.default):
- ``BucketType.guild`` for a per-guild basis.
- ``BucketType.channel`` for a per-channel basis.
If a cooldown is triggered, then :exc:`CommandOnCooldown` is triggered in
:func:`on_command_error` and the local error handler.
If a cooldown is triggered, then :exc:`.CommandOnCooldown` is triggered in
:func:`.on_command_error` and the local error handler.
A command can only have a single cooldown.

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

@ -38,7 +38,7 @@ class CommandError(DiscordException):
This exception and exceptions derived from it are handled
in a special way as they are caught and passed into a special event
from :class:`Bot`\, :func:`on_command_error`.
from :class:`.Bot`\, :func:`on_command_error`.
"""
def __init__(self, message=None, *args):
if message is not None:
@ -52,7 +52,7 @@ class UserInputError(CommandError):
"""The base exception type for errors that involve errors
regarding user input.
This inherits from :exc:`CommandError`.
This inherits from :exc:`.CommandError`.
"""
pass
@ -80,7 +80,7 @@ class MissingRequiredArgument(UserInputError):
class TooManyArguments(UserInputError):
"""Exception raised when the command was passed too many arguments and its
:attr:`Command.ignore_extra` attribute was not set to ``True``.
:attr:`.Command.ignore_extra` attribute was not set to ``True``.
"""
pass
@ -91,7 +91,7 @@ class BadArgument(UserInputError):
pass
class CheckFailure(CommandError):
"""Exception raised when the predicates in :attr:`Command.checks` have failed."""
"""Exception raised when the predicates in :attr:`.Command.checks` have failed."""
pass
class NoPrivateMessage(CheckFailure):
@ -128,7 +128,7 @@ class CommandOnCooldown(CommandError):
-----------
cooldown: Cooldown
A class with attributes ``rate``, ``per``, and ``type`` similar to
the :func:`cooldown` decorator.
the :func:`.cooldown` decorator.
retry_after: float
The amount of seconds to wait before you can retry again.
"""

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

@ -127,19 +127,19 @@ class HelpFormatter:
"""The default base implementation that handles formatting of the help
command.
To override the behaviour of the formatter, :meth:`format`
To override the behaviour of the formatter, :meth:`~.HelpFormatter.format`
should be overridden. A number of utility functions are provided for use
inside that method.
Parameters
Attributes
-----------
show_hidden : bool
show_hidden: bool
Dictates if hidden commands should be shown in the output.
Defaults to ``False``.
show_check_failure : bool
Dictates if commands that have their :attr:`Command.checks` failed
show_check_failure: bool
Dictates if commands that have their :attr:`.Command.checks` failed
shown. Defaults to ``False``.
width : int
width: 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."""
"""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."""
"""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."""
"""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
"""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
@ -202,8 +202,8 @@ class HelpFormatter:
@asyncio.coroutine
def filter_command_list(self):
"""Returns a filtered list of commands based on the two attributes
provided, :attr:`show_check_failure` and :attr:`show_hidden`. Also
filters based on if :meth:`is_cog` is valid.
provided, :attr:`show_check_failure` and :attr:`show_hidden`.
Also filters based on if :meth:`~.HelpFormatter.is_cog` is valid.
Returns
--------
@ -262,13 +262,13 @@ class HelpFormatter:
def format_help_for(self, context, command_or_bot):
"""Formats the help page and handles the actual heavy lifting of how
the help command looks like. To change the behaviour, override the
:meth:`format` method.
:meth:`~.HelpFormatter.format` method.
Parameters
-----------
context : :class:`Context`
context: :class:`.Context`
The context of the invoked help command.
command_or_bot : :class:`Command` or :class:`Bot`
command_or_bot: :class:`.Command` or :class:`.Bot`
The bot or command that we are getting the help of.
Returns

8
discord/guild.py
View File

@ -566,7 +566,7 @@ class Guild(Hashable):
Edits the guild.
You must have the :attr:`Permissions.manage_guild` permission
You must have the :attr:`~Permissions.manage_guild` permission
to edit the guild.
Parameters
@ -671,7 +671,7 @@ class Guild(Hashable):
that got banned along with a ``reason`` field specifying
why the user was banned that could be set to ``None``.
You must have :attr:`Permissions.ban_members` permission
You must have :attr:`~Permissions.ban_members` permission
to get this information.
Raises
@ -701,7 +701,7 @@ class Guild(Hashable):
The inactive members are denoted if they have not logged on in
``days`` number of days and they have no roles.
You must have the :attr:`Permissions.kick_members` permission
You must have the :attr:`~Permissions.kick_members` permission
to use this.
To check how many members you would prune without actually pruning,
@ -775,7 +775,7 @@ class Guild(Hashable):
Returns a list of all active instant invites from the guild.
You must have :attr:`Permissions.manage_guild` to get this information.
You must have :attr:`~Permissions.manage_guild` to get this information.
Raises
-------

6
discord/member.py
View File

@ -458,7 +458,7 @@ class Member(discord.abc.Messageable):
Moves a member to a new voice channel (they must be connected first).
You must have the :attr:`Permissions.move_members` permission to
You must have the :attr:`~Permissions.move_members` permission to
use this.
This raises the same exceptions as :meth:`edit`.
@ -478,7 +478,7 @@ class Member(discord.abc.Messageable):
Gives the member a number of :class:`Role`\s.
You must have the :attr:`Permissions.manage_roles` permission to
You must have the :attr:`~Permissions.manage_roles` permission to
use this.
Parameters
@ -505,7 +505,7 @@ class Member(discord.abc.Messageable):
Removes :class:`Role`\s from this member.
You must have the :attr:`Permissions.manage_roles` permission to
You must have the :attr:`~Permissions.manage_roles` permission to
use this.
Parameters

14
discord/message.py
View File

@ -413,7 +413,7 @@ class Message:
Deletes the message.
Your own messages could be deleted without any proper permissions. However to
delete other people's messages, you need the :attr:`Permissions.manage_messages`
delete other people's messages, you need the :attr:`~Permissions.manage_messages`
permission.
Parameters
@ -475,7 +475,7 @@ class Message:
def pin(self):
"""|coro|
Pins the message. You must have :attr:`Permissions.manage_messages`
Pins the message. You must have :attr:`~Permissions.manage_messages`
permissions to do this in a non-private channel context.
Raises
@ -496,7 +496,7 @@ class Message:
def unpin(self):
"""|coro|
Unpins the message. You must have :attr:`Permissions.manage_messages`
Unpins the message. You must have :attr:`~Permissions.manage_messages`
permissions to do this in a non-private channel context.
Raises
@ -520,8 +520,8 @@ class Message:
The emoji may be a unicode emoji or a custom guild :class:`Emoji`.
You must have the :attr:`Permissions.add_reactions` permission to
add new reactions to a message.
You must have the :attr:`~Permissions.add_reactions` and
:attr:`~Permissions.read_message_history` permissions to use this.
Parameters
------------
@ -560,7 +560,7 @@ class Message:
The emoji may be a unicode emoji or a custom guild :class:`Emoji`.
If the reaction is not your own (i.e. ``member`` parameter is not you) then
the :attr:`Permissions.manage_messages` permission is needed.
the :attr:`~Permissions.manage_messages` permission is needed.
The ``member`` parameter must represent a member and meet
the :class:`abc.Snowflake` abc.
@ -601,7 +601,7 @@ class Message:
Removes all the reactions from the message.
You need :attr:`Permissions.manage_messages` permission
You need :attr:`~Permissions.manage_messages` permission
to use this.
Raises

4
discord/user.py
View File

@ -197,7 +197,7 @@ class ClientUser(BaseUser):
The user's unique ID.
discriminator: str
The user's discriminator. This is given when the username has conflicts.
avatar: str
avatar: Optional[str]
The avatar hash the user has. Could be None.
bot: bool
Specifies if the user is a bot account.
@ -404,7 +404,7 @@ class User(BaseUser, discord.abc.Messageable):
The user's unique ID.
discriminator: str
The user's discriminator. This is given when the username has conflicts.
avatar: str
avatar: Optional[str]
The avatar hash the user has. Could be None.
bot: bool
Specifies if the user is a bot account.

4
discord/voice_client.py
View File

@ -62,8 +62,8 @@ from .player import AudioPlayer, AudioSource
class VoiceClient:
"""Represents a Discord voice connection.
This client is created solely through :meth:`Client.join_voice_channel`
and its only purpose is to transmit voice.
You do not create these, you typically get them from
e.g. :meth:`VoiceChannel.connect`.
Warning
--------