camel.bots.discord package

On this page

camel.bots.discord package#

Submodules#

camel.bots.discord.discord_app module#

class camel.bots.discord.discord_app.DiscordApp(channel_ids: List[int] | None = None, token: str | None = None, client_id: str | None = None, client_secret: str | None = None, redirect_uri: str | None = None, installation_store: DiscordBaseInstallationStore | None = None, intents: Intents | None = None)[source]#

Bases: object

A class representing a Discord app that uses the discord.py library to interact with Discord servers.

This bot can respond to messages in specific channels and only reacts to messages that mention the bot.

channel_ids#

A list of allowed channel IDs. If provided, the bot will only respond to messages in these channels.

Type:

Optional[List[int]]

token#

The Discord bot token used for authentication.

Type:

Optional[str]

property client#
async exchange_code_for_token_response(code: str) → str | None[source]#

Exchange the authorization code for an access token.

Parameters:

code (str) – The authorization code received from Discord after user authorization.

Returns:

The access token if successful, otherwise None.

Return type:

Optional[str]

Raises:

  • ValueError – If OAuth configuration is incomplete or invalid.

  • httpx.RequestError – If there is a network issue during the request.

async get_user_info(access_token: str) → dict | None[source]#

Retrieve user information using the access token.

Parameters:

access_token (str) – The access token received from Discord.

Returns:

The user information retrieved from Discord.

Return type:

dict

async get_valid_access_token(guild_id: str) → str | None[source]#

Retrieve a valid access token for the specified guild.

This method attempts to retrieve an access token for a specific guild. If the current access token is expired, it will refresh the token using the refresh token.

Parameters:

guild_id (str) – The ID of the guild to retrieve the access token for.

Returns:

The valid access token if successful,

otherwise None.

Return type:

Optional[str]

async on_message(message: Message) → None[source]#

Event handler for processing incoming messages.

This method is called whenever a new message is received by the bot. It will ignore messages sent by the bot itself, only respond to messages in allowed channels (if specified), and only to messages that mention the bot.

Parameters:

message (discord.Message) – The message object received from Discord.

async on_ready() → None[source]#

Event handler that is called when the bot has successfully connected to the Discord server.

When the bot is ready and logged into Discord, it prints a message displaying the bot’s username.

async refresh_access_token(refresh_token: str) → str | None[source]#

Refresh the access token using a refresh token.

Parameters:

refresh_token (str) – The refresh token issued by Discord that can be used to obtain a new access token.

Returns:

The new access token if successful, otherwise None.

Return type:

Optional[str]

async remove_installation(guild: Guild)[source]#

Remove the installation for a given guild.

Parameters:

guild (discord.Guild) – The guild from which the bot is being removed.

run() → None[source]#

Start the Discord bot using its token.

This method starts the bot and logs into Discord synchronously using the provided token. It blocks execution and keeps the bot running.

async save_installation(guild_id: str, access_token: str, refresh_token: str, expires_in: int)[source]#

Save the installation information for a given guild.

Parameters:

  • guild_id (str) – The ID of the guild where the bot is installed.

  • access_token (str) – The access token for the guild.

  • refresh_token (str) – The refresh token for the guild.

  • expires_in – (int): The expiration time of the access token.

async start()[source]#

Asynchronously start the Discord bot using its token.

This method starts the bot and logs into Discord asynchronously using the provided token. It should be awaited when used in an async environment.

camel.bots.discord.discord_installation module#

class camel.bots.discord.discord_installation.DiscordInstallation(guild_id: str, access_token: str, refresh_token: str, installed_at: datetime, token_expires_at: datetime | None = None)[source]#

Bases: object

Represents an installation of a Discord application in a

specific guild (server).

guild_id#

The unique identifier for the Discord guild (server) where the application is installed.

Type:

str

access_token#

The access token used to authenticate API requests for the installed application.

Type:

str

refresh_token#

The token used to refresh the access token when it expires.

Type:

str

installed_at#

The timestamp indicating when the application was installed in the guild.

Type:

datetime

token_expires_at#

The optional timestamp indicating when the access token will expire. Defaults to None if the token does not have an expiration time.

Type:

Optional[datetime]

camel.bots.discord.discord_store module#

class camel.bots.discord.discord_store.DiscordBaseInstallationStore[source]#

Bases: object

Abstract base class for managing Discord installations.

This class defines the interface for database operations related to storing and retrieving Discord installation data. Subclasses must implement these methods to handle database-specific logic.

async delete(guild_id: str)[source]#

Deletes an installation record by guild ID.

async find_by_guild(guild_id: str) → DiscordInstallation | None[source]#

Finds an installation record by guild ID.

async init()[source]#

Initializes the database connection or structure.

async save(installation: DiscordInstallation)[source]#

Saves or updates a Discord installation record.

class camel.bots.discord.discord_store.DiscordSQLiteInstallationStore(database: str)[source]#

Bases: DiscordBaseInstallationStore

SQLite-based implementation for managing Discord installations.

This class provides methods for initializing the database, saving, retrieving, and deleting installation records using SQLite.

database#

Path to the SQLite database file.

Type:

str

async delete(guild_id: str)[source]#

Deletes an installation record by guild ID.

Parameters:

guild_id (str) – The guild ID of the record to delete.

async find_by_guild(guild_id: str) → DiscordInstallation | None[source]#

Finds an installation record by guild ID.

Parameters:

guild_id (str) – The guild ID to search for.

Returns:

The installation record if found,

otherwise None.

Return type:

Optional[DiscordInstallation]

async init()[source]#

Initializes the database by creating the required table if it does not exist.

async save(installation: DiscordInstallation)[source]#

