API Reference

Bots

class novus.ext.client.Client(config: Config, *, load_plugins: bool = False)

A gateway and API connection into Discord.

config

The config file for the bot.

Type:: novus.ext.client.Config

state

The connection for the bot.

Type:: novus.api.HTTPConnection

plugins

A list of plugins that have been added to the bot. This does not mean that the plugin has been loaded necessarily, just that it has been added.

Type:: set[novus.ext.client.Plugin]

me

The user associated with the bot. Will be None if the bot has not connected to the gateway.

Type:: novus.User | None

commands

A list of commands that have been loaded into the bot.

Type:: set[novus.ext.client.Command]

get_guild(id: AnySnowflake) → n.Guild | None

Get a guild from the bot’s internal cache.

Parameters:: id (int | str) – The ID of the guild that you want to get.
Returns:: The object from the cache.
Return type:: novus.Guild | None

get_user(id: AnySnowflake) → n.User | None

Get a user from the bot’s internal cache.

Parameters:: id (int | str) – The ID of the user that you want to get.
Returns:: The object from the cache.
Return type:: novus.User | None

get_channel(id: AnySnowflake, or_partial: Literal[True]) → Channel

get_channel(id: AnySnowflake, or_partial: Literal[False]) → Channel | None

Get a channel from the bot’s internal cache.

Parameters:

id (int | str) – The ID of the channel that you want to get.
or_partial (bool) – If set to True, the bot will return a partial object if a channel was not available.

Returns:

The object from the cache.

Return type:

novus.Channel | None

async change_presence(activities: list[Activity] | None = None, status: str = 'online') → None

Change the presence of the client.

Parameters:

activities (list[novus.Activity]) – The activities that you want to set the client as displaying.
status (str) –
The status of the client.

See also

novus.Status

async wait_until_ready() → None: Wait until all of the shards for the bot have received the “ready” message from the gateway.

add_command(command: Command) → None

Add a command to the bot’s internal cache.

Parameters:: command (novus.ext.client.Command) – The command you want to add.
Raises:: NameError – You have tried to add a command with a duplicate name (and guild status) as an already cached command.

get_command(name: str, guild_id: int | None = None) → Command | CommandGroup | None

Get a command that’s been loaded into the bot from the cache.

Parameters:

name (str) – The name of the command thaty ou want to get.
guild_id (int | None) – The ID of the guild where the command is registered.

Returns:

The command from the command cache.

Return type:

novus.ext.client.Command | novus.ext.client.CommandGroup

get_plugin(name: str) → Plugin | None

Get a loaded plugin from the bot’s internal cache.

Parameters:: name (str) – The name of the plugin, case sensitive.
Returns:: The loaded plugin, if one could be found.
Return type:: novus.ext.client.Plugin | None

add_plugin(plugin: Type[Plugin], *, load: bool = False) → None

Load a plugin into the bot.

Parameters:: plugin (Type[novus.ext.client.Plugin]) – The plugin that you want to add to the bot.

async load_plugins() → None: Load all of the plugins that have been added to the bot.

remove_command(command: Command) → None

Remove a command from the bot’s internal cache.

Parameters:: command (novus.ext.client.Command) – The command you want to remove.
Raises:: NameError – You have tried to remove a command that has not been loaded or is not in the cache.

remove_plugin(plugin: Type[Plugin]) → None

Remove a plugin from the bot.

Parameters:: plugin (Type[novus.ext.client.Plugin]) – The plugin type that you want to remove.
Raises:: TypeError – There are no plugins with that plugin type loaded.

add_plugin_file(*plugin: str, load: bool = False, reload_import: bool = False) → None

Add a plugin via its filename:ClassName pair.

Parameters:: plugin (str) – The plugin reference.
Raises:: TypeError – No plugin could be loaded from the given reference.

remove_plugin_file(*plugin: str) → None

Remove a plugin via its filename:ClassName pair.

Parameters:: plugin (str) – The plugin reference.
Raises:: TypeError – No plugin could be loaded from the given reference.

dispatch(event_name: str, *args: Any, **kwargs: Any) → None: Dispatch an event to all loaded plugins.

