From b4b953bfc66adc235e06774b0481ceb847753793 Mon Sep 17 00:00:00 2001 From: Sebastian Law <44045823+SebbyLaw@users.noreply.github.com> Date: Sun, 28 Jun 2020 00:45:58 -0700 Subject: [PATCH] Fix various inconsistencies within the documentation (#5067) --- discord/abc.py | 8 +- discord/activity.py | 12 +- discord/channel.py | 12 +- discord/client.py | 12 +- discord/colour.py | 2 +- discord/embeds.py | 14 +- discord/ext/commands/bot.py | 13 +- discord/ext/commands/cog.py | 22 ++- discord/ext/commands/context.py | 32 +++-- discord/ext/commands/core.py | 52 +++++--- discord/ext/commands/errors.py | 2 +- discord/ext/commands/help.py | 2 +- discord/file.py | 5 + discord/guild.py | 24 +++- discord/invite.py | 24 +++- discord/member.py | 9 +- discord/message.py | 2 +- discord/permissions.py | 2 +- discord/player.py | 2 +- discord/user.py | 4 +- discord/utils.py | 16 ++- discord/webhook.py | 18 ++- docs/api.rst | 229 +++++++++++++++++++++++++------- docs/ext/commands/api.rst | 2 +- 24 files changed, 378 insertions(+), 142 deletions(-) diff --git a/discord/abc.py b/discord/abc.py index 07046a40f..41bde7093 100644 --- a/discord/abc.py +++ b/discord/abc.py @@ -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``. diff --git a/discord/activity.py b/discord/activity.py index cc4227f15..c56fec32d 100644 --- a/discord/activity.py +++ b/discord/activity.py @@ -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`. """ diff --git a/discord/channel.py b/discord/channel.py index 71e5580b1..442f80b29 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -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): diff --git a/discord/client.py b/discord/client.py index e6c12f68a..88cd09a1e 100644 --- a/discord/client.py +++ b/discord/client.py @@ -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. diff --git a/discord/colour.py b/discord/colour.py index 48d4538f5..78221eef0 100644 --- a/discord/colour.py +++ b/discord/colour.py @@ -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 diff --git a/discord/embeds.py b/discord/embeds.py index e02918eff..7bbe80305 100644 --- a/discord/embeds.py +++ b/discord/embeds.py @@ -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. diff --git a/discord/ext/commands/bot.py b/discord/ext/commands/bot.py index 8485c4aba..724ab7cb8 100644 --- a/discord/ext/commands/bot.py +++ b/discord/ext/commands/bot.py @@ -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 """ diff --git a/discord/ext/commands/cog.py b/discord/ext/commands/cog.py index 5c81e4a5a..b8e259177 100644 --- a/discord/ext/commands/cog.py +++ b/discord/ext/commands/cog.py @@ -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 `]] + The listeners defined in this cog. + """ return [(name, getattr(self, method_name)) for name, method_name in self.__cog_listeners__] @classmethod diff --git a/discord/ext/commands/context.py b/discord/ext/commands/context.py index 5635cb42e..bb48935c3 100644 --- a/discord/ext/commands/context.py +++ b/discord/ext/commands/context.py @@ -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 diff --git a/discord/ext/commands/core.py b/discord/ext/commands/core.py index 9534f5272..7bfe61969 100644 --- a/discord/ext/commands/core.py +++ b/discord/ext/commands/core.py @@ -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 diff --git a/discord/ext/commands/errors.py b/discord/ext/commands/errors.py index 23481a78d..34b0b979e 100644 --- a/discord/ext/commands/errors.py +++ b/discord/ext/commands/errors.py @@ -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. """ diff --git a/discord/ext/commands/help.py b/discord/ext/commands/help.py index 226e5f6a5..21a87396c 100644 --- a/discord/ext/commands/help.py +++ b/discord/ext/commands/help.py @@ -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() diff --git a/discord/file.py b/discord/file.py index 3bf440470..ddee82cbc 100644 --- a/discord/file.py +++ b/discord/file.py @@ -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`] diff --git a/discord/guild.py b/discord/guild.py index 7e24b4b47..fdad7389c 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -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) diff --git a/discord/invite.py b/discord/invite.py index e16fbe78d..b6d459120 100644 --- a/discord/invite.py +++ b/discord/invite.py @@ -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): diff --git a/discord/member.py b/discord/member.py index 8d73417c0..44a8e0945 100644 --- a/discord/member.py +++ b/discord/member.py @@ -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 diff --git a/discord/message.py b/discord/message.py index 2a289dc45..f6565ba14 100644 --- a/discord/message.py +++ b/discord/message.py @@ -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 diff --git a/discord/permissions.py b/discord/permissions.py index f3a9caeda..adc6a9261 100644 --- a/discord/permissions.py +++ b/discord/permissions.py @@ -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. diff --git a/discord/player.py b/discord/player.py index c31025121..4384d9fd3 100644 --- a/discord/player.py +++ b/discord/player.py @@ -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 diff --git a/discord/user.py b/discord/user.py index 1f5c508aa..e5e9640d4 100644 --- a/discord/user.py +++ b/discord/user.py @@ -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:: diff --git a/discord/utils.py b/discord/utils.py index 510096ddf..118b46913 100644 --- a/discord/utils.py +++ b/discord/utils.py @@ -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): diff --git a/discord/webhook.py b/discord/webhook.py index a45d27e03..7a7bf9506 100644 --- a/discord/webhook.py +++ b/discord/webhook.py @@ -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 ` 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[0-9]{17,21})/(?P[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. diff --git a/docs/api.rst b/docs/api.rst index 72ad9ae08..aa296958e 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -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 + + .. describe:: iter(diff) - Returns an iterator over (attribute, value) tuple of this 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 diff --git a/docs/ext/commands/api.rst b/docs/ext/commands/api.rst index 830509dc6..61488c08f 100644 --- a/docs/ext/commands/api.rst +++ b/docs/ext/commands/api.rst @@ -93,7 +93,7 @@ Cogs .. autoclass:: discord.ext.commands.CogMeta :members: -.. _ext_commands_api_formatters: +.. _ext_commands_help_command: Help Commands -----------------