API Reference#

The following section covers the API of Discode.

Clients#

These are the clients, that the library provides.

Client#

The base client to use to connect to the api and receive events.

Attributes
Methods
class discode.Client(token, *, intents=None, api_version=10, gateway_version=9, shard_count=None, gateway_timeout=5.0)#

Represents the Client that connects to the Discord Gateway and HTTP Api.

Parameters

  • token (str) – The token to use to communicate with the gateway and REST APIs.

  • intents (Intents) – The intents to use while connecting to the gateway. Defaults to Intents.all().

  • loop (asyncio.AbstractEventLoop) – The event loop the client should use for asynchronous operations.

token#

The token used to connect to the REST & gateway APIs.

Type

str

intents#

The intents the client is using.

Type

Intents

loop#

The event loop used by the client for asynchronous operations.

Type

asyncio.AbstractEventLoop

@on_event(event)#

Decorator to register event listeners to the client. The function decorated must be a coroutine. This decorator uses Client.add_listener() to register the listener.

Parameters

event (str) – The event the listener should be registered for.

Raises

TypeError – The function decorated isn’t a coroutine.

property latency#

The average latency of the websocket connection over all the shards.

Type

float

property is_ready#

bool Whether the client is completely ready for use or no.

property user#

The user object belonnging to the client.

Type

ClientUser

property users#

A list of all the users the client can see.

Type

List[User]

property guilds#

A list of all the guilds visible to the client.

Type

List[Guild]

property messages#

A list of all the messages cached by the client.

Type

List[Message]

property channels#

A list of all the channels cached by the client.

Type

List[Union[TextChannel, DMChannel]]

property dm_channels#

A list of all the direct message channels cached by the client.

Type

List[DMChannel]

property invite_url#

Generates an invite url forr the client and returns it.

Type

str

property session#

The client session used by the http client for making requests to the Discord API.

Type

aiohttp.ClientSession

property shards#

All the shards connected to the gateway.

Type

List[Shard]

async wait_until_ready()#

Client: Wait until the bot is completely ready to use.

async run_task(*args, reconnect=True, compress=True, **kwargs)#

This method is a coroutine. It is used to start the client, i.e., connect to gateway API and the REST API. It prepares the client completely.

Returns

The client itself.

Return type

Client

run(*args, **kwargs)#

Synchronous alternative to Client.run_task(). Uses asyncio.run() internally to run the bot.

Warning

Code written after this function is called will not get executed till the bot stops.

Returns

The client itself.

Return type

Client

async close()#

Closes the client, the http client, and the gateway connection.

add_listener(coro, event)#

This function registers a listener to the client.

Parameters

  • coro (Coro) – A callable coroutine.

  • event (str) – The event to which the listener should be registered to. This event must be a valid event documented under GatewayEvent.

Returns

The coroutine passed in as a parameter.

Return type

Coro

Raises

TypeError – The coro passed in parameters isn’t a coroutine.

async dispatch(event, *args, **kwargs)#
async wait_for(event, check, *, timeout=30)#

Waits for a dispatch event from the websocket.

This method can be used to wait for a user to send a message that matches the passed check.

Parameters

  • event (str) – The event to wait for. Must be a valid event documented under GatewayEvent.

  • check (Union[Callable[True], Coro]) – The check that should be run on the event. Can either be a normal function or a coroutine, with valid parameters specified under GatewayEvent. Must return True if the check is successful.

Returns

The future created to wait for the event.

Return type

asyncio.Future

Raises

asyncio.TimeoutError – The timeout has finished.

Event Reference#

Discode allows users to listen for dispatch events received thru the gateway. All events must be registered in the following format:

@client.on_event(discode.GatewayEvent.READY)
async def on_ready():
    print(client.user, "is ready"!)

See GatewayEvent for more information on dispatch events.

class discode.GatewayEvent#

This class has all available gateway events, and information on how to register a listener for each of the events. An event maybe registered like this:

@client.event(GatewayEvent.{EVENT_NAME})
async def example_listener(*args, **kwargs):
    ...
DISPATCH = 'dispatch'#

Dispatch is called whenever the websocket receives an event. Listeners waiting for dispatch must have 1 parameter- ‘payload’

