diff --git a/discord/abc.py b/discord/abc.py index 3132ca736..88e4bd969 100644 --- a/discord/abc.py +++ b/discord/abc.py @@ -114,7 +114,7 @@ class User(Snowflake, Protocol): The user's username. discriminator: :class:`str` The user's discriminator. - avatar: :class:`Asset` + avatar: :class:`~discord.Asset` The avatar asset the user has. bot: :class:`bool` If the user is a bot account. @@ -634,7 +634,7 @@ class GuildChannel: Deletes the channel. - You must have :attr:`~Permissions.manage_channels` permission to use this. + You must have :attr:`~discord.Permissions.manage_channels` permission to use this. Parameters ----------- @@ -678,7 +678,7 @@ class GuildChannel: If the ``overwrite`` parameter is ``None``, then the permission overwrites are deleted. - You must have the :attr:`~Permissions.manage_roles` permission to use this. + You must have the :attr:`~discord.Permissions.manage_roles` permission to use this. Examples ---------- @@ -860,7 +860,7 @@ class GuildChannel: A rich interface to help move a channel relative to other channels. - If exact position movement is required, :meth:`edit` should be used instead. + If exact position movement is required, ``edit`` should be used instead. You must have the :attr:`~discord.Permissions.manage_channels` permission to do this. @@ -990,7 +990,7 @@ class GuildChannel: Creates an instant invite from a text or voice channel. - You must have the :attr:`~Permissions.create_instant_invite` permission to + You must have the :attr:`~discord.Permissions.create_instant_invite` permission to do this. Parameters @@ -1040,7 +1040,7 @@ class GuildChannel: Returns a list of all active instant invites from this channel. - You must have :attr:`~Permissions.manage_channels` to get this information. + You must have :attr:`~discord.Permissions.manage_channels` to get this information. Raises ------- @@ -1321,7 +1321,7 @@ class Messageable(Protocol): def history(self, *, limit=100, before=None, after=None, around=None, oldest_first=None): """Returns an :class:`~discord.AsyncIterator` that enables receiving the destination's message history. - You must have :attr:`~Permissions.read_message_history` permissions to use this. + You must have :attr:`~discord.Permissions.read_message_history` permissions to use this. Examples --------- diff --git a/discord/client.py b/discord/client.py index 2ed8b4ef8..f30ed7f54 100644 --- a/discord/client.py +++ b/discord/client.py @@ -287,13 +287,13 @@ class Client: If this is not passed via ``__init__`` then this is retrieved through the gateway when an event contains the data. Usually - after :func:`on_connect` is called. + after :func:`~discord.on_connect` is called. """ return self._connection.application_id @property def application_flags(self) -> ApplicationFlags: - """:class:`ApplicationFlags`: The client's application flags. + """:class:`~discord.ApplicationFlags`: The client's application flags. .. versionadded: 2.0 """ @@ -1261,7 +1261,7 @@ class Client: .. note:: - This method is an API call. If you have :attr:`Intents.members` and member cache enabled, consider :meth:`get_user` instead. + This method is an API call. If you have :attr:`discord.Intents.members` and member cache enabled, consider :meth:`get_user` instead. Parameters ----------- diff --git a/discord/ext/commands/bot.py b/discord/ext/commands/bot.py index 4ab5ee350..1d5cd7bc6 100644 --- a/discord/ext/commands/bot.py +++ b/discord/ext/commands/bot.py @@ -220,7 +220,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:`.invoke` call. """ if call_once: @@ -253,7 +253,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:`.invoke` call. Regular global checks are called whenever a command is called or :meth:`.Command.can_run` is called. This type of check diff --git a/discord/ext/commands/cog.py b/discord/ext/commands/cog.py index 085bdb973..bda1b696d 100644 --- a/discord/ext/commands/cog.py +++ b/discord/ext/commands/cog.py @@ -334,7 +334,7 @@ class Cog(metaclass=CogMeta): @_cog_special_method def cog_check(self, ctx): - """A special method that registers as a :func:`commands.check` + """A special method that registers as a :func:`~discord.ext.commands.check` for every command and subcommand in this cog. This function **can** be a coroutine and must take a sole parameter, diff --git a/discord/ext/commands/context.py b/discord/ext/commands/context.py index 9699261d8..0f3c546ee 100644 --- a/discord/ext/commands/context.py +++ b/discord/ext/commands/context.py @@ -47,12 +47,12 @@ class Context(discord.abc.Messageable): The bot that contains the command being executed. args: :class:`list` The list of transformed arguments that were passed into the command. - If this is accessed during the :func:`on_command_error` event + If this is accessed during the :func:`.on_command_error` event then this list could be incomplete. kwargs: :class:`dict` A dictionary of transformed arguments that were passed into the command. Similar to :attr:`args`\, if this is accessed in the - :func:`on_command_error` event then this dict could be incomplete. + :func:`.on_command_error` event then this dict could be incomplete. current_parameter: Optional[:class:`inspect.Parameter`] The parameter that is currently being inspected and converted. This is only of use for within converters. diff --git a/discord/ext/commands/converter.py b/discord/ext/commands/converter.py index 1f1828b19..1beba3078 100644 --- a/discord/ext/commands/converter.py +++ b/discord/ext/commands/converter.py @@ -516,7 +516,7 @@ class ColourConverter(Converter[discord.Colour]): - ``#`` - ``0x#`` - ``rgb(, , )`` - - Any of the ``classmethod`` in :class:`Colour` + - Any of the ``classmethod`` in :class:`~discord.Colour` - The ``_`` in the name can be optionally replaced with spaces. diff --git a/discord/ext/commands/core.py b/discord/ext/commands/core.py index cb986e3b2..a736debb0 100644 --- a/discord/ext/commands/core.py +++ b/discord/ext/commands/core.py @@ -908,9 +908,9 @@ class Command(_BaseCommand): def short_doc(self): """:class:`str`: Gets the "short" documentation of a command. - By default, this is the :attr:`brief` attribute. + By default, this is the :attr:`.brief` attribute. If that lookup leads to an empty string then the first line of the - :attr:`help` attribute is used instead. + :attr:`.help` attribute is used instead. """ if self.brief is not None: return self.brief @@ -979,7 +979,7 @@ class Command(_BaseCommand): """|coro| Checks if the command can be executed by checking all the predicates - inside the :attr:`checks` attribute. This also checks whether the + inside the :attr:`~Command.checks` attribute. This also checks whether the command is disabled. .. versionchanged:: 1.3 diff --git a/discord/ext/commands/errors.py b/discord/ext/commands/errors.py index a624cf5fd..ecca00b4c 100644 --- a/discord/ext/commands/errors.py +++ b/discord/ext/commands/errors.py @@ -89,7 +89,7 @@ class CommandError(DiscordException): This exception and exceptions inherited 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: @@ -457,7 +457,7 @@ class CommandOnCooldown(CommandError): Attributes ----------- - cooldown: Cooldown + cooldown: ``Cooldown`` A class with attributes ``rate``, ``per``, and ``type`` similar to the :func:`.cooldown` decorator. retry_after: :class:`float` @@ -654,7 +654,7 @@ class BadUnionArgument(UserInputError): ----------- param: :class:`inspect.Parameter` The parameter that failed being converted. - converters: Tuple[Type, ...] + converters: Tuple[Type, ``...``] A tuple of converters attempted in conversion, in order of failure. errors: List[:class:`CommandError`] A list of errors that were caught from failing the conversion. @@ -692,7 +692,7 @@ class BadLiteralArgument(UserInputError): ----------- param: :class:`inspect.Parameter` The parameter that failed being converted. - literals: Tuple[Any, ...] + literals: Tuple[Any, ``...``] A tuple of values compared against in conversion, in order of failure. errors: List[:class:`CommandError`] A list of errors that were caught from failing the conversion. diff --git a/discord/ext/commands/help.py b/discord/ext/commands/help.py index 4dd1e745e..6de81bb5f 100644 --- a/discord/ext/commands/help.py +++ b/discord/ext/commands/help.py @@ -277,9 +277,9 @@ class HelpCommand: Defaults to ``False``. verify_checks: Optional[:class:`bool`] Specifies if commands should have their :attr:`.Command.checks` called - and verified. If ``True``, always calls :attr:`.Commands.checks`. - If ``None``, only calls :attr:`.Commands.checks` in a guild setting. - If ``False``, never calls :attr:`.Commands.checks`. Defaults to ``True``. + and verified. If ``True``, always calls :attr:`.Command.checks`. + If ``None``, only calls :attr:`.Command.checks` in a guild setting. + If ``False``, never calls :attr:`.Command.checks`. Defaults to ``True``. .. versionchanged:: 1.7 command_attrs: :class:`dict` @@ -615,8 +615,7 @@ class HelpCommand: """|coro| Handles the implementation when an error happens in the help command. - For example, the result of :meth:`command_not_found` or - :meth:`command_has_no_subcommand_found` will be passed here. + For example, the result of :meth:`command_not_found` will be passed here. You can override this method to customise the behaviour. @@ -949,7 +948,7 @@ class DefaultHelpCommand(HelpCommand): if the list of commands is greater than 0. max_size: Optional[:class:`int`] The max size to use for the gap between indents. - If unspecified, calls :meth:`get_max_size` on the + If unspecified, calls :meth:`~HelpCommand.get_max_size` on the commands parameter. """ diff --git a/discord/guild.py b/discord/guild.py index 4f1c8caba..7034da76c 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -143,7 +143,7 @@ class Guild(Hashable): - ``COMMERCE``: Guild can sell things using store channels. - ``PUBLIC``: Guild is a public guild. - ``NEWS``: Guild can create news channels. - - ``BANNER``: Guild can upload and use a banner (i.e. :meth:`banner_url`). + - ``BANNER``: Guild can upload and use a banner. (i.e. :attr:`.banner`) - ``ANIMATED_ICON``: Guild can upload an animated icon. - ``PUBLIC_DISABLED``: Guild cannot be public. - ``WELCOME_SCREEN_ENABLED``: Guild has enabled the welcome screen @@ -1042,7 +1042,7 @@ class Guild(Hashable): The new name of the guild. description: Optional[:class:`str`] The new description of the guild. Could be ``None`` for no description. - This is only available to guilds that contain ``PUBLIC`` in :attr:`Guild.features`. + This is only available to guilds that contain ``PUBLIC`` in :attr:`Guild.features`. icon: :class:`bytes` A :term:`py:bytes-like object` representing the icon. Only PNG/JPEG is supported. GIF is only available to guilds that contain ``ANIMATED_ICON`` in :attr:`Guild.features`. diff --git a/discord/invite.py b/discord/invite.py index 7a80d3012..ea551e1d5 100644 --- a/discord/invite.py +++ b/discord/invite.py @@ -281,7 +281,7 @@ class Invite(Hashable): The target of this invite in the case of stream invites. .. versionadded:: 2.0 - target_type: :class:`InviteType` + target_type: :class:`InviteTarget` The invite's target type. .. versionadded:: 2.0 diff --git a/discord/player.py b/discord/player.py index 48b702e65..2ea5308c5 100644 --- a/discord/player.py +++ b/discord/player.py @@ -73,7 +73,7 @@ class AudioSource: If the audio is complete, then returning an empty :term:`py:bytes-like object` to signal this is the way to do so. - If :meth:`is_opus` method returns ``True``, then it must return + If :meth:`~AudioSource.is_opus` method returns ``True``, then it must return 20ms worth of Opus encoded audio. Otherwise, it must be 20ms worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes per frame (20ms worth of audio). diff --git a/discord/utils.py b/discord/utils.py index d4f0a48ca..4a6922b6a 100644 --- a/discord/utils.py +++ b/discord/utils.py @@ -353,7 +353,7 @@ def find(predicate: Callable[[T], Any], seq: Iterable[T]) -> Optional[T]: ----------- predicate A function that returns a boolean-like result. - seq: iterable + seq: :class:`collections.abc.Iterable` The iterable to search through. """ @@ -530,7 +530,7 @@ async def sleep_until(when: datetime.datetime, result: Optional[T] = None) -> Op def utcnow() -> datetime.datetime: """A helper function to return an aware UTC datetime representing the current time. - This should be preferred to :func:`datetime.datetime.utcnow` since it is an aware + This should be preferred to :meth:`datetime.datetime.utcnow` since it is an aware datetime, compared to the naive datetime in the standard library. .. versionadded:: 2.0 diff --git a/discord/voice_client.py b/discord/voice_client.py index bca338edb..246ed7b6a 100644 --- a/discord/voice_client.py +++ b/discord/voice_client.py @@ -71,7 +71,7 @@ class VoiceProtocol: This class allows you to implement a protocol to allow for an external method of sending voice, such as Lavalink_ or a native library implementation. - These classes are passed to :meth:`abc.Connectable.connect`. + These classes are passed to :meth:`abc.Connectable.connect `. .. _Lavalink: https://github.com/freyacodes/Lavalink diff --git a/discord/webhook/async_.py b/discord/webhook/async_.py index 8daa62ca1..21e32d00f 100644 --- a/discord/webhook/async_.py +++ b/discord/webhook/async_.py @@ -788,8 +788,6 @@ class Webhook(BaseWebhook): received without authentication then this will be ``None``. name: Optional[:class:`str`] The default name of the webhook. - avatar: Optional[:class:`str`] - The default avatar of the webhook. source_guild: Optional[:class:`PartialWebhookGuild`] The guild of the channel that this webhook is following. Only given if :attr:`type` is :attr:`WebhookType.channel_follower`. diff --git a/discord/webhook/sync.py b/discord/webhook/sync.py index 635633fd1..2ad7b7534 100644 --- a/discord/webhook/sync.py +++ b/discord/webhook/sync.py @@ -478,8 +478,6 @@ class SyncWebhook(BaseWebhook): received without authentication then this will be ``None``. name: Optional[:class:`str`] The default name of the webhook. - avatar: Optional[:class:`str`] - The default avatar of the webhook. source_guild: Optional[:class:`PartialWebhookGuild`] The guild of the channel that this webhook is following. Only given if :attr:`type` is :attr:`WebhookType.channel_follower`. diff --git a/docs/api.rst b/docs/api.rst index ff4ec9071..44b1e727e 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -367,7 +367,7 @@ to handle it, which defaults to print a traceback and ignoring the exception. Messages might not be in cache if the message is too old or the client is participating in high traffic guilds. - If this occurs increase the :attr:`Client.max_messages` attribute + If this occurs increase the :class:`max_messages ` parameter or use the :func:`on_raw_message_delete` event instead. This requires :attr:`Intents.messages` to be enabled. @@ -384,7 +384,7 @@ to handle it, which defaults to print a traceback and ignoring the exception. the messages list. Messages might not be in cache if the message is too old or the client is participating in high traffic guilds. - If this occurs increase the :attr:`Client.max_messages` attribute + If this occurs increase the :class:`max_messages ` parameter or use the :func:`on_raw_bulk_message_delete` event instead. This requires :attr:`Intents.messages` to be enabled. @@ -425,7 +425,7 @@ to handle it, which defaults to print a traceback and ignoring the exception. Messages might not be in cache if the message is too old or the client is participating in high traffic guilds. - If this occurs increase the :attr:`Client.max_messages` attribute + If this occurs increase the :class:`max_messages ` parameter or use the :func:`on_raw_message_edit` event instead. The following non-exhaustive cases trigger this event: @@ -1078,6 +1078,59 @@ of :class:`enum.Enum`. .. versionadded:: 2.0 +.. class:: UserFlags + + Represents Discord User flags. + + .. attribute:: staff + + The user is a Discord Employee. + .. attribute:: partner + + The user is a Discord Partner. + .. attribute:: hypesquad + + The user is a HypeSquad Events member. + .. attribute:: bug_hunter + + The user is a Bug Hunter. + .. attribute:: mfa_sms + + The user has SMS recovery for Multi Factor Authentication enabled. + .. attribute:: premium_promo_dismissed + + The user has dismissed the Discord Nitro promotion. + .. attribute:: hypesquad_bravery + + The user is a HypeSquad Bravery member. + .. attribute:: hypesquad_brilliance + + The user is a HypeSquad Brilliance member. + .. attribute:: hypesquad_balance + + The user is a HypeSquad Balance member. + .. attribute:: early_supporter + + The user is an Early Supporter. + .. attribute:: team_user + + The user is a Team User. + .. attribute:: system + + The user is a system user (i.e. represents Discord officially). + .. attribute:: has_unread_urgent_messages + + The user has an unready system message. + .. attribute:: bug_hunter_level_2 + + The user is a Bug Hunter Level 2. + .. attribute:: verified_bot + + The user is a Verified Bot. + .. attribute:: verified_bot_developer + + The user is an Early Verified Bot Developer. + .. class:: ActivityType Specifies the type of :class:`Activity`. This is used to check how to @@ -1854,7 +1907,7 @@ of :class:`enum.Enum`. .. class:: TeamMembershipState - Represents the membership state of a team member retrieved through :func:`Bot.application_info`. + Represents the membership state of a team member retrieved through :func:`Client.application_info`. .. versionadded:: 1.3 @@ -2581,6 +2634,7 @@ Webhook .. autoclass:: Webhook() :members: + :inherited-members: WebhookMessage ~~~~~~~~~~~~~~~~ @@ -2597,6 +2651,7 @@ SyncWebhook .. autoclass:: SyncWebhook() :members: + :inherited-members: SyncWebhookMessage ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/conf.py b/docs/conf.py index aed9086b0..925d5339b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,7 +53,7 @@ extlinks = { intersphinx_mapping = { 'py': ('https://docs.python.org/3', None), 'aio': ('https://docs.aiohttp.org/en/stable/', None), - 'req': ('http://docs.python-requests.org/en/latest/', 'requests.inv') + 'req': ('https://docs.python-requests.org/en/latest/', None) } rst_prolog = """ diff --git a/docs/ext/commands/api.rst b/docs/ext/commands/api.rst index 9cd655b45..aa31a0003 100644 --- a/docs/ext/commands/api.rst +++ b/docs/ext/commands/api.rst @@ -42,7 +42,7 @@ Event Reference These events function similar to :ref:`the regular events `, except they are custom to the command extension module. -.. function:: on_command_error(ctx, error) +.. function:: discord.ext.commands.on_command_error(ctx, error) An error handler that is called when an error is raised inside a command either through user input error, check @@ -55,7 +55,7 @@ are custom to the command extension module. :param error: The error that was raised. :type error: :class:`.CommandError` derived -.. function:: on_command(ctx) +.. function:: discord.ext.commands.on_command(ctx) An event that is called when a command is found and is about to be invoked. @@ -65,7 +65,7 @@ are custom to the command extension module. :param ctx: The invocation context. :type ctx: :class:`.Context` -.. function:: on_command_completion(ctx) +.. function:: discord.ext.commands.on_command_completion(ctx) An event that is called when a command has completed its invocation. @@ -374,6 +374,9 @@ Exceptions .. autoexception:: discord.ext.commands.BadUnionArgument :members: +.. autoexception:: discord.ext.commands.BadLiteralArgument + :members: + .. autoexception:: discord.ext.commands.PrivateMessageOnly :members: @@ -533,6 +536,7 @@ Exception Hierarchy - :exc:`~.commands.TooManyFlags` - :exc:`~.commands.MissingRequiredFlag` - :exc:`~.commands.BadUnionArgument` + - :exc:`~.commands.BadLiteralArgument` - :exc:`~.commands.ArgumentParsingError` - :exc:`~.commands.UnexpectedQuoteError` - :exc:`~.commands.InvalidEndOfQuotedStringError` diff --git a/docs/ext/commands/commands.rst b/docs/ext/commands/commands.rst index a5f8998b1..6e1f42233 100644 --- a/docs/ext/commands/commands.rst +++ b/docs/ext/commands/commands.rst @@ -761,7 +761,7 @@ When our commands fail to parse we will, by default, receive a noisy error in `` that an error has happened and has been silently ignored. In order to handle our errors, we must use something called an error handler. There is a global error handler, called -:func:`on_command_error` which works like any other event in the :ref:`discord-api-events`. This global error handler is +:func:`.on_command_error` which works like any other event in the :ref:`discord-api-events`. This global error handler is called for every error reached. Most of the time however, we want to handle an error local to the command itself. Luckily, commands come with local error diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 52553cd40..8b3daeb2c 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -56,7 +56,7 @@ There's a lot going on here, so let's walk you through it step by step. is the same as the :attr:`Client.user`. 5. Afterwards, we check if the :class:`Message.content` starts with ``'$hello'``. If it does, then we send a message in the channel it was used in with ``'Hello!'``. This is a basic way of - handling commands, which can be later automated with the :ref:`ext.commands` framework. + handling commands, which can be later automated with the :doc:`./ext/commands/index` framework. 6. Finally, we run the bot with our login token. If you need help getting your token or creating a bot, look in the :ref:`discord-intro` section. diff --git a/docs/requests.inv b/docs/requests.inv deleted file mode 100644 index 7deac0ce1..000000000 Binary files a/docs/requests.inv and /dev/null differ diff --git a/docs/whats_new.rst b/docs/whats_new.rst index 2b774c15b..91207252a 100644 --- a/docs/whats_new.rst +++ b/docs/whats_new.rst @@ -1173,4 +1173,4 @@ Bug Fixes - Mentions are now triggered normally. This was changed due to the way discord handles it internally. - Fix issue when a :class:`Message` would attempt to upgrade a :attr:`Message.server` when the channel is a :class:`Object`. -- Unavailable servers were not being added into cache, this has been corrected. +- Unavailable servers were not being added into cache, this has been corrected. \ No newline at end of file diff --git a/setup.py b/setup.py index 43b8120aa..06016e63f 100644 --- a/setup.py +++ b/setup.py @@ -36,7 +36,7 @@ with open('README.rst') as f: extras_require = { 'voice': ['PyNaCl>=1.3.0,<1.5'], 'docs': [ - 'sphinx==3.5.3', + 'sphinx==3.5.4', 'sphinxcontrib_trio==1.1.2', 'sphinxcontrib-websupport', ]