{"id":13410782,"url":"https://github.com/hikari-py/hikari","last_synced_at":"2025-03-14T16:33:02.164Z","repository":{"id":37014338,"uuid":"287714309","full_name":"hikari-py/hikari","owner":"hikari-py","description":"A Discord API wrapper for Python and asyncio built on good intentions.","archived":false,"fork":false,"pushed_at":"2024-04-30T04:36:34.000Z","size":13629,"stargazers_count":770,"open_issues_count":39,"forks_count":94,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-05-01T15:19:24.227Z","etag":null,"topics":["asyncio","bot","bot-framework","discord","discord-api","hacktoberfest","hikari","python","python3","slash-commands"],"latest_commit_sha":null,"homepage":"https://docs.hikari-py.dev/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hikari-py.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["davfsa","FasterSpeeding"]}},"created_at":"2020-08-15T09:13:10.000Z","updated_at":"2024-05-02T15:42:02.658Z","dependencies_parsed_at":"2023-01-17T13:16:02.027Z","dependency_job_id":"de91003d-59ca-4c51-8b03-68320e81cb4a","html_url":"https://github.com/hikari-py/hikari","commit_stats":{"total_commits":3494,"total_committers":65,"mean_commits":"53.753846153846155","dds":0.611333714939897,"last_synced_commit":"cf6d0b006e90304583306feb4bdb6c56db8247cf"},"previous_names":[],"tags_count":134,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hikari-py%2Fhikari","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hikari-py%2Fhikari/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hikari-py%2Fhikari/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hikari-py%2Fhikari/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hikari-py","download_url":"https://codeload.github.com/hikari-py/hikari/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243610457,"owners_count":20318966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","bot","bot-framework","discord","discord-api","hacktoberfest","hikari","python","python3","slash-commands"],"created_at":"2024-07-30T20:01:09.104Z","updated_at":"2025-03-14T16:33:02.111Z","avatar_url":"https://github.com/hikari-py.png","language":"Python","funding_links":["https://github.com/sponsors/davfsa","https://github.com/sponsors/FasterSpeeding"],"categories":["API Libraries","Python","Libraries","💻 API Libraries"],"sub_categories":["Python"],"readme":"\u003cdiv align=\"center\"\u003e\n\u003ch1\u003ehikari\u003c/h1\u003e\n\u003ca href=\"https://pypi.org/project/hikari\"\u003e\u003cimg height=\"20\" alt=\"Supported python versions\" src=\"https://img.shields.io/pypi/pyversions/hikari\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/hikari\"\u003e\u003cimg height=\"20\" alt=\"PyPI version\" src=\"https://img.shields.io/pypi/v/hikari\"\u003e\u003c/a\u003e\n\u003cbr\u003e\n\u003ca href=\"https://github.com/hikari-py/hikari/actions\"\u003e\u003cimg height=\"20\" alt=\"CI status\" src=\"https://github.com/hikari-py/hikari/actions/workflows/ci.yml/badge.svg?branch=master\u0026event=push\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/mypy/\"\u003e\u003cimg height=\"20\" alt=\"Mypy badge\" src=\"https://img.shields.io/badge/mypy-checked-blue\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/ruff\"\u003e\u003cimg height=\"20\" alt=\"Ruff badge\" src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json\"\u003e\u003c/a\u003e\n\u003ca href=\"https://codeclimate.com/github/hikari-py/hikari/test_coverage\"\u003e\u003cimg height=\"20\" alt=\"Test coverage\" src=\"https://api.codeclimate.com/v1/badges/f95070b25136a69b0589/test_coverage\"\u003e\u003c/a\u003e\n\u003cbr\u003e\n\u003ca href=\"https://discord.gg/Jx4cNGG\"\u003e\u003cimg height=\"20\" alt=\"Discord invite\" src=\"https://discord.com/api/guilds/574921006817476608/widget.png\"\u003e\u003c/a\u003e\n\u003ca href=\"https://docs.hikari-py.dev/en/stable\"\u003e\u003cimg height=\"20\" alt=\"Documentation Status\" src=\"https://readthedocs.org/projects/hikari-py/badge/?version=latest\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\nAn opinionated, static typed Discord microframework for Python3 and asyncio that supports Discord's v10 REST and\nGateway APIs.\n\nBuilt on good intentions and the hope that it will be extendable and reusable, rather than an obstacle for future\ndevelopment.\n\nPython 3.9, 3.10, 3.11, 3.12 and 3.13 are currently supported.\n\n## Installation\n\nInstall hikari from PyPI with the following command:\n\n```bash\npython -m pip install -U hikari\n# Windows users may need to run this instead...\npy -3 -m pip install -U hikari\n```\n\n----\n\n## Bots\n\nHikari provides two different default bot implementations to suit your needs:\n\n- [GatewayBot](#gatewaybot)\n- [RESTBot](#restbot)\n\n### GatewayBot\n\nA [`GatewayBot`](https://docs.hikari-py.dev/en/stable/reference/hikari/impl/gateway_bot/#hikari.impl.gateway_bot.GatewayBot)\nis one which will connect to Discord through the gateway and receive\nevents through there. A simple startup example could be the following:\n\n```py\nimport hikari\n\nbot = hikari.GatewayBot(token=\"...\")\n\n@bot.listen()\nasync def ping(event: hikari.GuildMessageCreateEvent) -\u003e None:\n    \"\"\"If a non-bot user mentions your bot, respond with 'Pong!'.\"\"\"\n\n    # Do not respond to bots nor webhooks pinging us, only user accounts\n    if not event.is_human:\n        return\n\n    me = bot.get_me()\n\n    if me.id in event.message.user_mentions_ids:\n        await event.message.respond(\"Pong!\")\n\nbot.run()\n```\n\nThis will only respond to messages created in guilds. You can use `DMMessageCreateEvent` instead to only listen on\nDMs, or `MessageCreateEvent` to listen to both DMs and guild-based messages. A full list of events\ncan be found in the [events docs](https://docs.hikari-py.dev/en/stable/reference/hikari/events/).\n\nIf you wish to customize the intents being used in order to change which events your bot is notified about, then you\ncan pass the `intents` kwarg to the `GatewayBot` constructor:\n\n```py\nimport hikari\n\n# the default is to enable all unprivileged intents (all events that do not target the\n# presence, activity of a specific member nor message content).\nbot = hikari.GatewayBot(intents=hikari.Intents.ALL, token=\"...\")\n```\n\nThe above example would enable all intents, thus enabling events relating to member presences to be received\n(you'd need to whitelist your application first to be able to start the bot if you do this).\n\nEvents are determined by the type annotation on the event parameter, or alternatively as a type passed to the\n`@bot.listen()` decorator, if you do not want to use type hints.\n\n```py\nimport hikari\n\nbot = hikari.GatewayBot(\"...\")\n\n@bot.listen()\nasync def ping(event: hikari.MessageCreateEvent):\n    ...\n\n# or\n\n@bot.listen(hikari.MessageCreateEvent)\nasync def ping(event):\n    ...\n```\n\n### RESTBot\n\nA [`RESTBot`](https://docs.hikari-py.dev/en/stable/reference/hikari/impl/rest_bot/#hikari.impl.rest_bot.RESTBot)\nspawns an interaction server to which Discord will **only** send interaction events,\nwhich can be handled and responded to.\n\nAn example of a simple `RESTBot` could be the following:\n\n```py\nimport asyncio\n\nimport hikari\n\n\n# This function will handle the interactions received\nasync def handle_command(interaction: hikari.CommandInteraction):\n    # Create an initial response to be able to take longer to respond\n    yield interaction.build_deferred_response()\n\n    await asyncio.sleep(5)\n\n    # Edit the initial response\n    await interaction.edit_initial_response(\"Edit after 5 seconds!\")\n\n\n# Register the commands on startup.\n#\n# Note that this is not a nice way to manage this, as it is quite spammy\n# to do it every time the bot is started. You can either use a command handler\n# or only run this code in a script using `RESTApp` or add checks to not update\n# the commands if there were no changes\nasync def create_commands(bot: hikari.RESTBot):\n    application = await bot.rest.fetch_application()\n\n    await bot.rest.set_application_commands(\n        application=application.id,\n        commands=[\n            bot.rest.slash_command_builder(\"test\", \"My first test command!\"),\n        ],\n    )\n\n\nbot = hikari.RESTBot(\n    token=\"...\",\n    token_type=\"...\",\n    public_key=\"...\",\n)\n\nbot.add_startup_callback(create_commands)\nbot.set_listener(hikari.CommandInteraction, handle_command)\n\nbot.run()\n```\n\nUnlike `GatewayBot`, registering listeners is done through `.set_listener`, and it takes in an interaction type\nthat the handler will take in.\n\nNote that a bit of a setup is required to get the above code to work. You will need to host the project to\nthe World Wide Web (scary!) and then register the URL on the [Discord application portal](https://discord.com/developers/applications)\nfor your application under \"Interactions Endpoint URL\".\n\nA quick way you can get your bot onto the internet and reachable by Discord (**for development environment only**) is\nthrough a tool like [ngrok](https://ngrok.com/) or [localhost.run](https://localhost.run/). More information on how to\nuse them can be found in their respective websites.\n\n### Common helpful features\n\nBoth implementations take in helpful arguments such as [customizing timeouts for requests](https://docs.hikari-py.dev/en/stable/reference/hikari/impl/config/#hikari.impl.config.HTTPSettings.timeouts)\nand [enabling a proxy](https://docs.hikari-py.dev/en/stable/reference/hikari/impl/config/#hikari.impl.config.ProxySettings),\nwhich are passed directly into the bot during initialization.\n\nAlso note that you could pass extra options to `bot.run` during development, for example:\n\n```py\nimport hikari\n\nbot = hikari.GatewayBot(\"...\")\n# or\nbot = hikari.RESTBot(\"...\", \"...\")\n\nbot.run(\n    asyncio_debug=True,             # enable asyncio debug to detect blocking and slow code.\n\n    coroutine_tracking_depth=20,    # enable tracking of coroutines, makes some asyncio\n                                    # errors clearer.\n\n    propagate_interrupts=True,      # Any OS interrupts get rethrown as errors.\n)\n```\n\nMany other helpful options exist for you to take advantage of if you wish. Links to the respective docs can be seen\nbelow:\n\n- [GatewayBot.run](https://docs.hikari-py.dev/en/stable/reference/hikari/impl/gateway_bot/#hikari.impl.gateway_bot.GatewayBot.run)\n- [RESTBot.run](https://docs.hikari-py.dev/en/stable/reference/hikari/impl/rest_bot/#hikari.impl.rest_bot.RESTBot.run)\n\n---\n\n## REST-only applications\n\nYou may only want to integrate with the REST API, for example if writing a web dashboard.\n\nThis is relatively simple to do:\n\n```py\nimport hikari\nimport asyncio\n\nrest = hikari.RESTApp()\n\nasync def print_my_user(token):\n    await rest.start()\n  \n    # We acquire a client with a given token. This allows one REST app instance\n    # with one internal connection pool to be reused.\n    async with rest.acquire(token) as client:\n        my_user = await client.fetch_my_user()\n        print(my_user)\n\n    await rest.close()\n        \nasyncio.run(print_my_user(\"user token acquired through OAuth here\"))\n```\n\n---\n\n## Optional Features\n\nOptional features can be specified when installing hikari:\n\n* `server` - Install dependencies required to enable Hikari's standard interaction server (RESTBot) functionality.\n* `speedups` - Detailed in [`hikari[speedups]`](#hikarispeedups).\n\nExample:\n\n```bash\n# To install hikari with the speedups feature:\npython -m pip install -U hikari[speedups]\n\n# To install hikari with both the speedups and server features:\npython -m pip install -U hikari[speedups, server]\n```\n\n## Additional resources\n\nYou may wish to use a command framework on top of hikari so that you can start writing a bot quickly without\nimplementing your own command handler.\n\nHikari does not include a command framework by default, so you will want to pick a third party library to do it:\n\n- [`arc`](https://github.com/hypergonial/hikari-arc) - a bot framework with a focus on type-safety and correctness.\n- [`crescent`](https://github.com/magpie-dev/hikari-crescent) - a command handler for hikari that keeps your project neat and tidy.\n- [`lightbulb`](https://github.com/tandemdude/hikari-lightbulb) - a simple and easy to use command framework for hikari.\n- [`tanjun`](https://github.com/FasterSpeeding/Tanjun) - a flexible command framework designed to extend hikari.\n\nThere are also third party libraries to help you manage components:\n\n- [`miru`](https://github.com/hypergonial/hikari-miru) - A component handler for hikari, inspired by discord.py's views.\n- [`flare`](https://github.com/brazier-dev/hikari-flare/) - a component manager designed to write simple interactions with persistent data.\n\n---\n\n## Making your application more efficient\n\nAs your application scales, you may need to adjust some things to keep it performing nicely.\n\n### Python optimization flags\n\nCPython provides two optimization flags that remove internal safety checks that are useful for development, and change\nother internal settings in the interpreter.\n\n- `python bot.py` - no optimization - this is the default.\n- `python -O bot.py` - first level optimization - features such as internal assertions will be disabled.\n- `python -OO bot.py` - second level optimization - more features (**including all docstrings**) will be removed from\n  the loaded code at runtime.\n\n**A minimum of first level of optimization** is recommended when running bots in a production environment.\n\n### `hikari[speedups]`\n\nIf you have a C compiler (Microsoft VC++ Redistributable 14.0 or newer, or a modern copy of GCC/G++, Clang, etc), it is\nrecommended you install Hikari using `pip install -U hikari[speedups]`. This will install `aiohttp` with its available\nspeedups, `ciso8601` and `orjson` which will provide you with a substantial performance boost.\n\n### `uvloop`\n\n**If you use a UNIX-like system**, you will get additional performance benefits from using a library called `uvloop`.\nThis replaces the default `asyncio` event loop with one that uses `libuv` internally. You can run `pip install uvloop`\nand then amend your script to be something similar to the following example to utilise it in your application:\n\n```py\nimport asyncio\nimport os\n\nif os.name != \"nt\":\n    import uvloop\n    asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())\n\n\n# Your code goes here\n```\n\n### Compiled extensions\n\nEventually, we will start providing the option to use compiled components of this library over pure Python ones if it\nsuits your use case. This should also enable further scalability of your application, should\n[_PEP 554 -- Multiple Interpreters in the Stdlib_](https://www.python.org/dev/peps/pep-0554/#abstract) be accepted.\n\nCurrently, this functionality does not yet exist.\n\n---\n\n## Developing hikari\n\nTo familiarize yourself a bit with the project, we recommend reading our\n[contributing manual](https://github.com/hikari-py/hikari/blob/master/CONTRIBUTING.md).\n\nIf you wish to contribute something, you should first start by cloning the repository.\n\nIn the repository, make a virtual environment (`python -m venv .venv`) and enter it (`source .venv/bin/activate` on\nLinux, or for Windows use one of `.venv\\Scripts\\activate.ps1`, `.venv\\Scripts\\activate.bat`,\n`source .venv/Scripts/activate`).\n\nThe first thing you should run is `pip install --group nox` to install nox.\nThis handles running predefined tasks and pipelines.\n\nOnce this is complete, you can run `nox` without any arguments to ensure everything builds and is correct.\n\n### Where can I start?\n\nCheck out the issues tab on GitHub. If you are nervous, look for issues marked as \"good first issue\" for something\neasy to start with!\n\n[![good-first-issues](https://img.shields.io/github/issues/hikari-py/hikari/good%20first%20issue)](https://github.com/hikari-py/hikari/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)\n\nFeel free to also join our [Discord](https://discord.gg/Jx4cNGG) to directly ask questions to the maintainers! They will\nbe glad to help you out and point you in the right direction.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhikari-py%2Fhikari","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhikari-py%2Fhikari","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhikari-py%2Fhikari/lists"}