Saves a new installation record or updates an existing one.

Parameters:

installation (DiscordInstallation) – The installation data to save.

Module contents#

class camel.bots.discord.DiscordApp(channel_ids: List[int] | None = None, token: str | None = None, client_id: str | None = None, client_secret: str | None = None, redirect_uri: str | None = None, installation_store: DiscordBaseInstallationStore | None = None, intents: Intents | None = None)[source]#

Bases: object

A class representing a Discord app that uses the discord.py library to interact with Discord servers.

This bot can respond to messages in specific channels and only reacts to messages that mention the bot.

channel_ids#

A list of allowed channel IDs. If provided, the bot will only respond to messages in these channels.

Type:

Optional[List[int]]

token#

The Discord bot token used for authentication.

Type:

Optional[str]

property client#
async exchange_code_for_token_response(code: str) → str | None[source]#

Exchange the authorization code for an access token.

Parameters:

code (str) – The authorization code received from Discord after user authorization.

Returns:

The access token if successful, otherwise None.

Return type:

Optional[str]

Raises:

  • ValueError – If OAuth configuration is incomplete or invalid.

  • httpx.RequestError – If there is a network issue during the request.

async get_user_info(access_token: str) → dict | None[source]#

Retrieve user information using the access token.

Parameters:

access_token (str) – The access token received from Discord.

Returns:

The user information retrieved from Discord.

Return type:

dict

async get_valid_access_token(guild_id: str) → str | None[source]#

Retrieve a valid access token for the specified guild.

This method attempts to retrieve an access token for a specific guild. If the current access token is expired, it will refresh the token using the refresh token.

Parameters:

guild_id (str) – The ID of the guild to retrieve the access token for.

Returns:

The valid access token if successful,

otherwise None.

Return type:

Optional[str]

async on_message(message: Message) → None[source]#

Event handler for processing incoming messages.

This method is called whenever a new message is received by the bot. It will ignore messages sent by the bot itself, only respond to messages in allowed channels (if specified), and only to messages that mention the bot.

Parameters:

message (discord.Message) – The message object received from Discord.

async on_ready() → None[source]#

Event handler that is called when the bot has successfully connected to the Discord server.

When the bot is ready and logged into Discord, it prints a message displaying the bot’s username.

async refresh_access_token(refresh_token: str) → str | None[source]#

Refresh the access token using a refresh token.

Parameters:

refresh_token (str) – The refresh token issued by Discord that can be used to obtain a new access token.

Returns:

The new access token if successful, otherwise None.

Return type:

Optional[str]

async remove_installation(guild: Guild)[source]#

Remove the installation for a given guild.

Parameters:

guild (discord.Guild) – The guild from which the bot is being removed.

run() → None[source]#

Start the Discord bot using its token.

This method starts the bot and logs into Discord synchronously using the provided token. It blocks execution and keeps the bot running.

async save_installation(guild_id: str, access_token: str, refresh_token: str, expires_in: int)[source]#

Save the installation information for a given guild.

Parameters:

  • guild_id (str) – The ID of the guild where the bot is installed.

  • access_token (str) – The access token for the guild.

  • refresh_token (str) – The refresh token for the guild.

  • expires_in – (int): The expiration time of the access token.

async start()[source]#

Asynchronously start the Discord bot using its token.

This method starts the bot and logs into Discord asynchronously using the provided token. It should be awaited when used in an async environment.

class camel.bots.discord.DiscordBaseInstallationStore[source]#

Bases: object

Abstract base class for managing Discord installations.

This class defines the interface for database operations related to storing and retrieving Discord installation data. Subclasses must implement these methods to handle database-specific logic.

async delete(guild_id: str)[source]#

Deletes an installation record by guild ID.

async find_by_guild(guild_id: str) → DiscordInstallation | None[source]#

Finds an installation record by guild ID.

async init()[source]#

Initializes the database connection or structure.

async save(installation: DiscordInstallation)[source]#

Saves or updates a Discord installation record.

class camel.bots.discord.DiscordInstallation(guild_id: str, access_token: str, refresh_token: str, installed_at: datetime, token_expires_at: datetime | None = None)[source]#

Bases: object

Represents an installation of a Discord application in a

specific guild (server).

guild_id#

The unique identifier for the Discord guild (server) where the application is installed.

Type:

str

access_token#

The access token used to authenticate API requests for the installed application.

Type:

str

refresh_token#

The token used to refresh the access token when it expires.

Type:

str

installed_at#

The timestamp indicating when the application was installed in the guild.

Type:

datetime

token_expires_at#

The optional timestamp indicating when the access token will expire. Defaults to None if the token does not have an expiration time.

Type:

Optional[datetime]

class camel.bots.discord.DiscordSQLiteInstallationStore(database: str)[source]#

Bases: DiscordBaseInstallationStore

SQLite-based implementation for managing Discord installations.

This class provides methods for initializing the database, saving, retrieving, and deleting installation records using SQLite.

database#

Path to the SQLite database file.

Type:

str

async delete(guild_id: str)[source]#

Deletes an installation record by guild ID.

Parameters:

guild_id (str) – The guild ID of the record to delete.

async find_by_guild(guild_id: str) → DiscordInstallation | None[source]#

Finds an installation record by guild ID.

Parameters:

guild_id (str) – The guild ID to search for.

Returns:

The installation record if found,

otherwise None.

Return type:

Optional[DiscordInstallation]

async init()[source]#

Initializes the database by creating the required table if it does not exist.

async save(installation: DiscordInstallation)[source]#

Saves a new installation record or updates an existing one.

Parameters:

installation (DiscordInstallation) – The installation data to save.

On this page