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(shard_id: int, event_name: str, *args: Any, **kwargs: Any) → None: Dispatch an event to all loaded plugins.

async fetch_application_id() → int

Fetch and cache the application ID for the given token.

Returns:: The ID of the application
Return type:: int

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(*, check_concurrency: bool = True, 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 = '', owner_ids: list[int] | None = None, 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, statsd: dict[str, Any] | 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, integration_types: list[int] | None = None, contexts: list[int] | None = None, 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.
integration_types (list[int] | None) –
The integration types that the command will be added to.

See also

novus.ApplicationIntegrationType
contexts (list[int] | None) –
The contexts in which this command can be run.

See also

novus.ApplicationCommandContext
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.

Events

Most events can be handled by using an EventBuilder decorator within a plugin.

class novus.ext.client.EventBuilder

classmethod filtered_component(match_string: str) → Callable[[Callable[[Any, Any], Awaitable[Any]]], EventListener]

Match an component or modal interaction based on a regex match with its custom ID.

Parameters:: match_string (str) – The regex that should match with the component’s custom ID.

Examples

>>> @client.event.filtered_component("CUSTOM_ID_GOES_HERE")
>>> async def button_press(self, interaction: novus.Interaction):
>>>     pass

>>> @client.event.filtered_component(r"^my_button_\d+$")
>>> async def button_press(self, interaction: novus.Interaction):
>>>     pass

classmethod ready(func: Callable[[Any], Awaitable[Any]]) → EventListener

Capture the ready event from the gateway.

Example

>>> @client.event.ready
>>> async def on_ready(self):
>>>     print("Ready!")

classmethod component(func: W[t.ComponentI] | W[t.ComponentGI]) → EL

Capture a component interaction from the gateway or interaction webhook.

Example

>>> @client.event.component
>>> async def button_press(self, interaction: novus.Interaction):
>>>     pass

classmethod modal(func: W[Interaction[ModalSubmitData]]) → EL

Capture a modal submit interaction from the gateway or interaction webhook.

Example

>>> @client.event.modal
>>> async def modal_submit(self, interaction: novus.Interaction):
>>>     pass

Capture a command interaction from the gateway or interaction webhook.

Example

>>> @client.event.command
>>> async def command(self, interaction: novus.Interaction):
>>>     pass

classmethod autocomplete(func: W[Interaction[ApplicationCommandData]]) → EL

Capture an autocomplete interaction from the gateway or interaction webhook.

Example

>>> @client.event.autocomplete
>>> async def autocomplete(self, interaction: novus.Interaction):
>>>     pass

classmethod raw_guild_create(func: Callable[[Any, int], Awaitable[Any]]) → EventListener

Capture the raw guild create event from the gateway.

This is useful for when you want to capture the guild create event before the library has processed it, or if you want to capture the raw payload from the gateway for debugging purposes.

Example

>>> @client.event.raw_guild_create
>>> async def on_raw_guild_create(self, guild_id: int):
>>>     pass

classmethod guild_create(func: W[Guild]) → EL

Capture the guild create event from the gateway.

Example

>>> @client.event.guild_create
>>> async def on_guild_create(self, guild: novus.Guild):
>>>     pass

classmethod raw_guild_update(func: W[Guild]) → EL

Capture the raw guild update event from the gateway.

This is useful for when you want to capture the guild update event before the library has processed it, or if you want to capture the raw payload from the gateway for debugging purposes.

Example

>>> @client.event.raw_guild_update
>>> async def on_raw_guild_update(self, guild: novus.Guild):
>>>     pass

classmethod guild_update(func: W2[Guild, Guild]) → EL

Capture the guild update event from the gateway.

Example

>>> @client.event.guild_update
>>> async def on_guild_update(self, before: novus.Guild, after: novus.Guild):
>>>     pass

classmethod raw_guild_delete(func: Callable[[Any, int], Awaitable[Any]]) → EventListener

Capture the raw guild delete event from the gateway.

This is useful for when you want to capture the guild delete event before the library has processed it, or if you want to capture the raw payload from the gateway for debugging purposes.

Example

>>> @client.event.raw_guild_delete
>>> async def on_raw_guild_delete(self, guild_id: int):
>>>     pass

classmethod guild_delete(func: W[Guild]) → EL

Capture the guild delete event from the gateway.

Example

>>> @client.event.guild_delete
>>> async def on_guild_delete(self, guild: novus.Guild):
>>>     pass

classmethod raw_typing(func: Callable[[Any, int, int], Awaitable[Any]]) → EventListener

Capture the raw typing event from the gateway.

This is useful for when you want to capture the typing event before the library has processed it, or if you want to capture the raw payload from the gateway for debugging purposes.

Example

>>> @client.event.raw_typing
>>> async def on_raw_typing(self, channel_id: int, user_id: int):
>>>     pass

classmethod typing(func: W2[Channel, User | GuildMember]) → EL

Capture the typing event from the gateway.

Example

>>> @client.event.typing
>>> async def on_typing(self, channel: novus.Channel, user: novus.User | novus.GuildMember):
>>>     pass

classmethod message(func: W[Message]) → EL

Capture the message create event from the gateway.

Example

>>> @client.event.message
>>> async def on_message(self, message: novus.Message):
>>>     pass

classmethod guild_message(func: W[GuildMessage]) → EL

Capture the message create event from the gateway for messages sent in guilds.

Example

>>> @client.event.guild_message
>>> async def on_guild_message(self, message: novus.Message):
>>>     pass

classmethod dm_message(func: W[DMMessage]) → EL

Capture the message create event from the gateway for messages sent in DMs.

Example

>>> @client.event.dm_message
>>> async def on_dm_message(self, message: novus.Message):
>>>     pass

classmethod raw_message_edit(func: W[Message]) → EL

Capture the raw message update event from the gateway.

This is useful for when you want to capture the message update event before the library has processed it, or if you want to capture the raw payload from the gateway for debugging purposes.

Example

>>> @client.event.raw_message_edit
>>> async def on_raw_message_edit(self, message: novus.Message):
>>>     pass

classmethod message_edit(func: W2[Message, Message]) → EL

Capture the message update event from the gateway.

Example

>>> @client.event.message_edit
>>> async def on_message_edit(self, before: novus.Message, after: novus.Message):
>>>     pass

classmethod raw_message_delete(func: Callable[[Any, int, int], Awaitable[Any]]) → EventListener

Capture the raw message delete event from the gateway.

This is useful for when you want to capture the message delete event before the library has processed it, or if you want to capture the raw payload from the gateway for debugging purposes.

Example

>>> @client.event.raw_message_delete
>>> async def on_raw_message_delete(self, message_id: int, channel_id: int):
>>>     pass

classmethod message_delete(func: W[Message]) → EL

Capture the message delete event from the gateway.

Example

>>> @client.event.message_delete
>>> async def on_message_delete(self, message: novus.Message):
>>>     pass

classmethod channel_create(func: W[Channel]) → EL

Capture the channel create event from the gateway.

Example

>>> @client.event.channel_create
>>> async def on_channel_create(self, channel: novus.Channel):
>>>     pass

classmethod raw_channel_update(func: W[Channel]) → EL

Capture the raw channel update event from the gateway.

This is useful for when you want to capture the channel update event before the library has processed it, or if you want to capture the raw payload from the gateway for debugging purposes.

Example

>>> @client.event.raw_channel_update
>>> async def on_raw_channel_update(self, channel: novus.Channel):
>>>     pass

classmethod channel_update(func: W2[Channel, Channel]) → EL

Capture the channel update event from the gateway.

Example

>>> @client.event.channel_update
>>> async def on_channel_update(self, before: novus.Channel, after: novus.Channel):
>>>     pass

classmethod channel_delete(func: W[Channel]) → EL

Capture the channel delete event from the gateway.

Example

>>> @client.event.channel_delete
>>> async def on_channel_delete(self, channel: novus.Channel):
>>>     pass

classmethod guild_ban_add(func: W2[BaseGuild, User | GuildMember]) → EL

Capture a user being banned from a guild.

Example

>>> @client.event.guild_ban_add
>>> async def on_guild_ban_add(
...         self,
...         guild: novus.BaseGuild,
...         user: novus.User | novus.GuildMember):
>>>     pass

classmethod guild_ban_remove(func: W2[BaseGuild, User]) → EL

Capture a user being unbanned from a guild.

Example

>>> @client.event.guild_ban_remove
>>> async def on_guild_ban_remove(self, guild: novus.BaseGuild, user: novus.User):
>>>     pass

classmethod invite_create(func: Callable[[Any, Invite], Awaitable[Any]]) → EventListener

Capture the invite create event from the gateway.

Example

>>> @client.event.invite_create
>>> async def on_invite_create(self, invite: novus.Invite):
>>>     pass

classmethod invite_delete(func: Callable[[Any, Invite, str], Awaitable[Any]]) → EventListener

Capture the invite delete event from the gateway.

Example

>>> @client.event.invite_delete
>>> async def on_invite_delete(self, invite: novus.Invite, code: str):
>>>     pass

classmethod role_create(func: W[Role]) → EL

Capture the role create event from the gateway.

Example

>>> @client.event.role_create
>>> async def on_role_create(self, role: novus.Role):
>>>     pass

classmethod raw_role_update(func: W[Role]) → EL

Capture the raw role update event from the gateway.

This is useful for when you want to capture the role update event before the library has processed it, or if you want to capture the raw payload from the gateway for debugging purposes.

Example

>>> @client.event.raw_role_update
>>> async def on_raw_role_update(self, role: novus.Role):
>>>     pass

classmethod role_update(func: W2[Role, Role]) → EL

Capture the role update event from the gateway.

Example

>>> @client.event.role_update
>>> async def on_role_update(self, before: novus.Role, after: novus.Role):
>>>     pass

classmethod raw_role_delete(func: Callable[[Any, int, int], Awaitable[Any]]) → EventListener

Capture the raw role delete event from the gateway.

This is useful for when you want to capture the role delete event before the library has processed it, or if you want to capture the raw payload from the gateway for debugging purposes.

Example

>>> @client.event.raw_role_delete
>>> async def on_raw_role_delete(self, role_id: int, guild_id: int):
>>>     pass

classmethod role_delete(func: W[Role]) → EL

Capture the role delete event from the gateway.

Example

>>> @client.event.role_delete
>>> async def on_role_delete(self, role: novus.Role):
>>>     pass

classmethod guild_member_add(func: W[GuildMember]) → EL

Capture a user joining a guild.

Example

>>> @client.event.guild_member_add
>>> async def on_guild_member_add(self, member: novus.GuildMember):
>>>     pass

classmethod raw_guild_member_update(func: W[GuildMember]) → EL

Capture the raw guild member update event from the gateway.

This is useful for when you want to capture the guild member update event before the library has processed it, or if you want to capture the raw payload from the gateway for debugging purposes.

Example

>>> @client.event.raw_guild_member_update
>>> async def on_raw_guild_member_update(self, member: novus.GuildMember):
>>>     pass

classmethod guild_member_update(func: W2[GuildMember, GuildMember]) → EL

Capture the guild member update event from the gateway.

Example

>>> @client.event.guild_member_update
>>> async def on_guild_member_update(
...         self,
...         before: novus.GuildMember,
...         after: novus.GuildMember):
>>>     pass

classmethod raw_guild_member_remove(func: Callable[[Any, int, int], Awaitable[Any]]) → EventListener

Capture the raw guild member remove event from the gateway.

This is useful for when you want to capture the guild member remove event before the library has processed it, or if you want to capture the raw payload from the gateway for debugging purposes.

Example

>>> @client.event.raw_guild_member_remove
>>> async def on_raw_guild_member_remove(self, user_id: int, guild_id: int):
>>>     pass

classmethod guild_member_remove(func: W2[BaseGuild, GuildMember | User]) → EL

Capture a user leaving a guild.

Example

>>> @client.event.guild_member_remove
>>> async def on_guild_member_remove(
...         self,
...         guild: novus.BaseGuild,
...         member: novus.GuildMember | novus.User):
>>>     pass

classmethod reaction_add(func: W2[User | GuildMember | int, Reaction]) → EL

Capture the reaction add event from the gateway.

Example

>>> @client.event.reaction_add
>>> async def on_reaction_add(
...        self,
...        user: novus.User | novus.GuildMember,
...        reaction: novus.Reaction):
>>>     pass

classmethod reaction_remove(func: W2[User | GuildMember | int, Reaction]) → EL

Capture the reaction remove event from the gateway.

Example

>>> @client.event.reaction_remove
>>> async def on_reaction_remove(
...         self,
...         user: novus.User | novus.GuildMember,
...         reaction: novus.Reaction):
>>>     pass

classmethod audit_log_entry(func: Callable[[Any, AuditLogEntry], Awaitable[Any]]) → EventListener

Capture the audit log entry create event from the gateway.

Example

>>> @client.event.audit_log_entry
>>> async def on_audit_log_entry(self, entry: novus.AuditLogEntry):
>>>     pass

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[[Any], 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[[Any], 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.