Client

discord_http.client module

class discord_http.client.Client(*, token: str, application_id: int | None = None, public_key: str | None = None, guild_id: int | None = None, sync: bool = False, api_version: int = 10, loop: ~asyncio.events.AbstractEventLoop | None = None, allowed_mentions: ~discord_http.mentions.AllowedMentions = <discord_http.mentions.AllowedMentions object>, enable_gateway: bool = False, automatic_shards: bool = True, playing_status: PlayingStatus | None = None, chunk_guilds_on_startup: bool = False, guild_ready_timeout: float = 2.0, gateway_cache: GatewayCacheFlags | None = None, intents: Intents | None = None, logging_level: int = 20, call_after_delay: float | int = 0.1, disable_default_get_path: bool = False, debug_events: bool = False)[source]

Bases: object

async add_cog(cog: Cog) → None[source]

Adds a cog to the bot.

Parameters:

cog (Cog) – The cog to add to the bot.

add_command(func: Command) → Command[source]

Adds a command to the bot.

Parameters:

command (Command) – The command to add to the bot.

add_global_cmd_check(func: Callable) → Callable[source]

Add a check that will be run before every command

Parameters:

func (Callable) – The function to add

add_group(name: str) → SubGroup[source]

Used to add a sub-command group

Parameters:

name (str) – Name of the group

Returns:

The created group

Return type:

SubGroup

add_interaction(func: Interaction) → Interaction[source]

Adds an interaction to the bot.

Parameters:

interaction (Interaction) – The interaction to add to the bot.

add_listener(func: Listener) → Listener[source]

Adds a listener to the bot.

Parameters:

func (Listener) – The listener to add to the bot.

command(name: str | None = None, *, description: str | None = None, guild_ids: list[Snowflake | int] | None = None, guild_install: bool = True, user_install: bool = False)[source]

Used to register a command

Parameters:

  • name (Optional[str]) – Name of the command, if not provided, it will use the function name

  • description (Optional[str]) – Description of the command, if not provided, it will use the function docstring

  • guild_ids (Optional[list[Union[Snowflake, int]]]) – List of guild IDs to register the command in

  • user_install (bool) – Whether the command can be installed by users or not

  • guild_install (bool) – Whether the command can be installed by guilds or not

async create_application_emoji(name: str, *, image: File | bytes) → Emoji[source]

Creates an emoji for the application.

Parameters:

  • name (str) – Name of emoji

  • image (Union[File, bytes]) – The image data to use for the emoji.

Returns:

The created emoji object.

Return type:

Emoji

async create_guild(name: str, *, icon: File | bytes | None = None, reason: str | None = None) → Guild[source]

Create a guild

Note that the bot must be in less than 10 guilds to use this endpoint

Parameters:

  • name (str) – The name of the guild

  • icon (Optional[File]) – The icon of the guild

  • reason (Optional[str]) – The reason for creating the guild

Returns:

The created guild

Return type:

Guild

dispatch(event_name: str, /, *args: Any, **kwargs: Any)[source]

Dispatches an event to all listeners of that event.

Parameters:

  • event_name (str) – The name of the event to dispatch.

  • *args (Any) – The arguments to pass to the event.

  • **kwargs (Any) – The keyword arguments to pass to the event.

async fetch_application_emojis() → list[Emoji][source]

list[Emoji]: Fetches all emojis available to the application.

async fetch_automod_rule(rule_id: int, guild_id: int) → AutoModRule[source]

Fetches a automod object

Parameters:

  • rule_id (int) – The ID of the automod rule

  • guild_id (int) – The Guild ID where it comes from

Returns:

The automod object

Return type:

AutoModRule

async fetch_channel(channel_id: int, *, guild_id: int | None = None) → BaseChannel[source]

Fetches a channel object.

Parameters:

  • channel_id (int) – Channel ID to fetch the channel object with.

  • guild_id (Optional[int]) – Guild ID to fetch the channel object with.

Returns:

The channel object.

Return type:

BaseChannel

async fetch_emoji(emoji_id: int, *, guild_id: int | None = None) → Emoji[source]

Fetches an emoji object.

