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

conflict fixes

Browse Source
This commit is contained in:
iDutchy
2021-04-07 18:27:34 -05:00
parent f1309aa4a1 87e64dff06
commit a453266cd4
94 changed files with 4512 additions and 3018 deletions
Download Patch File Download Diff File Expand all files Collapse all files

430
docs/api.rst
View File

@ -40,6 +40,10 @@ Client
.. autoclass:: Client
:members:
:exclude-members: fetch_guilds
.. automethod:: Client.fetch_guilds
:async-for:
AutoShardedClient
~~~~~~~~~~~~~~~~~~
@ -200,11 +204,11 @@ to handle it, which defaults to print a traceback and ignoring the exception.
.. function:: on_disconnect()
Called when the client has disconnected from Discord. This could happen either through
the internet being disconnected, explicit calls to logout, or Discord terminating the connection
one way or the other.
Called when the client has disconnected from Discord, or a connection attempt to Discord has failed.
This could happen either through the internet being disconnected, explicit calls to close,
or Discord terminating the connection one way or the other.
This function can be called many times.
This function can be called many times without a corresponding :func:`on_connect` call.
.. function:: on_shard_disconnect(shard_id)
@ -250,7 +254,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
:param shard_id: The shard ID that has resumed.
:type shard_id: :class:`int`
.. function:: on_error(event, \*args, \*\*kwargs)
.. function:: on_error(event, *args, **kwargs)
Usually when an event raises an uncaught exception, a traceback is
printed to stderr and the exception is ignored. If you want to
@ -336,7 +340,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
:type channel: :class:`abc.Messageable`
:param user: The user that started typing.
:type user: Union[:class:`User`, :class:`Member`]
:param when: When the typing started as a naive datetime in UTC.
:param when: When the typing started as an aware datetime in UTC.
:type when: :class:`datetime.datetime`
.. function:: on_message(message)
@ -448,7 +452,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
regardless of the state of the internal message cache.
If the message is found in the message cache,
it can be accessed via :attr:`RawMessageUpdateEvent.cached_message`
it can be accessed via :attr:`RawMessageUpdateEvent.cached_message`. The cached message represents
the message before it has been edited. For example, if the content of a message is modified and
triggers the :func:`on_raw_message_edit` coroutine, the :attr:`RawMessageUpdateEvent.cached_message`
will return a :class:`Message` object that represents the message before the content was modified.
Due to the inherently raw nature of this event, the data parameter coincides with
the raw data given by the `gateway <https://discord.com/developers/docs/topics/gateway#message-update>`_.
@ -475,6 +482,14 @@ to handle it, which defaults to print a traceback and ignoring the exception.
This requires :attr:`Intents.reactions` to be enabled.
.. note::
This doesn't require :attr:`Intents.members` within a guild context,
but due to Discord not providing updated user information in a direct message
it's required for direct messages to receive this event.
Consider using :func:`on_raw_reaction_add` if you need this and do not otherwise want
to enable the members intent.
:param reaction: The current state of the reaction.
:type reaction: :class:`Reaction`
:param user: The user who added the reaction.
@ -500,7 +515,12 @@ to handle it, which defaults to print a traceback and ignoring the exception.
To get the message being reacted, access it via :attr:`Reaction.message`.
This requires :attr:`Intents.reactions` to be enabled.
This requires both :attr:`Intents.reactions` and :attr:`Intents.members` to be enabled.
.. note::
Consider using :func:`on_raw_reaction_remove` if you need this and do not want
to enable the members intent.
:param reaction: The current state of the reaction.
:type reaction: :class:`Reaction`
@ -565,6 +585,17 @@ to handle it, which defaults to print a traceback and ignoring the exception.
:param payload: The raw event payload data.
:type payload: :class:`RawReactionClearEmojiEvent`
.. function:: on_interaction(interaction)
Called when an interaction happened.
This currently happens due to slash command invocations.
.. versionadded:: 2.0
:param interaction: The interaction data.
:type interaction: :class:`Interaction`
.. function:: on_private_channel_delete(channel)
on_private_channel_create(channel)
@ -592,7 +623,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
:param channel: The private channel that had its pins updated.
:type channel: :class:`abc.PrivateChannel`
:param last_pin: The latest message that was pinned as a naive datetime in UTC. Could be ``None``.
:param last_pin: The latest message that was pinned as an aware datetime in UTC. Could be ``None``.
:type last_pin: Optional[:class:`datetime.datetime`]
.. function:: on_guild_channel_delete(channel)
@ -626,7 +657,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
:param channel: The guild channel that had its pins updated.
:type channel: :class:`abc.GuildChannel`
:param last_pin: The latest message that was pinned as a naive datetime in UTC. Could be ``None``.
:param last_pin: The latest message that was pinned as an aware datetime in UTC. Could be ``None``.
:type last_pin: Optional[:class:`datetime.datetime`]
.. function:: on_guild_integrations_update(guild)
@ -877,25 +908,6 @@ to handle it, which defaults to print a traceback and ignoring the exception.
:param user: The user that joined or left.
:type user: :class:`User`
.. function:: on_relationship_add(relationship)
on_relationship_remove(relationship)
Called when a :class:`Relationship` is added or removed from the
:class:`ClientUser`.
:param relationship: The relationship that was added or removed.
:type relationship: :class:`Relationship`
.. function:: on_relationship_update(before, after)
Called when a :class:`Relationship` is updated, e.g. when you
block a friend or a friendship is accepted.
:param before: The previous relationship status.
:type before: :class:`Relationship`
:param after: The updated relationship status.
:type after: :class:`Relationship`
.. _discord-api-utils:
Utility Functions
@ -909,6 +921,8 @@ Utility Functions
.. autofunction:: discord.utils.oauth_url
.. autofunction:: discord.utils.remove_markdown
.. autofunction:: discord.utils.escape_markdown
.. autofunction:: discord.utils.escape_mentions
@ -919,94 +933,7 @@ Utility Functions
.. autofunction:: discord.utils.sleep_until
Profile
---------
.. class:: Profile
A namedtuple representing a user's Discord public 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`.
.. attribute:: premium_since
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: List[Dict[:class:`str`, :class:`str`]]
.. autofunction:: discord.utils.utcnow
.. _discord-api-enums:
@ -1046,6 +973,12 @@ of :class:`enum.Enum`.
A guild store channel.
.. attribute:: stage_voice
A guild stage voice channel.
.. versionadded:: 1.7
.. class:: MessageType
Specifies the type of :class:`Message`. This is used to denote if a message
@ -1108,6 +1041,35 @@ of :class:`enum.Enum`.
The system message denoting that an announcement channel has been followed.
.. versionadded:: 1.3
.. attribute:: guild_stream
The system message denoting that a member is streaming in the guild.
.. versionadded:: 1.7
.. attribute:: guild_discovery_disqualified
The system message denoting that the guild is no longer eligible for Server
Discovery.
.. versionadded:: 1.7
.. attribute:: guild_discovery_requalified
The system message denoting that the guild has become eligible again for Server
Discovery.
.. versionadded:: 1.7
.. attribute:: guild_discovery_grace_period_initial_warning
The system message denoting that the guild has failed to meet the Server
Discovery requirements for one week.
.. versionadded:: 1.7
.. attribute:: guild_discovery_grace_period_final_warning
The system message denoting that the guild has failed to meet the Server
Discovery requirements for 3 weeks in a row.
.. versionadded:: 1.7
.. class:: ActivityType
@ -1138,6 +1100,20 @@ of :class:`enum.Enum`.
.. versionadded:: 1.5
.. class:: InteractionType
Specifies the type of :class:`Interaction`.
.. versionadded:: 2.0
.. attribute:: ping
Represents Discord pinging to see if the interaction response server is alive.
.. attribute:: application_command
Represents a slash command interaction.
.. class:: HypeSquadHouse
Specifies the HypeSquad house a user belongs to.
@ -1877,117 +1853,6 @@ of :class:`enum.Enum`.
The action is the update of something.
.. class:: RelationshipType
Specifies the type of :class:`Relationship`.
.. note::
This only applies to users, *not* bots.
.. attribute:: friend
You are friends with this user.
.. attribute:: blocked
You have blocked this user.
.. attribute:: incoming_request
The user has sent you a friend request.
.. attribute:: outgoing_request
You have sent a friend request to this user.
.. class:: UserContentFilter
Represents the options found in ``Settings > Privacy & Safety > Safe Direct Messaging``
in the Discord client.
.. note::
This only applies to users, *not* bots.
.. attribute:: all_messages
Scan all direct messages from everyone.
.. attribute:: friends
Scan all direct messages that aren't from friends.
.. attribute:: disabled
Don't scan any direct messages.
.. class:: FriendFlags
Represents the options found in ``Settings > Privacy & Safety > Who Can Add You As A Friend``
in the Discord client.
.. note::
This only applies to users, *not* bots.
.. attribute:: noone
This allows no-one to add you as a friend.
.. attribute:: mutual_guilds
This allows guild members to add you as a friend.
.. attribute:: mutual_friends
This allows friends of friends to add you as a friend.
.. attribute:: guild_and_friends
This is a superset of :attr:`mutual_guilds` and :attr:`mutual_friends`.
.. attribute:: everyone
This allows everyone to add you as a friend.
.. class:: PremiumType
Represents the user's Discord Nitro subscription type.
.. note::
This only applies to users, *not* bots.
.. attribute:: nitro
Represents the Discord Nitro with Nitro-exclusive games.
.. attribute:: nitro_classic
Represents the Discord Nitro with no Nitro-exclusive games.
.. class:: Theme
Represents the theme synced across all Discord clients.
.. note::
This only applies to users, *not* bots.
.. attribute:: light
Represents the Light theme on Discord.
.. attribute:: dark
Represents the Dark theme on Discord.
.. class:: TeamMembershipState
Represents the membership state of a team member retrieved through :func:`Bot.application_info`.
@ -2661,20 +2526,19 @@ interface, :meth:`WebhookAdapter.request`.
Abstract Base Classes
-----------------------
An :term:`py:abstract base class` (also known as an ``abc``) is a class that models can inherit
to get their behaviour. The Python implementation of an :doc:`abc <py:library/abc>` is
slightly different in that you can register them at run-time. **Abstract base classes cannot be instantiated**.
They are mainly there for usage with :func:`py:isinstance` and :func:`py:issubclass`\.
An :term:`abstract base class` (also known as an ``abc``) is a class that models can inherit
to get their behaviour. **Abstract base classes should not be instantiated**.
They are mainly there for usage with :func:`isinstance` and :func:`issubclass`\.
This library has a module related to abstract base classes, some of which are actually from the :doc:`abc <py:library/abc>` standard
module, others which are not.
This library has a module related to abstract base classes, in which all the ABCs are subclasses of
:class:`typing.Protocol`.
Snowflake
~~~~~~~~~~
.. attributetable:: discord.abc.Snowflake
.. autoclass:: discord.abc.Snowflake
.. autoclass:: discord.abc.Snowflake()
:members:
User
@ -2682,7 +2546,7 @@ User
.. attributetable:: discord.abc.User
.. autoclass:: discord.abc.User
.. autoclass:: discord.abc.User()
:members:
PrivateChannel
@ -2690,7 +2554,7 @@ PrivateChannel
.. attributetable:: discord.abc.PrivateChannel
.. autoclass:: discord.abc.PrivateChannel
.. autoclass:: discord.abc.PrivateChannel()
:members:
GuildChannel
@ -2698,7 +2562,7 @@ GuildChannel
.. attributetable:: discord.abc.GuildChannel
.. autoclass:: discord.abc.GuildChannel
.. autoclass:: discord.abc.GuildChannel()
:members:
Messageable
@ -2706,7 +2570,7 @@ Messageable
.. attributetable:: discord.abc.Messageable
.. autoclass:: discord.abc.Messageable
.. autoclass:: discord.abc.Messageable()
:members:
:exclude-members: history, typing
@ -2721,7 +2585,7 @@ Connectable
.. attributetable:: discord.abc.Connectable
.. autoclass:: discord.abc.Connectable
.. autoclass:: discord.abc.Connectable()
.. _discord_api_models:
@ -2759,14 +2623,6 @@ ClientUser
:members:
:inherited-members:
Relationship
~~~~~~~~~~~~~~
.. attributetable:: Relationship
.. autoclass:: Relationship()
:members:
User
~~~~~
@ -2828,22 +2684,6 @@ Reaction
.. automethod:: users
:async-for:
CallMessage
~~~~~~~~~~~~
.. attributetable:: CallMessage
.. autoclass:: CallMessage()
:members:
GroupCall
~~~~~~~~~~
.. attributetable:: GroupCall
.. autoclass:: GroupCall()
:members:
Guild
~~~~~~
@ -2851,11 +2691,30 @@ Guild
.. autoclass:: Guild()
:members:
:exclude-members: audit_logs
:exclude-members: fetch_members, audit_logs
.. automethod:: fetch_members
:async-for:
.. automethod:: audit_logs
:async-for:
.. class:: BanEntry
A namedtuple which represents a ban returned from :meth:`~Guild.bans`.
.. attribute:: reason
The reason this user was banned.
:type: Optional[:class:`str`]
.. attribute:: user
The :class:`User` that was banned.
:type: :class:`User`
Integration
~~~~~~~~~~~~
@ -2865,6 +2724,14 @@ Integration
.. autoclass:: IntegrationAccount()
:members:
Interaction
~~~~~~~~~~~~
.. attributetable:: Interaction
.. autoclass:: Interaction()
:members:
Member
~~~~~~
@ -2943,6 +2810,15 @@ TextChannel
.. automethod:: typing
:async-with:
StoreChannel
~~~~~~~~~~~~~
.. attributetable:: StoreChannel
.. autoclass:: StoreChannel()
:members:
:inherited-members:
VoiceChannel
~~~~~~~~~~~~~
@ -2952,6 +2828,15 @@ VoiceChannel
:members:
:inherited-members:
StageChannel
~~~~~~~~~~~~~
.. attributetable:: StageChannel
.. autoclass:: StageChannel()
:members:
:inherited-members:
CategoryChannel
~~~~~~~~~~~~~~~~~
@ -3106,6 +2991,21 @@ RawReactionClearEmojiEvent
.. autoclass:: RawReactionClearEmojiEvent()
:members:
PartialWebhookGuild
~~~~~~~~~~~~~~~~~~~~
.. attributetable:: PartialWebhookGuild
.. autoclass:: PartialWebhookGuild()
:members:
PartialWebhookChannel
~~~~~~~~~~~~~~~~~~~~~~~
.. attributetable:: PartialWebhookChannel
.. autoclass:: PartialWebhookChannel()
:members:
.. _discord_api_data:

