Package: hikari-atsume
hikari-atsumeDocumentationAn opinionated Discord bot framework inspired by Django and built on
top ofHikari,Tanjun,Ormar, andAlembic.Atsume is in alpha and breaking changes should be expected. If you have any feedback or advice, feel free
to find me in theHikari Discord.FeaturesAutomatic project scaffolding/file-based organizationConfiguration instead of boilerplateFunctionality split into modular, independent componentsAutomatically restart the bot on changes during developmentConfigure which components run in which serversDatabase ORM with OrmarAutomatic database migrations with AlembicQuick StartInstallationCreate a new project directory and install hikari-atsume
(make sure you are using Python 3.10+. If you are using Poetry,
your Python dependency should bepython = "^3.10,<3.12")# Install with your preferred database backend, SQLite recommended for beginnerspipinstallhikari-atsume[sqlite]pipinstallhikari-atsume[mysql]pipinstallhikari-atsume[postgresql]Start a new projectNow to start your new project, runatsumestartprojectmy_botwhich should generate some files for your project. Inmy_bot/local.py, add your
Discord bot token in. If you want to use message commands, make sure to set yourMESSAGE_PREFIXand addhikari.Intents.MESSAGE_CONTENTto yourINTENTS.# my_bot/settings.pyINTENTS=hikari.Intents.ALL_UNPRIVILEGED|hikari.Intents.MESSAGE_CONTENTStart a componentIn your project directory runpythonmanage.pystartappbasicwhich should generate a new directory calledbasic.Inbasic/commands.py, write your commands usingTanjun.
Commands are declared without explicitly attaching to a Component object
(Atsume takes care of that usingload_from_scope).This is an example of a hybrid slash/message command that takes one
optional positional argument, the user to say hi to.# basic/commands.py@tanjun.annotations.with_annotated_args(follow_wrapped=True)@tanjun.as_message_command("hi","hello","hey","howdy")@tanjun.as_slash_command("hi","The bot says hi.")asyncdefhello(ctx:atsume.Context,member:Annotated[Optional[Member],"The user to say hi to.",Positional()]=None,)->None:member=memberifmemberelsectx.memberifmember:awaitctx.respond(f"Hi{member.display_name}!")Now with our new component ready, register it in the bot's settings.# my_bot/settings.pyCOMPONENTS=["basic"]Working with the databaseLet's say we want to track how many times each member of a guild has said
hi to the bot. In ourmodels.pyfile, let's create a new database model
to keep track of this. Atsume usesOrmarfor its database models and queries.# basic/models.pyfromatsume.dbimportModelimportormarclassHiCounter(Model):user:int=ormar.BigInteger(primary_key=True)# Discord User IDs need to be stored as big integerscount:int=ormar.Integer(default=0)Now in ourcommands.py, let's increment a user's count every time they say hi.# basic/models.py# Skipping the decoratorsasyncdefhello(ctx:atsume.Context,member:Annotated[Optional[Member],"The user to say hi to.",Positional()]=None,)->None:member=memberifmemberelsectx.memberifmember:count_model,_=awaitHiCounter.objects.get_or_create(user=member.user.id,_defaults={"count":0})count_model.count=count_model.count+1awaitcount_model.upsert()awaitctx.respond(f"Hi{member.display_name}! (You've said hi{count_model.count}time[s]!)")Migrating the databaseBefore we run this though, we need to add our HiCounter model to the database! To do this,
we can generate a database migration that will migrate the database from it's current
state (nothing) to the state we want (a database with a table for HiCounter). Atsume
can generate migrations automatically in most cases so we'll use it's tool for that here.Run this command to generate migrations.pythonmanage.pymakemigrationsYou should see something likeMigrating ComponentConfig(name"basic")...
  Create model hicounter...Once that's done, your migration is ready to go! Run it on the database withpythonmanage.pyupgradeNote about Atsume MigrationsAtsume's migrations are still very much a work in progress (you can track ithere).
As a general rule of thumb, Atsume is good at migrations that create and delete
models and fields, but currently struggles with renames. You can always review
a migration and make any needed changes by looking in the component's
generated migration folder. Atsume usesAlembicfor migrations, so you can look at theAlembic operations docsto figure out how to write migrations manually.Run the botFinally, with the bot configured and our component's commands and models ready ,
it's time to run it!pythonmanage.pyrunSpecial thanks toThe Hikari Discord for help and feedbackFasterSpeeding forTanjunLunarmagpie for help with the CI and lintingTheDjangoanddjango-stubsprojects for their amazing work and some
code that I borrowed.