Client API

---

client

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

E = TypeVar('E', bound=Event) module-attribute

CoreHandler: TypeAlias = Callable[[E], Awaitable[None]] module-attribute

MaybeAwaitable: TypeAlias = Awaitable[None] | None module-attribute

HookHandler: TypeAlias = Callable[[], MaybeAwaitable] module-attribute

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.

• http (HTTPClientProtocol, default: None ) –

  HTTP protocol implementation. Leave blank for default client.

• gateway_impl (GatewayClientProtocol, default: None ) –

  Gateway protocol implementation. Leave blank for default client.

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: HTTPClientProtocol = http or HTTPClient() instance-attribute

Public HTTP session for requests.

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

Shards as a list of gateways.

shard_type = gateway_impl or GatewayClient instance-attribute

events: dict[EventType, list[CoreHandler[Any]]] = {} 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) –

  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.

Raises:

• InvalidCallbackSignature –

  invalid signature

Parameters:

• application_id (Snowflake) –

  ID of target application

Returns:

• Application –

  the Application resource

application_emoji

Creates an interactable application emoji resource.

Parameters:

• application_id (Snowflake) –

  ID of target application

Returns:

• ApplicationEmoji –

  the ApplicationEmoji 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 if command is in guild scope

Returns:

• GuildCommand –

  the GuildCommand resource

guild_emoji

Creates an interactable emoji resource.

Parameters:

• guild_id (Snowflake) –

  guild ID of target emojis

Returns:

• GuildEmoji –

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

message

Creates an interactable message resource.

Parameters:

• message_id (Snowflake) –

  ID of target message

• channel_id (Snowflake) –

  channel ID of target message

Returns:

• Message –

  the Message resource

sticker

Creates an interactable sticker resource

Returns:

• Sticker –

  the Sticker resource

user

Creates an interactable user resource.

Returns:

• User –

  the User resource

listen_shard async

Consume a gateway client's event queue.

Parameters:

• shard (GatewayClientProtocol) –

  gateway to listen on

start_shards async

Starts all shards batching by max_concurrency.

Parameters:

• gateway (GatewayEvent) –

  gatewway info event data

Returns:

• list[Task[Any]] –

  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.