Client¶

discord_http.client module¶

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

Bases: object

The main client class for discord.http.

Parameters:

token (str) – Discord bot token
guild_id (int | None) – Guild ID to sync commands to, if not provided, it will sync to global
sync (bool) – Whether to sync commands on boot or not (defaults to True)
max_pending_connections (int) – The maximum number of queued connections passed to the interaction URL, by default 128. If your bot is receiving a lot of traffic, you might want to increase this value.
api_version (int) – API version to use for both HTTP and WS, if not provided, it will use the default (10)
api_base_url (str | None) – Base URL to use for the API, if not provided, it will use the default (https://discord.com/api)
loop (asyncio.AbstractEventLoop | None) – Event loop to use, if not provided, it will use asyncio.get_running_loop()
allowed_mentions (AllowedMentions | None) – Allowed mentions to use, if not provided, it will use AllowedMentions.all()
enable_gateway (bool) – Whether to enable the gateway or not, which runs in the background
automatic_shards (bool) – Whether to automatically shard the bot or not
playing_status (PlayingStatus | None) – The playing status to use, if not provided, it will use None. This is only used if enable_gateway is True.
chunk_guilds_on_startup (bool) – Whether to chunk guilds or not when booting, which will reduce the amount of requests
guild_ready_timeout (float) – Gateway: How long to wait for last GUILD_CREATE to be recieved before triggering shard ready
gateway_cache (GatewayCacheFlags | None) – How the gateway should cache, only used if enable_gateway is True. Leave empty to use no cache.
intents (Intents | None) – Intents to use, only used if enable_gateway is True
logging_level (int) – Logging level to use, if not provided, it will use logging.INFO
call_after_delay (float | int) – How long to wait before calling the call_after coroutine
debug_events (bool) – Whether to log events or not, if not provided, on_raw_* events will not be useable
interaction_path (str | None) – Path to the interaction endpoint, if not provided, it will use the default path which is just / (aka. root).
disable_default_get_path (bool) – Whether to disable the default GET path or not, if not provided, it will use False. The default GET path only provides information about the bot and when it was last rebooted. Usually a great tool to just validate that your bot is online.
application_id (int | None)
public_key (str | None)

application: Application | None¶: The application object for the bot.

gateway: GatewayClient | None¶: The gateway client, if enabled.

commands: dict[str, Command]¶: The commands registered to the client.

listeners: list[Listener]¶: The listeners registered to the client.

interactions: dict[str, Interaction]¶: The interactions registered to the client.

interactions_regex: dict[str, Interaction]¶: The interactions registered to the client with regex.

cache: Cache¶: The cache for the client, used for caching guilds, users, etc.

state: DiscordAPI¶: The state for the client, used for making HTTP requests.

backend: DiscordHTTP¶: The backend for the client, used for serving HTTP requests.

async update_me() → User¶

Get’s the current application and returns the bot user.

Return type:: User

property application_id: int | None¶: Alias for getting the application ID.

property public_key: str | None¶: Alias for getting the public key of the bot.

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

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 (defaults to an empty string, which will return all members)
limit (int) – The maximum amount of members to return (defaults to 0, which will return all members)
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 sync_commands() → None¶

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

Return type:: None

property user: User¶

Returns the bot’s user object.

Raises:

AttributeError –

If used before the bot is ready - If the application does not have a bot user associated with it

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

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.

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

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

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

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

offline_run(func) → None¶

Used to run Discord API instructions without booting the bot.

The function will be ran only once and then the script ends. Useful for when you just want to run simple things without needing to run a full bot.

Parameters:: func (Callable[[], Coroutine[Any, Any, None]]) – The async function to run.
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 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

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

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.

async load_extension(package) → None¶

Loads an extension.

Parameters:: package (str) – The package to load the extension from.
Return type:: None

async unload_extension(package) → None¶

Unloads an extension.

Parameters:: package (str) – The package to unload the extension from.
Return type:: None

async reload_extension(package) → None¶

Reloads an extension.

Parameters:

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

Raises:

RuntimeError –

If the extension failed to reload, but the previous state was restored successfully - If the extension failed to reload, and the previous state failed to be restored

Return type:

None

async add_cog(cog) → None¶

Adds a cog to the bot.

Parameters:: cog (Cog) – The cog to add to the bot.
Return type:: None

async remove_cog(cog) → None¶

Removes a cog from the bot.

Parameters:: cog (Cog) – The cog to remove from the bot.
Return type:: None

async wait_for(event_name, *, check=None, timeout=None) → Coroutine[Any, Any, Any]¶

Waits for an event to be dispatched.

This requires gateway to be enabled. Otherwise it will log a warning and return None.

Parameters:

event_name (str) – The name of the event to wait for.
check (Callable[..., bool] | None) – The check to use, by default None.
timeout (float | None) – The timeout to use, by default None.

Return type:

Coroutine[Any, Any, Any]

Returns:

The event parameters

Raises:

TimeoutError – If the event was not dispatched within the timeout

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

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

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

before_invoke() → Callable¶

Decorator to register a function to be called before a command is ran globally.

If it returns anything other than True, the command will not be invoked. However if you raise a CheckFailure exception, it will fail and you can add a message to it.

Parameters:: func (Callable) – The function to be called before the command is invoked.
Return type:: Callable

after_invoke() → Callable¶

Decorator to register a function to be called after a command is ran globally.

This acts like before_invoke, however it only runs after the command has been invoked successfully.

Parameters:: func (Callable) – The function to be called after the command is invoked.
Return type:: Callable

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

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

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

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

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_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.

async fetch_current_application() → Application¶

Fetches and update cache of the current application object.

Return type:: Application

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.

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

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

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_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.

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.

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.

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

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.

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.

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.

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_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.

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.

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

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.

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.

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.

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.

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.

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_application_emojis() → list[Emoji]¶

Fetches all emojis available to the application.

Return type:: list[Emoji]

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.

get_partial_sku(sku_id) → PartialSKU¶

Creates a partial SKU object.

Return type:: PartialSKU
Returns:: The partial SKU object.
Parameters:: sku_id (int)

async fetch_skus() → list[SKU]¶

Fetches all SKUs available to the bot.

Return type:: list[SKU]

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.

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.

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.

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.

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.

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 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

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.

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.

add_listener(func) → Listener¶

Adds a listener to the bot.

Parameters:: func (Listener) – The listener to add to the bot.
Return type:: Listener

remove_listener(func) → None¶

Removes a listener from the bot.

Parameters:: func (Listener) – The listener to remove from 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

remove_command(func) → None¶

Removes a command from the bot.

Parameters:: func (Command) – The command to remove from the bot.
Return type:: None

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_interaction(func) → Interaction¶

Adds an interaction to the bot.

Parameters:: func (Interaction) – The interaction to add to the bot.
Return type:: Interaction

remove_interaction(func) → None¶

Removes an interaction from the bot.

Parameters:: func (Interaction) – The interaction to remove from the bot.
Return type:: None