API

class novus.api._route.Route(method: str, resource: str, **kwargs: str | int)

A route to access the API with.

Parameters:

method (str) – The HTTP method to use.
resource (str) – The resource that you want to access.
**kwargs – Any additional kwargs to be formatted into the resource.

method

The HTTP method to use.

Type:: str

resource

The resource that you want to access.

Type:: str

path

The resource with the kwargs mapped onto it.

Type:: str

url

The fully built route path.

Type:: str

kwargs

Any additional kwargs to be formatted into the resource.

Type:: dict

class novus.api.HTTPConnection(token: str | None = None, client_id: str | None = None, client_secret: str | None = None)

A wrapper around the API for HTTP handling.

As well as this class (and it’s subclasses), each applicable model should have an API mixin.

The mixins are intended to be user facing, so have all of the parameters added.

The HTTP connection classes have positional parameters for the resource params; a keyword only parameter for the reason (if applicable) and any GET parameters; and the kwargs are added to the JSON body. For the most part, kwargs get fixed up into a valid payload. Known kwargs are assumed to be the correct type (things like a channel kwarg will be fixed into a channel_id via the .id attribute; a flags class will get its .value attribute and cast to a string for the payload, etc). Any unknown kwargs will be added as is to the payload, which allows you to add any additional arguments should Discord update before the library.

Parameters:: token (str | None) – The token to use.

application_role_connection_metadata

Type:: ApplicationRoleHTTPConnection

audit_log

Type:: AuditLogHTTPConnection

auto_moderation

Type:: AutoModerationHTTPConnection

channel

Type:: ChannelHTTPConnection

emoji

Type:: EmojiHTTPConnection

guild

Type:: GuildHTTPConnection

guild_scheduled_event

Type:: GuildEventHTTPConnection

guild_template

Type:: GuildTemplateHTTPConnection

interaction

Type:: InteractionHTTPConnection

invite

Type:: InviteHTTPConnection

monetization

Type:: MonetizationHTTPConnection

oauth2

Type:: Oauth2HTTPConnection

stage_instance

Type:: StageHTTPConnection

sticker

Type:: StickerHTTPConnection

user

Type:: UserHTTPConnection

voice

Type:: VoiceHTTPConnection

webhook

Type:: WebhookHTTPConnection

application_id

The ID of the associated application.

Type:: int

class novus.api.APIIterator(method: Any, before: AnySnowflake | None, after: AnySnowflake | None, limit: int | None, method_limit: int)

An async iterator class for Discord API methods that return multiple - but limited - items in their return.

async flatten() → list[T]: Flatten the entire item from its original API generator into a list.

class novus.api.application_role_connection_metadata.ApplicationRoleHTTPConnection(parent: HTTPConnection)

async get_application_role_records(application_id: int) → list[dict]: Get the application role connection metadata objects for the given application.

async update_application_role_records(application_id: int, records: list[Any]) → list[dict]: Get one guild emoji.

class novus.api.audit_log.AuditLogHTTPConnection(parent: HTTPConnection)

async get_guild_audit_log(guild_id: int, *, user_id: int | None = None, action_type: int | None = None, before: int | None = None, after: int | None = None, limit: int = 50) → AuditLog: Get guild audit logs.

class novus.api.auto_moderation.AutoModerationHTTPConnection(parent: HTTPConnection)

async list_auto_moderation_rules_for_guild(guild_id: int) → list[AutoModerationRule]: Get a list of automoderator rules for the guild.

async get_auto_moderation_rule(guild_id: int, rule_id: int) → AutoModerationRule: Get a specific automoderator rule for the guild.

async create_auto_moderation_rule(guild_id: int, *, reason: str | None = None, **kwargs: dict[str, Any]) → AutoModerationRule: Create an automoderation rule.

async modify_auto_moderation_rule(guild_id: int, rule_id: int, *, reason: str | None = None, **kwargs: dict[str, Any]) → AutoModerationRule: Edit an automoderation rule.