READY = 'ready'#

Dispatched when the client is completely ready. Listeners waiting for this event must not have any parameters.

SHARD_READY = 'shard_ready'#

Dispatched when a shard is ready. This event takes 1 parameter- ‘shard_id’

GUILD_CREATE = 'guild_create'#

Dispatched when the client joins a new guild, or the client receives data on a guild it is already in. This event takes 1 parameter- ‘guild’

GUILD_UPDATE = 'guild_update'#

Dispatched when a guild that the client is already in gets updated. This event takes two parameters- ‘before’ & ‘after’

GUILD_DELETE = 'guild_delete'#

Dispatched when the client gets removed from a guild, or the guild itself gets deleted by the owner. This event takes 1 parameter- ‘guild’

MESSAGE_CREATE = 'message_create'#

Dispatched when a user / bot sends a message. This event takes 1 parameter- ‘message’

MESSAGE_UPDATE = 'message_update'#

Dispatched when a user/bot edits a message. This event takes 2 parameters- ‘before’ & ‘after’

MESSAGE_EDIT = 'message_update'#

Enumerations#

This section describes in detail all the available enumerations Discode Provides.

ButtonStyle#

class discode.ButtonStyle#

Buttons come in a variety of styles to convey different types of actions. These styles also define what fields are valid for a button.

primary = 1#
secondary = 2#
success = 3#
danger = 4#
blurple = 1#
grey = 2#
green = 3#
red = 4#
url = 5#

Utilities#

Discode provides a wide range of utilities for making developing Discord bots, and Discord related projects for developers. These are some of the documented utilities.

discode.utils.invite_url(client_id, *, permissions=..., scopes=..., redirect_uri=...)#

Generates an invite url based on the given parameters for the client.

Returns

The invite url generated.

Return type

str

discode.utils.get_event_loop()#

Alternative to asyncio.get_event_loop(). Creates a new loop or fetches an existing event loop and returns it. Avoids DeprecationWarning warning to be thrown while called in Python v3.10 and higher versions.

Returns

The existing or newly created loop.

Return type

asyncio.AbstractEventLoop

async discode.utils.run_async(func, *args, **kwargs)#

Run a function asynchronously and wait for it to complete.

Returns

The return value of the function.

Return type

Any

discode.utils.escape_markdown(text)#

Get rid of Discord markdown highlighting from given text.

Parameters

text (str) – The text to get freed from markdown highlighting in Discord.

Returns

Text passed in text parameter freed from Discord markdown highlighting.

Return type

str

@discode.utils.async_function#

Decorator to make synchronous function asynchronous. Useful with modules like Pillow, which have a synchronous backend but are extremely useful in image manipulation.

Usage of this decorator is equivalant to:

# inside coroutine:
await get_event_loop().run_in_executor(
    None,
    functools.partial(sync_function, *args, **kwargs)
)

Example

@discode.utils.async_function
def sync_function(msg: discode.Message):
    do_synchronous_operations_with_message(msg)

@client.on_event("message_create")
async def on_message(msg):
    await sync_function(msg)
@discode.utils.deprecated(instead=None, from_version='2.0.0b2')#

Deprecate a function with this decorator.

Example

@utils.deprecated(instead = "new_function")
def deprecated_function(*args, **kwargs)):
    ...

# somewhere else in code:
depreceated_function(...)

# Now this warns the user not to use the function and instead use an alternative method to do so..

Models#

Asset#

Warning

This class is not to be instanized manually.

Attributes
class discode.Asset(connection, *, url, key, animated=False)#

Represents a Discord Asset. An asset can be either of the following: user avatar, user banner, guild icon, guild banner.

property url#

Returns the url of the asset.

Type

str

property key#

Returns the identifying key of the asset.

Type

str

property animated#

Returns True if the asset is animated else False

Type

bool

ClientUser#

Warning

This class is not to be instanized manually.

Methods
class discode.ClientUser(connection, payload)#

Represents the User that is connected to the gateway.

async send(content=..., *, embed=..., file=..., embeds=[], files=[])#

Send a message to the current channel.