20
docs/conf.py
View File

@ -1,4 +1,3 @@
# -*- coding: utf-8 -*-
#
# discord.py documentation build configuration file, created by
# sphinx-quickstart on Fri Aug 21 05:43:30 2015.
@ -44,6 +43,7 @@ extensions = [
]
autodoc_member_order = 'bysource'
autodoc_typehints = 'none'
extlinks = {
'issue': ('https://github.com/Rapptz/discord.py/issues/%s', 'GH-'),
@ -76,8 +76,8 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'discord.py'
copyright = u'2015-2021, Rapptz'
project = 'discord.py'
copyright = '2015-present, Rapptz'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@ -160,7 +160,7 @@ resource_links = {
'discord': 'https://discord.gg/r3sSKJJ',
'issues': 'https://github.com/Rapptz/discord.py/issues',
'discussions': 'https://github.com/Rapptz/discord.py/discussions',
'examples': 'https://github.com/Rapptz/discord.py/tree/%s/examples' % branch,
'examples': f'https://github.com/Rapptz/discord.py/tree/{branch}/examples',
}
# Theme options are theme-specific and customize the look and feel of a theme
@ -283,8 +283,8 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'discord.py.tex', u'discord.py Documentation',
u'Rapptz', 'manual'),
('index', 'discord.py.tex', 'discord.py Documentation',
'Rapptz', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
@ -313,8 +313,8 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'discord.py', u'discord.py Documentation',
[u'Rapptz'], 1)
('index', 'discord.py', 'discord.py Documentation',
['Rapptz'], 1)
]
# If true, show URL addresses after external links.
@ -327,8 +327,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'discord.py', u'discord.py Documentation',
u'Rapptz', 'discord.py', 'One line description of project.',
('index', 'discord.py', 'discord.py Documentation',
'Rapptz', 'discord.py', 'One line description of project.',
'Miscellaneous'),
]

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

