astrae

API reference

Python source module catalog

Every module under python/astrae/ in this tree. Internal means "this is what the file is for", not "import it from your bot". Add a row when you add a file.

Root names you can import: exports.

Package root and process tooling

Name Purpose
astrae.__init__ Public re-exports and __version__.
astrae.json orjson-backed dumps/loads for gateway, cache, REST, bus. Internal codec.
astrae.cli astrae cluster parser, recommended shard lookup, process bootstrap.
astrae.cluster Shard allocation, env context, process records, telemetry, restart/reshard. ClusterSupervisor/ClusterContext public.
astrae.console Prompt-toolkit supervisor UI. Operational tool.

Client

Name Purpose
client.__init__ Constructor, properties, lifecycle. Client.
client.commands Command/listener/middleware/cog/extension/view registration and sync.
client.gateway Gateway event hookup, interaction/prefix dispatch, cluster control. Internal mixin.
client.census Event-derived guild/user counts. Estimates, not authoritative.
client.warmup Member chunk/warmup queue and progress.
client.voice.client Audio-source protocols, gateway voice-state ops. Incomplete. Voice.
client.voice.__init__ Voice exports.
client.sentry sentry_sdk / Tracelet ingest, dashboard forwarding, exception capture.
client.posthog PostHog hook, command-use events, Tracelet connection event.

Commands and interactions

Name Purpose
commands.__init__ Command package exports.
commands.app AppCommand, decorators, subcommands, prefix/slash metadata.
commands.context Shared, prefix, and interaction contexts.
commands.current Injection markers. Resolution helpers internal.
commands.dispatch Resolve invoke, run callbacks, listeners, middleware. Internal.
commands.middleware Stack runner, guild_only, owner_only.
commands.cogs Cog registration, @listener, extension load/unload and rollback.
commands.plugin Lightweight command/listener bundle.
commands.registry Current-client registration context for decorators. Internal.
commands.messages Message payload composition, mention policy. Internal.
commands.parsing.__init__ Parsing package exports.
commands.parsing.options Option descriptors, annotation inspection, Discord option payloads.
commands.parsing.converters Prefix token/flag/mention/attachment conversion. Internal.
commands.parsing.prefix Prefix tree/group/alias/choice matching. Internal.
commands.interactions.__init__ Interaction helper exports.
commands.interactions.views Views, @button, collectors, callback store.
commands.interactions.modals Modal payload and callback.
commands.interactions.waiters Redis/local interaction and message waiters.
commands.interactions.http ASGI endpoint, signature verification, PING, dispatch. InteractionApp public.

Core types, models, builders

Name Purpose
core.__init__ Core exports.
core.docs Discord URL map (DOCS, docs_for).
core.errors Framework, command, extension, HTTP/API errors.
core.events Event context, value types, payload parsing.
core.formatting Markdown, mentions, timestamps.
core.permissions Permission bit conversion and effective calculation.
core.types.__init__ Protocol type exports.
core.types.enums Command, interaction, component, channel, message, permission enums.
core.types.intents Intent flags and names.
core.types.presence Status/activity values and payload conversion.
core.types.snowflake Snowflake timestamp helpers and SnowflakeTime.
core.types.unset UNSET, omission, recursive payload conversion.
core.models.__init__ Model exports.
core.models.asset CDN asset URL/size/format/animation.
core.models.guild Guild, channel, role, overwrite, emoji, sticker.
core.models.ids Snowflake field extraction. Internal.
core.models.interaction Ready, interaction data, options, resolved objects.
core.models.message Message, attachment, embed, reaction, component, sticker.
core.models.users User, ClientUser, member, display/avatar helpers.
core.builders.__init__ Builder exports.
core.builders.components Button, select, text input, action row.
core.builders.embed Embed and field payloads.
core.builders.mentions Allowed-mention policy.
core.builders.poll Poll and poll-answer builders.
core.builders.v2 Components V2 container, section, gallery, file, text, separator.

REST and persistence

