Melisa Module#

Client#

Attributes
Methods
class Client(token, *, asyncio_debug=False, intents=None, activity=None, status=None, mobile=False, allowed_mentions=None, logs='INFO', cache=None)[source]#

Bases: object

This is the main instance which is between the programmer and the Discord API. This Client represents your bot.

Parameters:

  • token (str) – The token to login (you can found it in the developer portal)

  • asyncio_debug (bool) – If True, then debugging is enabled for the asyncio event loop in use.

  • intents (Union[~melisa.Intents, Iterable[~melisa.Intents]]) – The Discord Intents values.

  • activity (BotActivity) – The Activity to set (on connecting)

  • status (str) – The Status to set (on connecting). Can be generated using StatusType

  • mobile (bool) – Set user device as mobile?

  • allowed_mentions (Optional[AllowedMentions]) – Controls the mentions being processed in every message.

  • logs (Optional[None, str, Dict[str, Any]]) – The hint for configuring logging. This can be None to disable logging automatically. If you pass a str or a int, it is interpreted as the global logging level to use, and should match one of DEBUG, INFO, WARNING, ERROR or CRITICAL, if str.

user#

The user object of the client

Type:

User

http#

HTTP client for the http-requests to the Discord API

Type:

HTTPClient

shards#

Bot’s shards.

Type:

Dict[int, Shard]

@listen[source]#

Method or Decorator to set the listener. :param callback: Coroutine Callback Function :type callback: melisa.utils.types.Coro

await dispatch(name, args)[source]#

Dispatches an event :param name: Name of the event to dispatch. :type name: str

await fetch_channel(channel_id)[source]#

Fetch Channel from the Discord API (by id).

Parameters:

channel_id (Union[Snowflake, str, int]) – Id of channel to fetch

await fetch_guild(guild_id)[source]#

Fetch Guild from the Discord API (by id).

Parameters:

guild_id (Union[Snowflake, str, int]) – Id of guild to fetch

await fetch_user(user_id)[source]#

Fetch User from the Discord API (by id).

Parameters:

user_id (Union[Snowflake, str, int]) – Id of user to fetch

run()[source]#

Run Bot without shards (only 0 shard)

run_autosharded()[source]#

Runs the bot with the amount of shards specified by the Discord gateway.

run_shards(num_shards, *, shard_ids=None)[source]#

Run Bot with shards specified by the user. :param num_shards: The endpoint to send the request to. :type num_shards: int :param shard_ids: List of Ids of shards to start. :type shard_ids: Optional[List[int]]

await wait_for(event_name, *, check=None, timeout=None)[source]#

This function is a coroutine. Waits for a WebSocket event to be dispatched. This could be used to wait for a user to reply to a message, or to react to a message. The timeout parameter is passed onto asyncio.wait_for(). By default, it does not timeout. Note that this does propagate the asyncio.TimeoutError for you in case of timeout and is provided for ease of use. In case the event returns multiple arguments, a tuple containing those arguments is returned instead. This function returns the first event that meets the requirements.

Examples

Waiting for a user reply:

@client.listen
async def on_message_create(message):
    if message.content.startswith('$greet'):
        channel = await client.fetch_channel(message.channel_id)
        await channel.send('Say hello!')
        def check(m):
            return m.content == "hello" and channel.id == message.channel_id
        msg = await client.wait_for('on_message_create', check=check, timeout=10.0)
        await channel.send(f'Hello man!')
Parameters:

  • event_name (str) – The type of event. It should starts with on_.

  • check (Optional[Callable[[Any], bool]]) – A predicate to check what to wait for. The arguments must meet the parameters of the event being waited for.

  • timeout (Optional[float]) – The number of seconds to wait before timing out and raising asyncio.TimeoutError.

Returns:

Returns no arguments, a single argument, or a tuple of multiple arguments that mirrors the parameters passed in the event.

Return type:

Any

RESTApp#

Attributes
Methods
class RESTApp(token, default_image_format=None)[source]#

Bases: object

This instance may be used to send http requests to the Discord REST API.

It will not cache anything.

Parameters:

  • token (str) – The token to authorize (you can found it in the developer portal)

  • default_image_format (str) – Default image format

cdn#