@ -281,18 +281,27 @@ Converters
.. autoclass:: discord.ext.commands.MessageConverter
:members:
.. autoclass:: discord.ext.commands.PartialMessageConverter
:members:
.. autoclass:: discord.ext.commands.TextChannelConverter
:members:
.. autoclass:: discord.ext.commands.VoiceChannelConverter
:members:
.. autoclass:: discord.ext.commands.StoreChannelConverter
:members:
.. autoclass:: discord.ext.commands.CategoryChannelConverter
:members:
.. autoclass:: discord.ext.commands.InviteConverter
:members:
.. autoclass:: discord.ext.commands.GuildConverter
:members:
.. autoclass:: discord.ext.commands.RoleConverter
:members:
@ -407,6 +416,9 @@ Exceptions
.. autoexception:: discord.ext.commands.MemberNotFound
:members:
.. autoexception:: discord.ext.commands.GuildNotFound
:members:
.. autoexception:: discord.ext.commands.UserNotFound
:members:

27
docs/ext/commands/commands.rst
View File

@ -193,6 +193,8 @@ Converters come in a few flavours:
- A custom class that inherits from :class:`~ext.commands.Converter`.
.. _ext_commands_basic_converters:
Basic Converters
++++++++++++++++++
@ -373,16 +375,19 @@ A lot of discord models work out of the gate as a parameter:
- :class:`Member`
- :class:`User`
- :class:`Message` (since v1.1)
- :class:`PartialMessage` (since v1.7)
- :class:`TextChannel`
- :class:`VoiceChannel`
- :class:`StoreChannel` (since v1.7)
- :class:`CategoryChannel`
- :class:`Role`
- :class:`Message` (since v1.1)
- :class:`Invite`
- :class:`Guild` (since v1.7)
- :class:`Role`
- :class:`Game`
- :class:`Colour`
- :class:`Emoji`
- :class:`PartialEmoji`
- :class:`Colour`
Having any of these set as the converter will intelligently convert the argument to the appropriate target type you
specify.
@ -395,28 +400,34 @@ converter is given below:
+--------------------------+-------------------------------------------------+
| :class:`Member` | :class:`~ext.commands.MemberConverter` |
+--------------------------+-------------------------------------------------+
| :class:`User` | :class:`~ext.commands.UserConverter` |
+--------------------------+-------------------------------------------------+
| :class:`Message` | :class:`~ext.commands.MessageConverter` |
+--------------------------+-------------------------------------------------+
| :class:`User` | :class:`~ext.commands.UserConverter` |
| :class:`PartialMessage` | :class:`~ext.commands.PartialMessageConverter` |
+--------------------------+-------------------------------------------------+
| :class:`TextChannel` | :class:`~ext.commands.TextChannelConverter` |
+--------------------------+-------------------------------------------------+
| :class:`VoiceChannel` | :class:`~ext.commands.VoiceChannelConverter` |
+--------------------------+-------------------------------------------------+
| :class:`CategoryChannel` | :class:`~ext.commands.CategoryChannelConverter` |
| :class:`StoreChannel` | :class:`~ext.commands.StoreChannelConverter` |
+--------------------------+-------------------------------------------------+
| :class:`Role` | :class:`~ext.commands.RoleConverter` |
| :class:`CategoryChannel` | :class:`~ext.commands.CategoryChannelConverter` |
+--------------------------+-------------------------------------------------+
| :class:`Invite` | :class:`~ext.commands.InviteConverter` |
+--------------------------+-------------------------------------------------+
| :class:`Guild` | :class:`~ext.commands.GuildConverter` |
+--------------------------+-------------------------------------------------+
| :class:`Role` | :class:`~ext.commands.RoleConverter` |
+--------------------------+-------------------------------------------------+
| :class:`Game` | :class:`~ext.commands.GameConverter` |
+--------------------------+-------------------------------------------------+
| :class:`Colour` | :class:`~ext.commands.ColourConverter` |
+--------------------------+-------------------------------------------------+
| :class:`Emoji` | :class:`~ext.commands.EmojiConverter` |
+--------------------------+-------------------------------------------------+
| :class:`PartialEmoji` | :class:`~ext.commands.PartialEmojiConverter` |
+--------------------------+-------------------------------------------------+
| :class:`Colour` | :class:`~ext.commands.ColourConverter` |
+--------------------------+-------------------------------------------------+
By providing the converter it allows us to use them as building blocks for another converter:

