astrae

API reference

Complete top-level exports

from astrae import … is these names, nothing else. Submodules can export more; that is not the root contract. Signatures are on the installed package.

from astrae import Client, CommandContext, Intents, StringOption
from astrae.core.formatting import bold
from astrae.rest import RestClient
from astrae.runtime.tasks import Scheduler

Import from astrae unless a page tells you the name lives deeper.

Client, clustering, and voice

Client, voice, sharding.

Name Purpose
Client Bot process: gateway, commands, cache, REST, and lifecycle.
ClusterSupervisor Spawn, restart, and reshard local cluster processes.
ClusterContext Shard range and cluster identity for one child process.
VoiceClient Gateway voice-state helper. Not a complete UDP/DAVE voice stack.
PCMAudio PCM audio source wrapper used with VoiceClient.play.
OpusAudio Opus packet audio source wrapper.
__version__ Installed Astrae version string.

Command registration

Commands, catalog.

Name Purpose
command Register a prefix command that can also sync as an application command.
prefix_command Register a prefix-only command.
slash_command Register a chat-input application command.
hybrid_command One callback for prefix and slash invocation.
context_menu Register a user or message context-menu command.
AppCommand Command definition object created by those decorators.
Cog Group commands and listeners; supports cog_check and cog_command_error.
Plugin Lightweight command and listener bundle.
listener Mark a cog/plugin method as a gateway event listener.
guild_only Middleware that rejects DM invocations.
owner_only Middleware that allows configured owner IDs only.

Contexts, prompts, and pagination

Name Purpose
CommandContext Interaction invocation: reply, defer, followup, update, styled helpers.
PrefixContext Prefix-message invocation: channel replies and the same styled helpers.
ContextTheme Default colors and emojis for ctx.approve / ctx.error (ASTRAE_COLOR_*).
Confirmation Approve / Decline prompt view.
Approve Confirmation variant with approve-style labels.
Paginator Pages strings, embeds, fields, or files on a context.

Command options and injected values

Put option descriptors in Annotated. Author and the Current* names are not options. They come from the invoke and can be None in a DM.

Name Purpose
StringOption String application-command option.
IntegerOption Integer option.
NumberOption Number (float) option.
BooleanOption Boolean option.
UserOption User option.
ChannelOption Channel option.
RoleOption Role option.
MentionableOption User or role option.
AttachmentOption Attachment option.
Author Invoking user, without creating an option.
CurrentUser Same as Author from the resolved user object.
CurrentMember Invoking member when the command runs in a guild.
CurrentGuild Guild for this invocation.
CurrentChannel Channel for this invocation.
CurrentRole Invoking member's highest role.

Components, views, and interaction HTTP

Name Purpose
View Message component view with button/select callbacks.
button Decorator that binds a button callback onto a View.
Modal Modal submit payload and callback.
ComponentCollector Wait for a matching component interaction.
InteractionApp ASGI app that verifies and dispatches HTTP interactions.

Payload builders

JSON you send. Discord still says no if it is wrong. Enum members: protocol types.

Name Purpose
Embed Rich embed payload.
AllowedMentions Which mentions ping; UNSET fields inherit from a client default.
ActionRow Legacy row of buttons, selects, or text inputs.
Button Button component.
SelectMenu String, user, role, mentionable, or channel select.
SelectOption One option on a string select.
TextInput Modal text input.
Poll Poll create payload.
PollAnswer One poll answer.
Container Components V2 container.
Section Components V2 section.
TextDisplay Components V2 text block.
Thumbnail Components V2 thumbnail accessory.
MediaGallery Components V2 media gallery.
Separator Components V2 separator.
File Components V2 file component, or an embed/message file depending on use.
Upload Multipart upload stream, filename, and content type for REST.
COMPONENTS_V2_FLAG Message flag for Components V2 layouts (MessageFlags.IS_COMPONENTS_V2).

Models

A payload, not a live object and not a cache hit. Catalog.

Name Purpose
User Global Discord user.
ClientUser Connected bot user on client.user after READY.
Member Guild-local member plus user fields when Discord sent them.
Guild Guild snapshot from a payload or cache.
Role Guild role. is_dangerous flags elevated permission bits.
Channel Channel snapshot, including threads and categories.
Message Message snapshot.
Attachment Message attachment.
Interaction Incoming interaction.
ReadyEvent READY payload (user, guilds, session_id, resume URL).
Asset CDN asset URL helper.
EventContext Listener delivery metadata (name, shard, before, raw).

Protocol types

Ints and flags. Members: protocol types. Type.docs or docs_for(Type) is Discord's page.