CDN Builder to build images

Type:

CDNBuilder

await add_guild_member_role(guild_id, user_id, role_id, *, reason=None)[source]#

This function is a coroutine.

[REST API] Adds a role to a guild member.

Required permissions: MANAGE_ROLES

Parameters:

  • guild_id (Union[int, str, Snowflake]) – Id of guild where we will give member role

  • user_id (Union[int, str, Snowflake]) – Id of user to operate with.

  • role_id (Optional[int]) – Id of role to give.

  • reason (Optional[str]) – The reason of the action.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong guild, user or something else

await bulk_overwrite_global_application_commands(application_id, commands)[source]#

This function is a coroutine.

[REST API] Overwrites all existing global commands.

Parameters:

  • application_id (Snowflake) – ID of the parent application

  • commands (List[Union[SlashCommand,) –

:param PartialApplicationCommand]]:

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong arguments

await create_global_application_command(application_id, command_type, name, description=None, *, options=None, default_member_permissions=None, dm_permission=None, default_permission=None)[source]#

This function is a coroutine.

[REST API] Create a new global command.

Parameters:

  • application_id (Snowflake) – ID of the parent application

  • command_type (Optional[ApplicationCommandType]) – Type of command, defaults to 1

  • name (LocalizedField) – Name of command, 1-32 characters

  • description (Optional[LocalizedField]) – Description for CHAT_INPUT commands, 1-100 characters. Empty string for USER and MESSAGE commands

  • options (Optional[List[SlashCommandOption]]) – Parameters for the command, max of 25. Only available for CHAT_INPUT command type.

  • default_member_permissions (Optional[str]) – Set of permissions represented as a bit set

  • dm_permission (Optional[bool]) – Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible.

  • default_permission (Optional[bool]) – Not recommended for use as field will soon be deprecated. Indicates whether the command is enabled by default when the app is added to a guild, defaults to True

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong arguments

await create_guild_ban(guild_id, user_id, *, delete_message_days=0, reason=None)[source]#

This function is a coroutine.

[REST API] Create a guild ban, and optionally delete previous messages sent by the banned user.

Required permissions: BAN_MEMBERS

Parameters:

  • guild_id (Union[int, str, Snowflake]) – Id of guild where we will ban member

  • user_id (Union[int, str, Snowflake]) – Id of user to operate with.

  • delete_message_days (Optional[int]) – Number of days to delete messages for (0-7)

  • reason (Optional[str]) – The reason of the action.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong guild, user or something else

await create_guild_emoji(guild_id, emoji_name, emoji_image, *, reason=None, role_id=None)[source]#

This function is a coroutine.

[REST API] Create a new emoji for the guild. Required permissions: MANAGE_EMOJIS_AND_STICKERS.

Parameters:

  • guild_id (Union[int, str, Snowflake]) – ID of the guild in which we will create emoji

  • emoji_name (Optional[str]) – Name of the emoji

  • emoji_image (Optional[str]) – The 128x128 emoji image

  • reason (Optional[str]) – The reason of the action

  • role_id (Union[int, str, Snowflake]) – Roles allowed to use this emoji

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong guild

await create_message(channel_id, content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, allowed_mentions=None, delete_after=None, _client_allowed_mentions=None)[source]#

This function is a coroutine.

[REST API] Create message.

Sends a message to the destination with the content given.

The content must be a type that can convert to a string through str(content).

Parameters:

  • channel_id (Union[int, str, Snowflake]) – Id of channel where message should be sent

  • content (Optional[str]) – The content of the message to send.

  • tts (Optional[bool]) – Whether the message should be sent using text-to-speech.

  • embed (Optional[Embed]) – Embed

  • embeds (Optional[List[Embed]]) – List of embeds

  • file (Optional[File]) – File

  • files (Optional[List[File]]) – List of files

  • allowed_mentions (Optional[AllowedMentions]) – Controls the mentions being processed in this message.

  • delete_after (Optional[int]) – Provided value must be an int. if provided, deletes message after some seconds. May raise ForbiddenError or NotFoundError.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have the proper permissions to send the message.

  • BadRequestError – Some of specified parameters is invalid.

await delete_global_application_command(application_id, command_id)[source]#