Parameters

  • content (Optional[str]) – The content of the message to send.

  • embeds (List[Embed]) – A list containing embed objects.

  • files (List[File]) –

Returns

The message that was sent to the destination.

Return type

Message

DMChannel#

Warning

This class is not to be instanized manually.

Methods
class discode.DMChannel(connection, payload)#
async send(content=..., *, embed=..., file=..., embeds=[], files=[])#

Send a message to the current channel.

Parameters

  • content (Optional[str]) – The content of the message to send.

  • embeds (List[Embed]) – A list containing embed objects.

  • files (List[File]) –

Returns

The message that was sent to the destination.

Return type

Message

Emoji#

Warning

This class is not to be instanized manually.

class discode.Emoji(connection, payload)#

Guild#

Warning

This class is not to be instanized manually.

Attributes
Methods
class discode.Guild(connection, payload)#

Represents a Discord Guild.

id#

The unique ID of the guild.

Type

int

name#

The name of the guild.

Type

str

property me#

The member object of the client user in the guild.

Type

Member

property members#

An arry of all the members in the guild.

Type

List[Member]

get_member(member_id)#

Get a Member from the cache who matches the member_id parameter.

Returns

The member that was retrieved from the cache

Return type

Member

property channels#

All the channels attached to the guilds cached by the client.

Type

List[TextChannel]

property text_channels#

All the text channels cached by the guild.

Type

List[TextChannel]

Member#

Warning

This class is not to be instanized manually.

Attributes
Methods
class discode.Member(connection, payload)#
property display_name#

Returns the nickname of the member if they have one, else their username

Type

str

property guild#

The guild to which the member is attached to.

Type

Guild

async send(content=..., *, embed=..., file=..., embeds=[], files=[])#

Send a message to the current channel.

Parameters

  • content (Optional[str]) – The content of the message to send.

  • embeds (List[Embed]) – A list containing embed objects.

  • files (List[File]) –

Returns

The message that was sent to the destination.

Return type

Message

async edit(*, nick=..., mute=..., deafen=..., roles=[], reason=...)#

Edit the member.

Returns

The member which was edited.

Return type

Member

Message#

Warning

This class is not to be instanized manually.

class discode.Message(connection, payload)#

MessageReference#

Warning

This class is not to be instanized manually.

class discode.MessageReference(connection, payload)#

Role#

Warning

This class is not to be instanized manually.

class discode.Role(connection, payload)#

Represents a Discord role.

TextChannel#

Warning

This class is not to be instanized manually.

Attributes
Methods
class discode.TextChannel(connection, payload)#

Represents a text channel within a guild.

id#

The unique ID of the channel.

Type

int

name#

The name of the channel.

Type

str

type#

The type of the channel. Returns 0.

Type

int

guild_id#

The ID of the guild to which the channel belongs to.

Type

int

is_nsfw#

Returns whether the channel is an NSFW channel.

Type

bool

property guild#

The guild to which the channel belongs to.

Type

Guild

async send(content=..., *, embed=..., file=..., embeds=[], files=[])#

Send a message to the current channel.

Parameters

  • content (Optional[str]) – The content of the message to send.

  • embeds (List[Embed]) – A list containing embed objects.

  • files (List[File]) –

Returns

The message that was sent to the destination.

Return type

Message

User#

Warning

This class is not to be instanized manually.

Methods
class discode.User(connection, payload)#

Represents a Discord User.

async send(content=..., *, embed=..., file=..., embeds=[], files=[])#

Send a message to the current channel.

Parameters

  • content (Optional[str]) – The content of the message to send.

  • embeds (List[Embed]) – A list containing embed objects.

  • files (List[File]) –

Returns

The message that was sent to the destination.

Return type

Message

Dataclasses#

Embed#

Attributes
class discode.Embed(*, title=None, description=None, colour=None)#

Represents a Discord Embed.

title#

The title of the embed.

Type

str

description#

The description of the embed.

Type

str

colour#

The colour of the embed. Can be of type int, hex or of Colour

Type

Union[hex, int]

File#

class discode.File(fp, *, filename=None, spoiler=False)#

Sharding#

One of the useful features of sharding is that Discode provides it by default.

Shard Object#