Client API

---

client

logger = logging.getLogger('scurrypy.client') module-attribute

CoreHandler = Callable[[JsonQuery], Awaitable[None]]

HookHandler = Callable[[], Awaitable[None] | None]

Client

Main entry point for Discord bots. Ties together the moving parts: gateway, HTTP and event dispatching.

Parameters:

• token (str) –

  the bot's token

• intents (Intents, default: DEFAULT ) –

  gateway intents. Defaults to Intents.DEFAULT.

• shard_count (int, default: 0 ) –

  number of shards to spawn. Defaults to 0 or recommended shard count.

token: str = token instance-attribute

Bot's token.

intents: Intents = intents instance-attribute

Bot intents for listening to events.

shard_count = shard_count instance-attribute

http: HttpClient = HttpClient() instance-attribute

Public HTTP session for requests.

shards: list[GatewayClient] = [] instance-attribute

Shards as a list of gateways.

events: dict[EventType | str, list[CoreHandler]] = {} instance-attribute

Events for the client to listen to.

startup_hooks: list[HookHandler] = [] instance-attribute

Handlers to call once before the bot starts.

shutdown_hooks: list[HookHandler] = [] instance-attribute

Handlers to call once after the bot shuts down.

add_event_listener

Helper function to register listener functions.

Parameters:

• event (EventType | str) –

  name of the event to listen

• handler (CoreHandler) –

  listener function

add_startup_hook

Register a startup function. Runs once on startup BEFORE READY event.

Raises:

• InvalidCallbackSignature –

  invalid signature

Parameters:

• handler (HookHandler) –

  startup function

add_shutdown_hook

Register a shutdown function. Runs once on shutdown.

Raises:

• InvalidCallbackSignature –

  invalid signature

Parameters:

• handler (HookHandler) –

  shutdown function

application

Creates an interactable application resource.

Parameters:

• application_id (Snowflake) –

  ID of target application

Returns:

• Application –

  the Application resource

audit_log

Creates an interactable application resource.

Returns:

• AuditLog –

  the AuditLog resource

application_emoji

Creates an interactable application emoji resource.

Parameters:

• application_id (Snowflake) –

  ID of target application

Returns:

• ApplicationEmoji –

  the ApplicationEmoji resource

auto_moderation

Creates an interactable application auto moderation resource.

Parameters:

• guild_id (Snowflake) –

  guild ID of target automod rules

Returns:

• AutoModeration –

  the AutoModeration resource

channel

Creates an interactable channel resource.

Parameters:

• channel_id (Snowflake) –

  ID of target channel

Returns:

• Channel –

  the Channel resource

global_command

Creates an interactable command resource.

Parameters:

• application_id (Snowflake) –

  bot's user ID

Returns:

• GlobalCommand –

  the GlobalCommand resource

guild_command

Creates an interactable command resource.

Parameters:

• application_id (Snowflake) –

  bot's user ID

• guild_id (Snowflake) –

  ID of guild in which the command belongs

Returns:

• GuildCommand –

  the GuildCommand resource

guild_emoji

Creates an interactable guild emoji resource.

Parameters:

• guild_id (Snowflake) –

  guild ID of target emojis

Returns:

• GuildEmoji –

  the GuildEmoji resource

guild_scheduled_event

Creates an interactable guild scheduled event resource.

Parameters:

• guild_id (Snowflake) –

  ID of target guild

Returns:

• GuildScheduledEvent –

  the GuildScheduledEvent resource

guild_template

Creates an interactable guild template resource.

Returns:

• GuildTemplate –

  the GuildTemplate resource

guild

Creates an interactable guild resource.

Parameters:

• guild_id (Snowflake) –

  ID of target guild

Returns:

• Guild –

  the Guild resource

interaction

Creates an interactable interaction resource.

Parameters:

• id (Snowflake) –

  ID of the interaction

• token (str) –

  interaction token

Returns:

• Interaction –

  the Interaction resource

invite

Creates an interactable invite resource.

Parameters:

• code (str) –

  unique invite code

Returns:

• Invite –

  the Invite resource

message

Creates an interactable message resource.

Parameters:

• channel_id (Snowflake) –

  channel ID of target message

• message_id (Snowflake) –

  ID of target message

Returns:

• Message –

  the Message resource

poll

Creates an interactable poll resource

Parameters:

• channel_id (Snowflake) –

  ID of target message

• message_id (Snowflake) –

  channel ID of target message

Returns:

• Poll –

  the Poll resource

sticker

Creates an interactable sticker resource

Returns:

• Sticker –

  the Sticker resource

user

Creates an interactable user resource.

Returns:

• User –

  the User resource

webhook

Creates an interactable webhook resource.

Returns:

• Webhook –

  the Webhook resource

get_shard_from_guild_id

Fetch the shard in which the guild belongs.

Parameters:

• guild_id (Snowflake) –

  ID of the guild

Returns:

• GatewayClient –

  shard of the guild

get_shard_id_from_guild_id

Fetch the shard ID in which the guild belongs.

Parameters:

• guild_id (Snowflake) –

  ID of the guild

Returns:

• int –

  shard ID of the guild

listen_shard async

Consume a gateway client's event queue.

Parameters:

• shard (GatewayClient) –

  gateway to listen on

start_shards async

Starts all shards batching by max_concurrency.

Parameters:

• gateway (JsonQuery) –

  gatewway info event data

Returns:

• list[Task[None]] –

  list[asyncio.Task]: list of gateway connection tasks

start async

Starts the HTTP/Websocket client, run startup logic, and registers commands.

run_startup_hooks async

Runs registered startup hooks.

run_shutdown_hooks async

Runs registered shutdown hooks.

close async

Gracefully close HTTP session, websocket connections, and run shutdown logic.

run

User-facing entry point for starting the client.