Parameters:

  • emoji_id (int) – The ID of the emoji in question

  • guild_id (Optional[int]) – Guild ID of the emoji. If None, it will fetch the emoji from the application

Returns:

The emoji object

Return type:

Emoji

async fetch_entitlement(entitlement_id: int) → Entitlements[source]

Fetches an entitlement object.

Parameters:

entitlement_id (int) – Entitlement ID to fetch the entitlement object with.

Returns:

The entitlement object.

Return type:

Entitlements

async fetch_entitlement_list(*, user_id: int | None = None, sku_ids: list[int] | None = None, before: int | None = None, after: int | None = None, limit: int | None = 100, guild_id: int | None = None, exclude_ended: bool = False) → AsyncIterator[Entitlements][source]

Fetches a list of entitlement objects with optional filters.

Parameters:

  • user_id (Optional[int]) – Show entitlements for a specific user ID.

  • sku_ids (Optional[list[int]]) – Show entitlements for a specific SKU ID.

  • before (Optional[int]) – Only show entitlements before this entitlement ID.

  • after (Optional[int]) – Only show entitlements after this entitlement ID.

  • limit (int) – Limit the amount of entitlements to fetch. Use None to fetch all entitlements.

  • guild_id (Optional[int]) – Show entitlements for a specific guild ID.

  • exclude_ended (bool) – Whether to exclude ended entitlements or not.

Returns:

The entitlement objects.

Return type:

AsyncIterator[Entitlements]

async fetch_guild(guild_id: int) → Guild[source]

Fetches a guild object.

Parameters:

guild_id (int) – Guild ID to fetch the guild object with.

Returns:

The guild object.

Return type:

Guild

async fetch_invite(invite_code: str) → Invite[source]

Fetches an invite object.

Parameters:

invite_code (str) – Invite code to fetch the invite object with.

Returns:

The invite object.

Return type:

Invite

async fetch_member(user_id: int, guild_id: int) → Member[source]

Fetches a member object.

Parameters:

  • guild_id (int) – Guild ID that the member is in.

  • user_id (int) – User ID to fetch the member object with.

Returns:

The member object.

Return type:

Member

async fetch_message(message_id: int, channel_id: int, guild_id: int | None = None) → Message[source]

Fetches a message object.

Parameters:

  • message_id (int) – Message ID to fetch the message object with.

  • channel_id (int) – Channel ID to fetch the message object with.

  • guild_id (Optional[int]) – Guild ID to fetch the message object from.

Returns:

The message object

Return type:

Message

async fetch_scheduled_event(id: int, guild_id: int) → ScheduledEvent[source]

Fetches a scheduled event object.

Parameters:

  • id (int) – The ID of the scheduled event.

  • guild_id (int) – The guild ID of the scheduled event.

Returns:

The scheduled event object.

Return type:

ScheduledEvent

async fetch_skus() → list[SKU][source]

list[SKU]: Fetches all SKUs available to the bot.

async fetch_soundboard_sound(sound_id: int, guild_id: int) → SoundboardSound[source]

Fetches a soundboard sound object.

Parameters:

  • sticker_id (int) – Sound ID to fetch the soundboard sound object with.

  • guild_id (int) – Guild ID to fetch the soundboard sound object from.

Returns:

The soundboard sound object.

Return type:

SoundboardSound

async fetch_sticker(sticker_id: int, *, guild_id: int | None = None) → Sticker[source]

Fetches a sticker object.

Parameters:

sticker_id (int) – Sticker ID to fetch the sticker object with.

Returns:

The sticker object.

Return type:

Sticker

async fetch_user(user_id: int) → User[source]

Fetches a user object.

Parameters:

user_id (int) – User ID to fetch the user object with.

Returns:

The user object.

Return type:

User

async fetch_voice_state(member_id: int, guild_id: int | None = None) → VoiceState[source]

Fetches a voice state object.

Parameters:

  • member_id (int) – The ID of the member to fetch the voice state from

  • guild_id (Optional[int]) – Guild ID to fetch the voice state from

Returns:

The voice state object.

Return type:

VoiceState

