Client

discord_http.client module

class discord_http.client.Client(*, token, application_id=None, public_key=None, guild_id=None, sync=False, api_version=10, loop=None, allowed_mentions=None, enable_gateway=False, automatic_shards=True, playing_status=None, chunk_guilds_on_startup=False, guild_ready_timeout=2.0, gateway_cache=None, intents=None, logging_level=20, call_after_delay=0.1, disable_default_get_path=False, debug_events=False)

Bases: object

Parameters:
async add_cog(cog) None

Adds a cog to the bot.

Parameters:

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

Return type:

None

add_command(func) Command

Adds a command to the bot.

Parameters:

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

Return type:

Command

add_global_cmd_check(func) Callable

Add a check that will be run before every command.

Parameters:

func (Callable) – The function to add

Return type:

Callable

add_group(name) SubGroup

Used to add a sub-command group.

Parameters:

name (str) – Name of the group

Return type:

SubGroup

Returns:

The created group

add_interaction(func) Interaction

Adds an interaction to the bot.

Parameters:

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

Return type:

Interaction

add_listener(func) Listener

Adds a listener to the bot.

Parameters:

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

Return type:

Listener

command(name=None, *, description=None, guild_ids=None, guild_install=True, user_install=False) Callable

Used to register a command.

Parameters:
  • name (str | None) – Name of the command, if not provided, it will use the function name

  • description (str | None) – Description of the command, if not provided, it will use the function docstring

  • guild_ids (list[Snowflake | int] | None) – 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

Return type:

Callable

async create_application_emoji(name, *, image) Emoji

Creates an emoji for the application.

Parameters:
  • name (str) – Name of emoji

  • image (File | bytes) – The image data to use for the emoji.

Return type:

Emoji

Returns:

The created emoji object.

async create_guild(name, *, icon=None, reason=None) Guild

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 (File | bytes | None) – The icon of the guild

  • reason (str | None) – The reason for creating the guild

Return type:

Guild

Returns:

The created guild

dispatch(event_name, /, *args, **kwargs) None

Dispatches an event to all listeners of that event.

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

  • *args – The arguments to pass to the event.

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

Return type:

None

async fetch_application_emojis() list[Emoji]

Fetches all emojis available to the application.

Return type:

list[Emoji]

async fetch_automod_rule(rule_id, guild_id) AutoModRule

Fetches a automod object.

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

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

Return type:

AutoModRule

Returns:

The automod object

async fetch_channel(channel_id, *, guild_id=None) BaseChannel

Fetches a channel object.

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

  • guild_id (int | None) – Guild ID to fetch the channel object with.

Return type:

BaseChannel

Returns:

The channel object.

async fetch_emoji(emoji_id, *, guild_id=None) Emoji

Fetches an emoji object.

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

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

Return type:

Emoji

Returns:

The emoji object

async fetch_entitlement(entitlement_id) Entitlements

Fetches an entitlement object.

Parameters:

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

Return type:

Entitlements

Returns:

The entitlement object.

async fetch_entitlement_list(*, user_id=None, sku_ids=None, before=None, after=None, limit=100, guild_id=None, exclude_ended=False) AsyncIterator[Entitlements]

Fetches a list of entitlement objects with optional filters.

Parameters:
  • user_id (int | None) – Show entitlements for a specific user ID.

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

  • before (int | None) – Only show entitlements before this entitlement ID.

  • after (int | None) – Only show entitlements after this entitlement ID.

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

  • guild_id (int | None) – Show entitlements for a specific guild ID.

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

Return type:

AsyncIterator[Entitlements]

Returns:

The entitlement objects.

async fetch_guild(guild_id) Guild

Fetches a guild object.

Parameters:

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

Return type:

Guild

Returns:

The guild object.

async fetch_invite(invite_code) Invite

Fetches an invite object.

Parameters:

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

Return type:

Invite

Returns:

The invite object.

async fetch_member(user_id, guild_id) Member

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.

Return type:

Member

Returns:

The member object.

async fetch_message(message_id, channel_id, guild_id=None) Message

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 (int | None) – Guild ID to fetch the message object from.

Return type:

Message

Returns:

The message object

