API Reference#

Welcome to API Reference of Qord. This section details every single aspect of the core API.

The Starter Point#

Client#

class qord.Client(*, session: Optional[ClientSession] = None, shards_count: Optional[int] = None, intents: Optional[Intents] = None, cache: Optional[Cache] = None, session_owner: bool = False, max_retries: int = 5, debug_events: bool = False, connect_timeout: float = 5.0, ready_timeout: float = 2.0)#

A client that interacts with Discord API.

This is the core class of this library and the main starter point for every bot. All parameters passed during initializing are optional and keyword only.

This is a basic example using this class to build a “Ping Pong” bot:

import qord

client = qord.Client()

@client.event(qord.GatewayEvent.MESSAGE_CREATE)
async def on_message_create(event):
    message = event.message

    if message.author.bot:
        # Don't respond to bots.
        return

    if message.content == "!ping":
        await message.channel.send_message("🏓 Pong!")

if __name__ == "__main__":
    client.start(BOT_TOKEN)

Parameters

session (aiohttp.ClientSession) – The client session used for making HTTPs requests. If omitted, Library will initalize a session internally.
session_owner (builtins.bool) – Whether the session is owned by the user, If set to True, The session will not be closed upon bot’s close. Defaults to False.
max_retries (builtins.int) – The maximum number of re-tries for an unexpectedly failed HTTP request before raising HTTPException. This integer cannot be less than 5. None or 0 means no retries should be done.
shards_count (builtins.int) – The number of shards to spawn for this client. It is recommended to omit this parameter and let the library fetch the ideal shards count automatically for you.
connect_timeout (builtins.float) – The number of seconds to wait for a shard to connect before timing out. Defaults to 5. Greater the integer, The longer it will wait and if a shard raises an error, It will take longer to raise it.
ready_timeout (builtins.float) – The number of seconds to wait for lazy loading guilds cache initially before dispatching the ready event. Defaults to 2. Note that setting a very small timeout would cause ready event to fire with incomplete cache or setting too large value will increase the startup time.
debug_events (builtins.bool) – Whether to enable debug events. Defaults to False.
intents (Intents) – The intents for this client. By default, Only unprivileged intents are enabled using Intents.unprivileged() method.
cache (Cache) – The cache handler to use for the client. If not provided, Defaults to DefaultCache.

property shards: List[qord.core.shard.Shard]#

The list of shards associated to the client.

Return type: List[Shard]

property latency: float#

The websocket latency of the client.

If the client is running multiple shards, This returns the average of latencies of all shards. See Shard.latency for more info.

Return type: builtins.float

property max_concurrency: Optional[int]#

The maximum number of shards the client is allowed to start concurrently when launch() is called. This is set during setup().

This is retrieved from Discord and cannot be set by the user.

Return type: Optional[builtins.int]

property user: Optional[ClientUser]#

Returns the user associated to the client.

This is only available after initial connection has been made with the Discord gateway. This is not dependant on the members/users cache and is always available.

Return type: typing.Optional[ClientUser]

property cache: Cache#

Returns the cache handler associated to this client.

Return type: Cache

get_guild_cache(guild: Guild) → GuildCache#

Returns the cache handler for the provided guild.

This method is not meant to be called by the user. It is called by the library. By default, this returns the DefaultGuildCache. However, When implementing custom handlers, You may return instance of custom subclasses of GuildCache.

Example:

class MyGuildCache(qord.GuildCache):
    # implement abstract methods here.
    ...

class Client(qord.Client):
    def get_guild_cache(self, guild):
        return MyGuildCache(guild=guild)

The returned value must be an instance of GuildCache otherwise TypeError would be raised upon guild creations.

Return type: GuildCache

get_event_listeners(event_name: str, /) → List[Callable[[...], Any]]#

Gets the list of all events listener for the provided event.

Parameters: event_name (builtins.str) – The name of event to get listeners for.
Return type: The list of event listeners.

clear_event_listeners(event_name: str, /) → List[Callable[[...], Any]]#

Clears all events listener for the provided event.

Parameters: event_name (builtins.str) – The name of event to clear listeners for.
Return type: The list of removed event listeners.

walk_event_listeners() → List[Tuple[str, List[Callable[[...], Any]]]]#

Returns a list of tuples with first element being event name and second element being the list of event listeners for that event.

Example:

for name, listeners in client.walk_event_listeners():
    print(name, listeners)

register_event_listener(event_name: str, callback: Callable[[...], Any], /) → None#

Registers an event listener for provided event.

Parameters

event_name (builtins.str) – The name of event to register listener for.
callback – The callback listener. This must be a coroutine.

invoke_event(event: qord.events.base.BaseEvent) → None#

Invokes an event by calling all of it’s listeners.

This method is exposed to documentation to allow users to dispatch custom events. For more information about this topic, See Events API Reference.

Parameters: event (BaseEvent) – The event to invoke.

event(event_name: str)#

A decorator that registers an event listener for provided event.

The decorated function must be a coroutine. Example:

@client.event(qord.GatewayEvent.MESSAGE_CREATE)
async def on_message_create(event):
    ...

Parameters: event_name (builtins.str) – The name of event to register listener for. See GatewayEvent for names of various gateway events.

is_setup() → bool#

Returns: Indicates whether the client is setup.
Return type: builtins.bool

async setup(token: str, /) → None#

Setups the client with the provided authorization token.

This must be called before launch(). This setup fetches the shards count and spawns that many shards accordingly.

Parameters

token (builtins.str) – The token to setup the client with.

Raises

RuntimeError – The client is already setup.
HTTPException – Setup failed. Most probably the provided token is invalid. Consider checking for HTTP status code using status attribute on HTTPException.response object.

async launch() → None#

Launches the bot.

This method should be called after setup().

Raises: ClientSetupRequired – The client is not setup yet. See setup() for more info.

async close(clear_setup: bool = True) → None#

Gracefully closes the client.

The entire closing process includes:

Gracefully closing all the spawned shards.
Closing the HTTP session.
Clearing the client setup.

Parameters

clear_setup (builtins.bool) –

Whether to clear the client setup. Defaults to True.

If set to False, Client setup will not be closed and there will be no need of calling setup() again.

start(token: str) → None#

Setups the client with provided token and then starts it.

Unlike launch(), This method is not a coroutine and aims to abstract away the asyncio event loop handling from the user. For a granular control over the event loop, Consider using setup() and launch()

Parameters: token (builtins.str) – The token to setup the client with.
Raises: HTTPException – Startup failed. Most probably the provided token is invalid. Consider checking for HTTP status code using status attribute on HTTPException.response object.

is_ready() → bool#

Indicates whether the client is ready.

This returns True only when all shards are ready.

Return type: builtins.bool

async wait_until_ready() → None#: A coroutine that blocks until all shards are ready.

get_shard(shard_id: int, /) → Optional[qord.core.shard.Shard]#

Resolves a Shard by it’s ID.

Parameters: shard_id (builtins.int) – The ID of shard to get. See Shard.id documentation for more information about shard ID.
Returns: The resolved shard for the provided ID. If no shard exists with the provided ID, None is returned.
Return type: typing.Optional[Shard]

async fetch_user(user_id: int, /) → qord.models.users.User#

Fetches a User by it’s ID via REST API.

Parameters

user_id (builtins.int) – The ID of user to fetch.

Returns

The requested user.

Return type

User

Raises

HTTPNotFound – The user of provided ID does not exist.
HTTPException – HTTP request failed.

async fetch_guild(guild_id: int, /, *, with_counts: bool = False) → qord.models.guilds.Guild#

Fetches a Guild by it’s ID via REST API.

Parameters

guild_id (builtins.int) – The ID of guild to fetch.
with_counts (builtins.bool) – Whether to also include approximate_member_count and approximate_presence_count in the returned guild.

Returns

The requested guild.

Return type

Guild

Raises

HTTPNotFound – The guild of provided ID does not exist.
HTTPException – HTTP request failed.

async leave_guild(guild_id: int, /) → None#

Leaves a guild by it’s ID.

Parameters

guild_id (builtins.int) – The ID of guild to leave.

Raises

HTTPNotFound – The guild of provided ID does not exist or user is already not part of such guild.
HTTPException – HTTP request failed.

async fetch_channel(channel_id: int, /) → Union[GuildChannel, PrivateChannel]#

Fetches a channel through it’s ID.

Note

Due to an implementation limitation, When fetching channels related to a specific guild, The relevant guild is needed to be cached by the client otherwise a RuntimeError is raised. This is not the case for channel types that are not assoicated to guilds.

Parameters

channel_id (builtins.int) – The ID of channel to fetch.

Returns

The fetched channel.

Return type

Union[GuildChannel, PrivateChannel]

Raises

RuntimeError – The guild of channel is not cached.
HTTPNotFound – The channel does not exist.
HTTPException – The fetching failed.

Abstract Classes#

Other classes provided by the library can inherit these classes to implement the relevant common functionality.

BaseMessageChannel#

class qord.BaseMessageChannel#

A base class that implements support for messages managament.

Almost all classes that support the Message related operations inherit this class. The most common example is TextChannel.

async fetch_message(message_id: int) → qord.models.messages.Message#

Fetches a Message from the provided message ID.

Parameters

message_id (builtins.int) – The ID of message to fetch.

Returns

The fetched message.

Return type

Message

Raises

HTTPNotFound – Invalid or unknown message ID passed. Message might be deleted.
HTTPForbidden – Missing permissions to fetch that message.
HTTPException – The fetching failed.

async fetch_pins() → List[qord.models.messages.Message]#

Fetches the messages that are currently pinned in the channel.

Returns

The pinned messages in the channel.

Return type

List[Message]

Raises

HTTPForbidden – Missing permissions to fetch the pins.
HTTPException – The fetching failed.

async messages(limit: Optional[int] = 100, after: Union[datetime.datetime, int] = ..., before: Union[datetime.datetime, int] = ..., around: Union[datetime.datetime, int] = ..., oldest_first: bool = False) → AsyncIterator[qord.models.messages.Message]#

An async iterator for iterating through the channel’s messages.

Requires the read_message_history permission as well as view_channels permission in the given channel.

after, before, around and oldest_first are all mutually exclusive parameters.

Parameters

limit (Optional[builtins.int]) – The number of messages to fetch. If None is given, All messages are fetched from the channel. Defaults to 100.
after (Union[datetime.datetime, builtins.int]) – For pagination, To fetch messages after this message ID or time.
before (Union[datetime.datetime, builtins.int]) – For pagination, To fetch messages before this message ID or time.
around (Union[datetime.datetime, builtins.int]) – For pagination, To fetch messages around this message ID or time. Requires the limit to be greater than 100.
oldest_first (builtins.bool) – Whether to fetch the messages in reversed order i.e oldest message to newer messages.

Yields

Message – The message from the channel.

async send(content: str = ..., *, tts: bool = ..., allowed_mentions: AllowedMentions = ..., message_reference: MessageReference = ..., flags: MessageFlags = ..., embed: Embed = ..., file: File = ..., embeds: List[Embed] = ..., files: List[File] = ...)#

Sends a message to the channel.

If channel is a text based guild channel, This requires the send_messages permission in the channel.

For direct messages channel, No specific permission is required however relevant user must share a guild with the bot and the bot must not be blocked by the user.

Parameters

content (builtins.str) – The content of message.
allowed_mentions (AllowedMentions) – The mentions to allow in the message’s content.
flags (MessageFlags) – The message flags for the sent message. Bots can only apply the suppress_embeds flag. Other flags are unsupported.
embed (Embed) – The embed to include in message, cannot be mixed with embeds.
embeds (List[Embed]) – The list of embeds to include in the message, cannot be mixed with embed.
file (File) – The file to include in message, cannot be mixed with files.
files (List[File]) – The list of file attachments to send in message, cannot be mixed with file.
tts (builtins.bool) – Whether the sent message is a Text-To-Speech message.

Returns

The message that was sent.

Return type

Message

Raises

TypeError – Invalid arguments passed.
HTTPForbidden – You are not allowed to send message in this channel.
HTTPBadRequest – The message has invalid data.
HTTPException – The sending failed for some reason.

async trigger_typing() → None#

Triggers the typing indicator in the channel.

The typing indicator would automatically disappear after few seconds or once a message is sent in the channel.

Tip

Consider using typing() for a convenient context manager interface for triggering typing indicators.

Raises: HTTPException – Triggering typing failed.

typing() → qord.internal.context_managers.TypingContextManager#

Returns a context manager interface for triggering typing indicator in a channel.

Example:

async with channel.typing():
    # Typing indicator will appear until the context manager
    # is entered. Perform something heavy in this clause
    ...

Cache Handlers#

The classes documented below implement the logic of caching for various entities sent by Discord over gateway like users and guilds etc.

By default the library provides cache handlers that implement “in memory” caching usually suitable for most use cases. However if you want to write custom cache handlers for a specific use case, Qord also allows you to do that too. Following abstract classes will help you achieve that:

Cache
GuildCache

Cache#

class qord.Cache#

Base class for creating custom cache handlers.

This class is exposed to allow users to create implement custom cache handlers and configure them in a Client using the cache parameter.

Example:

class MyCache(qord.Cache):
    # Implement abstract methods.
    ...

cache = MyCache()
client = qord.Client(cache=cache)

Parameters: message_limit (builtins.int) – The number of messages to cache at a time. Defaults to 100. None or 0 will disable message cache.

message_limit#

The number of messages to cache at a time.

Type: builtins.int

property message_cache_enabled: bool#

Indicates whether the message cache is enabled.

Return type: builtins.bool

abstract clear() → None#: Clears the entire cache.

abstract users() → List[User]#

Returns all users that are currently cached.

Return type: List[User]

abstract get_user(user_id: int) → Optional[User]#

Gets a User from the cache with provided user ID.

Parameters: user_id (builtins.int) – The ID of user to get.
Returns: The gotten user if found. If no user existed with provided ID, None is returned.
Return type: Optional[User]

abstract add_user(user: User) → None#

Adds a User to the cache.

Parameters: user (User) – The user to add in the cache.

abstract delete_user(user_id: int) → Optional[User]#

Removes a User from the cache from the given ID.

Parameters: user_id (builtins.int) – The ID of user to delete.
Returns: The deleted user if any. If no user existed with provided ID, None is returned.
Return type: Optional[User]

abstract guilds() → List[Guild]#

Returns all guilds that are currently cached.

Return type: List[Guild]

abstract get_guild(guild_id: int) → Optional[Guild]#

Gets a Guild from the cache with provided guild ID.

Parameters: guild_id (builtins.int) – The ID of guild to get.
Returns: The gotten guild if found. If no guild existed with provided ID, None is returned.
Return type: Optional[Guild]

abstract add_guild(guild: Guild) → None#

Adds a Guild to the cache.

Parameters: guild (Guild) – The guild to add in the cache.

abstract delete_guild(guild_id: int) → Optional[Guild]#

Removes a Guild from the cache from the given ID.

Parameters: guild_id (builtins.int) – The ID of guild to delete.
Returns: The deleted guild if any. If no guild existed with provided ID, None is returned.
Return type: Optional[Guild]

abstract messages() → List[Message]#

Gets all messages that are currently cached.

Returns: The list of messages cached.
Return type: List[Message]

abstract add_message(message: Message) → None#

Adds a Message to the cache.

Once the message_limit is reached, The messages that are previously cache are removed, Clearing the message cache.

Parameters: message (Message) – The message to add in the cache.

abstract get_message(message_id: int) → Optional[Message]#

Gets a Message from the cache by the provided message ID.

Parameters: message_id (builtins.int) – The message ID to get message for.
Returns: The gotten message if any. If no message existed with provided ID, None is returned.
Return type: Optional[Message]

abstract delete_message(message_id: int) → Optional[Message]#

Deletes a Message from the cache by the provided message ID.

Parameters: message_id (builtins.int) – The message ID to remove message for.
Returns: The deleted message if any. If no message existed with provided ID, None is returned.
Return type: Optional[Message]

abstract private_channels() → List[PrivateChannel]#

Gets all private channels that are currently cached.

Returns: The list of private channels cached.
Return type: List[PrivateChannel]

abstract add_private_channel(private_channel: PrivateChannel) → None#

Adds a PrivateChannel to the cache.

Parameters: private_channel (Message) – The private channel to add in the cache.

abstract get_private_channel(channel_id: int) → Optional[PrivateChannel]#

Gets a PrivateChannel from the cache by the provided channel ID.

Parameters: channel_id (builtins.int) – The private channel ID to get channel for.
Returns: The gotten channel if any. If no private channel existed with provided ID, None is returned.
Return type: Optional[PrivateChannel]

abstract delete_private_channel(channel_id: int) → Optional[PrivateChannel]#

Deletes a PrivateChannel from the cache by the provided channel ID.

Parameters: channel_id (builtins.int) – The private channel ID to delete channel for.
Returns: The deleted channel if any. If no private channel existed with provided ID, None is returned.
Return type: Optional[PrivateChannel]

GuildCache#

class qord.GuildCache#

Abstract base class for creating custom cache handler for guilds.

You can use this class to implement custom cache handlers for caching guild related entities and configure them in a Client by overriding the get_guild_cache() method.

Parameters: guild (Guild) – The guild that this cache handler belongs to.

abstract clear() → None#: Clears the entire cache.

abstract roles() → List[Role]#

Returns all roles that are currently cached.

Return type: List[Role]

abstract get_role(role_id: int) → Optional[Role]#

Gets a Role from the cache with provided role ID.

Parameters: role_id (builtins.int) – The ID of role to get.
Returns: The gotten role if found. If no role existed with provided ID, None is returned.
Return type: Optional[Role]

abstract add_role(role: Role) → None#

Adds a Role to the cache.

Parameters: role (Role) – The role to add in the cache.

abstract delete_role(role_id: int) → Optional[Role]#

Removes a Role from the cache from the given ID.

Parameters: role_id (builtins.int) – The ID of role to delete.
Returns: The deleted role if any. If no role existed with provided ID, None is returned.
Return type: Optional[Role]

abstract members() → List[GuildMember]#

Returns all members that are currently cached.

Return type: List[GuildMember]

abstract get_member(user_id: int) → Optional[GuildMember]#

Gets a GuildMember from the cache for provided user ID.

Parameters: user_id (builtins.int) – The ID of user to get member of.
Returns: The gotten member if found. If no member existed with provided ID, None is returned.
Return type: Optional[GuildMember]

abstract add_member(member: GuildMember) → None#

Adds a GuildMember to the cache.

Parameters: member (GuildMember) – The member to add in the cache.

abstract delete_member(user_id: int) → Optional[GuildMember]#

Removes a GuildMember from the cache for provided user ID.

Parameters: user_id (builtins.int) – The ID of user to delete the member of.
Returns: The deleted member if any. If no member existed with provided ID, None is returned.
Return type: Optional[GuildMember]

abstract channels() → List[GuildChannel]#

Returns all channels that are currently cached.

Return type: List[GuildChannel]

abstract get_channel(channel_id: int) → Optional[GuildChannel]#

Gets a GuildChannel from the cache for provided channel ID.

Parameters: channel_id (builtins.int) – The ID of channel to get.
Returns: The gotten channel if found. If no channel existed with provided ID, None is returned.
Return type: Optional[GuildChannel]

abstract add_channel(channel: GuildChannel) → None#

Adds a GuildChannel to the cache.

Parameters: channel (GuildChannel) – The channel to add in the cache.

abstract delete_channel(channel_id: int) → Optional[GuildChannel]#

Removes a GuildChannel from the cache for provided channel ID.

Parameters: channel_id (builtins.int) – The ID of channel to delete.
Returns: The deleted channel if any. If no channel existed with provided ID, None is returned.
Return type: Optional[GuildChannel]

abstract emojis() → List[Emoji]#

Returns all the emojis that are currently cached.

Return type: List[Emoji]

abstract set_emojis(emojis: List[Emoji]) → None#

Replaces the emojis cache with the given list of emojis.

All previous emojis are removed from cache and new emojis from the given list are added to cache.

Parameters: emojis (List[Emoji]) – The list of emojis to set.

abstract get_emoji(emoji_id: int) → Optional[Emoji]#

Gets a Emoji from the cache for provided emoji ID.

Parameters: emoji_id (builtins.int) – The ID of emoji to get.
Returns: The gotten emoji if found. If no emoji existed with provided ID, None is returned.
Return type: Optional[Emoji]

abstract add_emoji(emoji: Emoji) → None#

Adds a Emoji to the cache.

Parameters: emoji (Emoji) – The emoji to add in the cache.

abstract delete_emoji(emoji_id: int) → Optional[Emoji]#

Removes a Emoji from the cache for provided emoji ID.

Parameters: emoji_id (builtins.int) – The ID of emoji to get.
Returns: The deleted emoji if found. If no emoji existed with provided ID, None is returned.
Return type: Optional[Emoji]

abstract scheduled_events() → List[ScheduledEvent]#

Returns all scheduled events that are currently cached.

Return type: List[ScheduledEvent]

abstract get_scheduled_event(scheduled_event_id: int) → Optional[ScheduledEvent]#

Gets a ScheduledEvent from the cache for provided event ID.

Parameters: scheduled_event_id (builtins.int) – The ID of scheduled event to get.
Returns: The gotten event if found. If no event existed with provided ID, None is returned.
Return type: Optional[ScheduledEvent]

abstract add_scheduled_event(scheduled_event: ScheduledEvent) → None#