async sync_commands(*, create: bool = True, edit: bool = True, delete: bool = True) → None: Get all commands from Discord. Determine if they all already exist. If not, PUT them there. If so, save command IDs. This command is required to run to be able to dispatch command events properly.

async connect(check_concurrency: bool = False, sleep: bool = False) → None: Connect the bot to the gateway, running the connection in the background.

async connect_webserver(*, port: int = 8000) → BaseSite

Open a webserver to receive interactions from Discord.

Parameters:: port (int) – The port to open the server on.

async close() → None: Close the gateway and session connection.

async run(*, sync: bool = True) → None

Connect the bot to the gateway, keeping the bot’s connection to the websocket alive.

Parameters:: sync (bool) – Whether or not to sync the bot’s commands to Discord.

async run_webserver(*, port: int = 8000, sync: bool = True) → None

Run a webserver for the bot so as to receive interactions from Discord.

Parameters:

port (int) – The port that you want to open the webserver on.
sync (bool) – Whether or not to sync the bot’s commands to Discord.

class novus.ext.client.Config(*, token: str = '', pubkey: str = '', shard_ids: list[int] | None = None, shard_count: int = 1, intents: Intents | None = None, plugins: list[str] | None = None, oauth: dict[str, str | None] | None = None, **kwargs: Any)

Plugins

class novus.ext.client.Plugin(*args: Any, **kwargs: Any)

The base command class for any novus client commands.

async on_load() → None: A function to be run when the plugin is loaded. The plugin is not automatically loaded on its addition to the bot, but on its connection to the gateway. If the bot does not connect to the gateway, this function will never be called.

async on_unload() → None: A function to be run automatically where the plugin is removed from the bot. This function is not run if there is not an event loop running.

dispatch(event_name: str, *args: Any, **kwargs: Any) → None: Send data to an event within the plugin.

Commands

novus.ext.client.command(name: str | None = None, description: str | None = None, type: int = 1, *, options: list[n.ApplicationCommandOption] | None = None, default_member_permissions: n.Permissions | None = None, dm_permission: bool = True, nsfw: bool = False, guild_ids: list[int] | None = None, cls: Type[Command] = <class 'novus.ext.client.command.Command'>, **kwargs: Any) → Callable[[CommandCallback], Command]

Wrap a function in a command.

Parameters:

name (str | None) – The name of the command. If not provided, the name of the function is used. If a name with spaces is given, then it is automatically implemented with subcommands (unless it is not a chat_input type).
description (str | None) – The description associated with the command. If not provided, the docstring for the function is used. If the command is built as a subcommand, you can give descriptions and localizations using the novus.ext.client.CommandDescription class.
type (int) –
The type of the command that you want to create.

See also

novus.ApplicationCommandType
options (list[novus.ApplicationCommandOption]) – A list of options to be added to the slash command. If the option names and the function parameter names don’t match up, an error will be raised.
default_member_permissions (novus.Permissions) – The permissions that are required (by default) to run this command. These can be changed by server admins.
dm_permission (bool) – Whether the command can be run in DMs.
nsfw (bool) – Whether the comamnd is set to only work in NSFW channels or not.
guild_ids (list[int]) – The guilds that the command will be added to. If not set, then the command will be added globally.

Raises:

ValueError – The command is missing a description.
Exception – The command’s parameters and the options don’t match up.

Examples

@client.command()
async def ping(self, ctx):
    '''Command description goes here.'''
    await ctx.send("Pong")

@client.command(
    options=[
        novus.ApplicationCommandOption(
            name="user",
            type=novus.ApplicationOptionType.USER,
            description="The user you want to mention.",
        )
    ]
)
async def mention(self, ctx, user):
    '''Command description goes here.'''
    await ctx.send(user.mention)

class novus.ext.client.Command(name: str, type: int, application_command: n.PartialApplicationCommand, callback: CommandCallback, guild_ids: list[int])

A command object for Novus command handling.

Parameters:

name (str) – The name of the command
type (int) –
The type of the command.

See also

novus.ApplicationCommandType
callback (CommandCallback) – The function that acts as the command.
application_command (novus.PartialApplicationCommand) – The application command used to generate the command.
guild_ids (list[int]) – A list of guild IDs that the command is present in.