async fetch_webhook(webhook_id: int, *, webhook_token: str | None = None) → Webhook[source]

Fetches a webhook object.

Parameters:

  • webhook_id (int) – Webhook ID to fetch the webhook object with.

  • webhook_token (Optional[str]) – Webhook token to fetch the webhook object with.

Returns:

The webhook object.

Return type:

Webhook

find_interaction(custom_id: str) → Interaction | None[source]

Finds an interaction by its Custom ID.

Parameters:

custom_id (str) – The Custom ID to find the interaction with. Will automatically convert to regex matching if some interaction Custom IDs are regex.

Returns:

The interaction that was found if any.

Return type:

Optional[Interaction]

get_channel(channel_id: int | None) → BaseChannel | PartialChannel | None[source]

Get a channel object from the cache.

Parameters:

channel_id (int) – The ID of the channel to get.

Returns:

The channel object with the specified ID, or None if not found.

Return type:

BaseChannel | PartialChannel | None

get_guild(guild_id: int) → Guild | PartialGuild | None[source]

Get a guild object from the cache.

Parameters:

guild_id (int) – The ID of the guild to get.

Returns:

The guild object with the specified ID, or None if not found.

Return type:

Guild | PartialGuild | None

get_partial_automod_rule(rule_id: int, guild_id: int) → PartialAutoModRule[source]

Creates a partial automod object

Parameters:

  • rule_id (int) – The ID of the automod rule

  • guild_id (int) – The Guild ID where it comes from

Returns:

The partial automod object

Return type:

PartialAutoModRule

get_partial_channel(channel_id: int, *, guild_id: int | None = None) → PartialChannel[source]

Creates a partial channel object.

Parameters:

  • channel_id (int) – Channel ID to create the partial channel object with.

  • guild_id (Optional[int]) – Guild ID to create the partial channel object with.

Returns:

The partial channel object.

Return type:

PartialChannel

get_partial_emoji(emoji_id: int, *, guild_id: int | None = None) → PartialEmoji[source]

Creates a partial emoji object.

Parameters:

  • emoji_id (int) – Emoji ID to create the partial emoji object with.

  • guild_id (Optional[int]) – Guild ID of where the emoji comes from. If None, it will get the emoji from the application.

Returns:

The partial emoji object.

Return type:

PartialEmoji

get_partial_entitlement(entitlement_id: int) → PartialEntitlements[source]

Creates a partial entitlement object.

Parameters:

entitlement_id (int) – Entitlement ID to create the partial entitlement object with.

Returns:

The partial entitlement object.

Return type:

PartialEntitlements

get_partial_guild(guild_id: int) → PartialGuild[source]

Creates a partial guild object.

Parameters:

guild_id (int) – Guild ID to create the partial guild object with.

Returns:

The partial guild object.

Return type:

PartialGuild

get_partial_invite(invite_code: str, *, channel_id: int | None = None, guild_id: int | None = None) → PartialInvite[source]

Creates a partial invite object.

Parameters:

invite_code (str) – Invite code to create the partial invite object with.

Returns:

The partial invite object.

Return type:

PartialInvite

get_partial_member(user_id: int, guild_id: int) → PartialMember[source]

Creates a partial member object.

Parameters:

  • user_id (int) – User ID to create the partial member object with.

  • guild_id (int) – Guild ID that the member is in.

Returns:

The partial member object.

Return type:

PartialMember

get_partial_message(message_id: int, channel_id: int, guild_id: int | None = None) → PartialMessage[source]

Creates a partial message object.

Parameters:

  • message_id (int) – Message ID to create the partial message object with.

  • channel_id (int) – Channel ID to create the partial message object with.

  • guild_id (Optional[int]) – Guild ID to create the partial message object with.

Returns:

The partial message object.

Return type:

PartialMessage

get_partial_role(role_id: int, guild_id: int) → PartialRole[source]

Creates a partial role object.

Parameters:

  • role_id (int) – Role ID to create the partial role object with.

  • guild_id (int) – Guild ID that the role is in.

Returns:

The partial role object.

Return type:

PartialRole