1
docs/ext/tasks/index.rst
View File

@ -139,5 +139,6 @@ API Reference
.. autoclass:: discord.ext.tasks.Loop()
:members:
:special-members: __call__
.. autofunction:: discord.ext.tasks.loop

6
docs/extensions/builder.py
View File

@ -58,11 +58,13 @@ def add_custom_jinja2(app):
def add_builders(app):
"""This is necessary because RTD injects their own for some reason."""
app.set_translator('html', DPYHTML5Translator, override=True)
app.add_builder(DPYStandaloneHTMLBuilder, override=True)
try:
original = app.registry.builders['readthedocs']
except KeyError:
app.set_translator('html', DPYHTML5Translator, override=True)
app.add_builder(DPYStandaloneHTMLBuilder, override=True)
pass
else:
injected_mro = tuple(base if base is not StandaloneHTMLBuilder else DPYStandaloneHTMLBuilder
for base in original.mro()[1:])

15
docs/faq.rst
View File

@ -85,8 +85,15 @@ in the repository.
How do I set the "Playing" status?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There is a method for this under :class:`Client` called :meth:`Client.change_presence`.
The relevant aspect of this is its ``activity`` keyword argument which takes in an :class:`Activity` object.
The ``activity`` keyword argument may be passed in the :class:`Client` constructor or :meth:`Client.change_presence`, given an :class:`Activity` object.
The constructor may be used for static activities, while :meth:`Client.change_presence` may be used to update the activity at runtime.
.. warning::
It is highly discouraged to use :meth:`Client.change_presence` or API calls in :func:`on_ready` as this event may be called many times while running, not just once.
There is a high chance of disconnecting if presences are changed right after connecting.
The status type (playing, listening, streaming, watching) can be set using the :class:`ActivityType` enum.
For memory optimisation purposes, some activities are offered in slimmed down versions:
@ -96,11 +103,11 @@ For memory optimisation purposes, some activities are offered in slimmed down ve
Putting both of these pieces of info together, you get the following: ::
await client.change_presence(activity=discord.Game(name='my game'))
client = discord.Client(activity=discord.Game(name='my game'))
# or, for watching:
activity = discord.Activity(name='my activity', type=discord.ActivityType.watching)
await client.change_presence(activity=activity)
client = discord.Client(activity=activity)
How do I send a message to a specific channel?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