This function is a coroutine.

[REST API] Delete a global command.

Parameters:

  • application_id (Snowflake) – ID of the parent application

  • command_id (Optional[bool]) – ID of command to delete.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong arguments

await delete_guild_emoji(guild_id, emoji_id, *, reason=None)[source]#

This function is a coroutine.

[REST API] Delete the given emoji Required permissions: MANAGE_EMOJIS_AND_STICKERS.

Parameters:

  • guild_id (Union[int, str, Snowflake]) – ID of the guild in which we will delete emoji

  • emoji_id (Union[int, str, Snowflake]) – The ID of the emoji that we will delete

  • reason (Optional[str]) – The reason of the action

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong guild and emoji

await delete_message(channel_id, message_id, *, reason=None)[source]#

This function is a coroutine.

[REST API] Deletes only one specified message.

Parameters:

  • channel_id (Union[int, str, Snowflake]) – Id of channel, where message should be deleted

  • message_id (Union[int, str, Snowflake]) – Id of message to delete.

  • reason (Optional[str]) – The reason of the message delete operation.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required. (You must have MANAGE_MESSAGES permission)

await delete_original_interaction_response(application_id, interaction_token)[source]#

This function is a coroutine.

[REST API] Delete Original Interaction Response.

Parameters:

  • application_id (Union[Snowflake, str, int]) – Id of interaction to fetch

  • interaction_token (str) – Interaction token

await edit_global_application_command(application_id, command_id, *, name=None, description=None, options=None, default_member_permissions=None, dm_permission=None, default_permission=None)[source]#

This function is a coroutine.

All parameters are optional, but any parameters provided will entirely overwrite the existing values of those parameters.

[REST API] Edit a global command.

Parameters:

  • application_id (Snowflake) – ID of the parent application

  • command_id (Optional[bool]) – ID of command to edit.

  • name (Optional[LocalizedField]) – Name of command, 1-32 characters

  • description (Optional[LocalizedField]) – Description for CHAT_INPUT commands, 1-100 characters. Empty string for USER and MESSAGE commands

  • options (Optional[List[ApplicationCommandOption]]) – Parameters for the command, max of 25. Only available for CHAT_INPUT command type.

  • default_member_permissions (Optional[str]) – Set of permissions represented as a bit set

  • dm_permission (Optional[bool]) – Indicates whether the command is available in DMs with the app, only for globally-scoped commands. By default, commands are visible.

  • default_permission (Optional[bool]) – Not recommended for use as field will soon be deprecated. Indicates whether the command is enabled by default when the app is added to a guild, defaults to true

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong arguments

await fetch_channel(channel_id)[source]#

This function is a coroutine.

[REST API] Fetch Channel from the Discord API (by id).

Parameters:

channel_id (Union[Snowflake, str, int]) – Id of channel to fetch

async for ... in fetch_channel_pins(channel_id)[source]#

This function is a coroutine.

Retrieves all messages that are currently pinned in the channel.

Parameters:

channel_id (Union[int, str, Snowflake]) – Id of channel where messages should be fetched.

Raises:

HTTPException – The request to perform the action failed with other http exception.

Returns:

AsyncIterator of Message objects.

Return type:

AsyncIterator[Message]

await fetch_guild(guild_id)[source]#

This function is a coroutine.

[REST API] Fetch Guild from the Discord API (by id).

Parameters:

guild_id (Union[Snowflake, str, int]) – Id of guild to fetch

await fetch_message(channel_id, message_id)[source]#

This function is a coroutine.

[REST API] Fetch message.

Returns a specific message in the channel.

Parameters:

  • message_id (Union[Snowflake]) – Id of message to fetch.

  • channel_id (Union[int, str, Snowflake]) – Id of channel where message should be fetched.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

Returns:

Message object.

Return type:

Message

await fetch_user(user_id)[source]#

This function is a coroutine.

[REST API] Fetch User from the Discord API (by id).

Parameters:

user_id (Union[Snowflake, str, int]) – Id of user to fetch

async for ... in get_channel_messages_history(channel_id, limit=50, *, before=None, after=None, around=None)[source]#

This function is a coroutine.

[REST API] Fetch messages history.