get_partial_scheduled_event(id: int, guild_id: int) → PartialScheduledEvent[source]

Creates a partial scheduled event object.

Parameters:

  • id (int) – The ID of the scheduled event.

  • guild_id (int) – The guild ID of the scheduled event.

Returns:

The partial scheduled event object.

Return type:

PartialScheduledEvent

get_partial_sku(sku_id: int) → PartialSKU[source]

Creates a partial SKU object.

Returns:

The partial SKU object.

Return type:

PartialSKU

get_partial_soundboard_sound(sound_id: int, *, guild_id: int | None = None) → PartialSoundboardSound[source]

Creates a partial sticker object.

Parameters:

  • sticker_id (int) – Sound ID to create the partial soundboard sound object with.

  • guild_id (Optional[int]) – Guild ID to create the partial soundboard sound object with.

Returns:

The partial soundboard sound object.

Return type:

PartialSoundboardSound

get_partial_sticker(sticker_id: int, *, guild_id: int | None = None) → PartialSticker[source]

Creates a partial sticker object.

Parameters:

  • sticker_id (int) – Sticker ID to create the partial sticker object with.

  • guild_id (Optional[int]) – Guild ID to create the partial sticker object with.

Returns:

The partial sticker object.

Return type:

PartialSticker

get_partial_user(user_id: int) → PartialUser[source]

Creates a partial user object.

Parameters:

user_id (int) – User ID to create the partial user object with.

Returns:

The partial user object.

Return type:

PartialUser

get_partial_voice_state(member_id: int, *, guild_id: int | None = None, channel_id: int | None = None) → PartialVoiceState[source]

Creates a partial voice state object.

Parameters:

  • member_id (int) – The ID of the member to create the partial voice state from

  • guild_id (Optional[int]) – Guild ID to create the partial voice state from

Returns:

The partial voice state object.

Return type:

PartialVoiceState

get_partial_webhook(webhook_id: int, *, webhook_token: str | None = None) → PartialWebhook[source]

Creates a partial webhook object.

Parameters:

  • webhook_id (int) – Webhook ID to create the partial webhook object with.

  • webhook_token (Optional[str]) – Webhook token to create the partial webhook object with.

Returns:

The partial webhook object.

Return type:

PartialWebhook

get_shard_by_guild_id(guild_id: Snowflake | int) → int | None[source]

Returns the shard ID of the shard that the guild is in

Parameters:

guild_id (Snowflake | int) – The ID of the guild to get the shard ID of

Returns:

The shard ID of the guild, or None if not found

Return type:

int | None

Raises:

NotImplementedError – If the gateway is not available

group(name: str | None = None, *, description: str | None = None)[source]

Used to register a sub-command group

Parameters:

  • name (Optional[str]) – Name of the group, if not provided, it will use the function name

  • description (Optional[str]) – Description of the group, if not provided, it will use the function docstring

property guilds: list[Guild | PartialGuild]

Returns a list of all the guilds the bot is in. Only useable if you are using gateway and caching

Type:

list[Guild]

has_any_dispatch(event_name: str) → bool[source]

Checks if the bot has any listeners for the event.

Parameters:

event_name (str) – The name of the event to check for.

Returns:

Whether the bot has any listeners for the event.

Return type:

bool

interaction(custom_id: str, *, regex: bool = False)[source]

Used to register an interaction

This does support regex, so you can use r”regex here” as the custom_id

Parameters:

  • custom_id (str) – Custom ID of the interaction

  • regex (bool) – Whether the custom_id is a regex or not

is_ready() → bool[source]

bool: Indicates if the client is ready.

is_shards_ready() → bool[source]
listener(name: str | None = None)[source]

Used to register a listener

Parameters:

name (Optional[str]) – Name of the listener, if not provided, it will use the function name

Raises:

TypeError –

  • If the listener name is not a string - If the listener is not a coroutine function

async load_extension(package: str) → None[source]

Loads an extension.

Parameters:

package (str) – The package to load the extension from.

message_command(name: str | None = None, *, guild_ids: list[Snowflake | int] | None = None, guild_install: bool = True, user_install: bool = False)[source]