async fetch_scheduled_event(event_id, guild_id) ScheduledEvent

Fetches a scheduled event object.

Parameters:
  • event_id (int) – The ID of the scheduled event.

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

Return type:

ScheduledEvent

Returns:

The scheduled event object.

async fetch_skus() list[SKU]

Fetches all SKUs available to the bot.

Return type:

list[SKU]

async fetch_soundboard_sound(sound_id, guild_id) SoundboardSound

Fetches a soundboard sound object.

Parameters:
  • sound_id (int) – Sound ID to fetch the soundboard sound object with.

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

Return type:

SoundboardSound

Returns:

The soundboard sound object.

async fetch_sticker(sticker_id, *, guild_id=None) Sticker

Fetches a sticker object.

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

  • guild_id (int | None) – Guild ID to fetch the sticker object from.

Return type:

Sticker

Returns:

The sticker object.

async fetch_user(user_id) User

Fetches a user object.

Parameters:

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

Return type:

User

Returns:

The user object.

async fetch_voice_state(member_id, guild_id=None) VoiceState

Fetches a voice state object.

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

  • guild_id (int | None) – Guild ID to fetch the voice state from

Return type:

VoiceState

Returns:

The voice state object.

async fetch_webhook(webhook_id, *, webhook_token=None) Webhook

Fetches a webhook object.

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

  • webhook_token (str | None) – Webhook token to fetch the webhook object with.

Return type:

Webhook

Returns:

The webhook object.

find_interaction(custom_id) Interaction | None

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.

Return type:

Interaction | None

Returns:

The interaction that was found if any.

get_channel(channel_id) BaseChannel | PartialChannel | None

Get a channel object from the cache.

Parameters:

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

Return type:

BaseChannel | PartialChannel | None

Returns:

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

get_guild(guild_id) Guild | PartialGuild | None

Get a guild object from the cache.

Parameters:

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

Return type:

Guild | PartialGuild | None

Returns:

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

get_partial_automod_rule(rule_id, guild_id) PartialAutoModRule

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

Return type:

PartialAutoModRule

Returns:

The partial automod object

get_partial_channel(channel_id, *, guild_id=None) PartialChannel

Creates a partial channel object.

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

  • guild_id (int | None) – Guild ID to create the partial channel object with.

Return type:

PartialChannel

Returns:

The partial channel object.

get_partial_emoji(emoji_id, *, guild_id=None) PartialEmoji

Creates a partial emoji object.

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

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

Return type:

PartialEmoji

Returns:

The partial emoji object.

get_partial_entitlement(entitlement_id) PartialEntitlements

Creates a partial entitlement object.

Parameters:

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

Return type:

PartialEntitlements

Returns:

The partial entitlement object.

get_partial_guild(guild_id) PartialGuild

Creates a partial guild object.

Parameters:

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

Return type:

PartialGuild

Returns:

The partial guild object.

get_partial_invite(invite_code, *, channel_id=None, guild_id=None) PartialInvite

Creates a partial invite object.

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

  • channel_id (int | None) – Channel ID to create the partial invite object with.

  • guild_id (int | None) – Guild ID to create the partial invite object with.

Return type:

PartialInvite

Returns:

The partial invite object.

get_partial_member(user_id, guild_id) PartialMember

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.

Return type:

PartialMember

Returns:

The partial member object.

get_partial_message(message_id, channel_id, guild_id=None) PartialMessage

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 (int | None) – Guild ID to create the partial message object with.

Return type:

PartialMessage

Returns:

The partial message object.

get_partial_role(role_id, guild_id) PartialRole

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.

Return type:

PartialRole

Returns:

The partial role object.

get_partial_scheduled_event(event_id, guild_id) PartialScheduledEvent

Creates a partial scheduled event object.

Parameters:
  • event_id (int) – The ID of the scheduled event.

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

Return type:

PartialScheduledEvent

Returns:

The partial scheduled event object.

get_partial_sku(sku_id) PartialSKU

Creates a partial SKU object.

Return type:

PartialSKU

Returns:

The partial SKU object.

Parameters:

sku_id (int)

get_partial_soundboard_sound(sound_id, *, guild_id=None) PartialSoundboardSound