Returns a list of messages in this channel.

Examples

Flattening messages into a list:

messages = [message async for message in channel.history(limit=111)]

All parameters are optional.

Parameters:

  • channel_id (Union[int, str, Snowflake]) – Id of channel where messages should be fetched.

  • limit (Optional[Snowflake]) – Max number of messages to return (1-100).

  • around (Optional[Snowflake]) – Get messages around this message ID.

  • before (Optional[Snowflake]) – Get messages before this message ID.

  • after (Optional[Snowflake]) – Get messages after this message ID.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

Returns:

An iterator of messages.

Return type:

AsyncIterator[Message]

await get_global_application_command(application_id, command_id)[source]#

This function is a coroutine.

[REST API] Fetch a global command for your application.

Parameters:

  • application_id (Snowflake) – ID of the parent application

  • command_id (Optional[bool]) – ID of command to fetch.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong arguments

await get_global_application_commands(application_id, *, with_localizations=False)[source]#

This function is a coroutine.

[REST API] Fetch all of the global commands for your application.

Parameters:

  • application_id (Snowflake) – ID of the parent application

  • with_localizations (Optional[bool]) – Whether to include full localization dictionaries (name_localizations and description_localizations) in the returned objects, instead of the name_localized` and ``description_localized fields. Default False.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong arguments

await get_guild_emoji(guild_id, emoji_id)[source]#

This function is a coroutine.

[REST API] Get emoji from guild

Parameters:

  • guild_id (Union[int, str, Snowflake]) – The ID of the guild in which we will receive emoji

  • emoji_id (Union[int, str, Snowflake]) – The ID of the emoji that we will get

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong guild and emoji

await get_original_interaction_response(application_id, interaction_token)[source]#

This function is a coroutine.

[REST API] Fetch Original Interaction Response from the Discord API.

Parameters:

  • application_id (Union[Snowflake, str, int]) – Id of interaction to fetch

  • interaction_token (str) – Interaction token

await interaction_respond(interaction, interaction_response)[source]#

This function is a coroutine.

[REST API] Respond to an interaciton

Parameters:

  • interaction (Interaction) – Interaction to respond to

  • interaction_response (InteractionResponse) – InteractionResponse`e``

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong arguments

await list_guild_emojis(guild_id)[source]#

This function is a coroutine.

[REST API] Getting all emojis from guild

Parameters:

guild_id (Union[int, str, Snowflake]) – ID of the guild in which we will get the list of emojis

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong guild

await modify_guild_emoji(guild_id, emoji_id, emoji_name, *, reason=None, role_id=None)[source]#

This function is a coroutine.

[REST API] Modify the given emoji. Required permissions: MANAGE_EMOJIS_AND_STICKERS.

Parameters:

  • guild_id (Union[int, str, Snowflake]) – ID of the guild in which we will modify emoji

  • emoji_id (Union[int, str, Snowflake]) – The ID of the emoji that we will modify

  • emoji_name (Optional[str]) – Name of the emoji

  • reason (Optional[str]) – The reason of the action

  • role_id (Union[int, str, Snowflake]) – Roles allowed to use this emoji

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong guild and emoji

await modify_guild_member(guild_id, user_id, *, nick=<UNDEFINED>, roles=<UNDEFINED>, is_mute=<UNDEFINED>, is_deaf=<UNDEFINED>, voice_channel_id=<UNDEFINED>, communication_disabled_until=<UNDEFINED>, reason=None)[source]#

This function is a coroutine.

[REST API] Modify attributes of a guild member.

Parameters:

  • guild_id (Union[int, str, Snowflake]) – Id of guild where we will modify member

  • user_id (Union[int, str, Snowflake]) – Id of user to operate with.

  • nick (Optional[str]) –

    Value to set user’s nickname to.

    Required permissions: MANAGE_NICKNAMES

  • roles (Optional[List[Snowflake]]) –

    List of role ids the member is assigned

    Required permissions: MANAGE_ROLES

  • is_mute –

    Whether the user is muted in voice channels.

    Required permissions: MUTE_MEMBERS

  • is_deaf –

    Whether the user is deafened in voice channels.

    Required permissions: DEAFEN_MEMBERS

  • voice_channel_id (Optional[Snowflake]) –

    Id of channel to move user to (if they are connected to voice)

    Required permissions: MOVE_MEMBERS

  • communication_disabled_until (Optional[Timestamp]) –

    When the user’s timeout will expire and the user will be able to communicate in the guild again (up to 28 days in the future), set to None to remove timeout.

    Will throw a 403 error if the user has the ADMINISTRATOR permission or is the owner of the guild

    Required permissions: MODERATE_MEMBERS

  • reason (Optional[str]) – The reason of the action.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong type of argument, or you set is_deaf, is_mute when user is not in the channel