Adds a ScheduledEvent to the cache.

Parameters: scheduled_event (ScheduledEvent) – The event to add in the cache.

abstract delete_scheduled_event(scheduled_event_id: int) → Optional[ScheduledEvent]#

Removes a ScheduledEvent from the cache for provided event ID.

Parameters: scheduled_event_id (builtins.int) – The ID of scheduled event to remove.
Returns: The removed event if any. If no event existed with provided ID, None is returned.
Return type: Optional[ScheduledEvent]

abstract stage_instances() → List[StageInstance]#

Returns all stage instances that are currently cached.

Return type: List[StageInstance]

abstract get_stage_instance(stage_instance_id: int) → Optional[StageInstance]#

Gets a StageInstance from the cache for provided instance ID.

Parameters: stage_instance_id (builtins.int) – The ID of stage instance to get.
Returns: The gotten stage instance if found. If no instance existed with provided ID, None is returned.
Return type: Optional[StageInstance]

abstract add_stage_instance(stage_instance: StageInstance) → None#

Adds a StageInstance to the cache.

Parameters: stage_instance (StageInstance) – The stage instance to add in the cache.

abstract delete_stage_instance(stage_instance_id: int) → Optional[StageInstance]#

Removes a StageInstance from the cache for provided ID.

Parameters: stage_instance_id (builtins.int) – The ID of stage instance to remove.
Returns: The removed stage instance if any. If none existed with provided ID, None is returned.
Return type: Optional[StageInstance]

DefaultCache#

class qord.DefaultCache#

In-memory cache implementation.

This is the default cache handler used by the Client that implements basic “in memory” caching. Obtainable through Client.cache.

Tip

If you want to implement custom cache handlers, See the Cache documentation.

clear() → None#: Clears the entire cache.

users() → List[qord.models.users.User]#

Returns all users that are currently cached.

Return type: List[User]

get_user(user_id: int) → Optional[qord.models.users.User]#

Gets a User from the cache with provided user ID.

Parameters: user_id (builtins.int) – The ID of user to get.
Returns: The gotten user if found. If no user existed with provided ID, None is returned.
Return type: Optional[User]

add_user(user: qord.models.users.User) → None#

Adds a User to the cache.

Parameters: user (User) – The user to add in the cache.

delete_user(user_id: int) → Optional[qord.models.users.User]#

Removes a User from the cache from the given ID.

Parameters: user_id (builtins.int) – The ID of user to delete.
Returns: The deleted user if any. If no user existed with provided ID, None is returned.
Return type: Optional[User]

guilds() → List[qord.models.guilds.Guild]#

Returns all guilds that are currently cached.

Return type: List[Guild]

get_guild(guild_id: int) → Optional[qord.models.guilds.Guild]#

Gets a Guild from the cache with provided guild ID.

Parameters: guild_id (builtins.int) – The ID of guild to get.
Returns: The gotten guild if found. If no guild existed with provided ID, None is returned.
Return type: Optional[Guild]

add_guild(guild: qord.models.guilds.Guild) → None#

Adds a Guild to the cache.

Parameters: guild (Guild) – The guild to add in the cache.

delete_guild(guild_id: int) → Optional[qord.models.guilds.Guild]#

Removes a Guild from the cache from the given ID.

Parameters: guild_id (builtins.int) – The ID of guild to delete.
Returns: The deleted guild if any. If no guild existed with provided ID, None is returned.
Return type: Optional[Guild]

messages() → List[qord.models.messages.Message]#

Gets all messages that are currently cached.

Returns: The list of messages cached.
Return type: List[Message]

get_message(message_id: int) → Optional[qord.models.messages.Message]#

Gets a Message from the cache by the provided message ID.

Parameters: message_id (builtins.int) – The message ID to get message for.
Returns: The gotten message if any. If no message existed with provided ID, None is returned.
Return type: Optional[Message]

add_message(message: qord.models.messages.Message) → None#

Adds a Message to the cache.

Once the message_limit is reached, The messages that are previously cache are removed, Clearing the message cache.

Parameters: message (Message) – The message to add in the cache.

delete_message(message_id: int) → Optional[qord.models.messages.Message]#

Deletes a Message from the cache by the provided message ID.

Parameters: message_id (builtins.int) – The message ID to remove message for.
Returns: The deleted message if any. If no message existed with provided ID, None is returned.
Return type: Optional[Message]

private_channels() → List[qord.models.channels.PrivateChannel]#

Gets all private channels that are currently cached.

Returns: The list of private channels cached.
Return type: List[PrivateChannel]

add_private_channel(private_channel: qord.models.channels.PrivateChannel) → None#

Adds a PrivateChannel to the cache.

Parameters: private_channel (Message) – The private channel to add in the cache.

get_private_channel(channel_id: int) → Optional[qord.models.channels.PrivateChannel]#

Gets a PrivateChannel from the cache by the provided channel ID.

Parameters: channel_id (builtins.int) – The private channel ID to get channel for.
Returns: The gotten channel if any. If no private channel existed with provided ID, None is returned.
Return type: Optional[PrivateChannel]

delete_private_channel(channel_id: int) → Optional[qord.models.channels.PrivateChannel]#

Deletes a PrivateChannel from the cache by the provided channel ID.

Parameters: channel_id (builtins.int) – The private channel ID to delete channel for.
Returns: The deleted channel if any. If no private channel existed with provided ID, None is returned.
Return type: Optional[PrivateChannel]

property message_cache_enabled: bool#

Indicates whether the message cache is enabled.

Return type: builtins.bool

DefaultGuildCache#

class qord.DefaultGuildCache#

In-memory cache implementation for guilds.

This is the default cache handler used by the Client that implements basic “in memory” caching for entities related to Guild. Obtainable through Guild.cache.

Tip

If you want to implement custom cache handlers, See the GuildCache documentation.

clear() → None#: Clears the entire cache.

roles() → List[qord.models.roles.Role]#

Returns all roles that are currently cached.

Return type: List[Role]

add_role(role: qord.models.roles.Role) → None#

Adds a Role to the cache.

Parameters: role (Role) – The role to add in the cache.

get_role(role_id: int) → Optional[qord.models.roles.Role]#

Gets a Role from the cache with provided role ID.

Parameters: role_id (builtins.int) – The ID of role to get.
Returns: The gotten role if found. If no role existed with provided ID, None is returned.
Return type: Optional[Role]

delete_role(role_id: int) → Optional[qord.models.roles.Role]#

Removes a Role from the cache from the given ID.

Parameters: role_id (builtins.int) – The ID of role to delete.
Returns: The deleted role if any. If no role existed with provided ID, None is returned.
Return type: Optional[Role]

members() → List[qord.models.guild_members.GuildMember]#

Returns all members that are currently cached.

Return type: List[GuildMember]

add_member(member: qord.models.guild_members.GuildMember) → None#

Adds a GuildMember to the cache.

Parameters: member (GuildMember) – The member to add in the cache.

get_member(user_id: int) → Optional[qord.models.guild_members.GuildMember]#

Gets a GuildMember from the cache for provided user ID.

Parameters: user_id (builtins.int) – The ID of user to get member of.
Returns: The gotten member if found. If no member existed with provided ID, None is returned.
Return type: Optional[GuildMember]

delete_member(user_id: int) → Optional[qord.models.guild_members.GuildMember]#

Removes a GuildMember from the cache for provided user ID.

Parameters: user_id (builtins.int) – The ID of user to delete the member of.
Returns: The deleted member if any. If no member existed with provided ID, None is returned.
Return type: Optional[GuildMember]

channels() → List[qord.models.channels.GuildChannel]#

Returns all channels that are currently cached.

Return type: List[GuildChannel]

get_channel(channel_id: int) → Optional[qord.models.channels.GuildChannel]#

Gets a GuildChannel from the cache for provided channel ID.

Parameters: channel_id (builtins.int) – The ID of channel to get.
Returns: The gotten channel if found. If no channel existed with provided ID, None is returned.
Return type: Optional[GuildChannel]

add_channel(channel: qord.models.channels.GuildChannel) → None#

Adds a GuildChannel to the cache.

Parameters: channel (GuildChannel) – The channel to add in the cache.

delete_channel(channel_id: int) → Optional[qord.models.channels.GuildChannel]#

Removes a GuildChannel from the cache for provided channel ID.

Parameters: channel_id (builtins.int) – The ID of channel to delete.
Returns: The deleted channel if any. If no channel existed with provided ID, None is returned.
Return type: Optional[GuildChannel]

emojis() → List[qord.models.emojis.Emoji]#

Returns all the emojis that are currently cached.

Return type: List[Emoji]

set_emojis(emojis: List[qord.models.emojis.Emoji]) → None#

Replaces the emojis cache with the given list of emojis.

All previous emojis are removed from cache and new emojis from the given list are added to cache.

Parameters: emojis (List[Emoji]) – The list of emojis to set.

get_emoji(emoji_id: int) → Optional[qord.models.emojis.Emoji]#

Gets a Emoji from the cache for provided emoji ID.

Parameters: emoji_id (builtins.int) – The ID of emoji to get.
Returns: The gotten emoji if found. If no emoji existed with provided ID, None is returned.
Return type: Optional[Emoji]

add_emoji(emoji: qord.models.emojis.Emoji) → None#

Adds a Emoji to the cache.

Parameters: emoji (Emoji) – The emoji to add in the cache.

delete_emoji(emoji_id: int) → Optional[qord.models.emojis.Emoji]#

Removes a Emoji from the cache for provided emoji ID.

Parameters: emoji_id (builtins.int) – The ID of emoji to get.
Returns: The deleted emoji if found. If no emoji existed with provided ID, None is returned.
Return type: Optional[Emoji]

scheduled_events() → List[qord.models.scheduled_events.ScheduledEvent]#

Returns all scheduled events that are currently cached.

Return type: List[ScheduledEvent]

get_scheduled_event(scheduled_event_id: int) → Optional[qord.models.scheduled_events.ScheduledEvent]#

Gets a ScheduledEvent from the cache for provided event ID.

Parameters: scheduled_event_id (builtins.int) – The ID of scheduled event to get.
Returns: The gotten event if found. If no event existed with provided ID, None is returned.
Return type: Optional[ScheduledEvent]

add_scheduled_event(scheduled_event: qord.models.scheduled_events.ScheduledEvent) → None#

Adds a ScheduledEvent to the cache.

Parameters: scheduled_event (ScheduledEvent) – The event to add in the cache.

delete_scheduled_event(scheduled_event_id: int) → Optional[qord.models.scheduled_events.ScheduledEvent]#

Removes a ScheduledEvent from the cache for provided event ID.

Parameters: scheduled_event_id (builtins.int) – The ID of scheduled event to remove.
Returns: The removed event if any. If no event existed with provided ID, None is returned.
Return type: Optional[ScheduledEvent]

stage_instances() → List[qord.models.stage_instances.StageInstance]#

Returns all stage instances that are currently cached.

Return type: List[StageInstance]

get_stage_instance(stage_instance_id: int) → Optional[qord.models.stage_instances.StageInstance]#

Gets a StageInstance from the cache for provided instance ID.

Parameters: stage_instance_id (builtins.int) – The ID of stage instance to get.
Returns: The gotten stage instance if found. If no instance existed with provided ID, None is returned.
Return type: Optional[StageInstance]

add_stage_instance(stage_instance: qord.models.stage_instances.StageInstance) → None#

Adds a StageInstance to the cache.

Parameters: stage_instance (StageInstance) – The stage instance to add in the cache.

delete_stage_instance(stage_instance_id: int) → Optional[qord.models.stage_instances.StageInstance]#

Removes a StageInstance from the cache for provided ID.

Parameters: stage_instance_id (builtins.int) – The ID of stage instance to remove.
Returns: The removed stage instance if any. If none existed with provided ID, None is returned.
Return type: Optional[StageInstance]

Enumerations#

These classes details the various enumerations including the integers based enumerations sent by Discord.

GatewayEvent#

class qord.GatewayEvent#

An enumeration that details names of various events sent over gateway.

These events names are commonly passed in Client.event decorator for registering a listener for relevant event.

GATEWAY_DISPATCH = 'gateway_dispatch'#: Called whenever gateway sends a dispatch event. See events.GatewayDispatch for more info.

SHARD_READY = 'shard_ready'#: Called whenever a shard is in ready state. See events.ShardReady for more info.

READY = 'ready'#: Called whenever all shards are ready. See events.Ready for more info.

RESUMED = 'resumed'#: Called whenever a shard successfully resumes a gateway session. See events.Resumed for more info.

USER_UPDATE = 'user_update'#: Called whenever a user is updated. See events.UserUpdate for more info.

GUILD_AVAILABLE = 'guild_available'#: Called whenever a guild becomes available to the client. See events.GuildAvailable for more info.

GUILD_UNAVAILABLE = 'guild_unavailable'#: Called whenever a guild becomes unavailable to the client. See events.GuildUnavailable for more info.

GUILD_JOIN = 'guild_join'#: Called whenever the bot joins a new guild. See events.GuildJoin for more info.

GUILD_LEAVE = 'guild_leave'#: Called whenever the bot leaves a guild. See events.GuildLeave for more info.

GUILD_UPDATE = 'guild_update'#: Called whenever a guild is updated. See events.GuildUpdate for more info.

ROLE_CREATE = 'role_create'#: Called whenever a guild role is created. See events.RoleCreate for more info.

ROLE_UPDATE = 'role_update'#: Called whenever a guild role is updated. See events.RoleUpdate for more info.

ROLE_DELETE = 'role_delete'#: Called whenever a guild role is deleted. See events.RoleDelete for more info.

GUILD_MEMBER_ADD = 'guild_member_join'#: Called whenever a member joins a guild. See events.GuildMemberAdd for more info.

GUILD_MEMBER_REMOVE = 'guild_member_remove'#: Called whenever a member is removed i.e left, kicked or banned from a guild. See events.GuildMemberRemove for more info.

GUILD_MEMBER_UPDATE = 'guild_member_update'#: Called whenever a member is updated. See events.GuildMemberUpdate for more info.

CHANNEL_CREATE = 'channel_create'#: Called whenever a channel is created. See events.ChannelCreate for more info.

CHANNEL_UPDATE = 'channel_update'#: Called whenever a channel is updated. See events.ChannelUpdate for more info.

CHANNEL_PINS_UPDATE = 'channel_pins_update'#: Called whenver a message is pinned/unpinned in a channel. See events.ChannelPinsUpdate for more info.

CHANNEL_DELETE = 'channel_delete'#: Called whenever a channel is deleted. See events.ChannelDelete for more info.

TYPING_START = 'typing_start'#: Called whenever a user starts typing. See events.TypingStart for more info.

MESSAGE_CREATE = 'message_create'#: Called whenever a message is sent. See events.MessageCreate for more info.

MESSAGE_DELETE = 'message_delete'#: Called whenever a message is deleted. See events.MessageDelete for more info.

MESSAGE_UPDATE = 'message_update'#: Called whenever a message is edited. See events.MessageUpdate for more info.

MESSAGE_BULK_DELETE = 'message_bulk_delete'#: Called whenever multiple messages are deleted. See events.MessageDelete for more info.

EMOJIS_UPDATE = 'emojis_update'#: Called whenever emojis for a guild are updated. See events.EmojisUpdate for more info.

REACTION_ADD = 'reaction_add'#: Called whenever a reaction is added on a message. See events.ReactionAdd for more info.

REACTION_REMOVE = 'reaction_remove'#: Called whenever a reaction is removed from a message. See events.ReactionRemove for more info.

REACTION_CLEAR = 'reaction_clear'#: Called whenever all reactions are cleared from a message. See events.ReactionClear for more info.

REACTION_CLEAR_EMOJI = 'reaction_clear_emoji'#: Called whenever all reactions for a specific emoji are cleared from a message. See events.ReactionClearEmoji for more info.

SCHEDULED_EVENT_CREATE = 'scheduled_event_create'#: Called whenever a scheduled event is created. See events.ScheduledEventCreate for more info.

SCHEDULED_EVENT_UPDATE = 'scheduled_event_update'#: Called whenever a scheduled event is updated. See events.ScheduledEventUpdate for more info.

SCHEDULED_EVENT_DELETE = 'scheduled_event_delete'#: Called whenever a scheduled event is deleted. See events.ScheduledEventDelete for more info.

SCHEDULED_EVENT_USER_ADD = 'scheduled_event_user_add'#: Called whenever a user subscribe to a scheduled event. See events.ScheduledEventUserAdd for more info.

SCHEDULED_EVENT_USER_REMOVE = 'scheduled_event_user_remove'#: Called whenever a user unsubscribes to a scheduled event. See events.ScheduledEventUserRemove for more info.

STAGE_INSTANCE_CREATE = 'stage_instance_create'#: Called whenever a stage instance is created. See events.StageInstanceCreate for more info.

STAGE_INSTANCE_UPDATE = 'stage_instance_update'#: Called whenever a stage instance is updated. See events.StageInstanceUpdate for more info.

STAGE_INSTANCE_DELETE = 'stage_instance_delete'#: Called whenever a stage instance is deleted. See events.StageInstanceDelete for more info.

PremiumType#

class qord.PremiumType#

An enumeration that details values for a user’s premium aka nitro subscription.

Most common place where this enumeration is useful is when working with the User.premium_type attribute.

NONE = 0#: User has no nitro subcription.

NITRO_CLASSIC = 1#: User has nitro classic subscription.

NITRO = 2#: User has nitro subscription.

ImageExtension#

class qord.ImageExtension#

An enumeration that details values for a various image extensions supported on the Discord CDN URLs.

PNG = 'png'#: PNG extension.

JPG = 'jpg'#: An alias of JPEG.

JPEG = 'jpeg'#: JPEG extension.

WEBP = 'webp'#: WEBP extension.

GIF = 'gif'#: GIF extension. This is only supported for animated image resources.

DefaultAvatar#

class qord.DefaultAvatar#

An enumeration that details values for a user’s default avatar.

A user’s default avatar value is calculated on the basis of user’s four digits discriminator. It can be generated by:

default_avatar = int(user.discriminator) % DefaultAvatar.INDEX

To get a user’s default avatar value, You should use User.default_avatar attribute.

BLURPLE = 0#: Blurple coloured default avatar.

GRAY = 1#: Gray coloured default avatar.

GREEN = 2#: Green coloured default avatar.

YELLOW = 3#: Yellow coloured default avatar.

RED = 4#: Red coloured default avatar.

PINK = 5#: Pink coloured default avatar.

INDEX = 5#

The zero based index integer used for generating the user’s default avatar.

This is based of number of colours available for default avatars. As such, If Discord adds a new avatar colour, This index will increment.

VerificationLevel#

class qord.VerificationLevel#

An enumeration that details values for a Guild’s verification_level

Verification level defines the requirements for a user account to be member of the guild.

NONE = 0#: No verification level set. Unrestricted.

LOW = 1#: Users must have verified email bound to their account.

MEDIUM = 2#: Users must also be registered to Discord for more then 5 minutes.

HIGH = 3#: Users must also be part of the guild for more then 10 minutes.

VERY_HIGH = 4#: Users must also have a verified phone number bound to their account.

NSFWLevel#

class qord.NSFWLevel#

An enumeration that details values for a Guild’s nsfw_level

NSFW level defines whether the guild is marked as Not Safe For Work (NSFW) or age restricted.

DEFAULT = 0#: No explicit NSFW level is set.

EXPLICIT = 1#: Guild is marked as explicit.

SAFE = 2#: Guild is marked as Safe For Work (SFW).

AGE_RESTRICTED = 3#: Guild is marked as age restricted.

NotificationLevel#

class qord.NotificationLevel#

An enumeration that details values for a Guild’s notification_level

Notification level defines the levels of notifications that the members of the guilds will receive upon messages.

ALL_MESSAGES = 0#: Members will receive notifications for every single message sent in the guild.

ONLY_MENTIONS = 1#: Members will receive notifications for only messages that mentions them.

ExplicitContentFilter#

class qord.ExplicitContentFilter#

An enumeration that details values for a Guild’s explicit_content_filter

Explicit content filter defines the explicit content checks and filters done on the files sent in the guild messages.

DISABLED = 0#: No scanning on sent files will be done.

MEMBERS_WITHOUT_ROLES = 1#: Scanning will be done for messages sent by members that don’t have any role assigned.

ALL_MEMBERS = 2#: Scanning will be done for all messages.

ChannelType#

class qord.ChannelType#

An enumeration that details the types of channels.

TEXT = 0#: The channel is a guild’s text channel.

DM = 1#: The channel is a private DM between two users.

VOICE = 2#: The channel is a guild’s voice channel.

GROUP = 3#: The channel is a private group DM channel.

CATEGORY = 4#: The channel is a guild’s category that holds other channels.

NEWS = 5#: The channel is a guild’s news channel.

STORE = 6#: The channel is a guild’s store channel.

NEWS_THREAD = 10#: The channel is a thread created inside a news channel.

PUBLIC_THREAD = 11#: The channel is a public thread.

PRIVATE_THREAD = 12#: The channel is a private thread.

STAGE = 13#: The channel is a guild’s stage channel.

VideoQualityMode#

class qord.VideoQualityMode#

An enumeration that details the video quality mode of a VoiceChannel.

AUTO = 1#: Automatic quality. Discord will chose the best quality for optimal performance.

FULL = 2#: 720p quality.

PremiumTier#

class qord.PremiumTier#