Name Purpose
Intents Gateway event subscriptions. Privileged bits also need portal approval.
Permission Discord permission bit flags. Hierarchy is separate from these bits.
ChannelType Channel kind. Unknown integers are kept as UNKNOWN_<n>.
MessageFlags Message flag bits, including ephemeral and Components V2.
ButtonStyle Button visual style. LINK requires url.
ComponentType Component kind, including Components V2 types.
ApplicationCommandType Chat input, user, or message context-menu command.
ApplicationCommandOptionType Application-command option kind.
InteractionType Ping, command, component, autocomplete, or modal.
InteractionCallbackType Interaction response kind (reply, defer, update, modal).
Status Presence status (online, idle, dnd, invisible, offline).
ActivityType Presence activity kind (playing, streaming, …).
Activity Presence activity payload (name, type, optional url).

Formatting and omitted fields

Name Purpose
Formatter Discord markdown, mentions, and timestamps. Helpers such as bold are on astrae.core.formatting.
UNSET Sentinel meaning omit this key from a partial payload.
UnsetType Type of UNSET. Distinct from None, which serializes as JSON null.

HTTP and token errors

Catch the narrow type. Do not parse str(err).

Name Purpose
AstraeError Base class for framework errors.
DiscordAPIError Discord returned a non-success HTTP status.
HTTPException Generic HTTP failure (discord.py name for DiscordAPIError).
BadRequest HTTP 400.
Unauthorized HTTP 401.
Forbidden HTTP 403.
NotFound HTTP 404.
RateLimited HTTP 429.
ServerError HTTP 5xx.
TokenRevoked REST 401 while a session was running; further REST is halted.
InvalidToken Discord rejected the bot token (REST 401 or gateway close 4004). Client.run() exits 78.
LoginFailure Alias of InvalidToken.
InvalidRequestBudget Request held because Discord's invalid-request window is nearly full.

Command errors

These stop a command. Most get a ctx.error or help reply. NotOwner and a bare CheckFailure stay quiet.

Name Purpose
CommandError Stop command execution, optionally with a user-facing message.
CheckFailure Middleware or check rejected the invocation.
CommandNotFound No command matched the invocation.
CommandInvokeError The callback raised; original exception is attached.
CommandOnCooldown Command cooldown is active.
MaxConcurrencyReached Too many concurrent runs of this command.
DisabledCommand Command is disabled.
UserInputError Base class for bad or missing user input.
MissingRequiredArgument A required prefix/option value was omitted.
MissingRequiredAttachment A required attachment was omitted.
BadArgument A value could not be converted.
ConversionError Converter raised while parsing an argument.
BadLiteralArgument Value was not one of the allowed literals.
BadUnionArgument Value matched none of a union's converters.
RangeError Numeric value was outside the allowed range.
BadInviteArgument Invite could not be resolved.
MemberNotFound Member lookup failed.
UserNotFound User lookup failed.
RoleNotFound Role lookup failed.
ChannelNotFound Channel lookup failed.
MessageNotFound Message lookup failed.
FlagError Base class for prefix flag parsing failures.
TooManyFlags A flag was repeated more times than allowed.
MissingFlagArgument A flag was present without its value.
MissingRequiredFlag A required flag was omitted.
BadFlagArgument A flag value could not be converted.
MissingPermissions Invoking member lacks required permission bits.
BotMissingPermissions The bot lacks required permission bits.
MissingRole Invoking member lacks a required role.
BotMissingRole The bot lacks a required role.
MissingAnyRole Invoking member has none of the required roles.
BotMissingAnyRole The bot has none of the required roles.
NSFWChannelRequired Command requires an NSFW channel.
PrivateMessageOnly Command must be used in a DM.
NoPrivateMessage Command cannot be used in a DM.
NotOwner Invoker is not a configured owner.

Extension errors

Name Purpose
ExtensionError Base class for extension load/unload failures.
ExtensionAlreadyLoaded Extension is already loaded.
ExtensionNotLoaded Extension is not loaded.
ExtensionNoEntryPoint Module has no setup(client).
ExtensionFailed setup raised.

Runtime, cache, and observability

Runtime, metrics.

Name Purpose
Cache Typed Discord entity cache (memory or Redis).
CacheConfig Per-namespace cache policies.
CachePolicy One namespace: enabled, size, TTL, optional retained fields.
MemoryBus In-process event bus. Not cross-process.
open_bus Build a bus from IPC configuration (memory, Redis, or stream).
RedisPool Process-local shared Redis pool. Not shared across cluster children.
loop Decorator for a client-managed periodic async callback.
METRICS Process-global metrics registry.
Metrics Metrics registry class (counters, gauges, dashboard feeds).
MetricsService Local HTTP dashboard, JSON API, and Prometheus exposition.
LoopMonitor Event-loop lag watchdog; stalls go to logs, metrics, and the dashboard.
GcFreezer Collect, trim, and freeze long-lived cache objects. Skips in-flight chunks.

Database

Database. Gateway events do not land in SQL.

Name Purpose
Database Async SQLAlchemy wrapper (client.db / client.postgres).
Migration One schema migration step.
Migrator Apply or roll back Migration records.

Debug

Name Purpose
Jishaku Owner debug cog (eval, shell, files). Grants process privileges to whoever can run it; do not load for untrusted users.