await remove_guild_ban(guild_id, user_id, *, reason=None)[source]#

This function is a coroutine.

[REST API] Remove the ban for a user.

Required permissions: BAN_MEMBERS

Parameters:

  • guild_id (Union[int, str, Snowflake]) – Id of guild where we will remove ban for member

  • user_id (Union[int, str, Snowflake]) – Id of user to operate with.

  • reason (Optional[str]) – The reason of the action.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong guild, user or something else Or if the user is not banned

await remove_guild_member(guild_id, user_id, *, reason=None)[source]#

This function is a coroutine.

[REST API] Remove a member from a guild.

Required permissions: KICK_MEMBERS

Parameters:

  • guild_id (Union[int, str, Snowflake]) – Id of guild where we will remove member

  • user_id (Union[int, str, Snowflake]) – Id of user to operate with.

  • reason (Optional[str]) – The reason of the action.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong guild, user or something else.

await remove_guild_member_role(guild_id, user_id, role_id, *, reason=None)[source]#

This function is a coroutine.

[REST API] Removes a role from a guild member.

Required permissions: MANAGE_ROLES

Parameters:

  • guild_id (Union[int, str, Snowflake]) – Id of guild where we will remove member role

  • user_id (Union[int, str, Snowflake]) – Id of user to operate with.

  • role_id (Optional[int]) – Id of role to remove.

  • reason (Optional[str]) – The reason of the action.

Raises:

  • HTTPException – The request to perform the action failed with other http exception.

  • ForbiddenError – You do not have proper permissions to do the actions required.

  • BadRequestError – You provided a wrong guild, user or something else

Event Reference#

This section outlines the different types of events.

To register an listener for an event you can use Client.event().

If an your listener raises an exception, on_error() will be called to handle it, which defaults to print a traceback and ignoring the exception.

Warning

Listeners functions must be a coroutine. If they aren’t, then you might get unexpected errors. In order to turn a function into a coroutine they must be async def functions.

on_error(exception)#

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.

Note

It will not be received by Client.wait_for().

Parameters:

exception (Exception) – Exception.

on_channel_create(channel)#
on_channel_delete(channel)#

Called whenever a guild channel is deleted or created.

Parameters:

channel (models.guild.channel.Channel) – The guild channel that got created or deleted.

on_channel_update(before, after)#

Called whenever a guild channel is updated. e.g. changed name, topic, permissions.

Parameters:
on_guild_create(guild)#

Called when a models.guild.guild.Guild is either created by the Client or when the Client joins a guild.

Parameters:

guild (models.guild.guild.Guild) – The guild that was joined or created.

on_guild_remove(guild)#

Called when a models.guild.guild.Guild is removed from the Client.

This happens through, but not limited to, these circumstances:

  • The client got banned.

  • The client got kicked.

  • The client left the guild.

  • The client or the guild owner deleted the guild.

In order for this event to be invoked then the Client must have been part of the guild to begin with.

Parameters:

guild (models.guild.guild.Guild) – The guild that got removed.

on_guild_update(before, after)#

Called when a models.guild.guild.Guild updates, for example:

  • Changed name

  • Changed AFK channel

  • Changed AFK timeout

  • etc

Parameters:
on_message_create(message)#

Called when a models.message.message.Message is created and sent.

Note

Not all messages will have content. This is a Discord limitation. See the docs of Intents.MESSAGE_CONTENT for more information.

Parameters:

message (models.message.message.Message) – The current message.

on_shard_ready(shard_id)#

Called when particular shard becomes ready.

Parameters:

shard_id (int) – The shard ID that is ready.