Package: hikari
hikariAn opinionated, static typed Discord microframework for Python3 and asyncio that supports Discord's v10 REST and
Gateway APIs.Built on good intentions and the hope that it will be extendable and reusable, rather than an obstacle for future
development.Python 3.8, 3.9, 3.10, 3.11 and 3.12 are currently supported.InstallationInstall Hikari from PyPI with the following command:python-mpipinstall-Uhikari# Windows users may need to run this instead...py-3-mpipinstall-UhikariBotsHikari provides two different default bot implementations to suit your needs:GatewayBotRESTBotGatewayBotAGatewayBotis one which will connect to Discord through the gateway and receive
events through there. A simple startup example could be the following:importhikaribot=hikari.GatewayBot(token="...")@bot.listen()asyncdefping(event:hikari.GuildMessageCreateEvent)->None:"""If a non-bot user mentions your bot, respond with 'Pong!'."""# Do not respond to bots nor webhooks pinging us, only user accountsifnotevent.is_human:returnme=bot.get_me()ifme.idinevent.message.user_mentions_ids:awaitevent.message.respond("Pong!")bot.run()This will only respond to messages created in guilds. You can useDMMessageCreateEventinstead to only listen on
DMs, orMessageCreateEventto listen to both DMs and guild-based messages. A full list of events
can be found in theevents docs.If you wish to customize the intents being used in order to change which events your bot is notified about, then you
can pass theintentskwarg to theGatewayBotconstructor:importhikari# the default is to enable all unprivileged intents (all events that do not target the# presence, activity of a specific member nor message content).bot=hikari.GatewayBot(intents=hikari.Intents.ALL,token="...")The above example would enable all intents, thus enabling events relating to member presences to be received
(you'd need to whitelist your application first to be able to start the bot if you do this).Events are determined by the type annotation on the event parameter, or alternatively as a type passed to the@bot.listen()decorator, if you do not want to use type hints.importhikaribot=hikari.GatewayBot("...")@bot.listen()asyncdefping(event:hikari.MessageCreateEvent):...# or@bot.listen(hikari.MessageCreateEvent)asyncdefping(event):...RESTBotARESTBotspawns an interaction server to which Discord willonlysend interaction events,
which can be handled and responded to.An example of a simpleRESTBotcould be the following:importasyncioimporthikari# This function will handle the interactions receivedasyncdefhandle_command(interaction:hikari.CommandInteraction):# Create an initial response to be able to take longer to respondyieldinteraction.build_deferred_response()awaitasyncio.sleep(5)# Edit the initial responseawaitinteraction.edit_initial_response("Edit after 5 seconds!")# Register the commands on startup.## Note that this is not a nice way to manage this, as it is quite spammy# to do it every time the bot is started. You can either use a command handler# or only run this code in a script using `RESTApp` or add checks to not update# the commands if there were no changesasyncdefcreate_commands(bot:hikari.RESTBot):application=awaitbot.rest.fetch_application()awaitbot.rest.set_application_commands(application=application.id,commands=[bot.rest.slash_command_builder("test","My first test command!"),],)bot=hikari.RESTBot(token="...",token_type="...",public_key="...",)bot.add_startup_callback(create_commands)bot.set_listener(hikari.CommandInteraction,handle_command)bot.run()UnlikeGatewayBot, registering listeners is done through.set_listener, and it takes in an interaction type
that the handler will take in.Note that a bit of a setup is required to get the above code to work. You will need to host the project to
the World Wide Web (scary!) and then register the URL on theDiscord application portalfor your application under "Interactions Endpoint URL".A quick way you can get your bot onto the internet and reachable by Discord (for development environment only) is
through a tool likengrokorlocalhost.run. More information on how to
use them can be found in their respective websites.Common helpful featuresBoth implementations take in helpful arguments such ascustomizing timeouts for requestsandenabling a proxy,
which are passed directly into the bot during initialization.Also note that you could pass extra options tobot.runduring development, for example:importhikaribot=hikari.GatewayBot("...")# orbot=hikari.RESTBot("...","...")bot.run(asyncio_debug=True,# enable asyncio debug to detect blocking and slow code.coroutine_tracking_depth=20,# enable tracking of coroutines, makes some asyncio# errors clearer.propagate_interrupts=True,# Any OS interrupts get rethrown as errors.)Many other helpful options exist for you to take advantage of if you wish. Links to the respective docs can be seen
below:GatewayBot.runRESTBot.runREST-only applicationsYou may only want to integrate with the REST API, for example if writing a web dashboard.This is relatively simple to do:importhikariimportasynciorest=hikari.RESTApp()asyncdefprint_my_user(token):awaitrest.start()# We acquire a client with a given token. This allows one REST app instance# with one internal connection pool to be reused.asyncwithrest.acquire(token)asclient:my_user=awaitclient.fetch_my_user()print(my_user)awaitrest.close()asyncio.run(print_my_user("user token acquired through OAuth here"))Optional FeaturesOptional features can be specified when installing hikari:server- Install dependencies required to enable Hikari's standard interaction server (RESTBot) functionality.speedups- Detailed inhikari[speedups].Example:# To install hikari with the speedups feature:python-mpipinstall-Uhikari[speedups]# To install hikari with both the speedups and server features:python-mpipinstall-Uhikari[speedups,server]Additional resourcesYou may wish to use a command framework on top of Hikari so that you can start writing a bot quickly without
implementing your own command handler.Hikari does not include a command framework by default, so you will want to pick a third party library to do it:lightbulb- a simple and easy to use command framework for Hikari.tanjun- a flexible command framework designed to extend Hikari.crescent- a command handler for Hikari that keeps your project neat and tidy.Making your application more efficientAs your application scales, you may need to adjust some things to keep it performing nicely.Python optimization flagsCPython provides two optimization flags that remove internal safety checks that are useful for development, and change
other internal settings in the interpreter.python bot.py- no optimization - this is the default.python -O bot.py- first level optimization - features such as internal assertions will be disabled.python -OO bot.py- second level optimization - more features (including all docstrings) will be removed from
the loaded code at runtime.A minimum of first level of optimizationis recommended when running bots in a production environment.hikari[speedups]If you have a C compiler (Microsoft VC++ Redistributable 14.0 or newer, or a modern copy of GCC/G++, Clang, etc), it is
recommended you install Hikari usingpip install -U hikari[speedups]. This will installaiohttpwith its available
speedups,ciso8601andorjsonwhich will provide you with a substantial performance boost.uvloopIf you use a UNIX-like system, you will get additional performance benefits from using a library calleduvloop.
This replaces the defaultasyncioevent loop with one that useslibuvinternally. You can runpip install uvloopand then amend your script to be something similar to the following example to utilise it in your application:importosifos.name!="nt":importuvloopuvloop.install()# Your code goes hereCompiled extensionsEventually, we will start providing the option to use compiled components of this library over pure Python ones if it
suits your use case. This should also enable further scalability of your application, shouldPEP 554 -- Multiple Interpreters in the Stdlibbe accepted.Currently, this functionality does not yet exist.Developing HikariTo familiarize yourself a bit with the project, we recommend reading ourcontributing manual.If you wish to contribute something, you should first start by cloning the repository.In the repository, make a virtual environment (python -m venv .venv) and enter it (source .venv/bin/activateon
Linux, or for Windows use one of.venv\Scripts\activate.ps1,.venv\Scripts\activate.bat,source .venv/Scripts/activate).The first thing you should run ispip install -r dev-requirements.txtto install nox.
This handles running predefined tasks and pipelines.Once this is complete, you can runnoxwithout any arguments to ensure everything builds and is correct.Where can I start?Check out the issues tab on GitHub. If you are nervous, look for issues marked as "good first issue" for something
easy to start with!Feel free to also join ourDiscordto directly ask questions to the maintainers! They will
be glad to help you out and point you in the right direction.