async delete_auto_moderation_rule(guild_id: int, rule_id: int, *, reason: str | None = None) → None: Delete an automoderation rule.

class novus.api.channel.ChannelHTTPConnection(parent: HTTPConnection)

async get_channel(channel_id: int) → Channel: Get a channel object by its ID.

async modify_channel(channel_id: int, *, reason: str | None = None, **kwargs: dict[str, Any]) → Channel: Modify a channel’s settings.

async delete_channel(channel_id: int, *, reason: str | None = None) → None: Delete a channel (or close a DM channel).

async get_channel_messages(channel_id: int, *, around: int = MISSING, before: int = MISSING, after: int = MISSING, limit: int = MISSING) → list[Message]: Get a channel object by its ID.

async get_channel_message(channel_id: int, message_id: int) → Message: Get a specific message inside of a channel.

async create_message(channel_id: int, **kwargs: dict[str, Any]) → Message: Create a new message inside of a channel.

async crosspost_message(channel_id: int, message_id: int) → Message: Crosspost a message.

async create_reaction(channel_id: int, message_id: int, emoji: str | PartialEmoji) → None: Create a reaction on a message.

async delete_own_reaction(channel_id: int, message_id: int, emoji: str | PartialEmoji) → None: Remove your own reaction to a message.

async delete_user_reaction(channel_id: int, message_id: int, emoji: str | PartialEmoji, user_id: int) → None: Remove another user’s reaction from a message.

async get_reactions(channel_id: int, message_id: int, emoji: str | PartialEmoji) → list[User]: Get a list of users who reacted to a message with a particular emoji.

async delete_all_reactions(channel_id: int, message_id: int) → None: Remove all reactions from a message.

async delete_all_reactions_for_emoji(channel_id: int, message_id: int, emoji: str | PartialEmoji) → None: Remove all reactions for the given emoji on a message.

async edit_message(channel_id: int, message_id: int, **kwargs: dict[str, Any]) → Message: Edit an existing message.

async delete_message(channel_id: int, message_id: int, *, reason: str | None = None) → None: Delete an existing message.

async bulk_delete_messages(channel_id: int, *, reason: str | None = None, message_ids: list[int]) → None: Delete multiple messages.

async edit_channel_permissions(channel_id: int, overwrite_id: int, *, reason: str | None = None, allow: Permissions = Permissions(0b0), deny: Permissions = Permissions(0b0), type: Type[User] | Type[GuildMember] | Type[Role]) → None: Update the permissions for a given item in the channel.

async get_channel_invites(channel_id: int) → list[Invite]: Get the invites for a channel.

async create_channel_invite(channel_id: int, *, reason: str | None = None, **kwargs: dict[str, Any]) → Invite: Create an invite for the channel.

async delete_channel_permission(channel_id: int, overwrite_id: int, *, reason: str | None = None) → None: Delete channel permission.

async follow_announcement_channel(channel_id: int, webhook_channel_id: int) → int: Follow an announcement channel. Returns the created webhook ID.

async trigger_typing_indicator(channel_id: int) → None: Trigger the typing indicator for the specified channel.

async get_pinned_messages(channel_id: int) → list[Message]: Return all of the pinned messages in the channel.

async pin_message(channel_id: int, message_id: int, *, reason: str | None = None) → None: Pin a message.

async unpin_message(channel_id: int, message_id: int, *, reason: str | None = None) → None: Unpin a message.

async start_thread_from_message(channel_id: int, message_id: int, *, reason: str | None = None, **kwargs: dict[str, Any]) → Channel: Create a thread from a message.

async start_thread_without_message(channel_id: int, *, reason: str | None = None, **kwargs: dict[str, Any]) → Channel: Create a thread not connected to an existing message.

async start_thread_in_forum_channel(channel_id: int, *, reason: str | None = None, **kwargs: dict[str, Any]) → Channel: Create a thread inside of a forum channel.

