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:

token (str)
application_id (int | None)
public_key (str | None)
guild_id (int | None)
sync (bool)
api_version (int)
loop (AbstractEventLoop | None)
allowed_mentions (AllowedMentions | None)
enable_gateway (bool)
automatic_shards (bool)
playing_status (PlayingStatus | None)
chunk_guilds_on_startup (bool)
guild_ready_timeout (float)
gateway_cache (GatewayCacheFlags | None)
intents (Intents | None)
logging_level (int)
call_after_delay (float | int)
disable_default_get_path (bool)
debug_events (bool)

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

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

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

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

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

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

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.

Raises:

TimeoutError – If the event was not dispatched within the timeout

Return type:

Coroutine[Any, Any, Any]

Returns:

The event parameters

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