Migration
Migrating from discord.py
Names look familiar. It is not a fork. import astrae in place of
import discord will not boot your bot. Port one piece at a time, on a test
app, with a way back.
Before you start
| Name |
Purpose |
0.1.0 |
Check events and REST you need actually run. Voice is a stub. |
| Native extension |
pip install of the Python tree without Maturin will not open a gateway. |
| Test app |
Portal intents and bot permissions are not the same switch. |
| Secrets |
DISCORD_TOKEN, Redis URL. Not production credentials. |
| Sharp edges |
commands.Context, converters, cogs, tasks, views, bot.http, "the cache always has this member." |
Concept mapping
| Name |
Purpose |
discord.Client / commands.Bot |
astrae.Client. Gateway, commands, cache, REST, lifecycle. |
commands.Bot(command_prefix=...) |
Client(command_prefix=...). Prefix needs Message Content in the portal and on the client. |
discord.Intents |
astrae.Intents. Rebuild the bitmask. Do not assume identical defaults. |
@bot.command() |
@bot.command(). Prefix callback gets PrefixContext. Conversion differs. |
@bot.tree.command() |
@bot.slash_command(). Options via Annotated. |
| Hybrid |
@bot.hybrid_command(). One callback; parsing and replies still differ. |
commands.Context |
PrefixContext or CommandContext. |
Member / User / ClientUser |
Parsed payloads. Cache does not guarantee presence. |
bot.user |
ClientUser after READY. Process stats (avg_latency, memory_usage, cpu) live on Client. |
@bot.event / @bot.listen |
Same names. Verify event coverage. |
commands.Cog |
astrae.Cog. cog_check and cog_command_error run automatically. Port cog_load / cog_unload yourself. |
discord.ui.View |
View, @button, builders. timeout=None and re-register stable custom IDs. |
discord.ext.tasks.loop |
@astrae.loop + client.add_loop. Decoration alone does not schedule. |
bot.http |
RestClient resource methods. |
discord.utils.get |
client.cache or REST. Misses are normal. |
discord.VoiceClient |
Names exist. Not feature-equivalent. |
discord.LoginFailure |
InvalidToken (LoginFailure alias). REST 401 or gateway 4004. Client.run() exits 78. |
Client lifecycle
from astrae import Client, Intents
bot = Client(
command_prefix="!",
intents=Intents.DEFAULT | Intents.MESSAGE_CONTENT,
)
async def main() -> None:
await bot.start()
bot.run()
| Name |
Purpose |
run() |
Owns the asyncio loop and signals. Reads DISCORD_TOKEN by default. |
start() |
Already-running loop. Do not call both. |
setup_hook() |
Async init once per start. on_ready can fire again on reconnect. |
Intents.MESSAGE_CONTENT |
Prefix parsing ordinary guild text. |
Intents.GUILD_MEMBERS |
Member chunking. Privileged: portal first. |
| Invite permissions |
Sending, roles, moderation. An intent is not a permission. |
Commands
from typing import Annotated
from astrae import Client, CommandContext, IntegerOption
bot = Client()
@bot.slash_command(name="repeat", description="Repeat text", guild_id=123456789)
async def repeat(
ctx: CommandContext,
count: Annotated[int, IntegerOption(description="Number of repeats", min_value=1, max_value=5)],
) -> None:
await ctx.reply(f"Repeated {count} times")
| Name |
Purpose |
| First argument |
Context. Not a Discord option. |
Annotated + option descriptor |
User-facing slash options. |
| discord.py converters |
Not recognized. Parse/validate yourself. |
Author / Current* |
Injected from the invoke. Not options. |
CurrentRole |
Invoking member's highest role (Member.top_role). |
Role.is_dangerous |
Kick, ban, administrator, manage guild/roles/channels, and similar bits. |
sync_commands=True |
Bulk overwrite at ready. False opts out. Do not compete with another deploy. |
ctx.reply() (prefix) |
Channel message. |
ctx.reply() (interaction) |
Initial response, or edit after defer. |
ctx.followup() |
Another interaction message. |
ctx.defer() / ctx.defer_update() |
Acknowledge slow work / component. |
| Ephemeral |
Interaction only. Branch in hybrid callbacks. |
cog_check |
False → silent CheckFailure. May be async. |
self.client.owners |
set[int]. Use id in self.client.owners. |
owner_only(*ids) |
Its own ID list. Does not read Client.owners. |
| Error handlers |
cog_command_error, @bot.command_error, @command.error. No tracebacks to users. |
Events, cogs, cache, REST
| Name |
Purpose |
| Event names |
Lowercase. Verify the parsed model. |
| Dispatch path |
No blocking time.sleep. |
Cog |
Binds decorated commands/listeners on add_cog(). |
setup(client) |
Extension entry. Sync or async. Safe to repeat. Optional teardown. |
| Cache miss |
Normal. Fetch when you need a current object. |
| Models |
Snapshots. Changing a field does not call REST. |
client.http / RestClient |
Replace private bot.http calls. |
client.add_view() |
Every process that should handle the view. |
@loop |
Register with the client. Distributed jobs need Redis locks and idempotency. |
Sequence
| Step |
Purpose |
| 1 |
Config, secrets, intents, minimal startup. |
| 2 |
One prefix command and one slash command in a test guild. |
| 3 |
Replies, errors, checks. DMs, missing permissions, deferral. |
| 4 |
Listeners. Required intents and model fields. |
| 5 |
Cogs/extensions with repeatable setup/teardown. |
| 6 |
Cache misses and explicit fetch. |
| 7 |
Loops and views. Restart and multi-process. |
| 8 |
REST traffic, metrics, logs, reconnects. Then production. |
Keep the discord.py deploy until each workflow passes a test-guild checklist.
Do not run both versions on the same token and shard IDs.