An enumeration that details values for a Guild’s premium_tier

Premium tier defines the server boosts level of the guild.

NONE = 0#: No boost level unlocked by the guild yet.

TIER_1 = 1#: Guild has unlocked boost level 1 perks.

TIER_2 = 2#: Guild has unlocked boost level 2 perks.

TIER_3 = 3#: Guild has unlocked boost level 3 perks.

MFALevel#

class qord.MFALevel#

An enumeration that details values for a Guild’s mfa_level

MFA level defines the 2 factor authentication requirement for the guild moderators for performing moderative actions.

DISABLED = 0#: 2FA is not required for performing moderative actions.

ELEVATED = 1#: 2FA is required for performing moderative actions..

MessageType#

class qord.MessageType#

An enumeration that details the type of a Message.

DEFAULT = 0#: Default text message.

RECIPIENT_ADD = 1#: Recipiient add notification in a group DM.

RECIPIENT_REMOVE = 2#: Recipient remove notification in a group DM.

CALL = 3#: Message representing status of a call.

CHANNEL_NAME_CHANGE = 4#: The channel name change notification.

CHANNEL_ICON_CHANGE = 5#: The channel icon change notification.

CHANNEL_PIN_ADD = 6#: A message is pinned in a channel.

GUILD_MEMBER_JOIN = 7#: Guild member welcome message.

GUILD_PREMIUM_SUBSCRIPTION_ADD = 8#: Guild boost added notification.

GUILD_PREMIUM_SUBSCRIPTION_TIER_1 = 9#: Guild reached level 1 boost tier notification.

GUILD_PREMIUM_SUBSCRIPTION_TIER_2 = 10#: Guild reached level 2 boost tier notification.

GUILD_PREMIUM_SUBSCRIPTION_TIER_3 = 11#: Guild reached level 3 boost tier notification.

CHANNEL_FOLLOW_ADD = 12#: New channel follow add notification.

GUILD_DISCOVERY_DISQUALIFIED = 14#: Guild discovery disqualified notification.

GUILD_DISCOVERY_REQUALIFIED = 15#: Guild discovery requalified notification.

GUILD_DISCOVERY_GRACE_PERIOD_INITIAL_WARNING = 16#: Guild discovery initial grace period warning.

GUILD_DISCOVERY_GRACE_PERIOD_FINAL_WARNING = 17#: Guild discovery final grace period warning.

THREAD_CREATED = 18#: Thread creation notification.

REPLY = 19#: Message is a reply to another message.

CHAT_INPUT_COMMAND = 20#: Message is a chat input or slash command.

THREAD_STARTER_MESSAGE = 21#: Message is a thread’s starter message.

GUILD_INVITE_REMINDER = 22#: Message is a guild’s invite reminder.

CONTEXT_MENU_COMMAND = 23#: Message is a context menu command.

ChannelPermissionType#

class qord.ChannelPermissionType#

An enumeration that details type of target in a ChannelPermission object.

ROLE = 0#: Overwrite belonging to a role.

MEMBER = 1#: Overwrite belonging to a guild member.

TimestampStyle#

class qord.TimestampStyle#

An enumeration that details all styles for a markdown timestamp.

SHORT_TIME = 't'#

Type: Short time e.g 16

LONG_TIME = 'T'#

Type: Long time e.g 16
Type: 20

SHORT_DATE = 'd'#: Short date e.g 20/04/2021

LONG_DATE = 'D'#: Long date e.g 20 April 2021

SHORT_DATE_TIME = 'f'#

This is default style that is applied when no style is provided in the timestamp.

Type: Short date and time e.g 20 April 2021 16

LONG_DATE_TIME = 'F'#

Type: Long date and time e.g Tuesday, 20 April 2021 16

RELATIVE_TIME = 'R'#: Relative time e.g 2 months ago

EventEntityType#

class qord.EventEntityType#

An enumeration that details entity types of a ScheduledEvent.

STAGE_INSTANCE = 1#: The event is happening in a stage instance.

VOICE = 2#: The event is happening in a voice channel.

EXTERNAL = 3#: The event is happening externally.

EventPrivacyLevel#

class qord.EventPrivacyLevel#

An enumeration that details privacy level of a ScheduledEvent.

GUILD_ONLY = 2#: The event is available guild members only.

EventStatus#

class qord.EventStatus#

An enumeration that details status of a ScheduledEvent

SCHEDULED = 1#: The event is currently scheduled.

ACTIVE = 2#: The event is currently active.

COMPLETED = 3#: The event has finished.

CANCELED = 3#: The event was cancelled.

StagePrivacyLevel#

class qord.StagePrivacyLevel#

An enumeration that details privacy level of a StageInstance.

GUILD_ONLY = 2#: The stage instance is available guild members only.

Data classes#

Shard#

class qord.Shard#

Represents a shard that connects to Discord gateway.

A shard is simply a separate websocket connection to Discord gateway. In bots that are in less then 1000 guilds, There is generally only one shard that maintains all the guilds. However when this limit is exceeded, Discord requires the bots to shard their connection to equally divide the workload of guilds in multiple shards.

Sharding is handled transparently by the library automatically and requires no user interaction. This class mostly is documented for completeness and is not usually not relevant to a general use case.

You should not instansiate this class yourself. Instead, Consider using one of the following ways to obtain it:

Client.shards
Client.get_shard

property id: int#

The ID of the shard. This starts from 0 and for each shard maintained by a client, This ID increments till Client.shards_count.

In theory, If a client is running 5 shards for example. All shard IDs can be obtained by:

>>> shard_ids = list(range(client.shards_count)) # shards_count is 5
[0, 1, 2, 3, 4]

Return type: builtins.int

property client: Client#

The client that instansiated the client.

Return type: Client

property latency: float#

The latency of this shard. This is measured on the basis of delay between a heartbeat sent by the shard and it’s acknowledgement sent by Discord gateway.

Return type: builtins.float

property heartbeat_interval: Optional[float]#

The heartbeat interval for this shard. This is only available after shard has done the initial websocket handshake.

Return type: builtins.float

property session_id: Optional[str]#

The current session ID for the shard. This is only available after shard has successfully connected to gateway.

The session ID is not same for all shards. Furthermore, The session ID is not guaranteed to be same through the shard lifetime as shard may start new sessions for reconnection purposes.

Return type: builtins.str

property sequence: Optional[int]#

The current dispatch sequence number of the shard. This may be None.

Return type: builtins.int

async reconnect(*, delay: float = 5.0) → None#

Reconnects the shard.

If the shard is already connected, will close the connection and attempt reconnect after provided delay. If the shard is disconnected, this simply reconnects it without delaying.

Parameters: delay (builtins.float) – The number of seconds to wait before reconnecting if the shard is already connected. Defaults to 5.

async disconnect() → None#

Disconnects the shard.

Once disconnected, The shard can be reconnected using reconnect().

Raises: RuntimeError – Shard is already closed.

AllowedMentions#

class qord.AllowedMentions(*, users: bool = False, roles: bool = False, everyone: bool = False, replied_user: bool = False, mentioned_roles: Optional[Sequence[int]] = None, mentioned_users: Optional[Sequence[int]] = None)#

Represents the allowed mentions of a message.

Allowed mentions are used to control the behaviour of mentions done in messages that are sent by the bot. You can toggle the mentions that should be parsed in the message content.

Parameters

users (builtins.bool) – Whether to enable users mentions in the messages.
roles (builtins.bool) – Whether to enable roles mentions in the messages.
everyone (builtins.bool) – Whether to enable mentions for @everyone/@here in messages.
replied_user (builtins.bool) – Whether to mention the author of replied message in messages that contain a reply.
mentioned_roles (Sequence[builtins.int]) – The list of role IDs to mention in the messages. Can contain maximum of 100 role IDs. Duplicate IDs will be removed.
mentioned_users (Sequence[builtins.int]) – The list of user IDs to mention in the messages. Can contain maximum of 100 user IDs. Duplicate IDs will be removed.

property mentioned_roles: Set[int]#

The roles that are allowed to be mentioned.

Return type: typing.Set[builtins.int]

add_role(role_id: int) → None#

Adds a role ID to the set of mentioned roles.

Parameters: role_id (builtins.int) – The ID of role to add.
Raises: ValueError – Roles limit has reached.

remove_role(role_id: int) → None#

Removes a role ID from the set of mentioned roles.

If the role ID does not exist, No error is raised.

Parameters: role_id (builtins.int) – The ID of role to remove.

property mentioned_users: Set[int]#

The users that are allowed to be mentioned.

Return type: typing.Set[builtins.int]

add_user(user_id: int) → None#

Adds a user ID to the set of mentioned users.

Parameters: user_id (builtins.int) – The ID of user to add.
Raises: ValueError – Users limit has reached.

remove_user(user_id: int) → None#

Removes a user ID from the set of mentioned users.

If the user ID does not exist, No error is raised.

Parameters: user_id (builtins.int) – The ID of user to remove.

classmethod all() → qord.dataclasses.allowed_mentions.AllowedMentions#: Creates a AllowedMentions with all options enabled.

Embed#

class qord.Embed(*, url: Optional[str] = None, title: Optional[str] = None, color: Optional[int] = None, description: Optional[str] = None, timestamp: Optional[datetime.datetime] = None, author: Optional[qord.dataclasses.embeds.EmbedAuthor] = None, image: Optional[qord.dataclasses.embeds.EmbedImage] = None, thumbnail: Optional[qord.dataclasses.embeds.EmbedThumbnail] = None, footer: Optional[qord.dataclasses.embeds.EmbedFooter] = None)#

Represents a message embed.

This class is mainly for facilitating the creation of rich embeds for sending in bot or webhook messages.

This class is also returned in several API responses like Message.embeds. Due to this reason, Some fields on the class are not able to be set by bots. These fields are generally returned for embeds from API that are created by external resources. You should not be setting those fields manually.

Parameters

url (builtins.str) – The URL of this embed this is hypedlinked in embed’s title.
title (builtins.str) – The title of the embed.
color (builtins.int) – The integer representation of color of this embed.
description (builtins.str) – The description of the embed.
timestamp (datetime) – The datetime representation of timestamp that is shown in footer of the embed.
author (EmbedAuthor) – The author of this embed.
image (EmbedImage) – The image of this embed.
thumbnail (EmbedThumbnail) – The thumbnail of this embed.
footer (EmbedFooter) – The footer of this embed.

property provider: Optional[qord.dataclasses.embeds.EmbedProvider]#

The provider of embed if any.

This property cannot be set manually as it is not available for bots and webhooks to set.

Return type: Optional[EmbedProvider]

property video: Optional[qord.dataclasses.embeds.EmbedVideo]#

The video of embed if any.

This property cannot be set manually as it is not available for bots and webhooks to set.

Return type: Optional[EmbedVideo]

property thumbnail: Optional[qord.dataclasses.embeds.EmbedThumbnail]#

The thumbnail of embed if any.

This property can be set a value of EmbedThumbnail manually. Setting the value to None will remove it.

Return type: Optional[EmbedThumbnail]

property image: Optional[qord.dataclasses.embeds.EmbedImage]#

The image of embed if any.

This property can be set a value of EmbedImage manually. Setting the value to None will remove it.

Return type: Optional[EmbedImage]

property footer: Optional[qord.dataclasses.embeds.EmbedFooter]#

The footer of embed if any.

This property can be set a value of EmbedFooter manually. Setting the value to None will remove it.

Return type: Optional[EmbedFooter]

property author: Optional[qord.dataclasses.embeds.EmbedAuthor]#

The author of embed if any.

This property can be set a value of EmbedAuthor manually. Setting the value to None will remove it.

Return type: Optional[EmbedFooter]

property fields: List[qord.dataclasses.embeds.EmbedField]#

The list of fields present on the embed.

Return type: List[EmbedField]

set_field(*, name: str, value: str, inline: bool = False, index: Optional[int] = None) → qord.dataclasses.embeds.EmbedField#

Sets a field on the embed at provided position.

This method by default adds the field to the last of current field however index parameter can be passed to provide an explicit index for the field where it should be inserted.

Parameters

name (builtins.str) – The name of field.
value (builtins.str) – The value of field.
inline (builtins.bool) – Whether the field should be inline with last field of embed. Defaults to True.
index (builtins.int) – The index where the field should be inserted. When not supplied, The field is appended.

Returns

The field that was created.

Return type

EmbedField

pop_field(index: Optional[int] = None) → Optional[qord.dataclasses.embeds.EmbedField]#

Removes a field from the provided position (last by default).

Parameters: index (builtins.int) – The index of field to remove. When not supplied, Removes the last field.
Returns: The removed field. If no field existed on provided index, None is returned
Return type: Optional[EmbedField]

clear_fields() → None#: Clears the fields that are currently present on the embed.

total_length() → int#

Returns the total length of this embed’s content.

This takes in account the length of embed’s content that are able to be set by bots, that are:

Fields name and values
Title and description
Footer text
Author name

This method can be useful when validating the embed’s total length before sending the embed. The total length of sent embed must be less than or equal to 6000.

len(embed) operation is equivalent to calling this method.

Returns: The total length of embed’s content.
Return type: builtins.int

EmbedImage#

class qord.EmbedImage(url: str, proxy_url: Optional[str] = None, height: Optional[int] = None, width: Optional[int] = None)#

A data class representing an embed’s image.

url: str#: The URL of the image.

proxy_url: Optional[str] = None#

The proxy URL of the image.

This field can only be returned by embeds from API responses that are created by external sources. This field is not available to be set by bots or webhooks. As such you should never set this field manually, setting it will either have no effect on the embed or you will run into unexpected issues.

height: Optional[int] = None#

The height of the image.

width: Optional[int] = None#

The width of the image.

EmbedThumbnail#

class qord.EmbedThumbnail(url: str, proxy_url: Optional[str] = None, height: Optional[int] = None, width: Optional[int] = None)#

A data class representing an embed’s thumbnail.

url: str#: The URL of the thumbnail image.

proxy_url: Optional[str] = None#

The proxy URL of the thumbnail image.

height: Optional[int] = None#

The height of the thumbnail.

width: Optional[int] = None#

The width of the thumbnail.

EmbedVideo#

class qord.EmbedVideo(url: str, proxy_url: Optional[str] = None, height: Optional[int] = None, width: Optional[int] = None)#

A data class representing an embed’s video.

Embed videos are only returned by embeds from API responses that are created by external sources. Videos cannot be set by bots or webhooks. As such, this class is not meant to be instansiated manually.

url: str#: The URL of video.

proxy_url: Optional[str] = None#: The proxy URL of the video.

height: Optional[int] = None#: The height of the video.

width: Optional[int] = None#: The width of the video.

EmbedField#

class qord.EmbedField(name: str, value: str, inline: bool = True)#

A data class representing an embed’s field.

name: str#: The name of field.

value: str#: The value of field.

inline: bool = True#: Whether the field lines with the last field on the embed, Defaults to True.

EmbedAuthor#

class qord.EmbedAuthor(name: str, url: Optional[str] = None, icon_url: Optional[str] = None, proxy_icon_url: Optional[str] = None)#

A data class representing an embed’s author.

name: str#: The name of author.

url: Optional[str] = None#: The URL of author.

icon_url: Optional[str] = None#: The URL of icon shown on author.

proxy_icon_url: Optional[str] = None#

The proxy URL of the author icon.

EmbedFooter#

class qord.EmbedFooter(text: Optional[str] = None, icon_url: Optional[str] = None, proxy_icon_url: Optional[str] = None)#

A data class representing an embed’s footer.

text: Optional[str] = None#: The name of author.

icon_url: Optional[str] = None#: The URL of icon shown on footers.

proxy_icon_url: Optional[str] = None#

The proxy URL of the footer icon.

EmbedProvider#

class qord.EmbedProvider(name: Optional[str] = None, url: Optional[str] = None)#

A data class representing an embed’s provider.

Embed providers are only returned by embeds from API responses that are created by external sources. Provider cannot be set by bots or webhooks. As such, this class is not meant to be instansiated manually.

name: Optional[str] = None#: The name of provider.

url: Optional[str] = None#: The URL of provider.

File#

class qord.File(content: Union[str, bytes, BufferedReader], /, *, name: Optional[str] = None, description: Optional[str] = None, spoiler: bool = False)#

Represents a file that is sent in messages.

Example usage with send() method:

file = qord.File("path/to/file.png")
await channel.send(file=file)

Parameters

content (Union[builtins.str, builtins.bytes, io.BufferedReader]) – The content of files. If a string is being passed, It would be considered the file path and would be opened and red in “read binary” mode.
name (builtins.str) – The name of file. The name would be retrieved from given file path or buffer object if possible and would fallback to “untitled” if couldn’t be resolved.
spoiler (builtins.bool) – Whether the file should be marked as spoiler when sent.
description (builtins.str) – The description of attachment.

content#

The file contents.

Type: builtins.bytes

property proper_name: str#: Returns the proper name of file with required prefixes attached if any.

MessageReference#

class qord.MessageReference(message_id: int, channel_id: Optional[int] = None, guild_id: Optional[int] = None, *, fail_if_not_exists: bool = True)#

Represents a reference to another message in a Message.

This class also allows you to create custom message references for replying to messages via send() method.

Note

If you have the Message that you are replying to, consider using the reply() method for more user friendly API interface.

Tip

For creating message replies, Only message_id parameter is required however channel_id and guild_id would be validated when supplied.

From API responses, This class is present on Message.message_reference attribute indicating a reference to another message. It is sent when the Message has the following type/flag:

MessageFlags.is_crosspost
MessageType.REPLY
MessageType.CHANNEL_FOLLOW_ADD
MessageType.CHANNEL_PIN_ADD
MessageType.THREAD_STARTER_MESSAGE

Parameters

message_id (builtins.int) – The ID of message being replied.
channel_id (builtins.int) – The ID of channel that the referenced message belongs to.
guild_id (builtins.int) – The ID of guild that the referenced message belongs to, if any.
fail_if_not_exists (builtins.bool) – Whether the API should throw HTTPException if the message being referenced does not exist. Defaults to True.

message_id#

The ID of message that is being referenced.

For message of type CHANNEL_FOLLOW_ADD, This is None.

Type: Optional[builtins.int]

channel_id#

The ID of channel that the reference belongs to. This is always present when getting this class from an API response and is optional when instansiating the class manually.

Type: Optional[builtins.int]

guild_id#

The ID of guild that the reference belongs to, if any.

Type: Optional[builtins.int]

classmethod from_message(message: Message, *, fail_if_not_exists: bool = True) → MessageReference#

Creates a message reference from a Message.

Tip

For creating message replies, Only message_id parameter is required however channel_id and guild_id would be validated when supplied.

Parameters

message (Message) – The message to create reference for.
fail_if_not_exists (builtins.bool) – Whether the API should throw HTTPException when sending message with this reference if the message being referenced does not exist. Defaults to True.

Returns

The created reference for given message.

Return type

MessageReference

PermissionOverwrite#

class qord.PermissionOverwrite(**permissions: Optional[bool])#

A class representing the permissions overwrite on a guild channel.

This class allows you to create permission overwrites that you can apply on guild channels.

While initializing, this class takes the same keyword parameters as Permissions i.e permissions. The permissions have their default value set to None indicating that no override is configured for the permission. The values of True and False explicitly indicates the allow and deny of the permission, respectively.

This class supports equality operation with other PermissionOverwrite instances to check if both have same overrides.

property create_instant_invite#: Overwrite value for create_instant_invite permission.

property kick_members#: Overwrite value for kick_members permission.

property ban_members#: Overwrite value for ban_members permission.

property administrator#: Overwrite value for administrator permission.

property manage_channels#: Overwrite value for manage_channels permission.

property manage_guild#: Overwrite value for manage_guild permission.

property add_reactions#: Overwrite value for add_reactions permission.

property view_audit_log#: Overwrite value for view_audit_log permission.

property priority_speaker#: Overwrite value for priority_speaker permission.

property stream#: Overwrite value for stream permission.

property view_channel#: Overwrite value for view_channel permission.

property send_messages#: Overwrite value for send_messages permission.

property send_tts_messages#: Overwrite value for send_tts_messages permission.

property manage_messages#: Overwrite value for manage_messages permission.

property embed_links#: Overwrite value for embed_links permission.

property attach_files#: Overwrite value for attach_files permission.

property read_message_history#: Overwrite value for read_message_history permission.

property mention_everyone#: Overwrite value for mention_everyone permission.

property use_external_emojis#: Overwrite value for use_external_emojis permission.

property view_guild_insights#: Overwrite value for view_guild_insights permission.

property connect#: Overwrite value for connect permission.

property speak#: Overwrite value for speak permission.

property mute_members#: Overwrite value for mute_members permission.

property deafen_members#: Overwrite value for deafen_members permission.

property move_members#: Overwrite value for move_members permission.

property use_vad#: Overwrite value for use_vad permission.

property change_nickname#: Overwrite value for change_nickname permission.

property manage_nicknames#: Overwrite value for manage_nicknames permission.

property manage_roles#: Overwrite value for manage_roles permission.

property manage_permissions#: Overwrite value for manage_permissions permission.

property manage_webhooks#: Overwrite value for manage_webhooks permission.

property manage_emojis_and_stickers#: Overwrite value for manage_emojis_and_stickers permission.

property use_application_commands#: Overwrite value for use_application_commands permission.

property request_to_speak#: Overwrite value for request_to_speak permission.

property manage_events#: Overwrite value for manage_events permission.

