dico.client module

class dico.client.Client(token, *, intents=<dico.model.gateway.Intents object>, default_allowed_mentions=None, loop=None, cache=True, application_id=None, monoshard=False, shard_count=None, shard_id=None, **cache_max_sizes)

Bases: APIClient

Client with async request handler and websocket connection.

Parameters:

  • token (str) – Token of the client.

  • intents (Intents) – Intents to use. Default everything except privileged.

  • default_allowed_mentions (Optional[AllowedMentions]) – Default allowed mentions object to use. Default None.

  • loop (Optional[asyncio.AbstractEventLoop]) – asyncio Event loop object to use. Default automatic.

  • cache (bool) – Whether to enable caching. Default True.

  • application_id (Optional[Union[int, str, Snowflake]]) – Application ID if needed.

  • monoshard (bool) – Whether to mono-shard this bot.

  • shard_count (Optional[int]) – Count of shards to launch, if monoshard is True.

  • shard_id (Optional[int]) – Shard ID of the client. This is not recommended.

  • cache_max_sizes – Max sizes of the cache per types. Message limit is set to 1000 by default.

Variables:

  • ~.http (AsyncHTTPRequest) – HTTP request client.

  • ~.default_allowed_mentions (Optional[AllowedMentions]) – Default model.channel.AllowedMentions object of the client.

  • ~.loop (asyncio.AbstractEventLoop) – asyncio Event loop object of the client.

  • ~.token (str) – Application token of the client.

  • ~.cache (Optional[CacheContainer]) – Cache container of the client.

  • ~.intents (Intents) – Intents of the client.

  • ~.ws (Optional[WebSocketClient]) – Websocket client of the client.

  • ~.events (EventHandler) – Event handler of the client.

  • ~.application (Optional[Application]) – Application object of the client.

  • ~.application_id (Optional[Snowflake]) – ID of the application. Can be None if Ready event is not called, and if it is, you must pass parameter application_id for all methods that has it.

  • ~.monoshard (bool) – Whether mono-sharding is enabled.

  • ~.shard_count (Optional[int]) – Current shard count of the bot.

  • user (Optional[User]) – Application user of the client.

on_(name=None, meth=None)

Adds new event listener. This can be used as decorator or function.

Example:

@client.on_("message_create")  # Also can use "@client.on(...)" or "@client.on_message_create", and event name is default name of the function.
async def on_message_create(message: dico.Message):
    ...

def initial_actions(ready: dico.Ready):  # Both coroutine and normal function can be used.
    ...
client.on_("ready", initial_actions)  # Alias is "client.on(..., ...)"

client.on_ready = lambda r: print("Ready!")  # You may also directly assign event.
Parameters:

  • name (Optional[str]) – Name of the event. Case-insensitive. Default name of the function.

  • meth (Optional[Union[Callable, Coroutine]]) – Method or Coroutine, if you don’t want to use as decorator.

property on

Alias of on_()

wait(event_name, timeout=None, check=None)

Waits for the event dispatch.

Parameters:

  • event_name (str) – Name of the event. Case insensitive.

  • timeout (Optional[float]) – Timeout time in second. If not passed, it will wait forever.

  • check (Optional[Callable[[Any], bool]]) – Check function of the event. If passed, it will wait until the event result passes the check.

Returns:

Payload of the event.

Raises:
dispatch(name, *args)

Dispatches new event.

Parameters:

  • name (str) – Name of the event.

  • args (Any) – Arguments of the event.

get_shard_id(guild)

Gets shard ID from guild.

Parameters:

guild – Guild to get shard ID.

Returns:

ID of the shard.

get_shard(guild)

Gets shard from guild.

Parameters:

guild – Guild to get shard.

Returns:

ws.websocket.WebSocketClient

get_voice_state(user)

Gets user’s voice state.

Parameters:

user – User to get voice state.

Returns:

Optional[VoiceState]

get_all_voice_states(guild, channel=None)

Gets guild’s all voice states.

Parameters:

  • guild – Guild to get voice states.

  • channel – Voice or Stage channel to get voice states.

Returns:

List[VoiceState]

async wait_ready()

Waits until bot is ready.

async connect_voice(guild, channel, *, timeout=10, raise_hand=False)

Connects to voice channel and prepares voice client.

Parameters:

  • guild – Guild to connect voice.

  • channel – Channel to connect.

  • timeout (int) – Timeout for waiting voice server update event. Default 30.

  • raise_hand (bool) – Whether to raise hand in stage channel. Default False.

Returns:

VoiceClient

Raises:

VoiceTimeout – Failed to connect to voice before timeout. Try again.

get_voice_client(guild)

Gets guild’s voice client.

Parameters:

guild – Guild to get voice client.

Returns:

Optional[VoiceClient]

property get

Alias of .cache.get.

Note

These shortcuts are also available: get_guild, get_channel, get_role, get_user, get_sticker, get_message

async start(reconnect_on_unknown_disconnect=False, compress=False)

Starts websocket connection.

Warning

You can call this only once.

Parameters:

  • reconnect_on_unknown_disconnect (bool) – Whether to reconnect on unknown websocket error.

  • compress (bool) – Whether to enable zlib compress.

async close()

Clears all connections and closes session.

async update_presence(*, since=None, activities, status='online', afk=False)

Updates the bot presence.

All parameters must be passed as keyword.

Parameters:

  • since (Optional[int]) – Time as millisecond when the bot was idle since.

  • activities (List[Union[Activity, dict]]) – List of activities.

  • status (str) – Status of the bot. Default online.

  • afk (bool) – Whether the bot is AFK.

update_voice_state(guild, channel=None, self_mute=False, self_deaf=False)

Changes the voice state of the bot in guild. (Connecting/Disconnecting from the guild, etc…)

Parameters:

  • guild – Guild to change presence.

  • channel – Voice channel to connect. Pass nothing or None to disconnect from the channel.

  • self_mute (bool) – Whether the bot is self-muted.

  • self_deaf (bool) – Whether the bot is self-deaf.

async increase_shards(number=1, *, auto=False)

Increases numbers of shards.

Warning

During this action, client will be offline.

Parameters:

  • number (int) – Number of shards to increase. Default 1.

  • auto (bool) – Whether to automatically use recommended number. Default False.

property has_cache

Whether the caching is enabled.

property websocket_closed

Whether the bot is disconnected from the Discord websocket. If the bot is sharded, then it will return whether every shards are available.

property shards_closed

Returns list of whether the shard is closed.

property guild_count

Total count of guilds this bot is in. This may be incorrect since this relies on initial guild count or cached guild count.

property ping

Websocket ping of the bot. If it is sharded, then it will return average ping between shards.

property shards

Tuple of shards this bot has.

run(*, reconnect_on_unknown_disconnect=False, compress=False)

Runs client and clears every connections after stopping due to error or KeyboardInterrupt.

Warning

This must be placed at the end of the code.

Parameters:

  • reconnect_on_unknown_disconnect (bool) – Whether to reconnect on unknown websocket error.

  • compress (bool) – Whether to enable zlib compress.

kill()

Kills event loop and stops bot.