30
docs/intents.rst
View File

@ -5,7 +5,7 @@
A Primer to Gateway Intents
=============================
In version 1.5 comes the introduction of :class:`Intents`. This is a radical change in how bots are written. An intent basically allows a bot to subscribe into specific buckets of events. The events that correspond to each intent is documented in the individual attribute of the :class:`Intents` documentation.
In version 1.5 comes the introduction of :class:`Intents`. This is a radical change in how bots are written. An intent basically allows a bot to subscribe to specific buckets of events. The events that correspond to each intent is documented in the individual attribute of the :class:`Intents` documentation.
These intents are passed to the constructor of :class:`Client` or its subclasses (:class:`AutoShardedClient`, :class:`~.AutoShardedBot`, :class:`~.Bot`) with the ``intents`` argument.
@ -118,9 +118,10 @@ It should be noted that certain things do not need a member cache since Discord
- :func:`on_message` will have :attr:`Message.author` be a member even if cache is disabled.
- :func:`on_voice_state_update` will have the ``member`` parameter be a member even if cache is disabled.
- :func:`on_reaction_add` will have the ``user`` parameter be a member even if cache is disabled.
- :func:`on_raw_reaction_add` will have :attr:`RawReactionActionEvent.member` be a member even if cache is disabled.
- The reaction removal events do not have the member information. This is a Discord limitation.
- :func:`on_reaction_add` will have the ``user`` parameter be a member when in a guild even if cache is disabled.
- :func:`on_raw_reaction_add` will have :attr:`RawReactionActionEvent.member` be a member when in a guild even if cache is disabled.
- The reaction add events do not contain additional information when in direct messages. This is a Discord limitation.
- The reaction removal events do not have member information. This is a Discord limitation.
Other events that take a :class:`Member` will require the use of the member cache. If absolute accuracy over the member cache is desirable, then it is advisable to have the :attr:`Intents.members` intent enabled.
@ -129,7 +130,7 @@ Other events that take a :class:`Member` will require the use of the member cach
Retrieving Members
--------------------
If cache is disabled or you disable chunking guilds at startup, we might still need a way to load members. The library offers a few ways to do this:
If the cache is disabled or you disable chunking guilds at startup, we might still need a way to load members. The library offers a few ways to do this:
- :meth:`Guild.query_members`
- Used to query members by a prefix matching nickname or username.
@ -180,27 +181,10 @@ The first solution is to request the privileged presences intent along with the
The second solution is to disable member chunking by setting ``chunk_guilds_at_startup`` to ``False`` when constructing a client. Then, when chunking for a guild is necessary you can use the various techniques to :ref:`retrieve members <retrieving_members>`.
To illustrate the slowdown caused the API change, take a bot who is in 840 guilds and 95 of these guilds are "large" (over 250 members).
To illustrate the slowdown caused by the API change, take a bot who is in 840 guilds and 95 of these guilds are "large" (over 250 members).
Under the original system this would result in 2 requests to fetch the member list (75 guilds, 20 guilds) roughly taking 60 seconds. With :attr:`Intents.members` but not :attr:`Intents.presences` this requires 840 requests, with a rate limit of 120 requests per 60 seconds means that due to waiting for the rate limit it totals to around 7 minutes of waiting for the rate limit to fetch all the members. With both :attr:`Intents.members` and :attr:`Intents.presences` we mostly get the old behaviour so we're only required to request for the 95 guilds that are large, this is slightly less than our rate limit so it's close to the original timing to fetch the member list.
Unfortunately due to this change being required from Discord there is nothing that the library can do to mitigate this.
I don't like this, can I go back?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For now, the old gateway will still work so downgrading to discord.py v1.4 is still possible and will continue to be supported until Discord officially kills the v6 gateway, which is imminent. However it is paramount that for the future of your bot that you upgrade your code to the new way things are done.
To downgrade you can do the following:
.. code-block:: python3
python3 -m pip install -U "discord.py>=1.4,<1.5"
On Windows use ``py -3`` instead of ``python3``.
.. warning::
There is no currently set date in which the old gateway will stop working so it is recommended to update your code instead.
If you truly dislike the direction Discord is going with their API, you can contact them via `support <https://dis.gd/contact>`_.