Name Purpose
rest.__init__ REST exports.
rest.client RestClient, HTTPClient, resource groups, generic request.
rest.emojis Application emoji data URI and sync. Internal.
rest.resources.__init__ Resource exports.
rest.resources.base Shared REST request/payload helper. Internal.
rest.resources.applications Application identity, command overwrite, application emojis.
rest.resources.automod Auto-moderation rules.
rest.resources.channels Channel, message, thread, reaction, pin, overwrite, invite.
rest.resources.gateway Gateway discovery.
rest.resources.guilds Guild, member, role, moderation, emoji, sticker, audit.
rest.resources.interactions Initial response, original edits, followups.
rest.resources.invites Invite fetch/delete.
rest.resources.polls Poll voters and expiration.
rest.resources.stage Stage instance create/get.
rest.resources.stickers Sticker and Nitro pack reads.
rest.resources.users Current user, lookup, DM, guild listing.
rest.resources.voice Voice-region listing. Not a complete voice client.
rest.resources.webhooks Webhook CRUD, execution, messages.
rest.wire.__init__ Transport/upload exports.
rest.wire.transport Native, local proxy, Redis proxy contracts.
rest.wire.proxy HTTP-facing REST proxy lifecycle.
rest.wire.uploads Upload and multipart/proxy encoding.
db.__init__ Lazy database exports.
db.core URL normalization, SQLAlchemy async engine, sessions, transactions.
db.migrations Ordered up/down migrations and runner.
db.orm SQLAlchemy declarative Model base.

Runtime

Name Purpose
runtime.__init__ Runtime exports.
runtime.services Redis/PostgreSQL/PostHog/Tracelet probes.
runtime.identify File-backed identify/session store. Format internal.
runtime.telemetry Cluster UDP telemetry and control. Internal wire.
runtime.tasks Periodic loops, cron, named leases/locks.
runtime.redis.__init__ Redis pool exports.
runtime.redis.pool Process-local URL-keyed Redis pool.
runtime.bus.__init__ Bus exports.
runtime.bus.ipc Bus protocol, memory/TCP/Unix, role selection, gateway worker.
runtime.bus.idempotency Delivery-key completion log and once-only wrapper.
runtime.bus.redis.__init__ Redis bus exports.
runtime.bus.redis.adapter Stream/lease partition assignment, publish, subscribe, ack. Internal.
runtime.cache.__init__ Cache exports.
runtime.cache.policy Per-namespace enable/size/TTL/field rules.
runtime.cache.store Facade, namespace methods, model construction, async write queue.
runtime.cache.ingest Gateway event → cache mutations. Internal.
runtime.cache.mutations Mutation buffer and batch ops. Internal.
runtime.cache.backends.__init__ Backend exports.
runtime.cache.backends.adapter Adapter/writer protocols and cache entry. Internal.
runtime.cache.backends.memory Process-local memory adapter.
runtime.cache.backends.redis.__init__ Redis backend exports.
runtime.cache.backends.redis.adapter Redis CRUD/index/bulk/stat. Internal.
runtime.cache.backends.redis.constants Key/schema version constants. Do not rely on key names.
runtime.cache.backends.redis.keys Key/relationship encoding. Internal.
runtime.cache.backends.redis.scripts Atomic Redis scripts. Internal.
runtime.observe.__init__ Observability exports.
runtime.observe.late Late-event timing. Internal.
runtime.observe.metrics Definitions, storage, snapshots, Prometheus.
runtime.observe.monitor Event-loop lag sampler and task stacks.
runtime.observe.gcfreeze Periodic collect/freeze. Pauses around member chunking.
runtime.observe.web.__init__ Metrics service exports.
runtime.observe.web.service HTTP routing, auth, API, Prometheus, dashboard lifecycle.
runtime.observe.web.dashboard Embedded dashboard HTML/CSS/JS. Internal.

Jishaku

Name Purpose
jishaku.__init__ Jishaku exports.
jishaku.cog Eval, inspect, shell/git/pip/files/network, owner controls. Trust boundary is critical.
jishaku.codeblocks Fenced code parsing. Internal.
jishaku.output Codeblock formatting and execution namespace. Internal.
jishaku.repl Async wrap/execute, scopes, inspect. Internal. Not a sandbox.

A file map, not a stability promise. Import from exports. Redis keys, wire formats, metric internals, and the native crate can change.