property manage_threads#: Overwrite value for manage_threads permission.

property create_public_threads#: Overwrite value for create_public_threads permission.

property create_private_threads#: Overwrite value for create_private_threads permission.

property use_external_stickers#: Overwrite value for use_external_stickers permission.

property send_messages_in_threads#: Overwrite value for send_messages_in_threads permission.

property start_embedded_activities#: Overwrite value for start_embedded_activities permission.

property moderate_members#: Overwrite value for moderate_members permission.

permissions() → Tuple[qord.flags.permissions.Permissions, qord.flags.permissions.Permissions]#

Returns the (allow, deny) tuple for the overwrite.

The first element of the tuple is Permissions instance with all permissions set to True that are explicitly allowed by this overwrite. The second element is Permissions with all permissions set to True that are explicitly denied in the overwrite.

Return type: Tuple[Permissions, Permissions]

classmethod from_permissions(allow: qord.flags.permissions.Permissions, deny: qord.flags.permissions.Permissions) → qord.dataclasses.permission_overwrite.PermissionOverwrite#

Creates a PermissionOverwrite with the given pair of permissions.

Parameters

allow (Permissions) – The permissions with all permissions set to True that are explicitly allowed in the overwrite.
deny (Permissions) – The permissions with all permissions set to True that are explicitly denied in the overwrite.

Return type

PermissionOverwrite

Bitwise Flags#

Flags#

class qord.Flags#

A class that interfaces manipulating bitwise flags.

This class provides a user friendly way of interacting with bitwise values returned by Discord. The most common example is Permissions.

This class is documented for allowing users to create custom flags classes. The way this class works can be described by the example below:

class MyFlags(qord.Flags):
    foo = 1 << 0
    bar = 1 << 2
    baz = 1 << 3
    bac = 1 << 4

>>> flags = MyFlags(foo=True, bar=False)
>>> flags.foo
True
>>> flags.bar
False
>>> flags.value
5
>>> flags = MyFlags(5)
>>> flags.foo
True
>>> flags.bar
False
>>> flags.bar = False
>>> flags.value
1

When initializing, Either a bitwise value can be passed as first positional argument or flags can be toggled using builtins.bool. Accessing a flag from non-initialized flags class returns it’s raw value.

Tip

This class also supports comparison with other Flags instances as well as int casting. On iterating, Yields the flag name and it’s toggle as bool.

Note

The parameters documented below are passed during subclassing this class.

Parameters: ignore_extraneous (builtins.bool) – Whether to ignore extra flags passed during initalization and not raise TypeError. Defaults to False.

value#

The raw flags value.

Type: builtins.int

Permissions#

class qord.Permissions#

A class that provides rich interface for manipulating permissions bitwise value.

This class subclasses Flags. See it’s documentation for more info about using this class for working with permissions.

create_instant_invite = 1#: Allows creating instant guild or channel invites.

kick_members = 2#: Allows kicking other members from a guild.

ban_members = 4#: Allows banning other members from a guild.

administrator = 8#

Bypasses all permissions.

Members with this permission enabled have all permissions enabled and they bypass all permission overwrites.

manage_channels = 16#: Allows management of the guild channels.

manage_guild = 32#: Allows management of the guild settings including adding bots.

add_reactions = 64#: Allows the addition of reactions on messages.

view_audit_log = 128#: Allows viewing of the guild’s audit log.

priority_speaker = 256#: Allows usage of priority speaker in a guild voice channel.

stream = 512#: Allows live streaming in a voice channel.

view_channel = 1024#: Allows viewing guild channel.

send_messages = 2048#: Allows to send messages in text channels.

send_tts_messages = 4096#: Allows the users to send TTS messages through /tts command.

manage_messages = 8192#: Allows management of messages.

embed_links = 16384#: Allows usage of embedded links in the messages.

attach_files = 32768#: Allows attaching files to the messages.

read_message_history = 65536#: Allows reading a text channel’s message history.

mention_everyone = 131072#: Allows mentioning the @everyone and @here roles.

use_external_emojis = 262144#: Allows usage of emojis from other guilds.

view_guild_insights = 524288#: Allows viewing the guild’s insights data.

connect = 1048576#: Allows joining a voice or stage channel.

speak = 2097152#: Allows speaking in a voice channel.

mute_members = 4194304#: Allows muting members in a voice channel.

deafen_members = 8388608#: Allows deafening members in a voice channel.

move_members = 16777216#: Allows moving and removing members from a voice channel.

use_vad = 33554432#: Allows usage of voice activity detection in a voice channel.

change_nickname = 67108864#: Allows changing own username in the guild.

manage_nicknames = 134217728#: Allows changing other members nickname in a guild.

manage_roles = 268435456#: Allows management of guild roles.

manage_permissions = 268435456#: An alias for manage_roles.

manage_webhooks = 536870912#: Allows management of guild webhooks.

manage_emojis_and_stickers = 1073741824#: Allows management of emojis and stickers of a guild.

use_application_commands = 2147483648#: Allows usage of application commands in a guild.

request_to_speak = 4294967296#: Allows requesting to speak in a stage channel.

manage_events = 8589934592#: Allows management of guild scheduled events.

manage_threads = 17179869184#: Allows management of threads.

create_public_threads = 34359738368#: Allows creation of public or news threads.

create_private_threads = 68719476736#: Allows creation of private threads.

use_external_stickers = 137438953472#: Allows usage of external stickers.

send_messages_in_threads = 274877906944#: Allows sending of messages in therads.

start_embedded_activities = 549755813888#: Allows starting embedded activities in a voice channel.

moderate_members = 1099511627776#: Allows moderating members including managing members timeout.

classmethod all() → qord.flags.permissions.Permissions#: Creates a Permissions instance with all permissions enabled.

Intents#

class qord.Intents#

Flags subclass that details the gateway intents.

Gateway intents allow you to toggle specific gateway events if whether you want to receive them or not. This also affects the caching for relevant entity. Gateway intents are useful to disable events that you don’t need for your bot and decrease the workload. For example, if your bot doesn’t need direct messages events, you can set direct_messages to False.

Some intents are marked as privileged. These intents are required to be enabled explicitly from the bot’s application page on Discord Developers Portal. If the bot is in more then 100 servers, These intents require verification and whitelisting.

Attempting to enable these intents without enabling them from Developers Portal will cause the bot to terminate with MissingPrivilegedIntents error.

Current privileged intents are:

members
presences
message_content

guilds = 1#

Whether to enable guild events and caching.

This intent is generally required by most bots and disabling it will cause most of functionality of library to be disabled. Only disable this when your bot is completely DMs or interactions based.

members = 2#

Whether to enable events and caching for guild members. This also controls most of bot’s user caching.

This is a privileged intent, See Intents documentation.

bans = 4#: Whether to enable events for guild bans.

emojis_and_stickers = 8#: Whether to enable events for guild stickers and emojis.

integrations = 16#: Whether to enable events for guild integrations.

webhooks = 32#: Whether to enable events for webhooks.

invites = 64#: Whether to enable events for invites.

voice_states = 128#: Whether to enable events for voice state updates.

presences = 256#

Whether to enable events and for presences.

This is a privileged intent, See Intents documentation.

guild_messages = 512#: Whether to enable events and caching for guild messages.

guild_message_reactions = 1024#: Whether to enable events and caching for reactions on guild messages.

guild_message_typing = 2048#: Whether to enable events for message typing in guilds.

direct_messages = 4096#: Whether to enable events and caching for direct messages.

direct_message_reactions = 8192#: Whether to enable events and caching for reactions on direct messages.

direct_message_typing = 16384#: Whether to enable events for message typing in DMs.

message_content = 32768#

Whether the bot can receive message content on message objects.

This is a privileged intent, See Intents documentation.

scheduled_events = 65536#: Whether to enable events and caching for guild scheduled events.

classmethod all() → qord.flags.intents.Intents#: Returns the Intents with all intents including privileged enabled.

classmethod unprivileged() → qord.flags.intents.Intents#: Returns the Intents with all intents excluding privileged enabled.

UserFlags#

class qord.UserFlags#

Flags subclass that details the flags of a User. This is mostly obtained using User.flags attribute.

A user’s flags include several things including the “badges” on the user’s account etc.

staff = 1#: User is a Discord employee/staff.

partner = 2#: User is a owner of a partnered guild.

hypesquad = 4#: User is a HypeSquad’s events coordinator.

bug_hunter_level_1 = 8#: User is a level 1 bug hunter.

hypesquad_bravery = 64#: User is member of HypeSquad bravey house.

hypesquad_brilliance = 256#: User is member of HypeSquad balance house.

early_premium_supporter = 512#: User is an early nitro supporter.

team = 1024#: User is a psuedo user, representing a team.

bug_hunter_level_2 = 16384#: User is a bug hunter of level 2.

verified_bot = 65536#: User is a verified bot.

verified_developer = 131072#: User is a “early” verified bot developer.

certified_moderator = 262144#: User is a certified Discord moderator.

bot_http_interactions = 524288#: The user (bot) only uses HTTPs for interactions.

SystemChannelFlags#

class qord.SystemChannelFlags#

Flags subclass that details the flags for a guild’s system channel.

suppress_join_notifications = 1#: Whether system channel will not receive a random message when a member joins.

suppress_premium_subscriptions = 2#: Whether system channel will not receive a notification when someone boosts the guild.

suppress_guild_reminders = 4#: Whether system channel will not receive tips for setting up guilds.

suppress_join_notification_replies = 8#: Whether messages sent on member join in system channel allow replying with stickers.

MessageFlags#

class qord.MessageFlags#

Flags subclass that details the flags of a Message.

This is mostly obtained using Message.flags attribute.

crossposted = 1#: The message is crossposted to following channels.

is_crosspost = 2#: The message is a crosspost from another channel.

suppress_embeds = 4#: The message does not include any embeds.

source_message_deleted = 8#: The source message for a crosspost message is deleted.

urgent = 16#: The message is an urgent message from system.

has_thread = 32#: The message has a thread associated to tit.

ephemeral = 64#: The message is an ephemeral message, in response to interaction.

loading = 128#: The message is an interaction response and application is in “Thinking” state.

thread_role_mention_failed = 256#: This message failed to mention some roles and add their members in a thread.

Utilities#

These are some utilities provided by qord.utils module that can be useful for many general use cases.

qord.utils.create_timestamp(time: Optional[Union[datetime.datetime, int, float]] = None, style: Optional[str] = None) → str#

Creates a markdown timestamp from the given datetime object or unix timestamp.

Parameters

time (Optional[Union[datetime.datetime, builtins.int, builtins.float]]) – The timestamp to use. If not given, The result of datetime.datetime.now() is used. If a datetime object is given, The epoch timestamp would be extracted from it. If a float is given, It would be rounded of.
style (builtins.str) –
The style for the timestamp. If not provided, The default style is used, See TimestampStyle for all possible values.

Note

This parameter is not validated by the library in case Discord adds a new style. You should consider validating it yourself.

Returns

The created timestamp in proper format.

Return type

builtins.str

Exceptions#

These are the exceptions raised by the library. All of these exceptions inherit a common class QordException.

QordException#

exception qord.QordException#: Base exception class for all exceptions raised by the library.

ClientSetupRequired#

exception qord.ClientSetupRequired#

An exception indicating that client setup is required to perform the attempted operation that caused the exception.

For HTTPs operations, This generally means that requested endpoint requires authorization with a bot token but no bot token is set yet.

You must call Client.setup() with a proper bot token first to setup the client first before retrying.

HTTPException#

exception qord.HTTPException#

Base exception class for all exceptions that indicate failure of a HTTP request i.e request returned with an unsuccessful status code..

response#

The failed request response.

Type: aiohttp.ClientResponse

data#

The data from the response. In most cases, This is a dictionary representing the JSON responose however in rare cases like CloudFlare errors, This can be a string of raw HTML.

Type: Union[builtins.dict, builtins.str]

HTTPBadRequest#

exception qord.HTTPBadRequest#: HTTPException indicating a 400 Bad Request response.

HTTPForbidden#

exception qord.HTTPForbidden#: HTTPException indicating a 403 Forbidden response.

HTTPNotFound#

exception qord.HTTPNotFound#: HTTPException indicating a 404 Not Found response.

HTTPServerError#

exception qord.HTTPServerError#: HTTPException indicating a 500s response.

ShardException#

exception qord.ShardException#

Base class for all shards related errors.

shard#

The shard that caused the error.

Type: Shard

ShardCloseException#

exception qord.ShardCloseException#

An exception indicating that a shard closed with an unhandleable close code.

This inherits ShardException.

code#

The close code that caused the error.

Type: builtins.int

MissingPrivilegedIntents#

exception qord.MissingPrivilegedIntents#

An exception indicating that a shard closed because client has requested access to certain privileged intents that are not provided by Discord.

This inherits ShardCloseException, The code attribute is always 4014 when this error is raised.

Discord Models#

BaseModel#

class qord.BaseModel#

Common base class for all other Discord models.

It is important to note that most of Discord models are not meant to be initialized by the user. You should either obtain them by using relevant HTTPs methods or from cache when available.

property client: Client#: The Client that had instansiated this model.

User#

class qord.User#

Representation of a Discord user entity.

id#

The ID of user.

Type: builtins.int

name#

The username of user.

Type: builtins.str

discriminator#

The four digits discriminator for the user.

Type: builtins.str

avatar#

The user’s avatar hash. This can be None if user has no custom avatar set. For obtaining the URL, consider using avatar_url().

Type: typing.Optional[builtins.str]

bot#

Whether the user is a bot.

Type: builtins.bool

system#

Whether the user is official Discord system user.

Type: builtins.bool

banner#

The user’s banner hash. This can be None if user has no custom banner set. For obtaining the URL, consider using banner_url().

Type: typing.Optional[builtins.str]

accent_color#

An integer representation of user’s accent colour.

Type: builtins.int

locale#

The user’s chosen default language.

Type: builtins.str

flags#

The user’s flags.

Type: UserFlags

public_flags#

The user’s public flags.

Type: UserFlags

premium_type#

The user’s premium subscription type integer value. See PremiumType for more information about all values meaning.

Type: builtins.int

property default_avatar: int#

Returns the default avatar index for this user.

This index integer is calculated on the basis of user’s discriminator. See DefaultAvatar for more information.

Return type: builtins.int

property proper_name: str#

Returns the proper name for this user as username#discriminator.

Return type: builtins.str

property mention: str#

Returns the string used for mentioning this user in Discord.

Return type: builtins.str

property dm: Optional[DMChannel]#

Returns the DM channel that belongs to the user.

This may return None if no DM channel is currently cached for this user. Instead of using this property, Consider using the create_dm() method that automatically handles caching for DM channels.

Return type: Optional[DMChannel]

default_avatar_url() → str#

Returns the default avatar URL for this user.

Note that default avatar is generated on the basis of discriminator and does not implies the user’s actual avatar. Consider using avatar_url() method instead if you want to obtain user’s actual avatar’s URL.

Unlike other URL generator methods, Default avatars do not support custom sizes and file extension is always PNG.

Return type: builtins.str

avatar_url(extension: str = ..., size: int = ...) → str#

Returns the avatar URL for this user.

If user has no custom avatar set, This returns the result of default_avatar_url().

The extension parameter only supports following extensions in the case of user avatars:

ImageExtension.GIF
ImageExtension.PNG
ImageExtension.JPG
ImageExtension.JPEG
ImageExtension.WEBP

Parameters

extension (builtins.str) – The extension to use in the URL. If not supplied, An ideal extension will be picked depending on whether user has static or animated avatar.
size (builtins.int) – The size to append to URL. Can be any power of 2 between 64 and 4096.

Raises

ValueError – Invalid extension or size was passed.

banner_url(extension: str = ..., size: int = ...) → Optional[str]#

Returns the banner URL for this user.

If user has no custom banner set, None is returned.

The extension parameter only supports following extensions in the case of user banners:

ImageExtension.GIF
ImageExtension.PNG
ImageExtension.JPG
ImageExtension.JPEG
ImageExtension.WEBP

Parameters

extension (builtins.str) – The extension to use in the URL. If not supplied, An ideal extension will be picked depending on whether user has static or animated banner.
size (builtins.int) – The size to append to URL. Can be any power of 2 between 64 and 4096.

Raises

ValueError – Invalid extension or size was passed.

is_avatar_animated() → bool#

Indicates whether the user has animated avatar.

Having no custom avatar set will also return False.

Return type: builtins.bool

is_banner_animated() → bool#

Indicates whether the user has animated banner.

Having no custom banner set will also return False.

Return type: builtins.bool

async create_dm(*, force: bool = False) → DMChannel#

Creates or gets the direct message channel associated to this user.

On initial call, The direct message channel is cached and further invocations would return the cached channel unless force parameter is explicity set to True.

Parameters: force (builtins.bool) – Whether to fetch the channel regardless of current state of cache. Defaults to False.
Returns: The DM channel for this user.
Return type: DMChannel

async send(*args, **kwargs) → Message#

A shorthand method for DMChannel.send().

This method is roughly equivalent to:

channel = await user.create_dm()
await channel.send(*args, **kwargs)

This method is just a shorthand. It is recommended to use the above way for sending messages to users.

To perform other operations on DM channels, you should consider retrieving them via the create_dm() method instead.

The parameters passed to this method are same as DMChannel.send().

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

ClientUser#

class qord.ClientUser#

Representation of user entity for the connected client.

This class also subclasses User. You can obtain class using the Client.user attribute.

verified#

Whether the user is verified using a valid email. Requires the email OAuth2 scope.

Type: typing.Optional[builtins.bool]

email#

The email of this user. Requires the email OAuth2 scope, None otherwise.

Type: typing.Optional[builtins.str]

mfa_enabled#

Whether the user has 2FA enabled on their account.

Type: builtins.bool

avatar_url(extension: str = ..., size: int = ...) → str#

Returns the avatar URL for this user.

If user has no custom avatar set, This returns the result of default_avatar_url().

The extension parameter only supports following extensions in the case of user avatars:

ImageExtension.GIF
ImageExtension.PNG
ImageExtension.JPG
ImageExtension.JPEG
ImageExtension.WEBP

Parameters

extension (builtins.str) – The extension to use in the URL. If not supplied, An ideal extension will be picked depending on whether user has static or animated avatar.
size (builtins.int) – The size to append to URL. Can be any power of 2 between 64 and 4096.

Raises

ValueError – Invalid extension or size was passed.

banner_url(extension: str = ..., size: int = ...) → Optional[str]#

Returns the banner URL for this user.

If user has no custom banner set, None is returned.

The extension parameter only supports following extensions in the case of user banners:

ImageExtension.GIF
ImageExtension.PNG
ImageExtension.JPG
ImageExtension.JPEG
ImageExtension.WEBP

Parameters

extension (builtins.str) – The extension to use in the URL. If not supplied, An ideal extension will be picked depending on whether user has static or animated banner.
size (builtins.int) – The size to append to URL. Can be any power of 2 between 64 and 4096.

Raises

ValueError – Invalid extension or size was passed.

property client: Client#: The Client that had instansiated this model.

async create_dm(*, force: bool = False) → DMChannel#

Creates or gets the direct message channel associated to this user.

On initial call, The direct message channel is cached and further invocations would return the cached channel unless force parameter is explicity set to True.

Parameters: force (builtins.bool) – Whether to fetch the channel regardless of current state of cache. Defaults to False.
Returns: The DM channel for this user.
Return type: DMChannel

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

property default_avatar: int#

Returns the default avatar index for this user.

This index integer is calculated on the basis of user’s discriminator. See DefaultAvatar for more information.

Return type: builtins.int

default_avatar_url() → str#

Returns the default avatar URL for this user.

Unlike other URL generator methods, Default avatars do not support custom sizes and file extension is always PNG.

Return type: builtins.str

property dm: Optional[DMChannel]#

Returns the DM channel that belongs to the user.

This may return None if no DM channel is currently cached for this user. Instead of using this property, Consider using the create_dm() method that automatically handles caching for DM channels.

Return type: Optional[DMChannel]

is_avatar_animated() → bool#

Indicates whether the user has animated avatar.

Having no custom avatar set will also return False.

Return type: builtins.bool

is_banner_animated() → bool#

Indicates whether the user has animated banner.

Having no custom banner set will also return False.

Return type: builtins.bool

property mention: str#

Returns the string used for mentioning this user in Discord.

Return type: builtins.str

property proper_name: str#

Returns the proper name for this user as username#discriminator.

Return type: builtins.str

async send(*args, **kwargs) → Message#

A shorthand method for DMChannel.send().

This method is roughly equivalent to:

channel = await user.create_dm()
await channel.send(*args, **kwargs)

This method is just a shorthand. It is recommended to use the above way for sending messages to users.

To perform other operations on DM channels, you should consider retrieving them via the create_dm() method instead.

The parameters passed to this method are same as DMChannel.send().

async edit(*, name: str = ..., avatar: Optional[bytes] = ...) → None#

Edits the client user.

Parameters

name (builtins.int) – The new name of user.
avatar (typing.Optional[builtins.int]) – The new avatar of user. None could be used to denote the removal of avatar.

Raises

HTTPBadRequest – The request body is not valid.
HTTPException – The editing failed.

Guild#

class qord.Guild#

Representation of a Discord guild entity often referred as “Server” in the UI.

This class supports equality comparison between instances of this class by the id attribute.

id#

The snowflake ID of this guild.

