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

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