@ -291,628 +291,125 @@ Connection
or Discord terminating the connection one way or the other.
This function can be called many times without a corresponding :func: `on_connect` call.
<<<<<<< HEAD
.. function :: on_ready()
Called when the client is done preparing the data received from Discord. Usually after login is successful
and the :attr: `Client.guilds` and co. are filled up.
.. warning ::
This function is not guaranteed to be the first event called.
Likewise, this function is **not** guaranteed to only be called
once. This library implements reconnection logic and thus will
end up calling this event whenever a RESUME request fails.
.. function :: on_resumed()
Called when the client has resumed a session.
=======
.. function :: on_shard_connect(shard_id)
Similar to :func: `on_connect` except used by :class: `AutoShardedClient`
to denote when a particular shard ID has connected to Discord.
.. versionadded :: 1.4
:param shard_id: The shard ID that has connected.
:type shard_id: :class:`int`
.. function :: on_shard_disconnect(shard_id)
Similar to :func: `on_disconnect` except used by :class: `AutoShardedClient`
to denote when a particular shard ID has disconnected from Discord.
.. versionadded :: 1.4
:param shard_id: The shard ID that has disconnected.
:type shard_id: :class:`int`
Debug
~~~~~~
>>>>>>> upstream/master
.. 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
change this behaviour and handle the exception for whatever reason
yourself, this event can be overridden. Which, when done, will
suppress the default action of printing the traceback.
The information of the exception raised and the exception itself can
be retrieved with a standard call to :func: `sys.exc_info` .
If you want exception to propagate out of the :class: `Client` class
you can define an `` on_error `` handler consisting of a single empty
:ref: `raise statement <py:raise>` . Exceptions raised by `` on_error `` will not be
handled in any way by :class: `Client` .
.. note ::
`` on_error `` will only be dispatched to :meth: `Client.event` .
It will not be received by :meth: `Client.wait_for` , or, if used,
:ref: `ext_commands_api_bot` listeners such as
:meth: `~ext.commands.Bot.listen` or :meth: `~ext.commands.Cog.listener` .
:param event: The name of the event that raised the exception.
:type event: :class:`str`
:param args: The positional arguments for the event that raised the
exception.
:param kwargs: The keyword arguments for the event that raised the
exception.
.. function :: on_socket_event_type(event_type)
Called whenever a websocket event is received from the WebSocket.
This is mainly useful for logging how many events you are receiving
from the Discord gateway.
.. versionadded :: 2.0
:param event_type: The event type from Discord that is received, e.g. ``'READY'``.
:type event_type: :class:`str`
.. function :: on_socket_raw_receive(msg)
Called whenever a message is completely received from the WebSocket, before
it's processed and parsed. This event is always dispatched when a
complete message is received and the passed data is not parsed in any way.
This is only really useful for grabbing the WebSocket stream and
debugging purposes.
This requires setting the `` enable_debug_events `` setting in the :class: `Client` .
.. note ::
This is only for the messages received from the client
WebSocket. The voice WebSocket will not trigger this event.
:param msg: The message passed in from the WebSocket library.
:type msg: :class:`str`
.. function :: on_socket_raw_send(payload)
Called whenever a send operation is done on the WebSocket before the
message is sent. The passed parameter is the message that is being
sent to the WebSocket.
This is only really useful for grabbing the WebSocket stream and
debugging purposes.
This requires setting the `` enable_debug_events `` setting in the :class: `Client` .
.. note ::
This is only for the messages sent from the client
WebSocket. The voice WebSocket will not trigger this event.
:param payload: The message that is about to be passed on to the
WebSocket library. It can be :class: `bytes` to denote a binary
message or :class: `str` to denote a regular text message.
Gateway
~~~~~~~~
<<<<<<< HEAD
The `` channel `` parameter can be a :class: `abc.Messageable` instance.
Which could either be :class: `TextChannel` , :class: `GroupChannel` , :class: `Thread` , or
:class: `DMChannel` .
If the `` channel `` is a :class: `TextChannel` or :class: `Thread` then the `` user `` parameter
is a :class: `Member` , otherwise it is a :class: `User` .
:param channel: The location where the typing originated from.
: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 an aware datetime in UTC.
:type when: :class:`datetime.datetime`
.. function :: on_message(message)
Called when a :class: `Message` is created and sent.
=======
.. function :: on_ready()
Called when the client is done preparing the data received from Discord. Usually after login is successful
and the :attr: `Client.guilds` and co. are filled up.
>>>>>>> upstream/master
.. warning ::
This function is not guaranteed to be the first event called.
Likewise, this function is **not** guaranteed to only be called
once. This library implements reconnection logic and thus will
end up calling this event whenever a RESUME request fails.
.. function :: on_resumed()
Called when the client has resumed a session.
.. function :: on_shard_ready(shard_id)
Similar to :func: `on_ready` except used by :class: `AutoShardedClient`
to denote when a particular shard ID has become ready.
<<<<<<< HEAD
=======
:param shard_id: The shard ID that is ready.
:type shard_id: :class:`int`
>>>>>>> upstream/master
.. function :: on_shard_resumed(shard_id)
<<<<<<< HEAD
Called when messages are bulk deleted. If none of the messages deleted
are found in the internal message cache, then this event will not be called.
If individual messages were not found in the internal message cache,
this event will still be called, but the messages not found will not be included in
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 :class: `max_messages <Client>` parameter
or use the :func: `on_raw_bulk_message_delete` event instead.
:param messages: The messages that have been deleted.
:type messages: List[:class:`Message`]
.. function :: on_raw_message_delete(payload)
Called when a message is deleted. Unlike :func: `on_message_delete` , this is
called regardless of the message being in the internal message cache or not.
If the message is found in the message cache,
it can be accessed via :attr: `RawMessageDeleteEvent.cached_message`
:param payload: The raw event payload data.
:type payload: :class:`RawMessageDeleteEvent`
.. function :: on_raw_bulk_message_delete(payload)
Called when a bulk delete is triggered. Unlike :func: `on_bulk_message_delete` , this is
called regardless of the messages being in the internal message cache or not.
If the messages are found in the message cache,
they can be accessed via :attr: `RawBulkMessageDeleteEvent.cached_messages`
:param payload: The raw event payload data.
:type payload: :class:`RawBulkMessageDeleteEvent`
.. function :: on_message_edit(before, after)
Called when a :class: `Message` receives an update event. If the message is not found
in the internal message cache, then these events will not be called.
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 :class: `max_messages <Client>` parameter
or use the :func: `on_raw_message_edit` event instead.
The following non-exhaustive cases trigger this event:
- A message has been pinned or unpinned.
- The message content has been changed.
- The message has received an embed.
- For performance reasons, the embed server does not do this in a "consistent" manner.
- The message's embeds were suppressed or unsuppressed.
- A call message has received an update to its participants or ending time.
:param before: The previous version of the message.
:type before: :class:`Message`
:param after: The current version of the message.
:type after: :class:`Message`
.. function :: on_raw_message_edit(payload)
Called when a message is edited. Unlike :func: `on_message_edit` , this is called
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` . 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> `_ .
Since the data payload can be partial, care must be taken when accessing stuff in the dictionary.
One example of a common case of partial data is when the `` 'content' `` key is inaccessible. This
denotes an "embed" only edit, which is an edit in which only the embeds are updated by the Discord
embed server.
:param payload: The raw event payload data.
:type payload: :class:`RawMessageUpdateEvent`
.. function :: on_reaction_add(reaction, user)
Called when a message has a reaction added to it. Similar to :func: `on_message_edit` ,
if the message is not found in the internal message cache, then this
event will not be called. Consider using :func: `on_raw_reaction_add` instead.
.. note ::
To get the :class: `Message` being reacted, access it via :attr: `Reaction.message` .
..
todo: check this out
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.
:type user: Union[:class:`Member`, :class:`User`]
.. function :: on_raw_reaction_add(payload)
Called when a message has a reaction added. Unlike :func: `on_reaction_add` , this is
called regardless of the state of the internal message cache.
:param payload: The raw event payload data.
:type payload: :class:`RawReactionActionEvent`
.. function :: on_reaction_remove(reaction, user)
Called when a message has a reaction removed from it. Similar to on_message_edit,
if the message is not found in the internal message cache, then this event
will not be called.
.. note ::
To get the message being reacted, access it via :attr: `Reaction.message` .
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`
:param user: The user who added the reaction.
:type user: Union[:class:`Member`, :class:`User`]
.. function :: on_raw_reaction_remove(payload)
Called when a message has a reaction removed. Unlike :func: `on_reaction_remove` , this is
called regardless of the state of the internal message cache.
:param payload: The raw event payload data.
:type payload: :class:`RawReactionActionEvent`
.. function :: on_reaction_clear(message, reactions)
Called when a message has all its reactions removed from it. Similar to :func: `on_message_edit` ,
if the message is not found in the internal message cache, then this event
will not be called. Consider using :func: `on_raw_reaction_clear` instead.
:param message: The message that had its reactions cleared.
:type message: :class:`Message`
:param reactions: The reactions that were removed.
:type reactions: List[:class:`Reaction`]
.. function :: on_raw_reaction_clear(payload)
Called when a message has all its reactions removed. Unlike :func: `on_reaction_clear` ,
this is called regardless of the state of the internal message cache.
:param payload: The raw event payload data.
:type payload: :class:`RawReactionClearEvent`
.. function :: on_reaction_clear_emoji(reaction)
Called when a message has a specific reaction removed from it. Similar to :func: `on_message_edit` ,
if the message is not found in the internal message cache, then this event
will not be called. Consider using :func: `on_raw_reaction_clear_emoji` instead.
.. versionadded :: 1.3
:param reaction: The reaction that got cleared.
:type reaction: :class:`Reaction`
.. function :: on_raw_reaction_clear_emoji(payload)
Called when a message has a specific reaction removed from it. Unlike :func: `on_reaction_clear_emoji` this is called
regardless of the state of the internal message cache.
.. versionadded :: 1.3
:param payload: The raw event payload data.
:type payload: :class:`RawReactionClearEmojiEvent`
.. function :: on_private_channel_update(before, after)
Called whenever a private group DM is updated. e.g. changed name or topic.
:param before: The updated group channel's old info.
:type before: :class:`GroupChannel`
:param after: The updated group channel's new info.
:type after: :class:`GroupChannel`
.. function :: on_private_channel_pins_update(channel, last_pin)
Called whenever a message is pinned or unpinned from a private channel.
: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 an aware datetime in UTC. Could be ``None``.
:type last_pin: Optional[:class:`datetime.datetime`]
.. function :: on_guild_channel_delete(channel)
on_guild_channel_create(channel)
Called whenever a guild channel is deleted or created.
Note that you can get the guild from :attr: `~abc.GuildChannel.guild` .
:param channel: The guild channel that got created or deleted.
:type channel: :class:`abc.GuildChannel`
.. function :: on_guild_channel_update(before, after)
Called whenever a guild channel is updated. e.g. changed name, topic, permissions.
:param before: The updated guild channel's old info.
:type before: :class:`abc.GuildChannel`
:param after: The updated guild channel's new info.
:type after: :class:`abc.GuildChannel`
.. function :: on_guild_channel_pins_update(channel, last_pin)
Called whenever a message is pinned or unpinned from a guild channel.
:param channel: The guild channel that had its pins updated.
:type channel: Union[:class:`abc.GuildChannel`, :class:`Thread`]
: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_thread_join(thread)
Called whenever a thread is joined or created. Note that from the API's perspective there is no way to
differentiate between a thread being created or the bot joining a thread.
Note that you can get the guild from :attr: `Thread.guild` .
.. versionadded :: 2.0
:param thread: The thread that got joined.
:type thread: :class:`Thread`
.. function :: on_thread_remove(thread)
Called whenever a thread is removed. This is different from a thread being deleted.
Note that you can get the guild from :attr: `Thread.guild` .
.. warning ::
Due to technical limitations, this event might not be called
as soon as one expects. Since the library tracks thread membership
locally, the API only sends updated thread membership status upon being
synced by joining a thread.
.. versionadded :: 2.0
:param thread: The thread that got removed.
:type thread: :class:`Thread`
.. function :: on_thread_delete(thread)
Called whenever a thread is deleted.
Note that you can get the guild from :attr: `Thread.guild` .
.. versionadded :: 2.0
:param thread: The thread that got deleted.
:type thread: :class:`Thread`
.. function :: on_thread_member_join(member)
on_thread_member_remove(member)
Called when a :class: `ThreadMember` leaves or joins a :class: `Thread` .
You can get the thread a member belongs in by accessing :attr: `ThreadMember.thread` .
.. versionadded :: 2.0
:param member: The member who joined or left.
:type member: :class:`ThreadMember`
.. function :: on_thread_update(before, after)
Called whenever a thread is updated.
.. versionadded :: 2.0
:param before: The updated thread's old info.
:type before: :class:`Thread`
:param after: The updated thread's new info.
:type after: :class:`Thread`
.. function :: on_guild_integrations_update(guild)
Called whenever an integration is created, modified, or removed from a guild.
=======
Similar to :func: `on_resumed` except used by :class: `AutoShardedClient`
to denote when a particular shard ID has resumed a session.
>>>>>>> upstream/master
Debug
~~~~~~
.. versionadded :: 1.4
.. function :: on_error(event, *args, * *kwargs)
:param shard_id: The shard ID that has resumed.
:type shard_id: :class:`int`
Usually when an event raises an uncaught exception, a traceback is
printed to stderr and the exception is ignored. If you want to
change this behaviour and handle the exception for whatever reason
yourself, this event can be overridden. Which, when done, will
suppress the default action of printing the traceback.
Guilds
~~~~~~~
The information of the exception raised and the exception itself can
be retrieved with a standard call to :func: `sys.exc_info` .
.. function :: on_guild_available(guild)
on_guild_unavailable(guild)
If you want exception to propagate out of the :class: `Client` class
you can define an `` on_error `` handler consisting of a single empty
:ref: `raise statement <py:raise>` . Exceptions raised by `` on_error `` will not be
handled in any way by :class: `Client` .
<<<<<<< HEAD
.. versionadded :: 2.0
.. note ::
:param integration: The integration that was created.
:type integration: :class:`Integration`
`` on_error `` will only be dispatched to :meth: `Client.event` .
.. function :: on_integration_update(integration)
It will not be received by :meth: `Client.wait_for` , or, if used,
:ref: `ext_commands_api_bot` listeners such as
:meth: `~ext.commands.Bot.listen` or :meth: `~ext.commands.Cog.listener` .
Called when an integration is updated.
:param event: The name of the event that raised the exception.
:type event: :class:`str`
.. versionadded :: 2.0
:param args: The positional arguments for the event that raised the
exception.
:param kwargs: The keyword arguments for the event that raised the
exception.
:param integration: The integration that was created.
:type integration: :class:`Integration`
.. function :: on_socket_event_type(event_type)
.. function :: on_raw_integration_delete(payload)
Called whenever a websocket event is received from the WebSocket.
Called when an integration is deleted.
This is mainly useful for logging how many events you are receiving
from the Discord gateway.
.. versionadded :: 2.0
:param payload: The raw event payload data.
:type payload: :class:`RawIntegrationDeleteEvent`
.. function :: on_webhooks_update(channel)
Called whenever a webhook is created, modified, or removed from a guild channel.
:param channel: The channel that had its webhooks updated.
:type channel: :class:`abc.GuildChannel`
.. function :: on_member_join(member)
on_member_remove(member)
:param event_type: The event type from Discord that is received, e.g. ``'READY'``.
:type event_type: :class:`str`
.. function :: on_socket_raw_receive(msg)
Called when a :class: `Member` leaves or joins a :class: `Guild` .
Called whenever a message is completely received from the WebSocket, before
it's processed and parsed. This event is always dispatched when a
complete message is received and the passed data is not parsed in any way.
:param member: The member who joined or left.
:type member: :class:`Member`
This is only really useful for grabbing the WebSocket stream and
debugging purposes.
.. function :: on_member_update(before, after)
This requires setting the `` enable_debug_events `` setting in the :class: `Client` .
Called when a :class: `Member` updates their profile.
.. note ::
This is called when one or more of the following things change:
This is only for the messages received from the client
WebSocket. The voice WebSocket will not trigger this event.
- nickname
- roles
- pending
:param msg: The message passed in from the WebSocket library.
:type msg: :class:`str`
.. function :: on_socket_raw_send(payload)
Called whenever a send operation is done on the WebSocket before the
message is sent. The passed parameter is the message that is being
sent to the WebSocket.
:param before: The updated member's old info.
:type before: :class:`Member`
:param after: The updated member's updated info.
:type after: :class:`Member`
This is only really useful for grabbing the WebSocket stream and
debugging purposes.
.. function :: on_presence_update(before, after)
This requires setting the `` enable_debug_events `` setting in the :class: `Client` .
Called when a :class: `Member` updates their presence.
.. note ::
This is called when one or more of the following things change:
This is only for the messages sent from the client
WebSocket. The voice WebSocket will not trigger this event.
- status
- activity
:param payload: The message that is about to be passed on to the
WebSocket library. It can be :class: `bytes` to denote a binary
message or :class: `str` to denote a regular text message.
Gateway
~~~~~~~~
.. versionadded :: 2.0
.. function :: on_ready()
:param before: The updated member's old info.
:type before: :class:`Member`
:param after: The updated member's updated info.
:type after: :class:`Member`
Called when the client is done preparing the data received from Discord. Usually after login is successful
and the :attr: `Client.guilds` and co. are filled up.
.. function :: on_user_update(before, after)
.. warning ::
Called when a :class: `User` updates their profile.
This function is not guaranteed to be the first event called.
Likewise, this function is **not** guaranteed to only be called
once. This library implements reconnection logic and thus will
end up calling this event whenever a RESUME request fails.
This is called when one or more of the following things change:
.. function :: on_resumed()
- avatar
- username
- discriminator
Called when the client has resumed a session.
Guilds
~~~~~~~
.. function :: on_guild_available(guild)
on_guild_unavailable(guild)
:param before: The updated user's old info.
:type before: :class:`User`
:param after: The updated user's updated info.
:type after: :class:`User`
=======
Called when a guild becomes available or unavailable. The guild must have
existed in the :attr: `Client.guilds` cache.
This requires :attr: `Intents.guilds` to be enabled.
:param guild: The :class:`Guild` that has changed availability.
>>>>>>> upstream/master
.. function :: on_guild_join(guild)
@ -959,32 +456,6 @@ Guilds
:param after: The guild after being updated.
:type after: :class:`Guild`
<<<<<<< HEAD
.. function :: on_guild_role_create(role)
on_guild_role_delete(role)
Called when a :class: `Guild` creates or deletes a new :class: `Role` .
To get the guild it belongs to, use :attr: `Role.guild` .
:param role: The role that was created or deleted.
:type role: :class:`Role`
.. function :: on_guild_role_update(before, after)
Called when a :class: `Role` is changed guild-wide.
:param before: The updated role's old info.
:type before: :class:`Role`
:param after: The updated role's updated info.
:type after: :class:`Role`
=======
>>>>>>> upstream/master
.. function :: on_guild_emojis_update(guild, before, after)
Called when a :class: `Guild` adds or removes :class: `Emoji` .
@ -1493,10 +964,6 @@ Roles
:param after: The updated role's updated info.
:type after: :class:`Role`
<<<<<<< HEAD
=======
>>>>>>> upstream/master
Scheduled Events
~~~~~~~~~~~~~~~~~
@ -1552,12 +1019,8 @@ Scheduled Events
Stages
~~~~~~~
<<<<<<< HEAD
=======
.. function :: on_stage_instance_create(stage_instance)
on_stage_instance_delete(stage_instance)
>>>>>>> upstream/master
Called when a :class: `StageInstance` is created or deleted for a :class: `StageChannel` .
@ -1566,11 +1029,7 @@ Stages
:param stage_instance: The stage instance that was created or deleted.
:type stage_instance: :class:`StageInstance`
<<<<<<< HEAD
=======
.. function :: on_stage_instance_update(before, after)
>>>>>>> upstream/master
Called when a :class: `StageInstance` is updated.
@ -1589,15 +1048,29 @@ Stages
Threads
~~~~~~~~
<<<<<<< HEAD
<<<<<<< HEAD
=======
>>>>>>> upstream/master
=======
.. function :: on_thread_create(thread)
Called whenever a thread is created.
Note that you can get the guild from :attr: `Thread.guild` .
This requires :attr: `Intents.guilds` to be enabled.
.. versionadded :: 2.0
:param thread: The thread that was created.
:type thread: :class:`Thread`
>>>>>>> 95deb553328d4d1c3e8b6b50239b67c56c4576fa
.. function :: on_thread_join(thread)
Called whenever a thread is joined or created. Note that from the API's perspective there is no way to
differentiate between a thread being created or the bot joining a thread.
Called whenever a thread is joined.
Note that you can get the guild from :attr: `Thread.guild` .
@ -1800,6 +1273,12 @@ of :class:`enum.Enum`.
.. versionadded :: 2.0
.. attribute :: forum
A forum channel.
.. versionadded :: 2.0
.. class :: MessageType
Specifies the type of :class: `Message` . This is used to denote if a message
@ -4294,6 +3773,7 @@ TextChannel
.. automethod :: typing
:async-with:
<<<<<<< HEAD
ChannelSettings
~~~~~~~~~~~~~~~~
@ -4305,6 +3785,17 @@ ChannelSettings
:inherited-members:
=======
ForumChannel
~~~~~~~~~~~~~
.. attributetable :: ForumChannel
.. autoclass :: ForumChannel()
:members:
:inherited-members:
>>>>>>> 95deb553328d4d1c3e8b6b50239b67c56c4576fa
Thread
~~~~~~~~
@ -4638,6 +4129,15 @@ ApplicationFlags
.. autoclass :: ApplicationFlags
:members:
ChannelFlags
~~~~~~~~~~~~~~
.. attributetable :: ChannelFlags
.. autoclass :: ChannelFlags
:members:
File
~~~~~
dolfies
3 years ago