Type: builtins.int

name#

The name of this guild.

Type: builtins.str

afk_timeout#

The AFK timeout after which AFK members are moved to designated AFK voice channel. 0 means no timeout.

Type: builtins.int

premium_subscription_count#

The number of nitro boosts this guild has.

Type: builtins.int

preferred_locale#

The chosen language for this guild.

Type: builtins.str

widget_enabled#

Whether guild has widget enabled.

Type: builtins.bool

large#

Whether guild is marked as large.

Type: builtins.bool

unavailable#

Whether guild is unavailable due to an outage.

Type: builtins.bool

premium_progress_bar_enabled#

Whether guild has premium progress bar or server boosts progress bar enabled.

Type: builtins.bool

features#

The list of string representations of features of this guild. Complete list of valid features with meanings can be found here:

https://discord.com/developers/docs/resources/guild#guild-object-guild-features

Type: builtins.str

system_channel_flags#

The system channel flags for this guild.

Type: SystemChannelFlags

member_count#

The member count of this guild.

Type: typing.Optional[builtins.int]

max_presences#

The maximum number of presences for this guild, This is generally None except for guilds marked as large.

Type: typing.Optional[builtins.int]

max_members#

The maximum number of members for this guild.

Type: typing.Optional[builtins.int]

max_video_channel_users#

The maximum number of video channel users for this guild.

Type: typing.Optional[builtins.int]

approximate_member_count#

The approximated member count for this guild.

Type: typing.Optional[builtins.int]

approximate_presence_count#

The approximated presences count for this guild.

Type: typing.Optional[builtins.int]

vanity_invite_code#

The vanity invite code for this guild. To get complete URL, see vanity_invite_url

Type: typing.Optional[builtins.str]

description#

The description of this guild, if any.

Type: typing.Optional[builtins.str]

joined_at#

The datetime representation of time when the bot had joined this guild.

Type: typing.Optional[datetime.datetime]

icon#

The icon hash of this guild. If guild has no icon set, This is None. See icon_url() to retrieve the URL to this.

Type: typing.Optional[builtins.str]

banner#

The banner hash of this guild. If guild has no banner set, This is None. See banner_url() to retrieve the URL to this.

Type: typing.Optional[builtins.str]

splash#

The splash hash of this guild. If guild has no splash set, This is None. See splash_url() to retrieve the URL to this.

Type: typing.Optional[builtins.str]

discovery_splash#

The discovery splash hash of this guild. If guild has no discovery splash set, This is None. See discovery_splash_url() to retrieve the URL to this.

Type: typing.Optional[builtins.str]

owner_id#

The ID of owner of this guild.

Type: typing.Optional[builtins.int]

afk_channel_id#

The ID of designated AFK voice channel of this guild or None if no channel is set.

Type: typing.Optional[builtins.int]

widget_channel_id#

The ID of channel designated to be shown on guild’s widget or None if no channel is set.

Type: typing.Optional[builtins.int]

application_id#

The ID of application or bot that created this guild or None if guild is not created by an application or bot.

Type: typing.Optional[builtins.int]

system_channel_id#

The ID of channel designated for the system messages or None if no channel is set.

Type: typing.Optional[builtins.int]

rules_channel_id#

The ID of channel marked as rules channel in community guilds or None if no channel is set.

Type: typing.Optional[builtins.int]

public_updates_channel_id#

The ID of channel designated for moderator updates community guilds or None if no channel is set.

Type: typing.Optional[builtins.int]

verification_level#

The verification level value of this guild. See VerificationLevel for more information about this.

Type: builtins.int

notification_level#

The message notification level value of this guild. See NotificationLevel for more information about this.

Type: builtins.int

explicit_content_filter#

The explicit content filter level value of this guild. See ExplicitContentFilter for more information about this.

Type: builtins.int

mfa_level#

The 2FA requirement value of this guild. See MFALevel for more information about this.

Type: builtins.int

premium_tier#

The premium tier or server boosts level value of this guild. See PremiumTier for more information about this.

Type: builtins.int

nsfw_level#

The NSFW level value of this guild. See NSFWLevel for more information about this.

Type: builtins.int

property cache: qord.core.cache.GuildCache#

Returns the cache handler associated to this guild.

Return type: GuildCache

property vanity_invite_url: Optional[str]#

The vanity invite URL for the guild. If guild has no vanity invite set, None is returned.

Return type: builtins.str

property shard_id: int#

The computed shard ID for this guild.

Note that the value returned by this property is just computed using the guild ID and total shards count of the bound client and the actual shard with that ID may not exist in the client’s cache. This is usually the case for guilds that are not cached by the client.

Return type: int

property shard: Optional[Shard]#

The shard associated to this guild.

This can be None in some cases, See shard_id documentation for more information. This is equivalent to calling Client.get_shard() using the shard_id.

Return type: Optional[Shard]

property default_role: Optional[qord.models.roles.Role]#

The default (@everyone) role of this guild.

This property returns the result of GuildCache.get_role() with role_id set to the guild ID. This returns None for the guilds fetched over REST API.

Return type: Optional[Role]

property me: Optional[qord.models.guild_members.GuildMember]#

Returns the GuildMember for the bot’s user.

If the bot is not part of guild or the guild is fetched using Client.fetch_guild(), this returns None.

Note that this property does not require members intents as bot member is sent by Discord regardless.

Return type: Optional[GuildMember]

property owner: Optional[qord.models.guild_members.GuildMember]#

Returns the owner of this guild.

This property utilizes members cache and as such requires members intents to be enabled.

Return type: Optional[GuildMember]

property afk_channel: Optional[qord.models.channels.VoiceChannel]#

Returns the AFK channel for this guild, if any.

Return type: Optional[VoiceChannel]

property widget_channel: Optional[qord.models.channels.GuildChannel]#

Returns the widget channel for this guild, if any.

Return type: Optional[GuildChannel]

property system_channel: Optional[TextChannel]#

Returns the system channel for this guild, if any.

Return type: Optional[TextChannel]

property rules_channel: Optional[TextChannel]#

Returns the rules channel for this guild, if any.

Return type: Optional[TextChannel]

property public_updates_channel: Optional[TextChannel]#

Returns the public updates channel for this guild, if any.

Return type: Optional[TextChannel]

icon_url(extension: str = ..., size: int = ...) → Optional[str]#

Returns the icon URL for this guild.

If guild has no custom icon set, None is returned.

The extension parameter only supports following extensions in the case of guild icons:

ImageExtension.GIF
ImageExtension.PNG
ImageExtension.JPG
ImageExtension.JPEG
ImageExtension.WEBP

Parameters

extension (builtins.str) – The extension to use in the URL. If not supplied, An ideal extension will be picked depending on whether guild has static or animated icon.
size (builtins.int) – The size to append to URL. Can be any power of 2 between 64 and 4096.

Raises

ValueError – Invalid extension or size was passed.

banner_url(extension: str = ..., size: int = ...) → Optional[str]#

Returns the banner URL for this guild.

If guild has no custom banner set, None is returned.

The extension parameter only supports following extensions in the case of guild banners:

ImageExtension.PNG
ImageExtension.JPG
ImageExtension.JPEG
ImageExtension.WEBP

Parameters

extension (builtins.str) – The extension to use in the URL. Defaults to PNG.
size (builtins.int) – The size to append to URL. Can be any power of 2 between 64 and 4096.

Raises

ValueError – Invalid extension or size was passed.

splash_url(extension: str = ..., size: int = ...) → Optional[str]#

Returns the splash URL for this guild.

If guild has no custom splash set, None is returned.

The extension parameter only supports following extensions in the case of guild splashes:

ImageExtension.PNG
ImageExtension.JPG
ImageExtension.JPEG
ImageExtension.WEBP

Parameters

extension (builtins.str) – The extension to use in the URL. Defaults to PNG.
size (builtins.int) – The size to append to URL. Can be any power of 2 between 64 and 4096.

Raises

ValueError – Invalid extension or size was passed.

discovery_splash_url(extension: str = ..., size: int = ...) → Optional[str]#

Returns the discovery splash URL for this guild.

If guild has no custom discovery splash set, None is returned.

The extension parameter only supports following extensions in the case of guild discovery splashes:

ImageExtension.PNG
ImageExtension.JPG
ImageExtension.JPEG
ImageExtension.WEBP

Parameters

extension (builtins.str) – The extension to use in the URL. Defaults to PNG.
size (builtins.int) – The size to append to URL. Can be any power of 2 between 64 and 4096.

Raises

ValueError – Invalid extension or size was passed.

is_icon_animated() → bool#

Indicates whether the guild has animated icon.

Having no custom icon set will also return False.

Return type: builtins.bool

async leave() → None#

Leaves the guild.

Raises

HTTPNotFound – The bot is already not part of this guild.
HTTPException – HTTP request failed.

async fetch_roles() → List[qord.models.roles.Role]#

Fetches the list of roles associated to this guild.

Returns: The list of fetched roles.
Return type: List[Role]
Raises: HTTPException – HTTPs request failed.

async create_role(*, name: str = ..., permissions: Permissions = ..., color: int = ..., hoist: bool = ..., icon: bytes = ..., unicode_emoji: str = ..., mentionable: bool = ..., reason: Optional[str] = None) → Role#

Creates a role in this guild.

This operation requires the manage_roles permission for the client user in the guild.

Parameters

name (builtins.str) – The name of this role. Defaults to "new role".
permissions (Permissions) – The permissions for this role. Defaults to @everyone role’s permissions in the guild.
color (builtins.int) – The color value of this role.
hoist (builtins.bool) – Whether this role should appear hoisted from other roles.
icon (builtins.bytes) – The bytes representing the icon of this role. The guild must have ROLES_ICON feature to set this. This parameter cannot be mixed with unicode_emoji.
unicode_emoji (builtins.str) – The unicode emoji used as icon for this role. The guild must have ROLES_ICON feature to set this. This parameter cannot be mixed with icon.
mentionable (builtins.bool) – Whether this role is mentionable.
reason (builtins.str) – The reason for performing this action that shows up on the audit log entry.

Returns

The created role.

Return type

Role

Raises

HTTPForbidden – You are missing the manage_roles permissions.
HTTPException – The creation failed.

async fetch_member(user_id: int) → qord.models.guild_members.GuildMember#

Fetches a member from this guild for the provided user ID.

Parameters

user_id (builtins.int) – The ID of user to get member for.

Raises

HTTPNotFound – Member not found.
HTTPException – Failed to fetch the member.

Returns

The requested member.

Return type

GuildMember

async members(limit: Optional[int] = None, after: Union[int, datetime.datetime] = ...) → AsyncIterator[qord.models.guild_members.GuildMember]#

Fetches and iterates through the members of this guild.

This operation requires members privileged intent to be enabled for the bot otherwise a RuntimeError is raised.

Parameters

limit (Optional[builtins.int]) – The number of members to fetch, None (default) indicates that all members should be fetched.
after (Union[builtins.int, datetime.datetime]) – For paginating, To fetch members after the given user ID or members created after the given time. By default, the oldest created member is yielded first.

Yields

GuildMember – The fetched member.

Raises

RuntimeError – Missing the members intents.

async search_members(query: str, *, limit: int = 1) → List[qord.models.guild_members.GuildMember]#

Fetches the members whose username or nickname start with the provided query.

Parameters

query (builtins.str) – The query to search with.
limit (builtins.int) – The maximum number of members to return. Defaults to 1. Provided integer cannot be larger then 1000.

Raises

HTTPException – The fetching failed.

Return type

List[GuildMember]

async fetch_channels() → List[qord.models.channels.GuildChannel]#

Fetches the list of all channels of this guild.

Return type: List[GuildChannel]
Raises: HTTPException – Failed to fetch the channels.

async create_channel(type: int, name: str, *, bitrate: int = ..., position: int = ..., nsfw: bool = ..., topic: Optional[str] = ..., user_limit: Optional[int] = ..., slowmode_delay: Optional[str] = ..., parent: Optional[CategoryChannel] = ..., reason: Optional[str] = None)#

Creates a channel in the guild.

The name and type parameters are the only parameters that are required. Other parameters are optional.

Requires the manage_channels permissions in the relevant guild to perform this action.

Parameters

name (builtins.str) – The name of this channel.
type (builtins.int) – The type of this channel.
topic (builtins.str) – The topic of this channel. Only valid for news and text channels.
bitrate (builtins.int) – The bitrate of this channel. Only valid for voice channels.
user_limit (builtins.int) – The number of users that can connect to the channel at a time. Only valid for voice channels.
slowmode_delay (builtins.int) – The slowmode delay of this channel. Only valid for text based channels.
position (builtins.int) – The position of this channel in the channels list.
parent (CategoryChannel) – The category that this channel belongs to.
nsfw (builtins.bool) – Whether this channel is marked as NSFW.
reason (builtins.str) – The reason for creating the channel that appears on the audit log.

Returns

The created channel.

Return type

GuildChannel

Raises

HTTPForbidden – Missing permissions.
HTTPBadRequest – Invalid data in the provided channel.
HTTPException – The creation failed.

async fetch_emojis() → List[qord.models.emojis.Emoji]#

Fetches the emojis of this guild.

Returns: The list of emojis from this guild.
Return type: List[Emoji]
Raises: HTTPException – The fetching failed.

async fetch_emoji(emoji_id: int) → qord.models.emojis.Emoji#

Fetches the emoji from the given emoji ID.

Returns

The requested emoji.

Return type

Emoji

Raises

HTTPNotFound – Emoji with that ID does not exist.
HTTPException – The fetching failed.

async create_emoji(image: bytes, name: str, *, roles: Optional[List[qord.models.roles.Role]] = ..., reason: Optional[str] = None) → qord.models.emojis.Emoji#

Creates an emoji in the guild.

This operation requires manage_emojis_and_stickers permission in the parent emoji guild. The guild must also have a remaining slot available for emojis.

The size of given image data must be less than or equal to 256 KB or the creation would fail.

Parameters

image (builtins.bytes) – The image data for the emoji in form of bytes object.
name (builtins.str) – The name of emoji.
roles (Optional[List[Role]]) – The list of roles that can use this emoji. None or empty list denotes that emoji is unrestricted.

Returns

The created emoji.

Return type

Emoji

Raises

HTTPForbidden – You are not allowed to do this.
HTTPException – The creation of emoji failed.

async fetch_scheduled_events(with_user_counts: bool = False) → List[qord.models.scheduled_events.ScheduledEvent]#

Fetches the scheduled events currently scheduled or active in the guild.

Parameters: with_user_count (builtins.int) – Whether to include ScheduledEvent.user_count data in the returned scheduled events.
Returns: The list of fetched events.
Return type: List[ScheduledEvent]
Raises: HTTPException – Failed to fetch the events.

async fetch_scheduled_event(scheduled_event_id: int, with_user_counts: bool = False) → qord.models.scheduled_events.ScheduledEvent#

Fetches the scheduled event by it’s ID.

Parameters

scheduled_event_id (builtins.int) – The ID of event to fetch.
with_user_count (builtins.int) – Whether to include ScheduledEvent.user_count data in the returned scheduled event.

Returns

The requested event.

Return type

ScheduledEvent

Raises

HTTPNotFound – The event with that ID does not exist.
HTTPException – Failed to fetch the event.

async create_scheduled_event(*, name: str, starts_at: datetime.datetime, ends_at: datetime.datetime = ..., description: str = ..., privacy_level: int = 2, location: str = ..., entity_type: int = ..., cover_image: bytes = ..., channel: Union[qord.models.channels.VoiceChannel, qord.models.channels.StageChannel] = ..., reason: Optional[str] = None) → qord.models.scheduled_events.ScheduledEvent#

Creates a scheduled event in the guild.

This operation requires manage_events permission in the guild.

The channel and location keyword arguments are mutually exlusive and either one of them must be provided.

The value of entity_type keyword argument is inferred from what is being passed from channel or location that is:

If a VoiceChannel is passed in channel, The inferred value would be EventEntityType.VOICE
If a StageChannel is passed in channel, The inferred value would be EventEntityType.STAGE_INSTANCE
If a location is passed, The inferred value would be EventEntityType.EXTERNAL.

If the entity_type parameter is passed explicitly, the value is not inferred and the given value is considered without validation.

ends_at keyword argument is required when passing the location argument.

Parameters

name (builtins.str) – The name of event.
starts_at (datetime.datetime) – The time when the event should start.
ends_at (datetime.datetime) – The time when the event should end. Required when passing location, optional otherwise.
description (builtins.str) – The description of event.
privacy_level (builtins.int) – The privacy level of the event. Defaults to EventPrivacyLevel.GUILD_ONLY.
location (builtins.str) – The location where the event is hosted.
entity_type (builtins.int) – The type of entity for this event. This parameter is inferred automatically when not given, see above.
cover_image (builtins.bytes) – The bytes representing the cover image of event.
channel (Union[VoiceChannel, StageChannel]) – The channel where the event is being hosted.
reason (builtins.str) – The reason for creating the event.

Returns

The created event.

Return type

ScheduledEvent

Raises

TypeError – Invalid arguments passed.
HTTPForbidden – You are not allowed to create the event.
HTTPException – Failed to create the event.

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

GuildMember#

class qord.GuildMember#

Representation of a guild member.

A guild member is simply a user that is part of a specific Guild. Every guild member has an underlying User object attached to it.

Note

This class provides shorthand properties to access the underlying user’s data however certain properties like name and avatar have different behaviour in this class.

For example, avatar and other avatar related methods and attributes also consider the guild specific avatar of member for relevant functionality with addition to user’s global avatar.

This class supports equality comparison between instances of this class by the id attribute.

guild#

The parent guild that this member belongs to.

Type: Guild

user#

The user associated to this member.

Type: User

nickname#

The nickname of this member in the guild. If member has no guild specific nickname set, This is None. See display_name property that aids in retrieving the name more efficiently.

Type: Optional[builtins.str]

guild_avatar#

The hash of avatar for this member in the guild. If member has no guild specific avatar set, This is None. See display_avatar property that aids in retrieving the avatar more efficiently.

Type: Optional[builtins.str]

deaf#

Whether the member is deafened in voice channels.

Type: builtins.bool

mute#

Whether the member is muted in voice channels.

Type: builtins.bool

pending#

Whether the member has passed the membership screening.

Type: builtins.bool

joined_at#

The time when member joined the guild.

Type: datetime.datetime

premium_since#

The time when member started boosting the guild if applicable. If member is not boosting the guild, This is None.

Type: Optional[datetime.datetime]

timeout_until#

The time until which member is timed out and cannot interact with the guild. If member is not timed out, This is None.

Note

This attribute may have a value set even if member is not actually timed out. In which case, The datetime object would be in past. See is_timed_out() check that covers all possible cases.

Type: Optional[datetime.datetime]

role_ids#

The list of IDs of roles that are associated to this member.

Type: List[builtins.int]

roles#

The list of roles associated to this member.

Type: List[Role]

property id#: Shorthand property for User.id.

property discriminator#: Shorthand property for User.discriminator.

property bot#: Shorthand property for User.bot.

property system#: Shorthand property for User.system.

property accent_color#: Shorthand property for User.accent_color.

property locale#: Shorthand property for User.locale.

property flags#: Shorthand property for User.flags.

property public_flags#: Shorthand property for User.public_flags.

property premium_type#: Shorthand property for User.premium_type.

property banner#: Shorthand property for User.banner.

property mention#: Shorthand property for User.mention.

property proper_name#: Shorthand property for User.proper_name.

property default_avatar#: Shorthand property for User.default_avatar.

property default_avatar_url#: Shorthand property for User.default_avatar_url.

property banner_url#: Shorthand property for User.banner_url.

property is_banner_animated#: Shorthand property for User.is_banner_animated.

property create_dm#: Shorthand property for User.create_dm.

property send#: Shorthand property for User.send.

property name: str#

Returns the name of this member as displayed in the guild.

This property would return the nickname of the member if it’s present and would fallback to underlying user’s name if nickname is not available.

Return type: builtins.str

property avatar: Optional[str]#

Returns the avatar’s hash of this member as displayed in the guild.

This property would return the guild_avatar of this member if available and would fallback to underlying user’s avatar when unavailable. If user has no avatar set, None would be returned.

Return type: Optional[builtins.str]

avatar_url(extension: str = ..., size: int = ...) → Optional[str]#

Returns the avatar URL for this member.

This method returns URL for the member’s displayed avatar i.e use the guild specific member avatar if present otherwise user’s global avatar. If none of these avatars are set, The result of default_avatar_url() is returned instead.

The extension parameter only supports following extensions in the case of avatars:

ImageExtension.GIF
ImageExtension.PNG
ImageExtension.JPG
ImageExtension.JPEG
ImageExtension.WEBP

Parameters

extension (builtins.str) – The extension to use in the URL. If not supplied, An ideal extension will be picked depending on whether member has static or animated avatar.
size (builtins.int) – The size to append to URL. Can be any power of 2 between 64 and 4096.

Raises

ValueError – Invalid extension or size was passed.

is_avatar_animated() → bool#

Checks whether the member’s avatar is animated.

This method checks for the avatar to be animated i.e either one of member’s guild specific or underlying user’s avatar should be animated. To check specifically for the underlying user’s avatar, Consider using User.is_avatar_animated() instead.

Return type: builtins.bool

is_boosting() → bool#

Checks whether the member is boosting the guild.

Return type: builtins.bool

is_timed_out() → bool#

