from dubious import pory

The dubious.pory module defines the main class that will act as the

bot: Pory.

It also includes a special subclass, ConfiguredPory, that makes

per-guild (read: per-server) configuration easier.

exception dubious.pory.CommandFailure(message: str)

This class is a front-facing Exception class to be thrown when

an error is made by a user of the bot.

It will be caught by Pory and its

error_embed() method will be used to decorate an appropriate error message.

Can be subclassed to alter the error_embed()

method.

error_embed()

Returns an Embed object which will be sent as the front-facing error message.

class dubious.pory.Pory(app_id: dataclasses.InitVar[str], public_key: str, token: str)

This class defines bot functionality.

Once an instance is created, commands can be added using its on_command CommandGroup as a decorator around the desired callback function.

Also contains various utility functions for things like sending messages to specific channels and sending followup responses to interactions.

app_id: dataclasses.InitVar[str]

The application ID shown in the General Information section of the application’s settings. This value is converted into a Snowflake object and stored in id.

public_key: str

The public key shown in the General Information section of the application’s settings.

token: str

The token generated by the Reset Token option in the Bot section of the application’s settings.

id: Snowflake

The application ID for the bot as a Snowflake.

on_command: CommandGroup

CommandGroup for callbacks to register as Slash Commands.

on_message: CommandGroup

CommandGroup for callbacks to register as Message Commands.

on_user: CommandGroup

CommandGroup for callbacks to register as User Commands.

on_modal: CallbackGroup

CallbackGroup for internal callbacks that corespond to Modal (popup) interactions.

on_component: CallbackGroup

CallbackGroup for internal callbacks that corespond to Message Component interactions.

flask()

The entry point for the app. Starts a Flask instance and accepts POST requests to the /interactions endpoint.

send_followup(token: str, followup: Form)

Using an interaction message token, sends a followup response after the initial response.

Shouldn’t be used before an on_command callback returns / yields.

edit_response(token: str, edit: Form, response_id: str = '@original')

Using an interaction message token, edits one of the responses (specified by ID) to that interaction. Defaults to the initial response.

delete_response(token: str, response_id: str = '@original')

Using an interaction message token, deletes one of the responses (specified by ID) to that interaction. Defaults to the initial response.

send(channel_id: Snowflake, message: Form)

Sends a standalone message.

The argument message is a req.CreateMessage.Form.

edit(channel_id: Snowflake, message_id: Snowflake, message: Form)

Edits a standalone message.

The argument message is a req.EditMessage.Form.

delete(channel_id: Snowflake, message_id: Snowflake)

Deletes a standalone message.

history(channel_id: Snowflake, limit: int = 200, chunk_size: int = 50)

Iterates over a channel’s messages, starting from the earliest message.

The number of messages retrieved depends on limit. The req.GetChannelMessages request will retrieve a chunk of messages from the channel, the size of which is determined by chunk_size, until the limit is reached. A higher chunk size means less total requests, but those requests will take more time.

send_error(channel_id: Snowflake, error_text: str)

Sends an error embed with the given text to the given channel.

class dubious.pory.ChannelSnowflake(r: str | int)

This class only serves to differentiate the type of Snowflake that’s stored in a ConfiguredPory.config_model’s field. Represents the ID of a channel in the guild.

class dubious.pory.RoleSnowflake(r: str | int)

This class only serves to differentiate the type of :class`~.disc.Snowflake` that’s stored in a ConfiguredPory.config_model’s field. Represents the ID of a role in the guild.

class dubious.pory.t_ConfigType

Represents the config dataclass used with ConfiguredPory.

alias of TypeVar(‘t_ConfigType’)

class dubious.pory.ConfiguredPory(app_id: dataclasses.InitVar[str], public_key: str, token: str, config_path: str, config_model: type[~dubious.pory.t_ConfigType], guild_configs: dict[~dubious.discord.disc.Snowflake, ~dubious.pory.t_ConfigType] = <factory>)

This class adds to Pory by wrapping a config_model dataclass, storing it per guild as json in a given location, and allowing the bot to do things per guild based on that guild’s dataclass. A guild’s config dataclass instance can be retrieved using get_current_config(). More info on defining a configuration dataclass can be found in config_model.

It automatically registers a /config slash command that users with Manage Channel permissions can use to configure the dataclass instance for the guild they’re in.

config_path: str

The path to where the config file will be stored.

config_model: type[t_ConfigType]

The dataclass with which to structure the bot.

The dataclass won’t recieve any arguments on instantiation - each of its fields must have a default value (or default_factory for fields that store lists).

ConfiguredPory will leaf through the dataclass’s fields to find each field that stores one of the above subclasses of Snowflake: ChannelSnowflake and RoleSnowflake. It will also find fields that store lists of those snowflake subclasses. For each of the snowflake fields, a subcommand group will be added to the /config slash command that coresponds to that field. Subcommands are then added to that group that will alter that field when used.

guild_configs: dict[Snowflake, t_ConfigType]

The json file, parsed into instances of config_model per guild.

load()

Reads the config file from disk.

write()

Writes the current config for all guilds to the disk.

get_current_config(guild_id: Snowflake | None)

Gets the config_model instance for a specified guild. If guild_id is None, raises an appropriate CommandFailure.

This method is usually used inside of interaction callbacks. The guild_id can be retrieved by adding guild_id to the callback signature as a keyword-specific argument (i.e. an argument that comes after *,). See do_callback() for more details.