Creates a partial sticker object.

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

  • guild_id (int | None) – Guild ID to create the partial soundboard sound object with.

Return type:

PartialSoundboardSound

Returns:

The partial soundboard sound object.

get_partial_sticker(sticker_id, *, guild_id=None) PartialSticker

Creates a partial sticker object.

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

  • guild_id (int | None) – Guild ID to create the partial sticker object with.

Return type:

PartialSticker

Returns:

The partial sticker object.

get_partial_user(user_id) PartialUser

Creates a partial user object.

Parameters:

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

Return type:

PartialUser

Returns:

The partial user object.

get_partial_voice_state(member_id, *, guild_id=None, channel_id=None) PartialVoiceState

Creates a partial voice state object.

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

  • guild_id (int | None) – Guild ID to create the partial voice state from

  • channel_id (int | None) – Channel ID to create the partial voice state from

Return type:

PartialVoiceState

Returns:

The partial voice state object.

get_partial_webhook(webhook_id, *, webhook_token=None) PartialWebhook

Creates a partial webhook object.

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

  • webhook_token (str | None) – Webhook token to create the partial webhook object with.

Return type:

PartialWebhook

Returns:

The partial webhook object.

get_shard_by_guild_id(guild_id) int | None

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

Return type:

int | None

Returns:

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

Raises:

NotImplementedError – If the gateway is not available

group(name=None, *, description=None) Callable

Used to register a sub-command group.

Parameters:
  • name (str | None) – Name of the group, if not provided, it will use the function name

  • description (str | None) – Description of the group, if not provided, it will use the function docstring

Return type:

Callable

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

has_any_dispatch(event_name) bool

Checks if the bot has any listeners for the event.

Parameters:

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

Return type:

bool

Returns:

Whether the bot has any listeners for the event.

interaction(custom_id, *, regex=False) Callable

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

Return type:

Callable

is_ready() bool

Indicates if the client is ready.

Return type:

bool

is_shards_ready() bool

Indicates if the client is shards ready.

Return type:

bool

listener(name=None) Callable

Used to register a listener.

Parameters:

name (str | None) – 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

Return type:

Callable

async load_extension(package) None

Loads an extension.

Parameters:

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

Return type:

None

message_command(name=None, *, guild_ids=None, guild_install=True, user_install=False) Callable

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 (str | None) – Name of the command, if not provided, it will use the function name

  • guild_ids (list[Snowflake | int] | None) – 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

Return type:

Callable

async query_members(guild_id, *, query=None, limit=0, presences=False, user_ids=None, shard_id=None) list[Member]

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

Return type:

list[Member]

Returns:

The members that matched the query

Raises:

ValueError

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

async remove_cog(cog) None

Removes a cog from the bot.

Parameters:

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

Return type:

None

remove_command(func) None

Removes a command from the bot.

Parameters:

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

Return type:

None

remove_interaction(func) None

Removes an interaction from the bot.

Parameters:

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

Return type:

None

remove_listener(func) None

Removes a listener from the bot.

Parameters:

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

Return type:

None

set_backend(*, cls=None) None

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 (Callable | None) – The backend to use for everything. Leave empty to use the default backend.

Return type:

None

set_context(*, cls=None) None

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 (Callable | None) – The context to use for commands. Leave empty to use the default context.

Return type:

None

async setup_hook() None

Runs before 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()
Return type:

None

start(*, host='127.0.0.1', port=8080) None

Boot up the bot and start the HTTP server.

Parameters:
  • host (str) – Host to use, if not provided, it will use 127.0.0.1

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

Return type:

None

async sync_commands() None

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

Return type:

None

async unload_extension(package) None

Unloads an extension.

Parameters:

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

Return type:

None

property user: UserClient

Returns the bot’s user object.

Return type:

The bot’s user object

Raises:

AttributeError – If used before the bot is ready

user_command(name=None, *, guild_ids=None, guild_install=True, user_install=False) Callable

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 (str | None) – Name of the command, if not provided, it will use the function name

  • guild_ids (list[Snowflake | int] | None) – 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

Return type:

Callable

async wait_until_ready() None

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

Return type:

None

async wait_until_shards_ready() None

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

Return type:

None