This release is a pre-release and may not be stable for production use.
hikari
An opinionated, static typed Discord microframework for Python3 and asyncio that supports Discord's V8 REST API and Gateway.
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 and 3.10-dev are currently supported.
Bots
import hikari
bot = hikari.BotApp(token="...")
@bot.listen()
async def ping(event: hikari.GuildMessageCreateEvent) -> None:
# If a non-bot user sends a message "hk.ping", respond with "Pong!"
# We check there is actually content first, if no message content exists,
# we would get `None' here.
if event.is_bot or not event.content:
return
if event.content.startswith("hk.ping"):
await event.message.reply("Pong!")
bot.run()
This will only respond to messages created in guilds. You can use DMMessageCreateEvent
instead to only listen on DMs, or MessageCreateEvent to listen to both DMs and guild-based
messages.
Logging will be automatically configured for you if you do not enable it manually. This has been implemented after seeing a large number of new bot developers struggle with writing their first bot in other frameworks simply because of working blind after not understanding or knowing how to set up standard logging messages.
If you wish to customise the intents being used in order to change which events your bot
is notified about, then you can pass the intents kwarg to the BotApp constructor:
# the default is to enable all unprivileged intents (all events that do not target the
# presence or activity of a specific member).
bot = hikari.BotApp(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). Other options also exist such as customising timeouts for requests and enabling a proxy.
Also note that you could pass extra options to bot.run during development, for example:
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.
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.
@bot.listen(hikari.MessageCreateEvent)
async def ping(event):
...
REST-only applications
You may only want to integrate with the REST API, for example if writing a web dashboard.
This is relatively simple to do:
rest = hikari.RESTApp()
async def print_my_user(token):
# We acquire a client with a given token. This allows one REST app instance
# with one internal connection pool to be reused.
async with rest.acquire(token) as client:
my_user = await client.fetch_my_user()
print(my_user)
asyncio.run(print_my_user("user token here"))
This client has been designed to be able to work in compliment with existing
OAuth2 client implementations, such as
aiohttp-oauth2.
Installation
Install hikari from PyPI with the following command:
python -m pip install hikari -U --pre
# Windows users may need to run this instead...
py -3 -m pip install hikari -U --pre
Additional resources
You 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.
Making your application more efficient
As your application scales, you may need to adjust some things to keep it performing nicely.
Python optimisation flags
CPython and Stackless Python provide two optimisation flags that remove internal safety checks that are useful for development, and change other internal settings in the interpreter.
python bot.py- no optimisation - this is the default.python -O bot.py- first level optimisation - features such as internal assertions will be disabled.python -OO bot.py- second level optimisation - more features (including all docstrings) will be removed from the loaded code at runtime.
hikari[speedups]
If you have a C compiler (Microsoft VC++ Redistributable 14.0 or newer, or a
modern copy of GCC/G++, Clang, etc), you can install hikari using
pip install -U hikari[speedups]. This will install aiodns, cchardet, and
ciso8601, which will provide you with a small performance boost.
uvloop
If you use Linux, you will get additional performance benefits from using
a library called uvloop. This replaces the default asyncio event loop with
one that uses libuv internally. You can run pip install uvloop and then
amend your script to be something similar to the following example to utilise it
in your application:
import os
import hikari
if os.name != "nt":
import uvloop
uvloop.install()
bot = hikari.Bot(...)
...
Compiled extensions
Eventually, 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, should PEP 554 -- Multiple Interpreters in the Stdlib be accepted.
Currently, this functionality does not yet exist.
Developing Hikari
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/activate on 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 is pip install nox to install nox. This handles
running predefined tasks and pipelines.
You can install any dependencies with
pip install -r requirements.txt -r dev-requirements.txt.
Once this is complete, you can run nox without 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!
1 maintainer
Release files for hikari 2.0.0.dev92
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| hikari-2.0.0.dev92.tar.gz | 293.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hikari-2.0.0.dev92-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 669.9 kB
Release files / hikari-2.0.0.dev92.tar.gz
| Download URL | hikari-2.0.0.dev92.tar.gz |
|---|---|
| Size | 293.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3a336f50eedc7198cbea7ea6fbccc6804ac848bcdfe7b038f7d265145db47d13
|
|
BLAKE2b-256 checksum How to use checksums |
b4f0114e289e7220cb1bca4b4323a51aa61e171246d3f4779c78015b099d9172
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.50.2 CPython/3.8.0
|
Release files / hikari-2.0.0.dev92-py3-none-any.whl
| Download URL | hikari-2.0.0.dev92-py3-none-any.whl |
|---|---|
| Size | 376.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7798b3e7486b5e7afc8415307dfc8c9b398482dec681c0f867e6fa643731efcd
|
|
BLAKE2b-256 checksum How to use checksums |
a3a94512ede224b1339d070ec6055154da6feda2b0b7977aa3732a2c91c98d02
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.50.2 CPython/3.8.0
|