name

The name of the command

Type:: str

type

The type of the command.

See also

novus.ApplicationCommandType

Type:: int

callback

The function that acts as the command.

Type:: CommandCallback

application_command

The application command used to generate the command.

Type:: novus.PartialApplicationCommand

guild_ids

A list of guild IDs that the command is present in.

Type:: list[int]

command_ids

A list of IDs that refer to the command.

Type:: set[int]

is_subcommand

Whether or not the command is implemented as a subcommand.

Type:: bool

to_application_command_option() → ApplicationCommandOption

Convert this instance of the command into a command option. This should only be used on subcommands.

Returns:: Although the command was generated as an application command, this will convert that application command into an option.
Return type:: novus.ApplicationCommandOption

add_id(guild_id: int | None, id: int) → None

Add an ID to the command. This means that any interaction invokations with the given command ID will be routed to this command instance.

Parameters:: id (int) – The ID that you want to add.

get_mention(guild_id: int | None = None) → str

Get a mention for the given command.

Parameters:: guild_id (int | None) – The ID of the guild that the command exists in.
Returns:: A mention for the command.
Return type:: str

async run(interaction: Interaction[ApplicationCommandData] | Interaction[ContextComandData], options: list[InteractionOption] | None = None) → None

Run the command with the given interaction.

Parameters:

interaction (novus.Interaction) – The interaction that invoked the command.
options (list[novus.InteractionOption] | None) – The list of options that the command is to be called with. If not provided, then the options are taken from the interaction itself. This is primarily used as a helper for subcommands.

autocomplete(func: AutocompleteCallback) → AutocompleteCallback

Add an autocomplete to this command.

Examples

@client.command(...)
async def echo(self, ctx: novus.Interaction, text: str):
    ...

@echo.autocomplete
async def echo_autocomplete(self, ctx: novus.Interaction):
    return [
        novus.ApplicationCommandChoice("name", "value"),
        novus.ApplicationCommandChoice("name2", "value2"),
        novus.ApplicationCommandChoice("name3", "value3"),
    ]

async run_autocomplete(interaction: Interaction[ApplicationCommandData], options: list[InteractionOption] | None = None) → None

This interaction has been triggered to autocomplete! Work out what parameter needs autocompleting, and then run that :)

Parameters:: interaction (novus.Interaction) – The interaction that needs completing.

class novus.ext.client.CommandDescription(description: str = MISSING, *, name_localizations: LocType = MISSING, description_localizations: LocType = MISSING, default_member_permissions: n.Permissions = MISSING, dm_permission: bool = MISSING, nsfw: bool = MISSING, guild_ids: list[int] | None = MISSING, children: dict[str, CommandDescription] | None = None): A description class to wrap around command groups.

class novus.ext.client.CommandGroup(application_command: PartialApplicationCommand, commands: Iterable[Command], guild_ids: list[int])

A group of commands and subcommands.

name

The name of the command.

Type:: str

application_command

The application command that builds the command.

Type:: novus.PartialApplicationCommand

guild_ids

The IDs of the guilds that the command is set to.

Type:: list[int]

command_ids

A list of command IDs that are associated with this command.

Type:: list[int]

commands

A dict of names and command objects that make up the child commands of this command group.

Type:: dict[str, novus.ext.client.Command]

add_description(d: CommandDescription) → None

Add a description to the command group.

Parameters:: d (novus.ext.client.CommandDescription) – The description that you want to add to the command group.

classmethod from_commands(commands: Iterable[Command], run_checks: bool = True) → Self

Generate a group from a list of commands.

Parameters:

commands (Iterable[novus.ext.client.Command]) – The commands that will make up the group.
run_checks (bool) – Whether to check that all implemented commands have the same basic attributes (dm_permission, NSFW, etc).

Raises:

novus.ext.client.CommandError – An error was encountered trying to group the commands together.

async run(interaction: Interaction[ApplicationCommandData]) → None

Run the command with the given interaction.

Parameters:: interaction (novus.Interaction) – The interaction that invoked the command.