3
docs/locale/ja/LC_MESSAGES/intents.po
View File

@ -1,5 +1,5 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2015-2020, Rapptz
# Copyright (C) 2015-present, Rapptz
# This file is distributed under the same license as the discord.py package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2020.
#
@ -427,4 +427,3 @@ msgid ""
"If you truly dislike the direction Discord is going with their API, you "
"can contact them via `support <https://dis.gd/contact>`_"
msgstr ""

177
docs/whats_new.rst
View File

@ -11,6 +11,97 @@ Changelog
This page keeps a detailed human friendly rendering of what's new and changed
in specific versions.
.. _vp1p7p1:
v1.7.1
-------
Bug Fixes
~~~~~~~~~~~
- |commands| Fix :meth:`Cog.has_error_handler <ext.commands.Cog.has_error_handler>` not working as intended.
.. _vp1p7p0:
v1.7.0
--------
This version is mainly for improvements and bug fixes. This is more than likely the last major version in the 1.x series.
Work after this will be spent on v2.0. As a result, **this is the last version to support Python 3.5**.
Likewise, **this is the last version to support user bots**.
Development of v2.0 will have breaking changes and support for newer API features.
- Add support for stage channels via :class:`StageChannel` (:issue:`6602`, :issue:`6608`)
- Add support for :attr:`MessageReference.fail_if_not_exists` (:issue:`6484`)
- By default, if the message you're replying to doesn't exist then the API errors out.
This attribute tells the Discord API that it's okay for that message to be missing.
- Add support for Discord's new permission serialisation scheme.
- Add an easier way to move channels using :meth:`abc.GuildChannel.move`
- Add :attr:`Permissions.use_slash_commands`
- Add :attr:`Permissions.request_to_speak`
- Add support for voice regions in voice channels via :attr:`VoiceChannel.rtc_region` (:issue:`6606`)
- Add support for :meth:`PartialEmoji.url_as` (:issue:`6341`)
- Add :attr:`MessageReference.jump_url` (:issue:`6318`)
- Add :attr:`File.spoiler` (:issue:`6317`)
- Add support for passing ``roles`` to :meth:`Guild.estimate_pruned_members` (:issue:`6538`)
- Allow callable class factories to be used in :meth:`abc.Connectable.play` (:issue:`6478`)
- Add a way to get mutual guilds from the client's cache via :attr:`User.mutual_guilds` (:issue:`2539`, :issue:`6444`)
- :meth:`PartialMessage.edit` now returns a full :class:`Message` upon success (:issue:`6309`)
- Add :attr:`RawMessageUpdateEvent.guild_id` (:issue:`6489`)
- :class:`AuditLogEntry` is now hashable (:issue:`6495`)
- :class:`Attachment` is now hashable
- Add :attr:`Attachment.content_type` attribute (:issue:`6618`)
- Add support for casting :class:`Attachment` to :class:`str` to get the URL.
- Add ``seed`` parameter for :class:`Colour.random` (:issue:`6562`)
- This only seeds it for one call. If seeding for multiple calls is desirable, use :func:`random.seed`.
- Add a :func:`utils.remove_markdown` helper function (:issue:`6573`)
- Add support for passing scopes to :func:`utils.oauth_url` (:issue:`6568`)
- |commands| Add support for ``rgb`` CSS function as a parameter to :class:`ColourConverter <ext.commands.ColourConverter>` (:issue:`6374`)
- |commands| Add support for converting :class:`StoreChannel` via :class:`StoreChannelConverter <ext.commands.StoreChannelConverter>` (:issue:`6603`)
- |commands| Add support for stripping whitespace after the prefix is encountered using the ``strip_after_prefix`` :class:`~ext.commands.Bot` constructor parameter.
- |commands| Add :attr:`Context.invoked_parents <ext.commands.Context.invoked_parents>` to get the aliases a command's parent was invoked with (:issue:`1874`, :issue:`6462`)
- |commands| Add a converter for :class:`PartialMessage` under :class:`ext.commands.PartialMessageConverter` (:issue:`6308`)
- |commands| Add a converter for :class:`Guild` under :class:`ext.commands.GuildConverter` (:issue:`6016`, :issue:`6365`)
- |commands| Add :meth:`Command.has_error_handler <ext.commands.Command.has_error_handler>`
- This is also adds :meth:`Cog.has_error_handler <ext.commands.Cog.has_error_handler>`
- |commands| Allow callable types to act as a bucket key for cooldowns (:issue:`6563`)
- |commands| Add ``linesep`` keyword argument to :class:`Paginator <ext.commands.Paginator>` (:issue:`5975`)
- |commands| Allow ``None`` to be passed to :attr:`HelpCommand.verify_checks <ext.commands.HelpCommand.verify_checks>` to only verify in a guild context (:issue:`2008`, :issue:`6446`)
- |commands| Allow relative paths when loading extensions via a ``package`` keyword argument (:issue:`2465`, :issue:`6445`)
Bug Fixes
~~~~~~~~~~
- Fix mentions not working if ``mention_author`` is passed in :meth:`abc.Messageable.send` without :attr:`Client.allowed_mentions` set (:issue:`6192`, :issue:`6458`)
- Fix user created instances of :class:`CustomActivity` triggering an error (:issue:`4049`)
- Note that currently, bot users still cannot set a custom activity due to a Discord limitation.
- Fix :exc:`ZeroDivisionError` being raised from :attr:`VoiceClient.average_latency` (:issue:`6430`, :issue:`6436`)
- Fix :attr:`User.public_flags` not updating upon edit (:issue:`6315`)
- Fix :attr:`Message.call` sometimes causing attribute errors (:issue:`6390`)
- Fix issue resending a file during request retries on newer versions of ``aiohttp`` (:issue:`6531`)
- Raise an error when ``user_ids`` is empty in :meth:`Guild.query_members`
- Fix ``__str__`` magic method raising when a :class:`Guild` is unavailable.
- Fix potential :exc:`AttributeError` when accessing :attr:`VoiceChannel.members` (:issue:`6602`)
- :class:`Embed` constructor parameters now implicitly convert to :class:`str` (:issue:`6574`)
- Ensure ``discord`` package is only run if executed as a script (:issue:`6483`)
- |commands| Fix irrelevant commands potentially being unloaded during cog unload due to failure.
- |commands| Fix attribute errors when setting a cog to :class:`~.ext.commands.HelpCommand` (:issue:`5154`)
- |commands| Fix :attr:`Context.invoked_with <ext.commands.Context.invoked_with>` being improperly reassigned during a :meth:`~ext.commands.Context.reinvoke` (:issue:`6451`, :issue:`6462`)
- |commands| Remove duplicates from :meth:`HelpCommand.get_bot_mapping <ext.commands.HelpCommand.get_bot_mapping>` (:issue:`6316`)
- |commands| Properly handle positional-only parameters in bot command signatures (:issue:`6431`)
- |commands| Group signatures now properly show up in :attr:`Command.signature <ext.commands.Command.signature>` (:issue:`6529`, :issue:`6530`)
Miscellaneous
~~~~~~~~~~~~~~
- User endpoints and all userbot related functionality has been deprecated and will be removed in the next major version of the library.
- :class:`Permission` class methods were updated to match the UI of the Discord client (:issue:`6476`)
- ``_`` and ``-`` characters are now stripped when making a new cog using the ``discord`` package (:issue:`6313`)
.. _vp1p6p0p7:
v1.6.0.7
@ -24,49 +115,6 @@ New Features
- Add ``silent`` kwargs to :meth:`Message.delete`
- Add :meth:`Client.get_message`
.. _vp1p5p1p6:
v1.5.1.6
--------
New Features
~~~~~~~~~~~~~~
- Add :meth:`Colour.random`
.. _vp1p5p1p5:
v1.5.1.5
--------
New Features
~~~~~~~~~~~~~~
- Add :meth:`Colour.nitro_booster`
- Add :attr:`Permissions.admin` as alias to :attr:`Permissions.administrator`
New Beta Features
~~~~~~~~~~~~~~~~~~~
These are all for message replies. I have added them to 1.5.1.5 but they will most likely officially get added in the original lib in 1.6 or 2.0
- |commands| Add :meth:`Context.reply <ext.commands.Context>`
- Add :meth:`Message.reply`
- Add ``replied_user`` to :class:`AllowedMentions`
- Add :meth:`MessageReference.to_dict`
- Add :meth:`MessageReference.from_message`
- Add ``message_reference`` kwarg to :meth:`abc.Messageable.send`
.. _vp1p5p1p4:
v1.5.1.4
--------
New Features
~~~~~~~~~~~~~~
- |commands| Add :attr:`Context.clean_prefix <ext.commands.Context>`
.. _vp1p6p0:
v1.6.0
@ -139,6 +187,49 @@ Miscellaneous
- |commands| :class:`UserConverter <ext.commands.UserConverter>` now fetches the API if an ID is passed and the user is not cached.
- |commands| :func:`max_concurrency <ext.commands.max_concurrency>` is now called before cooldowns (:issue:`6172`)
.. _vp1p5p1p6:
v1.5.1.6
--------
New Features
~~~~~~~~~~~~~~
- Add :meth:`Colour.random`
.. _vp1p5p1p5:
v1.5.1.5
--------
New Features
~~~~~~~~~~~~~~
- Add :meth:`Colour.nitro_booster`
- Add :attr:`Permissions.admin` as alias to :attr:`Permissions.administrator`
New Beta Features
~~~~~~~~~~~~~~~~~~~
These are all for message replies. I have added them to 1.5.1.5 but they will most likely officially get added in the original lib in 1.6 or 2.0
- |commands| Add :meth:`Context.reply <ext.commands.Context>`
- Add :meth:`Message.reply`
- Add ``replied_user`` to :class:`AllowedMentions`
- Add :meth:`MessageReference.to_dict`
- Add :meth:`MessageReference.from_message`
- Add ``message_reference`` kwarg to :meth:`abc.Messageable.send`
.. _vp1p5p1p4:
v1.5.1.4
--------
New Features
~~~~~~~~~~~~~~
- |commands| Add :attr:`Context.clean_prefix <ext.commands.Context>`
.. _vp1p5p1:
v1.5.1