async add_thread_member(channel_id: int, user_id: int | Literal['@me']) → None: Add a member to a thread.

async remove_thread_member(channel_id: int, user_id: int | Literal['@me']) → None: Remove another user from a thread.

async get_thread_member(channel_id: int, user_id: int, *, with_member: bool = False) → ThreadMember: Get a member in a thread.

async list_thread_members(channel_id: int, *, with_member: bool = False, after: int = MISSING, limit: int = 100) → list[ThreadMember]: Get an array of thread members.

async list_public_archived_threads(channel_id: int, *, before: datetime = MISSING, limit: int = MISSING) → list[Channel]: Get the archived threads inthe channel that are public.

async list_private_archived_threads(channel_id: int, *, before: datetime = MISSING, limit: int = MISSING) → list[Channel]: Get the archived threads inthe channel that are private.

async list_joined_private_archived_threads(channel_id: int, *, before: datetime = MISSING, limit: int = MISSING) → list[Channel]: Get the archived threads inthe channel that are private.

class novus.api.emoji.EmojiHTTPConnection(parent: HTTPConnection)

async list_guild_emojis(guild_id: int) → list[Emoji]: Get all guild emojis.

async get_emoji(guild_id: int, emoji_id: int) → Emoji: Get one guild emoji.

async create_guild_emoji(guild_id: int, /, *, reason: str | None = None, **kwargs: Any) → Emoji: Create a guild emoji.

async modify_guild_emoji(guild_id: int, emoji_id: int, /, *, reason: str | None = None, **kwargs: Any) → Emoji: Modify guild emoji.

async delete_guild_emoji(guild_id: int, emoji_id: int, /, *, reason: str | None = None) → None: Delete guild emoji.

class novus.api.guild.GuildHTTPConnection(parent: HTTPConnection)

async create_guild(**kwargs: Any) → Guild: Create a guild.

async get_guild(guild_id: int, /, with_counts: bool = False) → Guild: Get a guild.

async get_guild_preview(guild_id: int, /) → GuildPreview: Get a guild preview.

async modify_guild(guild_id: int, /, *, reason: str | None = None, **kwargs: Any) → Guild: Edit a guild.

async delete_guild(guild_id: int, /) → None: Delete a guild.

async get_guild_channels(guild_id: int, /) → list[Channel]: Get guild channels.

async create_guild_channel(guild_id: int, /, *, reason: str | None = None, **kwargs: Any) → Channel: Create a guild channel.

async get_active_guild_threads(guild_id: int) → list[Channel]: Get the threads from the guild.

async get_guild_member(guild_id: int, member_id: int) → GuildMember: Get a guild member.

async get_guild_members(guild_id: int, *, limit: int = 1, after: int = 0) → list[GuildMember]: Get a guild member.

async search_guild_members(guild_id: int, *, query: str, limit: int = 1) → list[GuildMember]: Get a guild member.

async add_guild_member(guild_id: int, user_id: int, *, access_token: str, **kwargs: Any) → GuildMember | None: Add a member to the guild. Only works if you have a valid Oauth2 access token with the guild.join scope.

async modify_guild_member(guild_id: int, user_id: int, /, *, reason: str | None = None, **kwargs: Any) → GuildMember: Update a guild member.

async modify_current_guild_member(guild_id: int, /, *, reason: str | None = None, **kwargs: Any) → None: Update the current guild member.

async add_guild_member_role(guild_id: int, user_id: int, role_id: int, /, *, reason: str | None = None) → None: Add a role to a guild member.

async remove_guild_member_role(guild_id: int, user_id: int, role_id: int, /, *, reason: str | None = None) → None: Remove a role from a guild member.

async remove_guild_member(guild_id: int, user_id: int, /, *, reason: str | None = None) → None: Remove a member from the guild.

async get_guild_bans(guild_id: int, /, *, limit: int | None = None, before: int | None = None, after: int | None = None) → list[GuildBan]: Get the bans from a guild.

