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

Fix various inconsistencies within the documentation (#5067)

Browse Source
This commit is contained in:
Sebastian Law 2020-06-28 00:45:58 -07:00 committed by GitHub
parent f94b00cb48
commit b4b953bfc6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
24 changed files with 378 additions and 142 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
discord/abc.py
View File

@ -53,7 +53,7 @@ class Snowflake(metaclass=abc.ABCMeta):
abstract base class.
If you want to create a snowflake on your own, consider using
:class:`Object`.
:class:`.Object`.
Attributes
-----------
@ -597,7 +597,7 @@ class GuildChannel:
target: Union[:class:`~discord.Member`, :class:`~discord.Role`]
The member or role to overwrite permissions for.
overwrite: Optional[:class:`~discord.PermissionOverwrite`]
The permissions to allow and deny to the target, or `None` to
The permissions to allow and deny to the target, or ``None`` to
delete the overwrite.
\*\*permissions
A keyword argument list of permissions to set for ease of use.
@ -700,10 +700,10 @@ class GuildChannel:
------------
max_age: :class:`int`
How long the invite should last in seconds. If it's 0 then the invite
doesn't expire. Defaults to 0.
doesn't expire. Defaults to ``0``.
max_uses: :class:`int`
How many uses the invite could be used for. If it's 0 then there
are unlimited uses. Defaults to 0.
are unlimited uses. Defaults to ``0``.
temporary: :class:`bool`
Denotes that the invite grants temporary membership
(i.e. they get kicked after they disconnect). Defaults to ``False``.

12
discord/activity.py
View File

@ -338,7 +338,7 @@ class Game(BaseActivity):
@property
def type(self):
"""Returns the game's type. This is for compatibility with :class:`Activity`.
""":class:`ActivityType`: Returns the game's type. This is for compatibility with :class:`Activity`.
It always returns :attr:`ActivityType.playing`.
"""
@ -445,7 +445,7 @@ class Streaming(BaseActivity):
@property
def type(self):
"""Returns the game's type. This is for compatibility with :class:`Activity`.
""":class:`ActivityType`: Returns the game's type. This is for compatibility with :class:`Activity`.
It always returns :attr:`ActivityType.streaming`.
"""
@ -530,7 +530,7 @@ class Spotify:
@property
def type(self):
"""Returns the activity's type. This is for compatibility with :class:`Activity`.
""":class:`ActivityType`: Returns the activity's type. This is for compatibility with :class:`Activity`.
It always returns :attr:`ActivityType.listening`.
"""
@ -547,14 +547,14 @@ class Spotify:
@property
def colour(self):
"""Returns the Spotify integration colour, as a :class:`Colour`.
""":class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`.
There is an alias for this named :attr:`color`"""
return Colour(0x1db954)
@property
def color(self):
"""Returns the Spotify integration colour, as a :class:`Colour`.
""":class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`.
There is an alias for this named :attr:`colour`"""
return self.colour
@ -697,7 +697,7 @@ class CustomActivity(BaseActivity):
@property
def type(self):
"""Returns the activity's type. This is for compatibility with :class:`Activity`.
""":class:`ActivityType`: Returns the activity's type. This is for compatibility with :class:`Activity`.
It always returns :attr:`ActivityType.custom`.
"""

12
discord/channel.py
View File

@ -835,6 +835,11 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
"""|coro|
A shortcut method to :meth:`Guild.create_text_channel` to create a :class:`TextChannel` in the category.
Returns
-------
:class:`TextChannel`
The channel that was just created.
"""
return await self.guild.create_text_channel(name, overwrites=overwrites, category=self, reason=reason, **options)
@ -842,6 +847,11 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
"""|coro|
A shortcut method to :meth:`Guild.create_voice_channel` to create a :class:`VoiceChannel` in the category.
Returns
-------
:class:`VoiceChannel`
The channel that was just created.
"""
return await self.guild.create_voice_channel(name, overwrites=overwrites, category=self, reason=reason, **options)
@ -1026,7 +1036,7 @@ class DMChannel(discord.abc.Messageable, Hashable):
@property
def created_at(self):
"""Returns the direct message channel's creation time in UTC."""
""":class:`datetime.datetime`: Returns the direct message channel's creation time in UTC."""
return utils.snowflake_time(self.id)
def permissions_for(self, user=None):

12
discord/client.py
View File

@ -123,10 +123,10 @@ class Client:
-----------
max_messages: Optional[:class:`int`]
The maximum number of messages to store in the internal message cache.
This defaults to 1000. Passing in ``None`` disables the message cache.
This defaults to ``1000``. Passing in ``None`` disables the message cache.
.. versionchanged:: 1.3
Allow disabling the message cache and change the default size to 1000.
Allow disabling the message cache and change the default size to ``1000``.
loop: Optional[:class:`asyncio.AbstractEventLoop`]
The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations.
Defaults to ``None``, in which case the default event loop is used via
@ -138,7 +138,7 @@ class Client:
proxy_auth: Optional[:class:`aiohttp.BasicAuth`]
An object that represents proxy HTTP Basic Authorization.
shard_id: Optional[:class:`int`]
Integer starting at 0 and less than :attr:`.shard_count`.
Integer starting at ``0`` and less than :attr:`.shard_count`.
shard_count: Optional[:class:`int`]
The total number of shards.
fetch_offline_members: :class:`bool`
@ -257,7 +257,7 @@ class Client:
@property
def user(self):
"""Optional[:class:`.ClientUser`]: Represents the connected client. None if not logged in."""
"""Optional[:class:`.ClientUser`]: Represents the connected client. ``None`` if not logged in."""
return self._connection.user
@property
@ -654,7 +654,7 @@ class Client:
@property
def allowed_mentions(self):
"""Optional[:class:`AllowedMentions`]: The allowed mention configuration.
"""Optional[:class:`~discord.AllowedMentions`]: The allowed mention configuration.
.. versionadded:: 1.4
"""
@ -999,7 +999,7 @@ class Client:
The number of guilds to retrieve.
If ``None``, it retrieves every guild you have access to. Note, however,
that this would make it a slow operation.
Defaults to 100.
Defaults to ``100``.
before: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]
Retrieves guilds before this date or object.
If a date is provided it must be a timezone-naive datetime representing UTC time.

2
discord/colour.py
View File

@ -114,7 +114,7 @@ class Colour:
@classmethod
def default(cls):
"""A factory method that returns a :class:`Colour` with a value of 0."""
"""A factory method that returns a :class:`Colour` with a value of ``0``."""
return cls(0)
@classmethod

14
discord/embeds.py
View File

@ -224,7 +224,7 @@ class Embed:
@property
def footer(self):
"""Returns an ``EmbedProxy`` denoting the footer contents.
"""Union[:class:`EmbedProxy`, :attr:`Empty`]: Returns an ``EmbedProxy`` denoting the footer contents.
See :meth:`set_footer` for possible values you can access.
@ -257,7 +257,7 @@ class Embed:
@property
def image(self):
"""Returns an ``EmbedProxy`` denoting the image contents.
"""Union[:class:`EmbedProxy`, :attr:`Empty`]: Returns an ``EmbedProxy`` denoting the image contents.
Possible attributes you can access are:
@ -296,7 +296,7 @@ class Embed:
@property
def thumbnail(self):
"""Returns an ``EmbedProxy`` denoting the thumbnail contents.
"""Union[:class:`EmbedProxy`, :attr:`Empty`]: Returns an ``EmbedProxy`` denoting the thumbnail contents.
Possible attributes you can access are:
@ -335,7 +335,7 @@ class Embed:
@property
def video(self):
"""Returns an ``EmbedProxy`` denoting the video contents.
"""Union[:class:`EmbedProxy`, :attr:`Empty`]: Returns an ``EmbedProxy`` denoting the video contents.
Possible attributes include:
@ -349,7 +349,7 @@ class Embed:
@property
def provider(self):
"""Returns an ``EmbedProxy`` denoting the provider contents.
"""Union[:class:`EmbedProxy`, :attr:`Empty`]: Returns an ``EmbedProxy`` denoting the provider contents.
The only attributes that might be accessed are ``name`` and ``url``.
@ -359,7 +359,7 @@ class Embed:
@property
def author(self):
"""Returns an ``EmbedProxy`` denoting the author contents.
"""Union[:class:`EmbedProxy`, :attr:`Empty`]: Returns an ``EmbedProxy`` denoting the author contents.
See :meth:`set_author` for possible values you can access.
@ -412,7 +412,7 @@ class Embed:
@property
def fields(self):
"""Returns a :class:`list` of ``EmbedProxy`` denoting the field contents.
"""Union[List[:class:`EmbedProxy`], :attr:`Empty`]: Returns a :class:`list` of ``EmbedProxy`` denoting the field contents.
See :meth:`add_field` for possible values you can access.

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

@ -215,7 +215,7 @@ class BotBase(GroupMixin):
The function that was used as a global check.
call_once: :class:`bool`
If the function should only be called once per
:meth:`Command.invoke` call.
:meth:`.Command.invoke` call.
"""
if call_once:
@ -248,7 +248,7 @@ class BotBase(GroupMixin):
r"""A decorator that adds a "call once" global check to the bot.
Unlike regular global checks, this one is called only once
per :meth:`Command.invoke` call.
per :meth:`.Command.invoke` call.
Regular global checks are called whenever a command is called
or :meth:`.Command.can_run` is called. This type of check
@ -513,6 +513,11 @@ class BotBase(GroupMixin):
The name of the cog you are requesting.
This is equivalent to the name passed via keyword
argument in class creation or the class name if unspecified.
Returns
--------
Optional[:class:`Cog`]
The cog that was requested. If not found, returns ``None``.
"""
return self.__cogs.get(name)
@ -991,11 +996,11 @@ class Bot(BotBase, discord.Client):
:meth:`.is_owner` then it is fetched automatically using
:meth:`~.Bot.application_info`.
owner_ids: Optional[Collection[:class:`int`]]
The user IDs that owns the bot. This is similar to `owner_id`.
The user IDs that owns the bot. This is similar to :attr:`owner_id`.
If this is not set and the application is team based, then it is
fetched automatically using :meth:`~.Bot.application_info`.
For performance reasons it is recommended to use a :class:`set`
for the collection. You cannot set both `owner_id` and `owner_ids`.
for the collection. You cannot set both ``owner_id`` and ``owner_ids``.
.. versionadded:: 1.3
"""

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

@ -72,7 +72,7 @@ class CogMeta(type):
The cog name. By default, it is the name of the class with no modification.
command_attrs: :class:`dict`
A list of attributes to apply to every command inside this cog. The dictionary
is passed into the :class:`Command` (or its subclass) options at ``__init__``.
is passed into the :class:`Command` options at ``__init__``.
If you specify attributes inside the command attribute in the class, it will
override the one specified inside this attribute. For example:
@ -188,12 +188,16 @@ class Cog(metaclass=CogMeta):
return self
def get_commands(self):
r"""Returns a :class:`list` of :class:`.Command`\s that are
defined inside this cog.
r"""
Returns
--------
List[:class:`.Command`]
A :class:`list` of :class:`.Command`\s that are
defined inside this cog.
.. note::
.. note::
This does not include subcommands.
This does not include subcommands.
"""
return [c for c in self.__cog_commands__ if c.parent is None]
@ -221,7 +225,13 @@ class Cog(metaclass=CogMeta):
yield from command.walk_commands()
def get_listeners(self):
"""Returns a :class:`list` of (name, function) listener pairs that are defined in this cog."""
"""Returns a :class:`list` of (name, function) listener pairs that are defined in this cog.
Returns
--------
List[Tuple[:class:`str`, :ref:`coroutine <coroutine>`]]
The listeners defined in this cog.
"""
return [(name, getattr(self, method_name)) for name, method_name in self.__cog_listeners__]
@classmethod

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

@ -52,16 +52,14 @@ class Context(discord.abc.Messageable):
:func:`on_command_error` event then this dict could be incomplete.
prefix: :class:`str`
The prefix that was used to invoke the command.
command
The command (i.e. :class:`.Command` or its subclasses) that is being
invoked currently.
command: :class:`Command`
The command that is being invoked currently.
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 subclasses) that was
invoked. If no valid subcommand was invoked then this is equal to
``None``.
invoked_subcommand: :class:`Command`
The subcommand that was invoked.
If no valid subcommand was invoked then this is equal to ``None``.
subcommand_passed: Optional[:class:`str`]
The string that was attempted to call a subcommand. This does not have
to point to a valid registered subcommand and could just point to a
@ -110,7 +108,7 @@ class Context(discord.abc.Messageable):
Parameters
-----------
command: :class:`.Command`
A command or subclass of a command that is going to be called.
The command that is going to be called.
\*args
The arguments to to use.
\*\*kwargs
@ -188,7 +186,7 @@ class Context(discord.abc.Messageable):
@property
def valid(self):
"""Checks if the invocation context is valid to be invoked with."""
""":class:`bool`: Checks if the invocation context is valid to be invoked with."""
return self.prefix is not None and self.command is not None
async def _get_channel(self):
@ -196,7 +194,7 @@ class Context(discord.abc.Messageable):
@property
def cog(self):
"""Returns the cog associated with this context's command. None if it does not exist."""
""":class:`.Cog`: Returns the cog associated with this context's command. None if it does not exist."""
if self.command is None:
return None
@ -204,22 +202,28 @@ class Context(discord.abc.Messageable):
@discord.utils.cached_property
def guild(self):
"""Returns the guild associated with this context's command. None if not available."""
"""Optional[:class:`.Guild`]: Returns the guild associated with this context's command. None if not available."""
return self.message.guild
@discord.utils.cached_property
def channel(self):
"""Returns the channel associated with this context's command. Shorthand for :attr:`.Message.channel`."""
""":class:`.TextChannel`:
Returns the channel associated with this context's command. Shorthand for :attr:`.Message.channel`.
"""
return self.message.channel
@discord.utils.cached_property
def author(self):
"""Returns the author associated with this context's command. Shorthand for :attr:`.Message.author`"""
"""Union[:class:`~discord.User`, :class:`.Member`]:
Returns the author associated with this context's command. Shorthand for :attr:`.Message.author`
"""
return self.message.author
@discord.utils.cached_property
def me(self):
"""Similar to :attr:`.Guild.me` except it may return the :class:`.ClientUser` in private message contexts."""
"""Union[:class:`.Member`, :class:`.ClientUser`]:
Similar to :attr:`.Guild.me` except it may return the :class:`.ClientUser` in private message contexts.
"""
return self.guild.me if self.guild is not None else self.bot.user
@property

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

@ -142,12 +142,11 @@ class Command(_BaseCommand):
The coroutine that is executed when the command is called.
help: :class:`str`
The long help text for the command.
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.
brief: Optional[:class:`str`]
The short help text for the command.
usage: :class:`str`
A replacement for arguments in the default help text.
aliases: Union[:class:`list`, :class:`tuple`]
aliases: Union[List[:class:`str`], Tuple[:class:`str`]]
The list of aliases the command can be invoked under.
enabled: :class:`bool`
A boolean that indicates if the command is currently enabled.
@ -384,7 +383,13 @@ class Command(_BaseCommand):
return other
def copy(self):
"""Creates a copy of this command."""
"""Creates a copy of this command.
Returns
--------
:class:`Command`
A new instance of this command.
"""
ret = self.__class__(self.callback, **self.__original_kwargs__)
return self._ensure_assignment_on_copy(ret)
@ -574,7 +579,8 @@ class Command(_BaseCommand):
@property
def clean_params(self):
"""Retrieves the parameter OrderedDict without the context or self parameters.
"""OrderedDict[:class:`str`, :class:`inspect.Parameter`]:
Retrieves the parameter OrderedDict without the context or self parameters.
Useful for inspecting signature.
"""
@ -608,7 +614,7 @@ class Command(_BaseCommand):
@property
def parents(self):
""":class:`Command`: Retrieves the parents of this command.
"""List[:class:`Command`]: Retrieves the parents of this command.
If the command has no parents then it returns an empty :class:`list`.
@ -626,7 +632,7 @@ class Command(_BaseCommand):
@property
def root_parent(self):
"""Retrieves the root parent of this command.
"""Optional[:class:`Command`]: Retrieves the root parent of this command.
If the command has no parents then it returns ``None``.
@ -920,7 +926,7 @@ class Command(_BaseCommand):
@property
def cog_name(self):
""":class:`str`: The name of the cog this command belongs to. None otherwise."""
"""Optional[:class:`str`]: The name of the cog this command belongs to, if any."""
return type(self.cog).__cog_name__ if self.cog is not None else None
@property
@ -1046,7 +1052,7 @@ class GroupMixin:
Attributes
-----------
all_commands: :class:`dict`
A mapping of command name to :class:`.Command` or subclass
A mapping of command name to :class:`.Command`
objects.
case_insensitive: :class:`bool`
Whether the commands should be case insensitive. Defaults to ``False``.
@ -1069,8 +1075,7 @@ class GroupMixin:
self.remove_command(command.name)
def add_command(self, command):
"""Adds a :class:`.Command` or its subclasses into the internal list
of commands.
"""Adds a :class:`.Command` into the internal list of commands.
This is usually not called, instead the :meth:`~.GroupMixin.command` or
:meth:`~.GroupMixin.group` shortcut decorators are used instead.
@ -1104,7 +1109,7 @@ 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` from the internal list
of commands.
This could also be used as a way to remove aliases.
@ -1116,9 +1121,9 @@ class GroupMixin:
Returns
--------
:class:`.Command` or subclass
Optional[:class:`.Command`]
The command that was removed. If the name is not valid then
`None` is returned instead.
``None`` is returned instead.
"""
command = self.all_commands.pop(name, None)
@ -1147,7 +1152,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` from the internal list
of commands.
This could also be used as a way to get aliases.
@ -1163,7 +1168,7 @@ class GroupMixin:
Returns
--------
:class:`Command` or subclass
Optional[:class:`Command`]
The command that was requested. If not found, returns ``None``.
"""
@ -1217,7 +1222,7 @@ class Group(GroupMixin, Command):
Attributes
-----------
invoke_without_command: Optional[:class:`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
@ -1226,7 +1231,7 @@ class Group(GroupMixin, Command):
the group callback will always be invoked first. This means
that the checks and the parsing dictated by its parameters
will be executed. Defaults to ``False``.
case_insensitive: Optional[:class:`bool`]
case_insensitive: :class:`bool`
Indicates if the group's commands should be case insensitive.
Defaults to ``False``.
"""
@ -1235,7 +1240,13 @@ class Group(GroupMixin, Command):
super().__init__(*args, **attrs)
def copy(self):
"""Creates a copy of this :class:`Group`."""
"""Creates a copy of this :class:`Group`.
Returns
--------
:class:`Group`
A new instance of this group.
"""
ret = super().copy()
for cmd in self.commands:
ret.add_command(cmd.copy())
@ -1856,7 +1867,6 @@ def is_nsfw():
def cooldown(rate, per, type=BucketType.default):
"""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
of times in a specific time frame. These cooldowns can be based

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

@ -90,7 +90,7 @@ class ConversionError(CommandError):
----------
converter: :class:`discord.ext.commands.Converter`
The converter that failed.
original
original: :exc:`Exception`
The original exception that was raised. You can also get this via
the ``__cause__`` attribute.
"""

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

@ -155,7 +155,7 @@ class Paginator:
@property
def pages(self):
"""Returns the rendered list of pages."""
"""class:`list`: Returns the rendered list of pages."""
# we have more than just the prefix in our current page
if len(self._current_page) > (0 if self.prefix is None else 1):
self.close_page()

5
discord/file.py
View File

@ -31,6 +31,11 @@ class File:
"""A parameter object used for :meth:`abc.Messageable.send`
for sending file objects.
.. note::
File objects are single use and are not meant to be reused in
multiple :meth:`abc.Messageable.send`\s.
Attributes
-----------
fp: Union[:class:`str`, :class:`io.BufferedIOBase`]

24
discord/guild.py
View File

@ -362,7 +362,7 @@ class Guild(Hashable):
@property
def me(self):
"""Similar to :attr:`Client.user` except an instance of :class:`Member`.
""":class:`Member`: Similar to :attr:`Client.user` except an instance of :class:`Member`.
This is essentially used to get the member version of yourself.
"""
self_id = self._state.user.id
@ -370,7 +370,7 @@ class Guild(Hashable):
@property
def voice_client(self):
"""Returns the :class:`VoiceClient` associated with this guild, if any."""
"""Optional[:class:`VoiceClient`:] Returns the :class:`VoiceClient` associated with this guild, if any."""
return self._state._get_voice_client(self.id)
@property
@ -526,7 +526,7 @@ class Guild(Hashable):
@property
def roles(self):
"""Returns a :class:`list` of the guild's roles in hierarchy order.
"""List[:class:`Role`]: Returns a :class:`list` of the guild's roles in hierarchy order.
The first element of this list will be the lowest role in the
hierarchy.
@ -550,7 +550,7 @@ class Guild(Hashable):
@property
def default_role(self):
"""Gets the @everyone role that all members have by default."""
""":class:`Role`: Gets the @everyone role that all members have by default."""
return self.get_role(self.id)
@property
@ -695,12 +695,12 @@ class Guild(Hashable):
@property
def member_count(self):
"""Returns the true member count regardless of it being loaded fully or not."""
""":class:`int`: Returns the true member count regardless of it being loaded fully or not."""
return self._member_count
@property
def chunked(self):
"""Returns a boolean indicating if the guild is "chunked".
""":class:`bool`: Returns a boolean indicating if the guild is "chunked".
A chunked guild means that :attr:`member_count` is equal to the
number of members stored in the internal :attr:`members` cache.
@ -748,7 +748,7 @@ class Guild(Hashable):
Returns
--------
:class:`Member`
Optional[:class:`Member`]
The member in this guild with the associated name. If not found
then ``None`` is returned.
"""
@ -903,6 +903,11 @@ class Guild(Hashable):
The channel's preferred audio bitrate in bits per second.
user_limit: :class:`int`
The channel's limit for number of members that can be in a voice channel.
Returns
-------
:class:`VoiceChannel`
The channel that was just created.
"""
data = await self._create_channel(name, overwrites, ChannelType.voice, category, reason=reason, **options)
channel = VoiceChannel(state=self._state, guild=self, data=data)
@ -920,6 +925,11 @@ class Guild(Hashable):
The ``category`` parameter is not supported in this function since categories
cannot have categories.
Returns
-------
:class:`CategoryChannel`
The channel that was just created.
"""
data = await self._create_channel(name, overwrites, ChannelType.category, reason=reason, position=position)
channel = CategoryChannel(state=self._state, guild=self, data=data)

24
discord/invite.py
View File

@ -163,7 +163,13 @@ class PartialInviteGuild:
return bool(self.icon and self.icon.startswith('a_'))
def icon_url_as(self, *, format=None, static_format='webp', size=1024):
"""The same operation as :meth:`Guild.icon_url_as`."""
"""The same operation as :meth:`Guild.icon_url_as`.
Returns
--------
:class:`Asset`
The resulting CDN asset.
"""
return Asset._from_guild_icon(self._state, self, format=format, static_format=static_format, size=size)
@property
@ -172,7 +178,13 @@ class PartialInviteGuild:
return self.banner_url_as()
def banner_url_as(self, *, format='webp', size=2048):
"""The same operation as :meth:`Guild.banner_url_as`."""
"""The same operation as :meth:`Guild.banner_url_as`.
Returns
--------
:class:`Asset`
The resulting CDN asset.
"""
return Asset._from_guild_image(self._state, self.id, self.banner, 'banners', format=format, size=size)
@property
@ -181,7 +193,13 @@ class PartialInviteGuild:
return self.splash_url_as()
def splash_url_as(self, *, format='webp', size=2048):
"""The same operation as :meth:`Guild.splash_url_as`."""
"""The same operation as :meth:`Guild.splash_url_as`.
Returns
--------
:class:`Asset`
The resulting CDN asset.
"""
return Asset._from_guild_image(self._state, self.id, self.splash, 'splashes', format=format, size=size)
class Invite(Hashable):

9
discord/member.py
View File

@ -413,8 +413,13 @@ class Member(discord.abc.Messageable, _BaseUser):
Parameters
-----------
channel: :class:`Channel`
channel: :class:`abc.GuildChannel`
The channel to check your permissions for.
Returns
-------
:class:`Permissions`
The resolved permissions for the member.
"""
return channel.permissions_for(self)
@ -433,7 +438,7 @@ class Member(discord.abc.Messageable, _BaseUser):
@property
def guild_permissions(self):
"""Returns the member's guild permissions.
""":class:`Permissions`: Returns the member's guild permissions.
This only takes into consideration the guild permissions
and not most of the implied permissions or any of the

2
discord/message.py
View File

@ -635,7 +635,7 @@ class Message:
@utils.cached_slot_property('_cs_system_content')
def system_content(self):
r"""A property that returns the content that is rendered
r""":class:`str`: A property that returns the content that is rendered
regardless of the :attr:`Message.type`.
In the case of :attr:`MessageType.default`\, this just returns the

2
discord/permissions.py
View File

@ -86,7 +86,7 @@ class Permissions(BaseFlags):
Attributes
-----------
value
value: :class:`int`
The raw value. This value is a bit array field of a 53-bit integer
representing the currently available permissions. You should query
permissions via the properties rather than using this raw value.

2
discord/player.py
View File

@ -524,7 +524,7 @@ class PCMVolumeTransformer(AudioSource):
@property
def volume(self):
"""Retrieves or sets the volume as a floating point percentage (e.g. 1.0 for 100%)."""
"""Retrieves or sets the volume as a floating point percentage (e.g. ``1.0`` for 100%)."""
return self._volume
@volume.setter

4
discord/user.py
View File

@ -139,7 +139,7 @@ class BaseUser(_BaseUser):
@property
def avatar_url(self):
"""Returns an :class:`Asset` for the avatar the user has.
""":class:`Asset`: Returns an :class:`Asset` for the avatar the user has.
If the user does not have a traditional avatar, an asset for
the default avatar is returned instead.
@ -717,7 +717,7 @@ class User(BaseUser, discord.abc.Messageable):
@property
def relationship(self):
"""Returns the :class:`Relationship` with this user if applicable, ``None`` otherwise.
"""Optional[:class:`Relationship`]: Returns the :class:`Relationship` with this user if applicable, ``None`` otherwise.
.. note::

16
discord/utils.py
View File

@ -143,6 +143,11 @@ def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None):
The guild to pre-select in the authorization screen, if available.
redirect_uri: :class:`str`
An optional valid redirect URI.
Returns
--------
:class:`str`
The OAuth2 URL for inviting the bot into guilds.
"""
url = 'https://discord.com/oauth2/authorize?client_id={}&scope=bot'.format(client_id)
if permissions is not None:
@ -156,7 +161,16 @@ def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None):
def snowflake_time(id):
"""Returns the creation date in UTC of a Discord snowflake ID."""
"""
Parameters
-----------
id: :class:`int`
The snowflake ID.
Returns
--------
:class:`datetime.datetime`
The creation date in UTC of a Discord snowflake ID."""
return datetime.datetime.utcfromtimestamp(((id >> 22) + DISCORD_EPOCH) / 1000)
def time_snowflake(datetime_obj, high=False):

18
discord/webhook.py
View File

@ -453,15 +453,13 @@ class Webhook:
@property
def url(self):
"""Returns the webhook's url."""
""":class:`str` : Returns the webhook's url."""
return 'https://discord.com/api/webhooks/{}/{}'.format(self.id, self.token)
@classmethod
def partial(cls, id, token, *, adapter):
"""Creates a partial :class:`Webhook`.
A partial webhook is just a webhook object with an ID and a token.
Parameters
-----------
id: :class:`int`
@ -472,6 +470,12 @@ class Webhook:
The webhook adapter to use when sending requests. This is
typically :class:`AsyncWebhookAdapter` for :doc:`aiohttp <aio:index>` or
:class:`RequestsWebhookAdapter` for :doc:`req:index`.
Returns
--------
:class:`Webhook`
A partial :class:`Webhook`.
A partial webhook is just a webhook object with an ID and a token.
"""
if not isinstance(adapter, WebhookAdapter):
@ -502,6 +506,12 @@ class Webhook:
-------
InvalidArgument
The URL is invalid.
Returns
--------
:class:`Webhook`
A partial :class:`Webhook`.
A partial webhook is just a webhook object with an ID and a token.
"""
m = re.search(r'discord(?:app)?.com/api/webhooks/(?P<id>[0-9]{17,21})/(?P<token>[A-Za-z0-9\.\-\_]{60,68})', url)
@ -560,7 +570,7 @@ class Webhook:
@property
def avatar_url(self):
"""Returns an :class:`Asset` for the avatar the webhook has.
""":class:`Asset`: Returns an :class:`Asset` for the avatar the webhook has.
If the webhook does not have a traditional avatar, an asset for
the default avatar is returned instead.

229
docs/api.rst
View File

@ -739,9 +739,13 @@ Profile
.. attribute:: user
The :class:`User` the profile belongs to.
:type: :class:`User`
.. attribute:: premium
A boolean indicating if the user has premium (i.e. Discord Nitro).
:type: :class:`bool`
.. attribute:: nitro
An alias for :attr:`premium`.
@ -749,47 +753,70 @@ Profile
A naive UTC datetime indicating how long the user has been premium since.
This could be ``None`` if not applicable.
:type: :class:`datetime.datetime`
.. attribute:: staff
A boolean indicating if the user is Discord Staff.
:type: :class:`bool`
.. attribute:: partner
A boolean indicating if the user is a Discord Partner.
:type: :class:`bool`
.. attribute:: bug_hunter
A boolean indicating if the user is a Bug Hunter.
:type: :class:`bool`
.. attribute:: early_supporter
A boolean indicating if the user has had premium before 10 October, 2018.
:type: :class:`bool`
.. attribute:: hypesquad
A boolean indicating if the user is in Discord HypeSquad.
:type: :class:`bool`
.. attribute:: hypesquad_houses
A list of :class:`HypeSquadHouse` that the user is in.
:type: List[:class:`HypeSquadHouse`]
.. attribute:: team_user
A boolean indicating if the user is in part of a team.
.. versionadded:: 1.3
:type: :class:`bool`
.. attribute:: system
A boolean indicating if the user is officially part of the Discord urgent message system.
.. versionadded:: 1.3
:type: :class:`bool`
.. attribute:: mutual_guilds
A list of :class:`Guild` that the :class:`ClientUser` shares with this
user.
:type: List[:class:`Guild`]
.. attribute:: connected_accounts
A list of dict objects indicating the accounts the user has connected.
An example entry can be seen below: ::
{type: "twitch", id: "92473777", name: "discordapp"}
{"type": "twitch", "id": "92473777", "name": "discordapp"}
:type: List[Dict[:class:`str`, :class:`str`]]
.. _discord-api-enums:
@ -1783,6 +1810,34 @@ of :class:`enum.Enum`.
Represents a webhook that is internally managed by Discord, used for following channels.
.. class:: DefaultAvatar
Represents the default avatar of a Discord :class:`User`
.. attribute:: blurple
Represents the default avatar with the color blurple.
See also :attr:`Colour.blurple`
.. attribute:: grey
Represents the default avatar with the color grey.
See also :attr:`Colour.greyple`
.. attribute:: gray
An alias for :attr:`grey`.
.. attribute:: green
Represents the default avatar with the color green.
See also :attr:`Colour.green`
.. attribute:: orange
Represents the default avatar with the color orange.
See also :attr:`Colour.orange`
.. attribute:: red
Represents the default avatar with the color red.
See also :attr:`Colour.red`
Async Iterator
----------------
@ -1873,7 +1928,7 @@ Certain utilities make working with async iterators easier, detailed below.
message_length = len(content)
:param func: The function to call on every element. Could be a |coroutine_link|_.
:return: An async iterator.
:rtype: :class:`AsyncIterator`
.. method:: filter(predicate)
@ -1890,7 +1945,7 @@ Certain utilities make working with async iterators easier, detailed below.
...
:param predicate: The predicate to call on every element. Could be a |coroutine_link|_.
:return: An async iterator.
:rtype: :class:`AsyncIterator`
.. _discord-api-audit-logs:
@ -1962,102 +2017,138 @@ this goal, it must make use of a couple of data classes that aid in this goal.
on the action being done, check the documentation for :class:`AuditLogAction`,
otherwise check the documentation below for all attributes that are possible.
.. describe:: iter(diff)
.. container:: operations
Returns an iterator over (attribute, value) tuple of this diff.
.. describe:: iter(diff)
Returns an iterator over (attribute, value) tuple of this diff.
.. attribute:: name
:class:`str` – A name of something.
A name of something.
:type: :class:`str`
.. attribute:: icon
:class:`str` – A guild's icon hash. See also :attr:`Guild.icon`.
A guild's icon hash. See also :attr:`Guild.icon`.
:type: :class:`str`
.. attribute:: splash
:class:`str` – The guild's invite splash hash. See also :attr:`Guild.splash`.
The guild's invite splash hash. See also :attr:`Guild.splash`.
:type: :class:`str`
.. attribute:: owner
Union[:class:`Member`, :class:`User`] – The guild's owner. See also :attr:`Guild.owner`
The guild's owner. See also :attr:`Guild.owner`
:type: Union[:class:`Member`, :class:`User`]
.. attribute:: region
:class:`VoiceRegion` – The guild's voice region. See also :attr:`Guild.region`.
The guild's voice region. See also :attr:`Guild.region`.
:type: :class:`VoiceRegion`
.. attribute:: afk_channel
Union[:class:`VoiceChannel`, :class:`Object`] – The guild's AFK channel.
The guild's AFK channel.
If this could not be found, then it falls back to a :class:`Object`
with the ID being set.
See :attr:`Guild.afk_channel`.
:type: Union[:class:`VoiceChannel`, :class:`Object`]
.. attribute:: system_channel
Union[:class:`TextChannel`, :class:`Object`] – The guild's system channel.
The guild's system channel.
If this could not be found, then it falls back to a :class:`Object`
with the ID being set.
See :attr:`Guild.system_channel`.
:type: Union[:class:`TextChannel`, :class:`Object`]
.. attribute:: afk_timeout
:class:`int` – The guild's AFK timeout. See :attr:`Guild.afk_timeout`.
The guild's AFK timeout. See :attr:`Guild.afk_timeout`.
:type: :class:`int`
.. attribute:: mfa_level
:class:`int` - The guild's MFA level. See :attr:`Guild.mfa_level`.
The guild's MFA level. See :attr:`Guild.mfa_level`.
:type: :class:`int`
.. attribute:: widget_enabled
:class:`bool` – The guild's widget has been enabled or disabled.
The guild's widget has been enabled or disabled.
:type: :class:`bool`
.. attribute:: widget_channel
Union[:class:`TextChannel`, :class:`Object`] – The widget's channel.
The widget's channel.
If this could not be found then it falls back to a :class:`Object`
with the ID being set.
:type: Union[:class:`TextChannel`, :class:`Object`]
.. attribute:: verification_level
:class:`VerificationLevel` – The guild's verification level.
The guild's verification level.
See also :attr:`Guild.verification_level`.
:type: :class:`VerificationLevel`
.. attribute:: default_notifications
:class:`NotificationLevel` – The guild's default notification level.
The guild's default notification level.
See also :attr:`Guild.default_notifications`.
:type: :class:`NotificationLevel`
.. attribute:: explicit_content_filter
:class:`ContentFilter` – The guild's content filter.
The guild's content filter.
See also :attr:`Guild.explicit_content_filter`.
:type: :class:`ContentFilter`
.. attribute:: default_message_notifications
:class:`int` – The guild's default message notification setting.
The guild's default message notification setting.
:type: :class:`int`
.. attribute:: vanity_url_code
:class:`str` – The guild's vanity URL.
The guild's vanity URL.
See also :meth:`Guild.vanity_invite` and :meth:`Guild.edit`.
:type: :class:`str`
.. attribute:: position
:class:`int` – The position of a :class:`Role` or :class:`abc.GuildChannel`.
The position of a :class:`Role` or :class:`abc.GuildChannel`.
:type: :class:`int`
.. attribute:: type
Union[:class:`int`, :class:`str`] – The type of channel or channel permission overwrite.
The type of channel or channel permission overwrite.
If the type is an :class:`int`, then it is a type of channel which can be either
``0`` to indicate a text channel or ``1`` to indicate a voice channel.
@ -2065,22 +2156,27 @@ this goal, it must make use of a couple of data classes that aid in this goal.
If the type is a :class:`str`, then it is a type of permission overwrite which
can be either ``'role'`` or ``'member'``.
:type: Union[:class:`int`, :class:`str`]
.. attribute:: topic
:class:`str` – The topic of a :class:`TextChannel`.
The topic of a :class:`TextChannel`.
See also :attr:`TextChannel.topic`.
:type: :class:`str`
.. attribute:: bitrate
:class:`int` – The bitrate of a :class:`VoiceChannel`.
The bitrate of a :class:`VoiceChannel`.
See also :attr:`VoiceChannel.bitrate`.
:type: :class:`int`
.. attribute:: overwrites
List[Tuple[target, :class:`PermissionOverwrite`]] – A list of
permission overwrite tuples that represents a target and a
A list of permission overwrite tuples that represents a target and a
:class:`PermissionOverwrite` for said target.
The first element is the object being targeted, which can either
@ -2089,122 +2185,161 @@ this goal, it must make use of a couple of data classes that aid in this goal.
a ``type`` attribute set to either ``'role'`` or ``'member'`` to help
decide what type of ID it is.
:type: List[Tuple[target, :class:`PermissionOverwrite`]]
.. attribute:: roles
List[Union[:class:`Role`, :class:`Object`]] – A list of roles being added or removed
from a member.
A list of roles being added or removed from a member.
If a role is not found then it is a :class:`Object` with the ID and name being
filled in.
:type: List[Union[:class:`Role`, :class:`Object`]]
.. attribute:: nick
Optional[:class:`str`] – The nickname of a member.
The nickname of a member.
See also :attr:`Member.nick`
:type: Optional[:class:`str`]
.. attribute:: deaf
:class:`bool` – Whether the member is being server deafened.
Whether the member is being server deafened.
See also :attr:`VoiceState.deaf`.
:type: :class:`bool`
.. attribute:: mute
:class:`bool` – Whether the member is being server muted.
Whether the member is being server muted.
See also :attr:`VoiceState.mute`.
:type: :class:`bool`
.. attribute:: permissions
:class:`Permissions` – The permissions of a role.
The permissions of a role.
See also :attr:`Role.permissions`.
:type: :class:`Permissions`
.. attribute:: colour
color
:class:`Colour` – The colour of a role.
The colour of a role.
See also :attr:`Role.colour`
:type: :class:`Colour`
.. attribute:: hoist
:class:`bool` – Whether the role is being hoisted or not.
Whether the role is being hoisted or not.
See also :attr:`Role.hoist`
:type: :class:`bool`
.. attribute:: mentionable
:class:`bool` – Whether the role is mentionable or not.
Whether the role is mentionable or not.
See also :attr:`Role.mentionable`
:type: :class:`bool`
.. attribute:: code
:class:`str` – The invite's code.
The invite's code.
See also :attr:`Invite.code`
:type: :class:`str`
.. attribute:: channel
Union[:class:`abc.GuildChannel`, :class:`Object`] – A guild channel.
A guild channel.
If the channel is not found then it is a :class:`Object` with the ID
being set. In some cases the channel name is also set.
:type: Union[:class:`abc.GuildChannel`, :class:`Object`]
.. attribute:: inviter
:class:`User` – The user who created the invite.
The user who created the invite.
See also :attr:`Invite.inviter`.
:type: :class:`User`
.. attribute:: max_uses
:class:`int` – The invite's max uses.
The invite's max uses.
See also :attr:`Invite.max_uses`.
:type: :class:`int`
.. attribute:: uses
:class:`int` – The invite's current uses.
The invite's current uses.
See also :attr:`Invite.uses`.
:type: :class:`int`
.. attribute:: max_age
:class:`int` – The invite's max age in seconds.
The invite's max age in seconds.
See also :attr:`Invite.max_age`.
:type: :class:`int`
.. attribute:: temporary
:class:`bool` – If the invite is a temporary invite.
If the invite is a temporary invite.
See also :attr:`Invite.temporary`.
:type: :class:`bool`
.. attribute:: allow
deny
:class:`Permissions` – The permissions being allowed or denied.
The permissions being allowed or denied.
:type: :class:`Permissions`
.. attribute:: id
:class:`int` – The ID of the object being changed.
The ID of the object being changed.
:type: :class:`int`
.. attribute:: avatar
:class:`str` – The avatar hash of a member.
The avatar hash of a member.
See also :attr:`User.avatar`.
:type: :class:`str`
.. attribute:: slowmode_delay
:class:`int` – The number of seconds members have to wait before
The number of seconds members have to wait before
sending another message in the channel.
See also :attr:`TextChannel.slowmode_delay`.
:type: :class:`int`
.. this is currently missing the following keys: reason and application_id
I'm not sure how to about porting these

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

@ -93,7 +93,7 @@ Cogs
.. autoclass:: discord.ext.commands.CogMeta
:members:
.. _ext_commands_api_formatters:
.. _ext_commands_help_command:
Help Commands
-----------------