Checks whether the member is timed out.

Return type: builtins.bool

permissions() → qord.flags.permissions.Permissions#

Computes the permissions for this member in the parent guild.

This returns overall permissions for this member in the guild. In order to get more precise permissions set for the member in a specific guild channel, Consider using permissions_in() that also takes channel’s overwrites into account while computation.

Returns: The computed permissions.
Return type: Permissions

permissions_in(channel: GuildChannel) → Permissions#

Computes the permissions of this member in a GuildChannel.

This method computes the permissions by taking in account the member’s base permissions as well as the permission overrides of that channel.

Parameters: channel (GuildChannel) – The target channel for which the member’s permissions should be computed.
Returns: The computed permissions.
Return type: Permissions

async kick(*, reason: Optional[str] = None) → None#

Kicks the member from the associated guild.

Bot requires the kick_members permission in the relevant guild to perform this action.

Parameters

reason (builtins.str) – The reason for this action that shows up on audit log.

Raises

HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

async edit(*, nickname: Optional[str] = ..., roles: Optional[List[Role]] = ..., mute: bool = ..., deaf: bool = ..., timeout_until: datetime = ..., channel: Optional[VoiceChannel] = ..., reason: Optional[str] = None)#

Edits this member.

When successfully edited, The member instance would be updated with new data in place.

Parameters

nickname (Optional[builtins.str]) – The member’s guild nickname. None could be used to remove the nickname and reset guild name to the default username.
roles (List[Role]) – The list of roles to apply on members. None can be used to remove all roles. It is important to note that the roles provided in this parameter are overwritten to the existing roles. To work with roles in an efficient way, Consider using add_roles() and remove_roles() methods.
mute (builtins.bool) – Whether the member is muted in the voice channels.
deaf (builtins.bool) – Whether the member is deafened in the voice channels.
timeout_until (datetime.datetime) – The time until the member will be timed out. None can be used to remove timeout.
channel (Optional[VoiceChannel]) – The channel to move this member to, requires member to be in a voice channel already. None can be used to disconnect the member from existing voice channel.
reason (builtins.str) – The reason for this action that shows up on audit log.

Raises

HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

async add_roles(*roles: Role, overwrite: bool = False, ignore_extra: bool = True, reason: Optional[str] = None) → List[Role]#

Adds the provided roles to the members.

The behaviour of this method is summarized as:

The default behaviour is, roles to add are passed as positional arguments and they are added to the user without overwriting the previous roles.
When overwrite keyword parameter is set to True, The provided roles will be bulkly added and previous roles of the member would be overwritten. This is equivalent to roles parameter in edit().
When ignore_extra is False, Will always attempt to add the role regardless of whether the role already exists on the member. This would cause unnecessary API calls.
Returns the list of roles that were added to the member.

Parameters

*roles (Role) – The roles to add, passed as positional arguments.
overwrite (builtins.bool) – Whether to overwrite existing roles with new ones.
ignore_extra (builtins.bool) – Whether to ignore extra roles that already exist on members. Defaults to True.
reason (builtins.str) – The reason for performing this action.

Returns

The list of added roles. This only includes roles that were actually added and not the ones that were provided but weren’t added because they already exist on member.

Return type

List[Role]

property client: Client#: The Client that had instansiated this model.

property dm#: Shorthand property for User.dm.

async remove_roles(*roles: Role, ignore_extra: bool = True, reason: Optional[str] = None) → List[Role]#

Removes the provided roles from the members.

The behaviour of this method is summarized as:

The default behaviour is, roles to remove are passed as positional arguments and they are added to the user without overwriting the previous roles.
Calling this method without any roles passed will remove all roles from the member.
When ignore_extra is False, Will always attempt to remove the role regardless of whether the role is already not on the member. This would cause unnecessary API calls.
Returns the list of roles that were removed to the member.

Parameters

*roles (Role) – The roles to remove, passed as positional arguments.
ignore_extra (builtins.bool) – Whether to ignore extra roles that are already not on member. Defaults to True.
reason (builtins.str) – The reason for performing this action.

Returns

The list of removed roles. This only includes roles that were actually removed and not the ones that were provided but weren’t removed because they already exist on member.

Return type

List[Role]

Role#

class qord.Role#

Representation of a guild’s role.

This class supports equality comparison between instances of this class by the id attribute.

guild#

The guild that this role belongs to.

Type: Guild

id#

The snowflake ID of this role.

Type: builtins.int

name#

The name of this role.

Type: builtins.str

position#

The position of this role in the roles hierarchy.

Warning

Multiple roles in a guild may share same position. This is a Discord API limitation. As such, Do not rely on this attribute when comparing roles positions, Consider using is_higher_than() and is_lower_than() methods instead that efficiently check the role positions.

Type: builtins.int

color#

The integer representation of color of this role.

Type: builtins.int

permissions#

The permissions of this role.

Type: Permissions

hoist#

Whether members with this role are shown separately from other online members in the members list.

Type: builtins.bool

managed#

Whether this role is managed by an integration.

Type: builtins.bool

mentionable#

Whether this role is mentionable by other roles.

Type: builtins.bool

icon#

The icon hash for this role. If role has no icon set, This is None

Type: Optional[builtins.str]

unicode_emoji#

The unicode emoji set as icon of this role. None indicates that this role has no unicode emoji set.

Type: Optional[builtins.str]

bot_id#

The ID of bot that this role is for if any. If this role is not managed by a bot, then this is None.

Type: Optional[builtins.int]

integration_id#

The ID of integration that this role is for if any. If this role is not managed by an integration, then this is None.

Type: Optional[builtins.int]

premium_subscriber#

Whether this role is the guild’s “Server Booster” role and is given to members that boost the guild.

Type: builtins.bool

property mention: str#

Returns the string used for mentioning this role in Discord.

Return type: builtins.str

icon_url(extension: str = ..., size: int = ...) → Optional[str]#

Returns the icon URL for this user.

If role has no icon set, This method would return None.

The extension parameter only supports following extensions in the case of role icons:

ImageExtension.PNG
ImageExtension.JPG
ImageExtension.JPEG
ImageExtension.WEBP

Parameters

extension (builtins.str) – The extension to use in the URL. If not supplied, Defaults to PNG.
size (builtins.int) – The size to append to URL. Can be any power of 2 between 64 and 4096.

Raises

ValueError – Invalid extension or size was passed.

is_bot_managed() → bool#

Checks whether the role is managed by a bot.

Bot managed roles don’t have the bot_id set to None.

Return type: builtins.bool

is_integration_managed() → bool#

Checks whether the role is managed by an integration.

Integration managed roles don’t have the bot_id set to None.

Return type: builtins.bool

is_default() → bool#

Checks whether this role is the guild’s default i.e the “@everyone” role.

Guild default roles have the same ID as the parent guild.

Return type: builtins.bool

is_higher_than(other: qord.models.roles.Role) → bool#

Compares this role with another role of the same guild and checks whether this role is higher than the other.

Parameters: other (Role) – The role to check against.
Raises: RuntimeError – The provided role is not associated to the guild that this role is associated to.

is_lower_than(other: qord.models.roles.Role) → bool#

Compares this role with another role of the same guild and checks whether this role is lower than the other.

Parameters: other (Role) – The role to check against.
Raises: RuntimeError – The provided role is not associated to the guild that this role is associated to.

async delete(*, reason: Optional[str] = None) → None#

Deletes this role.

This operation requires the manage_roles permission for the client user in the guild.

Parameters

reason (builtins.str) – The reason for performing this operation that shows up on the audit log entry.

Raises

HTTPForbidden – You are missing the manage_roles permissions.
HTTPException – The deletion failed failed.

permissions_in(channel: qord.models.channels.GuildChannel) → qord.flags.permissions.Permissions#

Computes the permissions of this role in a GuildChannel.

This method computes the permissions by taking in account the role’s base permissions as well as the permission overrides of that channel.

Parameters: channel (GuildChannel) – The target channel for which the role’s permissions should be computed.
Returns: The computed permissions.
Return type: Permissions

async edit(*, name: str = ..., permissions: qord.flags.permissions.Permissions = ..., hoist: bool = ..., mentionable: bool = ..., icon: Optional[bytes] = ..., unicode_emoji: Optional[str] = ..., color: Optional[int] = ..., reason: Optional[str] = None) → None#

Edits this role.

This operation requires the manage_roles permission for the client user in the parent guild.

When the request is successful, This role is updated in place with the returned data.

Parameters

name (builtins.str) – The name of this role.
permissions (Permissions) – The permissions for this role.
color (typing.Optional[builtins.int]) – The color value of this role. None can be used to reset the role color to default.
hoist (builtins.bool) – Whether this role should appear hoisted from other roles.
icon (typing.Optional[builtins.bytes]) – The bytes representing the icon of this role. The guild must have ROLES_ICON feature to set this. This parameter cannot be mixed with unicode_emoji. None can be used to remove the icon.
unicode_emoji (typing.Optional[builtins.str]) – The unicode emoji used as icon for this role. The guild must have ROLES_ICON feature to set this. This parameter cannot be mixed with icon. None can be used to remove the icon.
mentionable (builtins.bool) – Whether this role is mentionable.
reason (builtins.str) – The reason for performing this action that shows up on the audit log entry.

Raises

HTTPForbidden – You are missing the manage_roles permissions.
HTTPException – The editing failed.

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

GuildChannel#

class qord.GuildChannel#

The base class for channel types that are associated to a specific guild.

For each channel types, Library provides separate subclasses that implement related functionality for that channel type.

Following classes currently inherit this class:

TextChannel
NewsChannel
CategoryChannel
VoiceChannel
StageChannel

This class supports equality comparison between instances of this class by the id attribute.

guild#

The guild associated to this channel.

Type: Guild

id#

The ID of this channel.

Type: builtins.int

type#

The type of this channel. See ChannelType for more information.

Type: builtins.int

name#

The name of this channel.

Type: builtins.str

position#

The position of this channel in channels list.

Type: builtins.int

parent_id#

The ID of category that this channel is associated to.

Type: builtins.int

property mention: str#

The string used for mentioning the channel in Discord client.

Return type: builtins.str

property permissions: List[qord.models.channels.ChannelPermission]#

The list of permission overwrites set on this channel.

Return type: List[ChannelPermission]

property url: str#

The URL for this channel.

Return type: builtins.str

permission_overwrite_for(target: Union[GuildMember, User, Role]) → Optional[PermissionOverwrite]#

Gets the permission overwrite for the given target.

Parameters: target (Union[Role, User, GuildMember]) – The target to get the overwrite for.
Returns: The permission overwrite, if any. If no overwrite is explicitly configured, None is returned.
Return type: Optional[PermissionOverwrite]

async delete(*, reason: Optional[str] = None) → None#

Deletes this channel.

Requires the manage_channels on the bot in the parent guild for performing this action.

Parameters

reason (builtins.str) – The reason for performing this action.

Raises

HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

async set_permission_overwrite(target: Union[GuildMember, User, Role], overwrite: PermissionOverwrite, reason: Optional[str] = None) → None#

Sets a permission overwrite for the given target on the channel.

This requires manage_channels permission for the given channel and only those permissions that the bot has can be overriden in the overwrite.

Parameters

target (Union[GuildMember, User, Role]) – The role or member for which the permission overwrite is being set.
overwrite (PermissionOverwrite) – The new permission overwrite to set.
reason (builtins.str) – The audit log reason for this operation.

Raises

HTTPForbidden – You are not allowed to do this or you are trying to override permissions that are not on the bot.
HTTPException – The operation failed.

async remove_permission_overwrite(target: Union[GuildMember, User, Role], reason: Optional[str] = None) → None#

Removes the permission overwrite for the given targets.

This requires manage_channels permission in the given channel.

Parameters

target (Union[GuildMember, User, Role]) – The role or member for which the permission overwrite is being removed.
reason (builtins.str) – The audit log reason for this operation.

Raises

HTTPForbidden – You are not allowed to do this.
HTTPNotFound – Permission overwrite does not exist for this user.
HTTPException – The operation failed.

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

CategoryChannel#

class qord.CategoryChannel#

Represents a category channel that holds other guild channels.

This class inherits the GuildChannel class.

property channels: List[qord.models.channels.GuildChannel]#

The list of channels associated to this category.

Return type: List[GuildChannel]

async edit(*, name: str = ..., position: int = ..., permission_overwrites: Dict[Union[GuildMember, User, Role], PermissionOverwrite] = ..., reason: Optional[str] = None) → None#

Edits the channel.

This operation requires the manage_channels permission for the client user in the parent guild.

When the request is successful, This channel is updated in place with the returned data.

Parameters

name (builtins.str) – The name of this channel.
position (builtins.int) – The position of this channel in channels list.
permission_overwrites (Dict[Union[GuildMember, User, Role], PermissionOverwrite]) – The permission overwrites of this channel. This is a dictionary with key being the target whose permission overwrite is being edited and value is the new permission overwrite.
reason (builtins.str) – The reason for performing this action that shows up on guild’s audit log.

Raises

ValueError – Invalid values supplied in some arguments.
HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

async delete(*, reason: Optional[str] = None) → None#

Deletes this channel.

Requires the manage_channels on the bot in the parent guild for performing this action.

Parameters

reason (builtins.str) – The reason for performing this action.

Raises

HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

property mention: str#

The string used for mentioning the channel in Discord client.

Return type: builtins.str

permission_overwrite_for(target: Union[GuildMember, User, Role]) → Optional[PermissionOverwrite]#

Gets the permission overwrite for the given target.

Parameters: target (Union[Role, User, GuildMember]) – The target to get the overwrite for.
Returns: The permission overwrite, if any. If no overwrite is explicitly configured, None is returned.
Return type: Optional[PermissionOverwrite]

property permissions: List[qord.models.channels.ChannelPermission]#

The list of permission overwrites set on this channel.

Return type: List[ChannelPermission]

async remove_permission_overwrite(target: Union[GuildMember, User, Role], reason: Optional[str] = None) → None#

Removes the permission overwrite for the given targets.

This requires manage_channels permission in the given channel.

Parameters

target (Union[GuildMember, User, Role]) – The role or member for which the permission overwrite is being removed.
reason (builtins.str) – The audit log reason for this operation.

Raises

HTTPForbidden – You are not allowed to do this.
HTTPNotFound – Permission overwrite does not exist for this user.
HTTPException – The operation failed.

async set_permission_overwrite(target: Union[GuildMember, User, Role], overwrite: PermissionOverwrite, reason: Optional[str] = None) → None#

Sets a permission overwrite for the given target on the channel.

This requires manage_channels permission for the given channel and only those permissions that the bot has can be overriden in the overwrite.

Parameters

target (Union[GuildMember, User, Role]) – The role or member for which the permission overwrite is being set.
overwrite (PermissionOverwrite) – The new permission overwrite to set.
reason (builtins.str) – The audit log reason for this operation.

Raises

HTTPForbidden – You are not allowed to do this or you are trying to override permissions that are not on the bot.
HTTPException – The operation failed.

property url: str#

The URL for this channel.

Return type: builtins.str

TextChannel#

class qord.TextChannel#

Represents a text messages based channel in a guild.

This class inherits GuildChannel and BaseMessageChannel.

topic#

The topic of this channel.

Type: Optional[builtins.str]

last_message_id#

The ID of last message sent in this channel. Due to Discord limitation, This may not point to the actual last message of the channel.

Type: Optional[builtins.int]

slowmode_delay#

The slowmode per user (in seconds) that is set on this channel.

Type: builtins.int

nsfw#

Whether this channel is marked as NSFW.

Type: builtins.bool

default_auto_archive_duration#

The default auto archiving duration (in minutes) of this channel after which in active threads associated to this channel are automatically archived.

Type: builtins.int

last_pin_timestamp#

The time when last pin in this channel was created.

Type: Optional[datetime.datetime]

async edit(*, name: str = ..., type: int = ..., position: int = ..., nsfw: bool = ..., parent: Optional[CategoryChannel] = ..., topic: Optional[str] = ..., slowmode_delay: Optional[int] = ..., default_auto_archive_duration: int = ..., permission_overwrites: Dict[Union[GuildMember, User, Role], PermissionOverwrite] = ..., reason: Optional[str] = None) → None#

Edits the channel.

This operation requires the manage_channels permission for the client user in the parent guild.

When the request is successful, This channel is updated in place with the returned data.

Parameters

name (builtins.str) – The name of this channel.
type (builtins.int) – The type of this channel. In this case, Only NEWS and TEXT are supported.
position (builtins.int) – The position of this channel in channels list.
parent (Optional[CategoryChannel]) – The parent category in which this channel should be moved to. None to remove current category of this channel.
nsfw (builtins.bool) – Whether this channel is marked as NSFW.
topic (Optional[builtins.str]) – The topic of this channel. None can be used to remove the topic.
slowmode_delay (Optional[builtins.int]) – The slowmode delay of this channel (in seconds). None can be used to disable it. Cannot be greater then 21600 seconds.
default_auto_archive_duration (builtins.int) – The default auto archive duration after which in active threads are archived automatically (in minutes). Valid values are 60, 1440, 4320 and 10080.
permission_overwrites (Dict[Union[GuildMember, User, Role], PermissionOverwrite]) – The permission overwrites of this channel. This is a dictionary with key being the target whose permission overwrite is being edited and value is the new permission overwrite.
reason (builtins.str) – The reason for performing this action that shows up on guild’s audit log.

Raises

ValueError – Invalid values supplied in some arguments.
HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

async delete(*, reason: Optional[str] = None) → None#

Deletes this channel.

Requires the manage_channels on the bot in the parent guild for performing this action.

Parameters

reason (builtins.str) – The reason for performing this action.

Raises

HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

async fetch_message(message_id: int) → qord.models.messages.Message#

Fetches a Message from the provided message ID.

Parameters

message_id (builtins.int) – The ID of message to fetch.

Returns

The fetched message.

Return type

Message

Raises

HTTPNotFound – Invalid or unknown message ID passed. Message might be deleted.
HTTPForbidden – Missing permissions to fetch that message.
HTTPException – The fetching failed.

async fetch_pins() → List[qord.models.messages.Message]#

Fetches the messages that are currently pinned in the channel.

Returns

The pinned messages in the channel.

Return type

List[Message]

Raises

HTTPForbidden – Missing permissions to fetch the pins.
HTTPException – The fetching failed.

property mention: str#

The string used for mentioning the channel in Discord client.

Return type: builtins.str

An async iterator for iterating through the channel’s messages.

Requires the read_message_history permission as well as view_channels permission in the given channel.

after, before, around and oldest_first are all mutually exclusive parameters.

Parameters

limit (Optional[builtins.int]) – The number of messages to fetch. If None is given, All messages are fetched from the channel. Defaults to 100.
after (Union[datetime.datetime, builtins.int]) – For pagination, To fetch messages after this message ID or time.
before (Union[datetime.datetime, builtins.int]) – For pagination, To fetch messages before this message ID or time.
around (Union[datetime.datetime, builtins.int]) – For pagination, To fetch messages around this message ID or time. Requires the limit to be greater than 100.
oldest_first (builtins.bool) – Whether to fetch the messages in reversed order i.e oldest message to newer messages.

Yields

Message – The message from the channel.

permission_overwrite_for(target: Union[GuildMember, User, Role]) → Optional[PermissionOverwrite]#

Gets the permission overwrite for the given target.

Parameters: target (Union[Role, User, GuildMember]) – The target to get the overwrite for.
Returns: The permission overwrite, if any. If no overwrite is explicitly configured, None is returned.
Return type: Optional[PermissionOverwrite]

property permissions: List[qord.models.channels.ChannelPermission]#

The list of permission overwrites set on this channel.

Return type: List[ChannelPermission]

async remove_permission_overwrite(target: Union[GuildMember, User, Role], reason: Optional[str] = None) → None#

Removes the permission overwrite for the given targets.

This requires manage_channels permission in the given channel.

Parameters

target (Union[GuildMember, User, Role]) – The role or member for which the permission overwrite is being removed.
reason (builtins.str) – The audit log reason for this operation.

Raises

HTTPForbidden – You are not allowed to do this.
HTTPNotFound – Permission overwrite does not exist for this user.
HTTPException – The operation failed.

Sends a message to the channel.

If channel is a text based guild channel, This requires the send_messages permission in the channel.

For direct messages channel, No specific permission is required however relevant user must share a guild with the bot and the bot must not be blocked by the user.

Parameters

content (builtins.str) – The content of message.
allowed_mentions (AllowedMentions) – The mentions to allow in the message’s content.
flags (MessageFlags) – The message flags for the sent message. Bots can only apply the suppress_embeds flag. Other flags are unsupported.
embed (Embed) – The embed to include in message, cannot be mixed with embeds.
embeds (List[Embed]) – The list of embeds to include in the message, cannot be mixed with embed.
file (File) – The file to include in message, cannot be mixed with files.
files (List[File]) – The list of file attachments to send in message, cannot be mixed with file.
tts (builtins.bool) – Whether the sent message is a Text-To-Speech message.

Returns

The message that was sent.

Return type

Message

Raises

TypeError – Invalid arguments passed.
HTTPForbidden – You are not allowed to send message in this channel.
HTTPBadRequest – The message has invalid data.
HTTPException – The sending failed for some reason.

async set_permission_overwrite(target: Union[GuildMember, User, Role], overwrite: PermissionOverwrite, reason: Optional[str] = None) → None#

Sets a permission overwrite for the given target on the channel.