async get_guild_ban(guild_id: int, user_id: int, /) → GuildBan: Get a ban for a particular member.

async create_guild_ban(guild_id: int, user_id: int, /, *, reason: str | None = None, **kwargs: Any) → None: Ban a user.

async remove_guild_ban(guild_id: int, user_id: int, /, *, reason: str | None = None) → None: Unban a user.

async get_guild_roles(guild_id: int) → list[Role]: List the roles for the guild.

async get_guild_role_member_counts(guild_id: int) → dict[int, int]: Get a dict of role_id: member_count for every role in the guild (minus the everyone role).

async create_guild_role(guild_id: int, *, reason: str | None = None, **kwargs: Any) → Role: Create a role in the guild.

async search_channel_messages(guild_id: int, /, *, limit: int | None = None, offset: int | None = None, max_id: str | None = None, min_id: str | None = None, slop: int | None = None, content: str | None = None, channel_id: list[str] | None = None, author_type: list[str] | None = None, author_id: str | None = None, mentions: list[str] | None = None, mentions_role_id: list[str] | None = None, mention_everyone: bool | None = None, replied_to_user_id: list[str] | None = None, replied_to_message_id: list[str] | None = None, pinned: bool | None = None, has: list[str] | None = None, embed_type: list[str] | None = None, embed_provider: list[str] | None = None, link_hostname: list[str] | None = None, attachment_filename: list[str] | None = None, sort_by: str | None = None, sort_order: str | None = None, include_nsfw: bool | None = None, wait: bool = True) → MessageSearchResults: Get a list of messages (minus its reactions) that match a search query in the guild. Requires the READ_MESSAGE_HISTORY permission.

async modify_guild_role_positions(guild_id: int, /, *, reason: str | None = None, **kwargs: Any) → list[Role]: Edit guild role positions.

async modify_guild_role(guild_id: int, role_id: int, /, *, reason: str | None = None, **kwargs: Any) → Role: Edit a guild role.

async delete_guild_role(guild_id: int, role_id: int, /, *, reason: str | None = None) → None: Delete a guild role.

async get_guild_invites(guild_id: int, /) → list[Invite]: Get the invites for a guild.

class novus.api.guild_scheduled_event.GuildEventHTTPConnection(parent: HTTPConnection)

async list_scheduled_events_for_guild(guild_id: int, *, with_user_count: bool = MISSING) → list[ScheduledEvent]: Get the scheduled events for the guild.

async create_guild_scheduled_event(guild_id: int, *, reason: str | None, **kwargs: Any) → ScheduledEvent: Get the scheduled events for the guild.

async get_guild_scheduled_event(guild_id: int, event_id: int, *, with_user_count: bool = MISSING) → ScheduledEvent: Get a particular guild scheduled event.

async modify_guild_scheduled_event(guild_id: int, event_id: int, *, reason: str | None, **kwargs: Any) → ScheduledEvent: Modify a particular scheduled event.

async delete_guild_scheduled_event(guild_id: int, event_id: int) → None: Delete a given guild scheduled event.

async get_guild_scheduled_event_users(guild_id: int, event_id: int, *, limit: int = 100, with_member: bool = False, before: int | None = None, after: int | None = None) → list[User | GuildMember]: Get the event users for a guild scheduled event.

class novus.api.guild_template.GuildTemplateHTTPConnection(parent: HTTPConnection)

class novus.api.invite.InviteHTTPConnection(parent: HTTPConnection)

async get_invite(invite_code: str, *, with_counts: bool | None = None, with_expiration: bool | None = None, guild_scheduled_event_id: int | None = None) → Invite: Get an invite from the API.

async delete_invite(invite_code: str, *, reason: str | None = None) → Invite: Get an invite from the API.

class novus.api.stage_instance.StageHTTPConnection(parent: HTTPConnection)

async create_stage_instance(*, reason: str | None = None, **kwargs: dict[str, Any]) → StageInstance: Create a stage instance aassociated with a stage channel.