Used to register a message command

Example usage

@message_command()
async def content(ctx, msg: Message):
    await ctx.send(f"Content: {msg.content}")
Parameters:

  • name (Optional[str]) – Name of the command, if not provided, it will use the function name

  • guild_ids (Optional[list[Union[Snowflake, int]]]) – List of guild IDs to register the command in

  • user_install (bool) – Whether the command can be installed by users or not

  • guild_install (bool) – Whether the command can be installed by guilds or not

async query_members(guild_id: Snowflake | int, *, query: str | None = None, limit: int = 0, presences: bool = False, user_ids: list[Snowflake | int] | None = None, shard_id: int | None = None) → list[Member][source]

Query members in a guild

Parameters:

  • guild_id (Snowflake | int) – The ID of the guild to query members in

  • query (str | None) – The query to search for

  • limit (int) – The maximum amount of members to return

  • presences (bool) – Whether to include presences in the response

  • user_ids (list[Snowflake | int] | None) – The user IDs to fetch members for

  • shard_id (int | None) – The shard ID to query the members from

Returns:

The members that matched the query

Return type:

list[Member]

Raises:

ValueError –

  • If shard_id is not provided - If shard_id is not valid

async remove_cog(cog: Cog) → None[source]

Removes a cog from the bot.

Parameters:

cog (Cog) – The cog to remove from the bot.

remove_command(func: Command) → None[source]

Removes a command from the bot.

Parameters:

command (Command) – The command to remove from the bot.

remove_interaction(func: Interaction) → None[source]

Removes an interaction from the bot.

Parameters:

interaction (Interaction) – The interaction to remove from the bot.

remove_listener(func: Listener) → None[source]

Removes a listener from the bot.

Parameters:

func (Listener) – The listener to remove from the bot.

set_backend(*, cls: Callable | None = None) → None[source]

Set the backend to use for the bot

Example of making one:

from discord_http import DiscordHTTP

class CustomBackend(DiscordHTTP):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

Client.set_backend(cls=CustomBackend)
Parameters:

cls (Optional[Callable]) – The backend to use for everything. Leave empty to use the default backend.

set_context(*, cls: Callable | None = None) → None[source]

Get the context for a command, while allowing custom context as well

Example of making one:

from discord_http import Context

class CustomContext(Context):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

Client.set_context(cls=CustomContext)
Parameters:

cls (Optional[Callable]) – The context to use for commands. Leave empty to use the default context.

async setup_hook() → None[source]

This will be running after the bot is ready, to get variables set up You can overwrite this function to do your own setup

Example:

async def setup_hook(self) -> None:
    # Making database connection available through the bot
    self.pool = SQLite.Database()
start(*, host: str = '127.0.0.1', port: int = 8080) → None[source]

Boot up the bot and start the HTTP server

Parameters:

  • host (Optional[str]) – Host to use, if not provided, it will use 127.0.0.1

  • port (Optional[int]) – Port to use, if not provided, it will use 8080

async sync_commands() → None[source]

Make the bot fetch all current commands, to then sync them all to Discord API.

async unload_extension(package: str) → None[source]

Unloads an extension.

Parameters:

package (str) – The package to unload the extension from.

property user: UserClient

returns: The bot’s user object :rtype: User

Raises:

AttributeError – If used before the bot is ready

user_command(name: str | None = None, *, guild_ids: list[Snowflake | int] | None = None, guild_install: bool = True, user_install: bool = False)[source]

Used to register a user command

Example usage

@user_command()
async def content(ctx, user: Union[Member, User]):
    await ctx.send(f"Target: {user.name}")
Parameters:

  • name (Optional[str]) – Name of the command, if not provided, it will use the function name

  • guild_ids (Optional[list[Union[Snowflake, int]]]) – List of guild IDs to register the command in

  • user_install (bool) – Whether the command can be installed by users or not

  • guild_install (bool) – Whether the command can be installed by guilds or not

async wait_until_ready() → None[source]

Waits until the client is ready using asyncio.Event.wait().

async wait_until_shards_ready() → None[source]

Waits until the client is ready using asyncio.Event.wait().