This requires manage_channels permission for the given channel and only those permissions that the bot has can be overriden in the overwrite.

Parameters

target (Union[GuildMember, User, Role]) – The role or member for which the permission overwrite is being set.
overwrite (PermissionOverwrite) – The new permission overwrite to set.
reason (builtins.str) – The audit log reason for this operation.

Raises

HTTPForbidden – You are not allowed to do this or you are trying to override permissions that are not on the bot.
HTTPException – The operation failed.

async trigger_typing() → None#

Triggers the typing indicator in the channel.

The typing indicator would automatically disappear after few seconds or once a message is sent in the channel.

Tip

Consider using typing() for a convenient context manager interface for triggering typing indicators.

Raises: HTTPException – Triggering typing failed.

typing() → qord.internal.context_managers.TypingContextManager#

Returns a context manager interface for triggering typing indicator in a channel.

Example:

async with channel.typing():
    # Typing indicator will appear until the context manager
    # is entered. Perform something heavy in this clause
    ...

property url: str#

The URL for this channel.

Return type: builtins.str

NewsChannel#

class qord.NewsChannel#

Represents a news channel that holds other guild channels.

This class inherits TextChannel so all attributes of TextChannel and GuildChannel classes are valid here too.

Currently this class has no extra functionality compared to TextChannel.

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

async delete(*, reason: Optional[str] = None) → None#

Deletes this channel.

Requires the manage_channels on the bot in the parent guild for performing this action.

Parameters

reason (builtins.str) – The reason for performing this action.

Raises

HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

Edits the channel.

This operation requires the manage_channels permission for the client user in the parent guild.

When the request is successful, This channel is updated in place with the returned data.

Parameters

name (builtins.str) – The name of this channel.
type (builtins.int) – The type of this channel. In this case, Only NEWS and TEXT are supported.
position (builtins.int) – The position of this channel in channels list.
parent (Optional[CategoryChannel]) – The parent category in which this channel should be moved to. None to remove current category of this channel.
nsfw (builtins.bool) – Whether this channel is marked as NSFW.
topic (Optional[builtins.str]) – The topic of this channel. None can be used to remove the topic.
slowmode_delay (Optional[builtins.int]) – The slowmode delay of this channel (in seconds). None can be used to disable it. Cannot be greater then 21600 seconds.
default_auto_archive_duration (builtins.int) – The default auto archive duration after which in active threads are archived automatically (in minutes). Valid values are 60, 1440, 4320 and 10080.
permission_overwrites (Dict[Union[GuildMember, User, Role], PermissionOverwrite]) – The permission overwrites of this channel. This is a dictionary with key being the target whose permission overwrite is being edited and value is the new permission overwrite.
reason (builtins.str) – The reason for performing this action that shows up on guild’s audit log.

Raises

ValueError – Invalid values supplied in some arguments.
HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

async fetch_message(message_id: int) → qord.models.messages.Message#

Fetches a Message from the provided message ID.

Parameters

message_id (builtins.int) – The ID of message to fetch.

Returns

The fetched message.

Return type

Message

Raises

HTTPNotFound – Invalid or unknown message ID passed. Message might be deleted.
HTTPForbidden – Missing permissions to fetch that message.
HTTPException – The fetching failed.

async fetch_pins() → List[qord.models.messages.Message]#

Fetches the messages that are currently pinned in the channel.

Returns

The pinned messages in the channel.

Return type

List[Message]

Raises

HTTPForbidden – Missing permissions to fetch the pins.
HTTPException – The fetching failed.

property mention: str#

The string used for mentioning the channel in Discord client.

Return type: builtins.str

An async iterator for iterating through the channel’s messages.

Requires the read_message_history permission as well as view_channels permission in the given channel.

after, before, around and oldest_first are all mutually exclusive parameters.

Parameters

limit (Optional[builtins.int]) – The number of messages to fetch. If None is given, All messages are fetched from the channel. Defaults to 100.
after (Union[datetime.datetime, builtins.int]) – For pagination, To fetch messages after this message ID or time.
before (Union[datetime.datetime, builtins.int]) – For pagination, To fetch messages before this message ID or time.
around (Union[datetime.datetime, builtins.int]) – For pagination, To fetch messages around this message ID or time. Requires the limit to be greater than 100.
oldest_first (builtins.bool) – Whether to fetch the messages in reversed order i.e oldest message to newer messages.

Yields

Message – The message from the channel.

permission_overwrite_for(target: Union[GuildMember, User, Role]) → Optional[PermissionOverwrite]#

Gets the permission overwrite for the given target.

Parameters: target (Union[Role, User, GuildMember]) – The target to get the overwrite for.
Returns: The permission overwrite, if any. If no overwrite is explicitly configured, None is returned.
Return type: Optional[PermissionOverwrite]

property permissions: List[qord.models.channels.ChannelPermission]#

The list of permission overwrites set on this channel.

Return type: List[ChannelPermission]

async remove_permission_overwrite(target: Union[GuildMember, User, Role], reason: Optional[str] = None) → None#

Removes the permission overwrite for the given targets.

This requires manage_channels permission in the given channel.

Parameters

target (Union[GuildMember, User, Role]) – The role or member for which the permission overwrite is being removed.
reason (builtins.str) – The audit log reason for this operation.

Raises

HTTPForbidden – You are not allowed to do this.
HTTPNotFound – Permission overwrite does not exist for this user.
HTTPException – The operation failed.

Sends a message to the channel.

If channel is a text based guild channel, This requires the send_messages permission in the channel.

For direct messages channel, No specific permission is required however relevant user must share a guild with the bot and the bot must not be blocked by the user.

Parameters

content (builtins.str) – The content of message.
allowed_mentions (AllowedMentions) – The mentions to allow in the message’s content.
flags (MessageFlags) – The message flags for the sent message. Bots can only apply the suppress_embeds flag. Other flags are unsupported.
embed (Embed) – The embed to include in message, cannot be mixed with embeds.
embeds (List[Embed]) – The list of embeds to include in the message, cannot be mixed with embed.
file (File) – The file to include in message, cannot be mixed with files.
files (List[File]) – The list of file attachments to send in message, cannot be mixed with file.
tts (builtins.bool) – Whether the sent message is a Text-To-Speech message.

Returns

The message that was sent.

Return type

Message

Raises

TypeError – Invalid arguments passed.
HTTPForbidden – You are not allowed to send message in this channel.
HTTPBadRequest – The message has invalid data.
HTTPException – The sending failed for some reason.

async set_permission_overwrite(target: Union[GuildMember, User, Role], overwrite: PermissionOverwrite, reason: Optional[str] = None) → None#

Sets a permission overwrite for the given target on the channel.

This requires manage_channels permission for the given channel and only those permissions that the bot has can be overriden in the overwrite.

Parameters

target (Union[GuildMember, User, Role]) – The role or member for which the permission overwrite is being set.
overwrite (PermissionOverwrite) – The new permission overwrite to set.
reason (builtins.str) – The audit log reason for this operation.

Raises

HTTPForbidden – You are not allowed to do this or you are trying to override permissions that are not on the bot.
HTTPException – The operation failed.

async trigger_typing() → None#

Triggers the typing indicator in the channel.

The typing indicator would automatically disappear after few seconds or once a message is sent in the channel.

Tip

Consider using typing() for a convenient context manager interface for triggering typing indicators.

Raises: HTTPException – Triggering typing failed.

typing() → qord.internal.context_managers.TypingContextManager#

Returns a context manager interface for triggering typing indicator in a channel.

Example:

async with channel.typing():
    # Typing indicator will appear until the context manager
    # is entered. Perform something heavy in this clause
    ...

property url: str#

The URL for this channel.

Return type: builtins.str

VoiceChannel#

class qord.VoiceChannel#

Represents a voice channel in a guild.

This class inherits the GuildChannel class.

bitrate#

The bitrate of this channel, in bits.

Type: builtins.int

user_limit#

The number of users that can connect to this channel at a time. The value of 0 indicates that there is no limit set.

Type: builtins.int

rtc_region#

The string representation of RTC region of the voice channel. This is only available when a region is explicitly set. None indicates that region is chosen automatically.

Type: Optional[builtins.str]

video_quality_mode#

The video quality mode of this channel. See VideoQualityMode for more information.

Type: builtins.int

async edit(*, name: str = ..., position: int = ..., bitrate: int = ..., parent: Optional[CategoryChannel] = ..., rtc_region: Optional[str] = ..., user_limit: Optional[int] = ..., video_quality_mode: int = ..., permission_overwrites: Dict[Union[GuildMember, User, Role], PermissionOverwrite] = ..., reason: Optional[str] = None) → None#

Edits the channel.

This operation requires the manage_channels permission for the client user in the parent guild.

When the request is successful, This channel is updated in place with the returned data.

Parameters

name (builtins.str) – The name of this channel.
position (builtins.int) – The position of this channel in channels list.
parent (Optional[CategoryChannel]) – The parent category in which this channel should be moved to. None to remove current category of this channel.
bitrate (builtins.int) – The bitrate of this channel in bits. This value can be in range of 8000 and 96000 (128000 for VIP servers).
rtc_region (Optional[builtins.str]) – The RTC region of this voice channel. None can be used to set this to automatic selection of regions.
user_limit (Optional[builtins.int]) – The number of users that can connect to the channel at a time. None or 0 will remove the explicit limit allowing unlimited number of users.
video_quality_mode (builtins.int) – The video quality mode of the voice channel. See VideoQualityMode for valid values.
permission_overwrites (Dict[Union[GuildMember, User, Role], PermissionOverwrite]) – The permission overwrites of this channel. This is a dictionary with key being the target whose permission overwrite is being edited and value is the new permission overwrite.
reason (builtins.str) – The reason for performing this action that shows up on guild’s audit log.

Raises

ValueError – Invalid values supplied in some arguments.
HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

async delete(*, reason: Optional[str] = None) → None#

Deletes this channel.

Requires the manage_channels on the bot in the parent guild for performing this action.

Parameters

reason (builtins.str) – The reason for performing this action.

Raises

HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

property mention: str#

The string used for mentioning the channel in Discord client.

Return type: builtins.str

permission_overwrite_for(target: Union[GuildMember, User, Role]) → Optional[PermissionOverwrite]#

Gets the permission overwrite for the given target.

Parameters: target (Union[Role, User, GuildMember]) – The target to get the overwrite for.
Returns: The permission overwrite, if any. If no overwrite is explicitly configured, None is returned.
Return type: Optional[PermissionOverwrite]

property permissions: List[qord.models.channels.ChannelPermission]#

The list of permission overwrites set on this channel.

Return type: List[ChannelPermission]

async remove_permission_overwrite(target: Union[GuildMember, User, Role], reason: Optional[str] = None) → None#

Removes the permission overwrite for the given targets.

This requires manage_channels permission in the given channel.

Parameters

target (Union[GuildMember, User, Role]) – The role or member for which the permission overwrite is being removed.
reason (builtins.str) – The audit log reason for this operation.

Raises

HTTPForbidden – You are not allowed to do this.
HTTPNotFound – Permission overwrite does not exist for this user.
HTTPException – The operation failed.

async set_permission_overwrite(target: Union[GuildMember, User, Role], overwrite: PermissionOverwrite, reason: Optional[str] = None) → None#

Sets a permission overwrite for the given target on the channel.

This requires manage_channels permission for the given channel and only those permissions that the bot has can be overriden in the overwrite.

Parameters

target (Union[GuildMember, User, Role]) – The role or member for which the permission overwrite is being set.
overwrite (PermissionOverwrite) – The new permission overwrite to set.
reason (builtins.str) – The audit log reason for this operation.

Raises

HTTPForbidden – You are not allowed to do this or you are trying to override permissions that are not on the bot.
HTTPException – The operation failed.

property url: str#

The URL for this channel.

Return type: builtins.str

StageChannel#

class qord.StageChannel#

Represents a stage channel in a guild.

This class is a subclass of VoiceChannel as such all attributes of VoiceChannel and GuildChannel are valid in this class too.

property stage_instance: Optional[qord.models.stage_instances.StageInstance]#

The stage instance belonging to this channel. If any.

Return type: Optional[StageInstance]

async fetch_stage_instance() → qord.models.stage_instances.StageInstance#

Fetches the stage instance for this channel.

Returns: The stage instance for this channel.
Return type: StageInstance
Raises: HTTPNotFound – No instance belongs to the channel.

async create_stage_instance(*, topic: str, privacy_level: int = 2, send_start_notification: bool = ..., reason: Optional[str] = None) → qord.models.stage_instances.StageInstance#

Creates a stage instance in this channel.

This operation requires the bot to be stage moderator, i.e has following permissions in the stage channel:

manage_channels
move_members
mute_members

Additionally, when setting send_start_notification to True, The mention_everyone permission is required.

Parameters

topic (builtins.str) – The topic of stage instance.
privacy_level (builtins.int) – The privacy level of stage instance. See StagePrivacyLevel for all possible values. Defaults to GUILD_ONLY.
send_start_notification (builtins.bool) – Whether to send start notification to guild members. Defaults to False.
reason (builtins.str) – The reason for doing this action.

Returns

The created stage instance.

Return type

StageInstance

Raises

HTTPForbidden – You are not allowed to do this.
HTTPException – The operation failed.

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

async delete(*, reason: Optional[str] = None) → None#

Deletes this channel.

Requires the manage_channels on the bot in the parent guild for performing this action.

Parameters

reason (builtins.str) – The reason for performing this action.

Raises

HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

Edits the channel.

This operation requires the manage_channels permission for the client user in the parent guild.

When the request is successful, This channel is updated in place with the returned data.

Parameters

name (builtins.str) – The name of this channel.
position (builtins.int) – The position of this channel in channels list.
parent (Optional[CategoryChannel]) – The parent category in which this channel should be moved to. None to remove current category of this channel.
bitrate (builtins.int) – The bitrate of this channel in bits. This value can be in range of 8000 and 96000 (128000 for VIP servers).
rtc_region (Optional[builtins.str]) – The RTC region of this voice channel. None can be used to set this to automatic selection of regions.
user_limit (Optional[builtins.int]) – The number of users that can connect to the channel at a time. None or 0 will remove the explicit limit allowing unlimited number of users.
video_quality_mode (builtins.int) – The video quality mode of the voice channel. See VideoQualityMode for valid values.
permission_overwrites (Dict[Union[GuildMember, User, Role], PermissionOverwrite]) – The permission overwrites of this channel. This is a dictionary with key being the target whose permission overwrite is being edited and value is the new permission overwrite.
reason (builtins.str) – The reason for performing this action that shows up on guild’s audit log.

Raises

ValueError – Invalid values supplied in some arguments.
HTTPForbidden – Missing permissions.
HTTPException – Failed to perform this action.

property mention: str#

The string used for mentioning the channel in Discord client.

Return type: builtins.str

permission_overwrite_for(target: Union[GuildMember, User, Role]) → Optional[PermissionOverwrite]#

Gets the permission overwrite for the given target.

Parameters: target (Union[Role, User, GuildMember]) – The target to get the overwrite for.
Returns: The permission overwrite, if any. If no overwrite is explicitly configured, None is returned.
Return type: Optional[PermissionOverwrite]

property permissions: List[qord.models.channels.ChannelPermission]#

The list of permission overwrites set on this channel.

Return type: List[ChannelPermission]

async remove_permission_overwrite(target: Union[GuildMember, User, Role], reason: Optional[str] = None) → None#

Removes the permission overwrite for the given targets.

This requires manage_channels permission in the given channel.

Parameters

target (Union[GuildMember, User, Role]) – The role or member for which the permission overwrite is being removed.
reason (builtins.str) – The audit log reason for this operation.

Raises

HTTPForbidden – You are not allowed to do this.
HTTPNotFound – Permission overwrite does not exist for this user.
HTTPException – The operation failed.

async set_permission_overwrite(target: Union[GuildMember, User, Role], overwrite: PermissionOverwrite, reason: Optional[str] = None) → None#

Sets a permission overwrite for the given target on the channel.

This requires manage_channels permission for the given channel and only those permissions that the bot has can be overriden in the overwrite.

Parameters

target (Union[GuildMember, User, Role]) – The role or member for which the permission overwrite is being set.
overwrite (PermissionOverwrite) – The new permission overwrite to set.
reason (builtins.str) – The audit log reason for this operation.

Raises

HTTPForbidden – You are not allowed to do this or you are trying to override permissions that are not on the bot.
HTTPException – The operation failed.

property url: str#

The URL for this channel.

Return type: builtins.str

PrivateChannel#

class qord.PrivateChannel#

Base class for channel types that are private and not associated to a guild.

Currently only one channel type is available for private channels that is DMChannel.

This class supports equality comparison between instances of this class by the id attribute.

id#

The ID of this channel.

Type: builtins.int

type#

The type of this channel. See ChannelType for valid values.

Type: builtins.int

property url: str#

The URL for this channel.

Return type: builtins.str

async close() → None#

Closes the private channel.

This should rarely be used. The channel may be reopened using relevant methods like User.create_dm() for DM channels.

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

DMChannel#

class qord.DMChannel#

Represents a direct message channel between two users.

This class inherits PrivateChannel.

recipient#

The user that this direct message is with.

Type: User

last_message_id#

The ID of last message associated to this channel. May not be accurate.

Type: Optional[builtins.int]

last_pin_timestamp#

The time when last pin in the channel was created.

Type: Optional[datetime]

property client: Client#: The Client that had instansiated this model.

async close() → None#

Closes the private channel.

This should rarely be used. The channel may be reopened using relevant methods like User.create_dm() for DM channels.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

async fetch_message(message_id: int) → qord.models.messages.Message#

Fetches a Message from the provided message ID.

Parameters

message_id (builtins.int) – The ID of message to fetch.

Returns

The fetched message.

Return type

Message

Raises

HTTPNotFound – Invalid or unknown message ID passed. Message might be deleted.
HTTPForbidden – Missing permissions to fetch that message.
HTTPException – The fetching failed.

async fetch_pins() → List[qord.models.messages.Message]#

Fetches the messages that are currently pinned in the channel.

Returns

The pinned messages in the channel.

Return type

List[Message]

Raises

HTTPForbidden – Missing permissions to fetch the pins.
HTTPException – The fetching failed.

An async iterator for iterating through the channel’s messages.

Requires the read_message_history permission as well as view_channels permission in the given channel.

after, before, around and oldest_first are all mutually exclusive parameters.

Parameters

limit (Optional[builtins.int]) – The number of messages to fetch. If None is given, All messages are fetched from the channel. Defaults to 100.
after (Union[datetime.datetime, builtins.int]) – For pagination, To fetch messages after this message ID or time.
before (Union[datetime.datetime, builtins.int]) – For pagination, To fetch messages before this message ID or time.
around (Union[datetime.datetime, builtins.int]) – For pagination, To fetch messages around this message ID or time. Requires the limit to be greater than 100.
oldest_first (builtins.bool) – Whether to fetch the messages in reversed order i.e oldest message to newer messages.

Yields

Message – The message from the channel.

Sends a message to the channel.

If channel is a text based guild channel, This requires the send_messages permission in the channel.

For direct messages channel, No specific permission is required however relevant user must share a guild with the bot and the bot must not be blocked by the user.

Parameters

content (builtins.str) – The content of message.
allowed_mentions (AllowedMentions) – The mentions to allow in the message’s content.
flags (MessageFlags) – The message flags for the sent message. Bots can only apply the suppress_embeds flag. Other flags are unsupported.
embed (Embed) – The embed to include in message, cannot be mixed with embeds.
embeds (List[Embed]) – The list of embeds to include in the message, cannot be mixed with embed.
file (File) – The file to include in message, cannot be mixed with files.
files (List[File]) – The list of file attachments to send in message, cannot be mixed with file.
tts (builtins.bool) – Whether the sent message is a Text-To-Speech message.

Returns

The message that was sent.

Return type

Message

Raises

TypeError – Invalid arguments passed.
HTTPForbidden – You are not allowed to send message in this channel.
HTTPBadRequest – The message has invalid data.
HTTPException – The sending failed for some reason.

async trigger_typing() → None#

Triggers the typing indicator in the channel.

The typing indicator would automatically disappear after few seconds or once a message is sent in the channel.

Tip

Consider using typing() for a convenient context manager interface for triggering typing indicators.

Raises: HTTPException – Triggering typing failed.

typing() → qord.internal.context_managers.TypingContextManager#

Returns a context manager interface for triggering typing indicator in a channel.

Example:

async with channel.typing():
    # Typing indicator will appear until the context manager
    # is entered. Perform something heavy in this clause
    ...

property url: str#

The URL for this channel.

Return type: builtins.str

ChannelPermission#

class qord.ChannelPermission#

Represents the detail of a channel permission override for a specific target.

This class supports comparison between other ChannelPermission objects considering both having same target and same permission overrides.

target_id#

The ID of target that this permission overwrite is for. This can either be ID of a role or member.

Type: builtins.int

type#

The type of target that this permission overwrite is for. See ChannelPermissionType for possible values.

Type: builtins.int

permission_overwrite#

The permission overwrite for the given target.

Type: PermissionOverwrite

property target: Optional[Union[Role, GuildMember]]#

The target that the permission is for.

Note

This property is resolved from relevant channel’s guild cache. If the client is missing Intents.members and the permission override is for a guild member, This would potentially return None. In which case, you should consider fetching the member directly using the given target_id