async run_autocomplete(interaction: Interaction[ApplicationCommandData]) → None

Run the autocomplete for the given command with the given options.

Parameters:: interaction (novus.Interaction) – The interaction that invoked the autocomplete.

add_id(guild_id: int | None, id: int) → None

Add an ID to the command. This means that any interaction invokations with the given command ID will be routed to this command instance.

Parameters:: id (int) – The ID that you want to add.

autocomplete(func: AutocompleteCallback) → AutocompleteCallback

Add an autocomplete to this command.

Examples

@client.command(...)
async def echo(self, ctx: novus.Interaction, text: str):
    ...

@echo.autocomplete
async def echo_autocomplete(self, ctx: novus.Interaction):
    return [
        novus.ApplicationCommandChoice("name", "value"),
        novus.ApplicationCommandChoice("name2", "value2"),
        novus.ApplicationCommandChoice("name3", "value3"),
    ]

get_mention(guild_id: int | None = None) → str

Get a mention for the given command.

Parameters:: guild_id (int | None) – The ID of the guild that the command exists in.
Returns:: A mention for the command.
Return type:: str

to_application_command_option() → ApplicationCommandOption

Convert this instance of the command into a command option. This should only be used on subcommands.

Returns:: Although the command was generated as an application command, this will convert that application command into an option.
Return type:: novus.ApplicationCommandOption

Events

novus.ext.client.event(predicate: Callable[..., bool] | None = None) → WEL

class novus.ext.client.EventListener(event_name: str, func: Callable[[...], Awaitable[Any]], predicate: Callable[[...], bool] | None = None): An object that listens for an event.

Loops

novus.ext.client.loop(loop_time: float, start_behavior: LoopBehavior = LoopBehavior.immediate, end_behavior: LoopBehavior = LoopBehavior.end, autostart: bool = True, wait_until_ready: bool = True) → Callable[[...], Loop]

A wrapper to create a loop object.

Parameters:

loop_time (float) – The number of seconds between each loop. This is not guarenteed to be accurate, but is used internally for the wait function.
start_behavior (LoopBehavior) – How the loop should behave on its start.
end_behavior (LoopBehavior) – How the loop should behave on its end.
autostart (bool) – Whether the loop should start immediately when the plugin is loaded.
wait_until_ready (bool) – If the plugin should wait until the bot has received the ready payload before beginning its task.

Examples

@client.loop(60)
async def every_minute(self):
    self.log.info("Ping")

class novus.ext.client.Loop(func: Callable[[], Coroutine[None, None, Any]], loop_time: float, start_behavior: LoopBehavior = LoopBehavior.immediate, end_behavior: LoopBehavior = LoopBehavior.end, autostart: bool = True, wait_until_ready: bool = True)

A piece of code that should be looped within a plugin.

func

The function that is part of the loop.

Type:: Callable[…, Awaitable[Any]]

loop_time

The number of seconds between each loop iteration.

Type:: float

start_behavior

The behaviour for how each loop will end.

Type:: novus.ext.client.LoopBehaviour

end_behavior

The behaviour for how each loop will end.

Type:: novus.ext.client.LoopBehaviour

autostart

If the plugin should start automatically.

Type:: bool

wait_until_ready

If the loop should wait until the bot receives the ready payload.

Type:: bool

owner

The plugin where the loop resides.

Type:: novus.ext.client.Plugin

task

The last instance of the given function that the bot ran in this loop.

Type:: asyncio.Task | None

before(func: Callable[[], Coroutine[None, None, Any]]) → None: Set a function that is to run before the loop starts.

start(*args: Any, **kwargs: Any) → None: Start the loop.

stop() → None: Stop the loop. This will not stop the currently running task instance, if one is running.

See also

novus.ext.client.Loop.cancel()

cancel() → None: Stop the loop and cancel any running tasks.

See also

novus.ext.client.Loop.stop()

class novus.ext.client.LoopBehavior(value)

How a loop should behave on its ending.

end: The previous loop should have finished executing before a new loop is triggered to start.

immediate: A new loop should be triggered immediately after the previous one is triggered.

Errors

class novus.ext.client.CommandError: Base error for all other command errors.