async get_stage_instance(channel_id: int) → StageInstance: Get a stage instance.

async modify_stage_instance(channel_id: int, *, reason: str | None = None, **kwargs: dict[str, Any]) → StageInstance: Update a stage instance.

async delete_stage_instance(channel_id: int, *, reason: str | None = None) → None: Delete a stage instance.

class novus.api.sticker.StickerHTTPConnection(parent: HTTPConnection)

async get_sticker(sticker_id: int) → Sticker

Get a sticker from the API via its ID.

This route shouldn’t really be used, but is included for completeness sake.

async list_guild_stickers(guild_id: int) → list[Sticker]: List the stickers within a guild.

async get_guild_sticker(guild_id: int, sticker_id: int) → Sticker: Get a sticker form a guild.

async create_guild_sticker(guild_id: int, *, reason: str | None = None, **kwargs: dict[str, Any]) → Sticker: Create a sticker within a guild.

async modify_guild_sticker(guild_id: int, sticker_id: int, *, reason: str | None = None, **kwargs: dict[str, Any]) → Sticker: Edit a sticker within a guild.

async delete_guild_sticker(guild_id: int, sticker_id: int, *, reason: str) → None: Delete a guild sticker.

class novus.api.user.UserHTTPConnection(parent: HTTPConnection)

async get_current_user() → User: Get the current user from the API.

async get_user(user_id: int) → User: Get a user from the API.

async modify_current_user(**kwargs: Any) → User: Edit the current user.

async get_current_user_guilds(*, before: int | None = None, after: int | None = None, limit: int = 200) → list[OauthGuild]: Get a list of guilds from the oauth user.

async get_current_user_guild_member(guild_id: int) → GuildMember: Get the current user’s guild member object.

async leave_guild(guild_id: int) → None: Leave a given guild.

async create_dm(recipient_id: int) → Channel: Create a DM with a user.

async get_user_connections() → Any: Get a list of connection objects from the API.

async get_user_application_role_connection(application_id: int) → Any: Get the current role connection for an application.

async update_user_application_role_connection(application_id: int) → Any: Update a role connection for an application.

class novus.api.voice.VoiceHTTPConnection(parent: HTTPConnection)

class novus.api.webhook.WebhookHTTPConnection(parent: HTTPConnection)

async create_webhook(channel_id: int, *, reason: str | None = None, **kwargs: dict[str, Any]) → Webhook: Create a webhook instance.

async get_channel_webhooks(channel_id: int) → list[Webhook]: Get all webhooks associated with a channel.

async get_guild_webhooks(guild_id: int) → list[Webhook]: Get all webhooks associated with a guild.

async get_webhook(webhook_id: int, *, token: str | None = None) → Webhook: Get a webhook via its ID.

async modify_webhook(webhook_id: int, *, reason: str | None = None, token: str | None = None, **kwargs: dict[str, Any]) → Webhook: Modify a webhook.

async delete_webhook(webhook_id: int, *, reason: str | None = None, token: str | None = None) → None: Delete a webhook.

async execute_webhook(webhook_id: int, token: str, *, wait: Literal[True] = False, thread_id: int | None = None, with_components: bool = False, **kwargs: dict[str, Any]) → WebhookMessage
async execute_webhook(webhook_id: int, token: str, *, wait: Literal[False] = False, thread_id: int | None = None, with_components: bool = False, **kwargs: dict[str, Any]) → None: Create a webhook message.

async get_webhook_message(webhook_id: int, token: str, message_id: int, *, thread_id: int | None = None) → WebhookMessage: Get a webhook message.

async edit_webhook_message(webhook_id: int, token: str, message_id: int, *, thread_id: int | None = None, **kwargs: dict[str, Any]) → WebhookMessage: Edit a webhook message.

async delete_webhook_message(webhook_id: int, token: str, message_id: int, *, thread_id: int | None = None) → None: Delete a webhook message.