Returns: The resolved target, or None if couldn’t be resolved.
Return type: Optional[Role, GuildMember]

Message#

class qord.Message#

Represents a message generated in channels by users, bots and webhooks.

This class supports equality comparison between instances of this class by the id attribute.

channel#

The channel in which message was sent.

Type: Union[TextChannel, DMChannel]

id#

The ID of this message.

Type: builtins.int

type#

The type of this message. See MessageType for possible values.

Type: builtins.int

channel_id#

The channel ID that the message was sent in.

Type: builtins.int

created_at#

The time when this message was sent.

Type: datetime.datetime

tts#

Whether the message is a TTS message.

Type: builtins.bool

mention_everyone#

Whether the @everyone role is mentioned in the message.

Type: builtins.bool

pinned#

Whether the message is pinned.

Type: builtins.bool

author#

The author of this message.

Note

This may not point to an actual user when the message is created by a webhook. If the webhook_id is not None then the user would represent the ID, name and avatar of the webhook and would not represent an “actual” user.

Type: Union[User, GuildMember]

mentions#

The list of mentions in this message.

Type: List[User, GuildMember]

mentioned_roles#

The list of roles mentioned in this message.

Type: List[Role]

mentioned_channels#

The list of channels mentioned in this message.

Type: List[ChannelMention]

guild#

The guild that this message belongs to.

Type: Optional[Guild]

content#

The content of this message.

Type: Optional[builtins.str]

nonce#

The nonce used for indicating whether the message was sent.

Type: Optional[Union[builtins.int, builtins.str]]

edited_at#

The time when the message was last edited or None if never.

Type: Optional[datetime.datetime]

guild_id#

The ID of guild that this message belongs to.

Type: Optional[builtins.int]

webhook_id#

The ID of webhook that generated this message. Note that when this is present, the author will be a “fake” User object represeting ID, name and avatar of the webhook and would not point to a valid user.

Type: Optional[builtins.int]

application_id#

The ID of application that generated this application only if the message is response to an interaction.

Type: Optional[builtins.int]

attachments#

The list of attachments attached to the message.

Type: List[Attachment]

embeds#

The list of embeds attached to the message.

Type: List[Embed]

reactions#

The list of reactions on this message.

Type: List[Reaction]

flags#

The flags of this message.

Type: MessageFlags

message_reference#

The referenced message if any, See the MessageReference documentation for the list of scenarios when this attribute is not None.

Type: Optional[MessageReference]

referenced_message#

The referenced message. This is only valid when type is either REPLY or THREAD_STARTER_MESSAGE.

For thread starter messages, This is always present. For replies however, If this is None, It indicates that either the message was deleted or wasn’t sent loaded by Discord API.

Type: Optional[Message]

property url: str#

The URL for this message.

Return type: builtins.str

async crosspost() → None#

Crossposts the message across the channels following the message’s channel.

This operation is only possible with messages sent in a NewsChannel. In order to crosspost message sent by the bot, the send_messages permission is required otherwise manage_messages permission is required.

Raises

HTTPForbidden – You are not allowed to do this.
HTTPException – Crossposting failed.

async delete() → None#

Deletes this message.

To delete other’s messages, the manage_messages permission is required in the target channel.

Raises

HTTPNotFound – Message is already deleted.
HTTPForbidden – You don’t have permission to do this.
HTTPException – The operation failed.

async reply(*args, fail_if_not_exists: bool = True, **kwargs) → qord.models.messages.Message#

Replies to this message.

This is an equivalent to send() that handles the instansiation of message reference. All parameters except message_reference that are passed in send() are valid in this method too. Additional parameters are documented below:

Parameters

*args – The positional arguments of send().
fail_if_not_exists (builtins.bool) – Whether to throw HTTPException if the replied message does not exist. If set to False, If the message is deleted, A a default non-reply message would be sent.
**kwargs – The keyword arguments of send().

Returns

The sent message.

Return type

Message

property client: Client#: The Client that had instansiated this model.

async edit(content: str = ..., *, embed: Embed = ..., file: File = ..., flags: MessageFlags = ..., allowed_mentions: AllowedMentions = ..., embeds: List[Embed] = ..., files: List[File] = ...)#

Edits the message.

Bots can only modify the flags of other author’s messages. All other fields can only be edited if bot is the message’s author.

When successful the message is updated in-place.

Parameters

content (builtins.str) – The new content of message. It is worth noting that the mentions in this content will not respect the allowed mentions properties that were set during sending of message. A new AllowedMentions must be supplied for new content.
allowed_mentions (AllowedMentions) – The mentions to allow in the message’s new content.
flags (MessageFlags) – The message flags for the edited message. Bots can only apply or remove the suppress_embeds flag. Other flags are unsupported. This is the only field that can be set or unset by bots on other user’s messages.
embed (Embed) – The embed to include in message, cannot be mixed with embeds.
embeds (List[Embed]) – The list of embeds to include in the message, cannot be mixed with embed.
file (File) – The file to include in message, cannot be mixed with files.
files (List[File]) – The list of file attachments to include in message, cannot be mixed with file.

Raises

TypeError – Invalid arguments passed.
HTTPForbidden – You are not allowed to send message in this channel.
HTTPBadRequest – The message has invalid data.
HTTPException – The editing failed for some reason.

async add_reaction(emoji: Union[qord.models.emojis.Emoji, qord.models.emojis.PartialEmoji, str]) → None#

Adds a reaction to the message.

This operation requires read_message_history permission and additionally add_reactions permission if no one has reacted to the message yet.

Warning

It is a common misconception of passing unicode emoji in Discord markdown format such as :smile:. The emoji must be passed as unicode emoji. For custom emojis, The format <:name:id> is used.

Parameters

emoji (Union[builtins.str, Emoji, PartialEmoji]) – The emoji to react with.

Raises

HTTPForbidden – Missing permissions.
HTTPException – The operation failed.

async remove_reation(emoji: Union[qord.models.emojis.Emoji, qord.models.emojis.PartialEmoji, qord.models.messages.Reaction, str], user: Union[qord.models.users.User, qord.models.guild_members.GuildMember] = ...) → None#

Removes a reaction from the message.

When removing own reaction (not passing the user parameter), No permissions are required however when removing other’s reactions, The manage_messages permissions are needed.

Warning

It is a common misconception of passing unicode emoji in Discord markdown format such as :smile:. The emoji must be passed as unicode emoji. For custom emojis, The format <:name:id> is used.

Parameters

emoji (Union[builtins.str, Emoji, PartialEmoji, Reaction]) – The emoji to remove reaction of.
user (Union[User, GuildMember]) – The user to remove reaction of. If not provided, This defaults to own (bot) user.

Raises

HTTPForbidden – Missing permissions.
HTTPException – The operation failed.

async clear_reactions(emoji: Union[qord.models.emojis.Emoji, qord.models.emojis.PartialEmoji, qord.models.messages.Reaction, str] = ...) → None#

Clears all reactions or reactions for a specific emoji from the message.

The manage_messages permissions are needed to perform this action.

Warning

It is a common misconception of passing unicode emoji in Discord markdown format such as :smile:. The emoji must be passed as unicode emoji. For custom emojis, The format <:name:id> is used.

Parameters

emoji (Union[builtins.str, Emoji, PartialEmoji, Reaction]) – The emoji to clear reactions of. If not provided, All reactions are removed from the message.

Raises

HTTPForbidden – Missing permissions.
HTTPException – The operation failed.

Attachment#

class qord.Attachment#

Represents an attachment that is attached to a message.

This class supports equality comparison between instances of this class by the id attribute.

message#

The message associated to this attachment.

Type: Message

filename#

The name of file of attachment.

Type: builtins.str

description#

The description of attachment, If any.

Type: Optional[builtins.str]

content_type#

The attachment’s media type.

Type: Optional[builtins.str]

size#

The size of attachment; in bytes.

Type: builtins.int

url#

The URL of this attachment.

Type: builtins.str

proxy_url#

The proxy URL of this attachment.

Type: builtins.str

height#

The height of attachment, if the attachment is an image.

Type: Optional[builtins.int]

width#

The width of attachment, if the attachment is an image.

Type: Optional[builtins.int]

ephemeral#

Whether the attachment is part of ephemeral message.

Type: builtins.bool

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

Reaction#

class qord.Reaction#

Represents a reaction on a Message.

message#

The message that this reaction belongs to.

Type: Message

count#

The count of this reaction.

Type: builtins.int

emoji#

The emoji for this reaction.

Type: PartialEmoji

me#

Whether the reaction is added by the bot user.

Type: builtins.bool

async users(*, limit: Optional[int] = None, after: int = ...) → AsyncIterator[Union[qord.models.guild_members.GuildMember, qord.models.users.User]]#

Asynchronous Iterator for fetching the users who have reacted to this reaction.

Parameters

limit (Optional[builtins.int]) – The number of users to fetch. When not provided, all users are fetched.
after (Union[builtins.int, datetime.datetime]) – For pagination, If an ID is given, Fetch the user after that user ID. If a datetime object is given, Fetch the user created after that time.

Yields

Union[GuildMember, User] – The users that reacted with this reaction. When member intents are present and reaction is in a guild, GuildMember is returned. In some cases, such as when member has left the guild or member isn’t cached, the User is yielded.

ChannelMention#

class qord.ChannelMention#

Represents a mention to a specific channel in a message’s content.

Warning

Channels from other guilds can be mentioned in a message. As such you should not rely on resolving the mentioned channel from the parent message guild’s cache. It is possible that the guild that the mention channel belongs to is not available to you mostly because the bot isn’t the part of it.

message#

The message that the mention was done in.

Type: Message

id#

The ID of channel that was mentioned.

Type: builtins.int

guild_id#

The ID of guild that the mentioned channel belonged to.

Type: builtins.int

type#

The type of channel that was mentioned. See ChannelType for possible values.

Type: builtins.int

name#

The name of channel that was mentioned.

Type: builtins.str

property client: Client#: The Client that had instansiated this model.

Emoji#

class qord.Emoji#

Represents a custom guild emoji.

This class supports equality comparison between instances of this class by the id attribute.

guild#

The guild that this emoji belongs to.

Type: Guild

id#

The ID of this emoji.

Type: builtins.int

name#

The name of this emoji.

Type: builtins.str

user#

The user that created this emoji, this can be None.

Type: Optional[User]

require_colons#

Whether the emoji requires to be wrapped in colons for rendering in Discord client.

Type: builtins.bool

managed#

Whether the emoji is managed by an integration e.g Twitch.

Type: builtins.bool

animated#

Whether the emoji is animated.

Type: builtins.bool

available#

Whether the emoji is available. This may be False due to losing the server boosts causing less emoji slots in the guild.

Type: builtins.bool

property mention: str#

The string used to mention/render the emoji in Discord client.

Return type: builtins.str

property roles: List[Role]#

The list of roles that can use this emoji.

If the returned list is empty, the emoji is unrestricted and can be used by anyone in the guild.

Return type: List[Role]

url(extension: str = ..., size: int = ...) → str#

Returns the URL for this emoji.

The extension parameter only supports following extensions in the case of custom emojis:

ImageExtension.GIF
ImageExtension.PNG
ImageExtension.JPG
ImageExtension.JPEG
ImageExtension.WEBP

Parameters

extension (builtins.str) – The extension to use in the URL. If not supplied, An ideal extension will be picked depending on whether emoji is static or animated.
size (builtins.int) – The size to append to URL. Can be any power of 2 between 64 and 4096.

Raises

ValueError – Invalid extension or size was passed.

is_useable() → bool#

Checks whether the emoji can be used by the bot.

Return type: builtins.bool

async edit(name: str = ..., roles: Optional[List[Role]] = ..., reason: Optional[str] = None) → None#

Edits this emoji.

This operation requires manage_emojis_and_stickers permission in the parent emoji guild.

Parameters

name (builtins.str) – The name of emoji.
roles (Optional[List[Role]]) – The list of roles that can use this emoji. None or empty list denotes that emoji is unrestricted.
reason (builtins.str) – The reason for performing this action that appears on guild audit log.

Raises

HTTPForbidden – You are missing permissions to do this.
HTTPException – The editing failed.

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime

async delete(reason: Optional[str] = None) → None#

Deletes this emoji.

This operation requires manage_emojis_and_stickers permission in the parent emoji guild.

Parameters

reason (builtins.str) – The reason for performing this action that appears on guild audit log.

Raises

HTTPForbidden – You are missing permissions to do this.
HTTPException – The deleting failed.

PartialEmoji#

class qord.PartialEmoji#

Represents a partial emoji.

A partial emoji is returned by in API responses in following cases:

For representing standard unicode emojis.
For representing emojis in reactions.
A full Emoji object cannot be resolved from cache.

This class supports comparison between Emoji and PartialEmoji.

Tip

If you have the custom emoji’s parent guild, You can resolve the complete Emoji object using the resolve() method.

id#

The ID of emoji. This can be None when the class is representing a standard unicode emoji rather than a custom emoji.

Type: Optional[builtins.int]

name#

The name of emoji. For standard unicode emojis, This is the actual emoji representation and for the custom emojis, It’s the emoji’s name.

For custom emojis obtained from message reactions events, This may be None when the custom emoji data isn’t available to the API. This generally happens when the emoji was deleted.

Type: Optional[builtins.str]

animated#

Whether the emoji is animated. For unicode emojis, This is always False.

Type: builtins.bool

property mention: str#

The string used for mentioning/rendering the emoji in Discord client.

Return type: builtins.str

is_unicode_emoji() → bool#

Indicates whether the emoji is a unicode emoji.

Unicode emojis don’t have an ID associated to them.

Return type: builtins.bool

async resolve(guild: Guild) → Emoji#

Resolves the full Emoji object.

Note that this operation is not possible for unicode emojis (i.e is_unicode_emoji() returns True)

This method attempts to resolve the emoji from given guild’s cache and if not found, would make an HTTP request to fetch the emoji. If the emoji is not found, the HTTPNotFound error is raised.

Parameters

guild (Guild) – The guild to fetch the emoji from.

Returns

The resolved emoji.

Return type

Emoji

Raises

RuntimeError – The emoji is a unicode emoji.
HTTPNotFound – The emoji could not be resolved.

ScheduledEvent#

class qord.ScheduledEvent#

Represents a guild scheduled event.

This class supports equality comparison between instances of this class by the id attribute.

guild#

The guild that belongs to this scheduled event.

Type: Guild

id#

The ID of this scheduled event.

Type: builtins.int

guild_id#

The ID of guild that the event belongs to.

Type: builtins.int

name#

The name of event.

Type: builtins.str

privacy_level#

The privacy level of this event. All possible values are detailed in EventPrivacyLevel.

Type: builtins.int

status#

The current status of this event. All possible values are detailed in EventStatus.

Type: builtins.int

entity_type#

The type of entity that belongs to this event. All possible values are detailed in EventEntityType.

Type: builtins.int

user_count#

The number of users subscribed to this event. This is only present when fetching the event via Guild.fetch_scheduled_event() or fetch_scheduled_events() with with_user_count set to True.

Type: Optional[builtins.int]

description#

The description of event, if any.

Type: Optional[builtins.str]

starts_at#

The time when the event starts.

Type: datetime.datetime

ends_at#

The time when the event ends. This can be None.

Type: Optional[datetime.datetime]

channel_id#

The ID of voice or stage channel in which the event is being hosted, This is always None when entity_type is EXTERNAL.

Type: Optional[builtins.int]

creator_id#

The ID of user who created the event. For events created before 25 October 2021, This is None.

Type: Optional[builtins.int]

entity_id#

The ID of entity (currently stage instance) that is hosting the event.

Type: Optional[builtins.int]

creator#

The user who created the event. For events created before 25 October 2021, This is None.

Type: Optional[User]

location#

The location where the event is hosted. This is only present when entity_type is EXTERNAL.

Type: Optional[builtins.str]

cover_image#

The cover image’s hash for the event, if any.

Type: Optional[builtins.str]

property channel: Optional[Union[VoiceChannel, StageChannel]]#

The channel in which event is hosted.

Return type: Optional[Union[VoiceChannel, StageChannel]]

cover_image_url(extension: str = ..., size: int = ...) → Optional[str]#

Returns the cover image’s URL for this event.

If event has no cover image set, This method would return None.

The extension parameter only supports following extensions in the case of event cover images:

ImageExtension.PNG
ImageExtension.JPG
ImageExtension.JPEG
ImageExtension.WEBP

Parameters

extension (builtins.str) – The extension to use in the URL. If not supplied, Defaults to PNG.
size (builtins.int) – The size to append to URL. Can be any power of 2 between 64 and 4096.

Raises

ValueError – Invalid extension or size was passed.

async delete(reason: Optional[str] = None) → None#

Deletes the scheduled event.

This operation requires manage_events permission in the parent event’s guild.

Parameters

reason (builtins.str) – The reason for this operation.

Raises

HTTPForbidden – You don’t have permissions to do that.
HTTPException – The deletion failed.

async start(*, reason: Optional[str] = None) → None#

Starts the event.

This operation requires manage_events permission in the parent event guild.

Parameters

reason (builtins.str) – The reason for this action.

Raises

RuntimeError – Status transition is not supported.
HTTPForbidden – You are missing permissions to perform this action.
HTTPException – Failed to perform this action.

async end(*, reason: Optional[str] = None) → None#

Ends the event.

This operation requires manage_events permission in the parent event guild.

Parameters

reason (builtins.str) – The reason for this action.

Raises

RuntimeError – Status transition is not supported.
HTTPForbidden – You are missing permissions to perform this action.
HTTPException – Failed to perform this action.

async cancel(*, reason: Optional[str] = None) → None#

Cancels the event.

This operation requires manage_events permission in the parent event guild.

Parameters

reason (builtins.str) – The reason for this action.

Raises

RuntimeError – Status transition is not supported.
HTTPForbidden – You are missing permissions to perform this action.
HTTPException – Failed to perform this action.

async edit(*, name: str = ..., privacy_level: int = ..., starts_at: datetime = ..., entity_type: int = ..., status: int = ..., channel: Optional[Union[VoiceChannel, StageChannel]] = ..., location: Optional[str] = ..., description: Optional[str] = ..., cover_image: Optional[bytes] = ..., ends_at: Optional[datetime] = ..., reason: Optional[str] = None)#

Edits the event.

This operation requires manage_events permission in the parent event guild.

Unlike Guild.create_scheduled_event() method, this method does not automatically infers the values for various arguments and their values must be explicitly given.

When specifying location to a non-external event to convert it to an external event, the entity_type must be set to EventEntityType.EXTERNAL and channel parameter must be set to None explicitly. Furthermore ends_at must also be given.
When specifying channel to an external event to convert it to a channel-hosted event, the entity_type must be set to EventEntityType.VOICE or EventEntityType.STAGE_INSTANCE depending on what type of channel is being passed and location must be expliclty set to None.

For editing the event’s status, Following are the limitations:

Events that have the status of EventStatus.SCHEDULED can get their status be edited to either to EventStatus.ACTIVE or EventStatus.CANCELED.
Events that have the status of EventStatus.ACTIVE can only be edited to EventStatus.COMPLETED.
No other transitions are possible.

These limitations are described by Discord and are not validated by the library.

Tip

For easier transitions of events, consider using other methods provided by the class such as start(), end() or cancel().

Parameters

name (builtins.str) – The name of event.
description (Optional[builtins.str]) – The description of event. Set to None to remove description.
cover_image (Optional[builtins.bytes]) – The bytes representing cover image of event. Set to None to remove the image.
privacy_level (builtins.int) – The EventPrivacyLevel of the event.
starts_at (datetime.datetime) – The time when the event starts.
ends_at (Optional[datetime.datetime]) – The time when the event ends. This is required when converting events to EXTERNAL.
entity_type (builtins.int) – The entity type of event. This parameter has specific considerations described above.
status (builtins.int) – The status of event. The valid transitions of status are described above.
location (Optional[builtins.str]) – The location of event. This parameter has specific considerations described above.
channel (Optional[Union[VoiceChannel, StageChannel]]) – The channel of event. This parameter has specific considerations described above.
reason (Optional[builtins.str]) – The audit log reason for this operation.

Raises

HTTPForbidden – You are missing permissions to perform this action.
HTTPBadRequest – Invalid data was sent.
HTTPException – Failed to perform this action.

async users(with_member: bool = True, limit: Optional[int] = None, before: Union[datetime.datetime, int] = ..., after: Union[datetime.datetime, int] = ...) → AsyncIterator[Union[qord.models.guild_members.GuildMember, qord.models.users.User]]#

Iterates through the users that are subscribed to this event.

Parameters

with_member (builtins.bool) – Whether to yield GuildMember when available. If this is set to False, User will always be yielded.
limit (Optional[builtins.int]) – The number of users to fetch, None (default) indicates to fetch all subscribed users.
before (Union[builtins.int, datetime.datetime]) – For pagination, fetch the users created before the given time or fetch users before the given ID.
after (Union[builtins.int, datetime.datetime]) – For pagination, fetch the users created after the given time or fetch users after the given ID.

Yields

Union[GuildMember, User] – The subscribed user. When with_member is True, GuildMember object will be yielded when available. In some cases such as when member has left the guild, User may still be yielded. When with_member is False, User is always yielded.

property client: Client#: The Client that had instansiated this model.

property created_at: datetime#

The time when this entity was created.

Returns: UTC aware datetime object representing the creation time.
Return type: datetime.datetime