# hikari-crescent
<div align="center">
[](https://github.com/hikari-crescent/hikari-crescent/actions/workflows/ci.yml)
[](https://github.com/charliermarsh/ruff)
</div>
<a href="https://github.com/hikari-crescent/crescent-chan">
<img src="https://raw.githubusercontent.com/hikari-crescent/crescent-chan/main/1x.png" align=right width="264" height="397">
</a>
🌙 A command handler for [Hikari](https://github.com/hikari-py/hikari) that keeps your project neat and tidy.
## Features
- Simple and intuitive API.
- Slash, user, and message commands.
- Command localization.
- Error handling for commands, events, and autocomplete.
- Hooks to run function before or after a command (or any command from a group!)
- Plugin system to easily split bot into different modules.
- Easily use a custom context class.
- Makes typehinting easy.
- RESTBot and GatewayBot support.
### Links
> 📦 | [Pypi](https://pypi.org/project/hikari-crescent/)<br>
> 🗃️ | [Docs](https://hikari-crescent.github.io/hikari-crescent/)<br>
> 🎨 | [Template Project](https://github.com/hikari-crescent/template)<br>
## Installation
Crescent is supported in python3.8+.
```
pip install hikari-crescent
```
## Bots using Crescent
- [mCodingBot](https://github.com/mcb-dev/mCodingBot) - The bot for the mCoding Discord server.
- [Starboard 3](https://github.com/circuitsacul/starboard-3) - A starbord bot by [@CircuitSacul](https://github.com/CircuitSacul)
in over 17k servers.
## Usage
Crescent uses [class commands](https://github.com/hikari-crescent/hikari-crescent/blob/main/examples/basic/basic.py)
to simplify creating commands. Class commands allow you to create a command similar to how you declare a
dataclass. The option function takes a type followed by the description, then optional information.
```python
import crescent
import hikari
bot = hikari.GatewayBot("YOUR_TOKEN")
client = crescent.Client(bot)
# Include the command in your client - don't forget this
@client.include
# Create a slash command
@crescent.command(name="say")
class Say:
word = crescent.option(str, "The word to say")
async def callback(self, ctx: crescent.Context) -> None:
await ctx.respond(self.word)
bot.run()
```
Simple commands can use functions instead of classes. It is recommended to use a function when your
command does not have any options.
```python
@client.include
@crescent.command
async def ping(ctx: crescent.Context):
await ctx.respond("Pong!")
```
Adding arguments to the function adds more options. Information for arguments can be provided using the `Annotated` type hint.
See [this example](https://github.com/hikari-crescent/hikari-crescent/blob/main/examples/basic/function_commands.py) for more information.
```python
# python 3.9 +
from typing import Annotated as Atd
# python 3.8
from typing_extensions import Annotated as Atd
@client.include
@crescent.command
async def say(ctx: crescent.Context, word: str):
await ctx.respond(word)
# The same command but with a description for `word`
@client.include
@crescent.command
async def say(ctx: crescent.Context, word: Atd[str, "The word to say"]) -> None:
await ctx.respond(word)
```
### Typing to Option Types Lookup Table
| Type | Option Type |
|---|---|
| `str` | Text |
| `int` | Integer |
| `bool` | Boolean |
| `float` | Number |
| `hikari.User` | User |
| `hikari.Role` | Role |
| `crescent.Mentionable` | Role or User |
| Any Hikari channel type. | Channel. The options will be the channel type and its subclasses. |
| `List[Channel Types]` (classes only) | Channel. ^ |
| `Union[Channel Types]` (functions only) | Channel. ^ |
| `hikari.Attachment` | Attachment |
### Autocomplete
Autocomplete is supported by using a callback function. This function returns a list of tuples where the first
value is the option name and the second value is the option value. `str`, `int`, and `float` value types
can be used.
```python
async def autocomplete(
ctx: crescent.AutocompleteContext, option: hikari.AutocompleteInteractionOption
) -> list[tuple[str, str]]:
return [("Option 1", "Option value 1"), ("Option 2", "Option value 2")]
@client.include
@crescent.command(name="class-command")
class ClassCommand:
option = crescent.option(str, autocomplete=autocomplete)
async def callback(self) -> None:
await ctx.respond(self.option)
@client.include
@crescent.command
async def function_command(
ctx: crescent.Context,
option: Annotated[str, crescent.Autocomplete(autocomplete)]
) -> None:
await ctx.respond(option)
```
### Error Handling
Errors that are raised by a command can be handled by `crescent.catch_command`.
```python
class MyError(Exception):
...
@client.include
@crescent.catch_command(MyError)
async def on_err(exc: MyError, ctx: crescent.Context) -> None:
await ctx.respond("An error occurred while running the command.")
@client.include
@crescent.command
async def my_command(ctx: crescent.Context):
raise MyError()
```
There is also a `crescent.catch_event` and `crescent.catch_autocomplete` function for
events and autocomplete respectively.
### Events
```python
import hikari
@client.include
@crescent.event
async def on_message_create(event: hikari.MessageCreateEvent):
if event.message.author.is_bot:
return
await event.message.respond("Hello!")
```
Using crescent's event decorator lets you use
crescent's [event error handling system](https://github.com/hikari-crescent/hikari-crescent/blob/main/examples/error_handling/basic.py#L27).
# Extensions
Crescent has 3 builtin extensions.
- [crescent-ext-cooldowns](https://github.com/hikari-crescent/hikari-crescent/tree/main/examples/ext/cooldowns) - Allows you to add sliding window rate limits to your commands.
- [crescent-ext-locales](https://github.com/hikari-crescent/hikari-crescent/tree/main/examples/ext/locales) - Contains classes that cover common use cases for localization.
- [crescent-ext-tasks](https://github.com/hikari-crescent/hikari-crescent/tree/main/examples/ext/tasks) - Schedules background tasks using loops or cronjobs.
These extensions can be installed with pip.
- [crescent-ext-docstrings](https://github.com/hikari-crescent/crescent-ext-docstrings) - Lets you use docstrings to write descriptions for commands and options.
- [crescent-ext-kebabify](https://github.com/hikari-crescent/crescent-ext-kebabify) - Turns your command names into kebabs!
# Support
You can ask questions in the `#crescent` channel in the [Hikari Discord server](https://discord.gg/Jx4cNGG). My Discord username is `lunarmagpie`.
# Contributing
Create an issue for your feature. There aren't any guidelines right now so just don't be rude.
Raw data
{
"_id": null,
"home_page": "https://github.com/hikari-crescent/hikari-crescent",
"name": "hikari-crescent",
"maintainer": "Lunarmagpie",
"docs_url": null,
"requires_python": ">=3.8,<3.13",
"maintainer_email": "bambolambo0@gmail.com",
"keywords": "discord,hikari,command handler,slash commands,application commands",
"author": "Lunarmagpie",
"author_email": "bambolambo0@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8f/55/0c46d3f66cdfa90a0c95ea312b4efaae4603ba1565bddd852eecb4f000aa/hikari_crescent-0.6.6.tar.gz",
"platform": null,
"description": "# hikari-crescent\n\n<div align=\"center\">\n\n\n[](https://github.com/hikari-crescent/hikari-crescent/actions/workflows/ci.yml)\n\n\n[](https://github.com/charliermarsh/ruff)\n\n\n</div>\n\n<a href=\"https://github.com/hikari-crescent/crescent-chan\">\n <img src=\"https://raw.githubusercontent.com/hikari-crescent/crescent-chan/main/1x.png\" align=right width=\"264\" height=\"397\">\n</a>\n\n\ud83c\udf19 A command handler for [Hikari](https://github.com/hikari-py/hikari) that keeps your project neat and tidy.\n\n## Features\n - Simple and intuitive API.\n - Slash, user, and message commands.\n - Command localization.\n - Error handling for commands, events, and autocomplete.\n - Hooks to run function before or after a command (or any command from a group!)\n - Plugin system to easily split bot into different modules.\n - Easily use a custom context class.\n - Makes typehinting easy.\n - RESTBot and GatewayBot support.\n\n### Links\n> \ud83d\udce6 | [Pypi](https://pypi.org/project/hikari-crescent/)<br>\n> \ud83d\uddc3\ufe0f | [Docs](https://hikari-crescent.github.io/hikari-crescent/)<br>\n> \ud83c\udfa8 | [Template Project](https://github.com/hikari-crescent/template)<br>\n\n## Installation\nCrescent is supported in python3.8+.\n```\npip install hikari-crescent\n```\n\n## Bots using Crescent\n\n- [mCodingBot](https://github.com/mcb-dev/mCodingBot) - The bot for the mCoding Discord server.\n- [Starboard 3](https://github.com/circuitsacul/starboard-3) - A starbord bot by [@CircuitSacul](https://github.com/CircuitSacul)\nin over 17k servers.\n\n\n## Usage\nCrescent uses [class commands](https://github.com/hikari-crescent/hikari-crescent/blob/main/examples/basic/basic.py)\nto simplify creating commands. Class commands allow you to create a command similar to how you declare a\ndataclass. The option function takes a type followed by the description, then optional information.\n\n```python\nimport crescent\nimport hikari\n\nbot = hikari.GatewayBot(\"YOUR_TOKEN\")\nclient = crescent.Client(bot)\n\n# Include the command in your client - don't forget this\n@client.include\n# Create a slash command\n@crescent.command(name=\"say\")\nclass Say:\n word = crescent.option(str, \"The word to say\")\n\n async def callback(self, ctx: crescent.Context) -> None:\n await ctx.respond(self.word)\n\nbot.run()\n```\n\nSimple commands can use functions instead of classes. It is recommended to use a function when your\ncommand does not have any options.\n\n```python\n@client.include\n@crescent.command\nasync def ping(ctx: crescent.Context):\n await ctx.respond(\"Pong!\")\n```\n\nAdding arguments to the function adds more options. Information for arguments can be provided using the `Annotated` type hint.\nSee [this example](https://github.com/hikari-crescent/hikari-crescent/blob/main/examples/basic/function_commands.py) for more information.\n\n```python\n# python 3.9 +\nfrom typing import Annotated as Atd\n\n# python 3.8\nfrom typing_extensions import Annotated as Atd\n\n@client.include\n@crescent.command\nasync def say(ctx: crescent.Context, word: str):\n await ctx.respond(word)\n\n# The same command but with a description for `word`\n@client.include\n@crescent.command\nasync def say(ctx: crescent.Context, word: Atd[str, \"The word to say\"]) -> None:\n await ctx.respond(word)\n```\n\n\n### Typing to Option Types Lookup Table \n| Type | Option Type |\n|---|---|\n| `str` | Text |\n| `int` | Integer |\n| `bool` | Boolean |\n| `float` | Number |\n| `hikari.User` | User |\n| `hikari.Role` | Role |\n| `crescent.Mentionable` | Role or User |\n| Any Hikari channel type. | Channel. The options will be the channel type and its subclasses. |\n| `List[Channel Types]` (classes only) | Channel. ^ |\n| `Union[Channel Types]` (functions only) | Channel. ^ |\n| `hikari.Attachment` | Attachment |\n\n\n### Autocomplete\nAutocomplete is supported by using a callback function. This function returns a list of tuples where the first\nvalue is the option name and the second value is the option value. `str`, `int`, and `float` value types\ncan be used.\n\n```python\nasync def autocomplete(\n ctx: crescent.AutocompleteContext, option: hikari.AutocompleteInteractionOption\n) -> list[tuple[str, str]]:\n return [(\"Option 1\", \"Option value 1\"), (\"Option 2\", \"Option value 2\")]\n\n@client.include\n@crescent.command(name=\"class-command\")\nclass ClassCommand:\n option = crescent.option(str, autocomplete=autocomplete)\n\n async def callback(self) -> None:\n await ctx.respond(self.option)\n\n@client.include\n@crescent.command\nasync def function_command(\n ctx: crescent.Context,\n option: Annotated[str, crescent.Autocomplete(autocomplete)]\n) -> None:\n await ctx.respond(option)\n```\n\n### Error Handling\nErrors that are raised by a command can be handled by `crescent.catch_command`.\n\n```python\nclass MyError(Exception):\n ...\n\n@client.include\n@crescent.catch_command(MyError)\nasync def on_err(exc: MyError, ctx: crescent.Context) -> None:\n await ctx.respond(\"An error occurred while running the command.\")\n\n@client.include\n@crescent.command\nasync def my_command(ctx: crescent.Context):\n raise MyError()\n```\n\nThere is also a `crescent.catch_event` and `crescent.catch_autocomplete` function for\nevents and autocomplete respectively.\n\n### Events\n```python\nimport hikari\n\n@client.include\n@crescent.event\nasync def on_message_create(event: hikari.MessageCreateEvent):\n if event.message.author.is_bot:\n return\n await event.message.respond(\"Hello!\")\n```\nUsing crescent's event decorator lets you use\ncrescent's [event error handling system](https://github.com/hikari-crescent/hikari-crescent/blob/main/examples/error_handling/basic.py#L27).\n\n# Extensions\nCrescent has 3 builtin extensions.\n\n- [crescent-ext-cooldowns](https://github.com/hikari-crescent/hikari-crescent/tree/main/examples/ext/cooldowns) - Allows you to add sliding window rate limits to your commands.\n- [crescent-ext-locales](https://github.com/hikari-crescent/hikari-crescent/tree/main/examples/ext/locales) - Contains classes that cover common use cases for localization.\n- [crescent-ext-tasks](https://github.com/hikari-crescent/hikari-crescent/tree/main/examples/ext/tasks) - Schedules background tasks using loops or cronjobs.\n\nThese extensions can be installed with pip.\n\n- [crescent-ext-docstrings](https://github.com/hikari-crescent/crescent-ext-docstrings) - Lets you use docstrings to write descriptions for commands and options.\n- [crescent-ext-kebabify](https://github.com/hikari-crescent/crescent-ext-kebabify) - Turns your command names into kebabs!\n\n# Support\nYou can ask questions in the `#crescent` channel in the [Hikari Discord server](https://discord.gg/Jx4cNGG). My Discord username is `lunarmagpie`.\n\n# Contributing\nCreate an issue for your feature. There aren't any guidelines right now so just don't be rude.\n",
"bugtrack_url": null,
"license": "MPL-2.0",
"summary": "\ud83c\udf19 A command handler for Hikari that keeps your project neat and tidy.",
"version": "0.6.6",
"project_urls": {
"Documentation": "https://hikari-crescent.github.io/hikari-crescent/crescent.html",
"Homepage": "https://github.com/hikari-crescent/hikari-crescent",
"Repository": "https://github.com/hikari-crescent/hikari-crescent"
},
"split_keywords": [
"discord",
"hikari",
"command handler",
"slash commands",
"application commands"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9c04f9fefc8b0070247445b1b91a93a0f0b0ab1985fcd4774f3396cfe0fdf6c4",
"md5": "ddb4467db02dde9672041ad35e776ca3",
"sha256": "cbb3a976f8b958cddf66ab1cdc1a09027f767444fce0acdb8989b4f7bf36ea9d"
},
"downloads": -1,
"filename": "hikari_crescent-0.6.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ddb4467db02dde9672041ad35e776ca3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.13",
"size": 56764,
"upload_time": "2024-01-11T18:18:14",
"upload_time_iso_8601": "2024-01-11T18:18:14.849351Z",
"url": "https://files.pythonhosted.org/packages/9c/04/f9fefc8b0070247445b1b91a93a0f0b0ab1985fcd4774f3396cfe0fdf6c4/hikari_crescent-0.6.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f550c46d3f66cdfa90a0c95ea312b4efaae4603ba1565bddd852eecb4f000aa",
"md5": "b92da4bd4b4cbe8752ce76eace135328",
"sha256": "479e5307d4c59c1a85b96d93a28e1efdd48c974d9e27cce1d3b4cfcbd848b832"
},
"downloads": -1,
"filename": "hikari_crescent-0.6.6.tar.gz",
"has_sig": false,
"md5_digest": "b92da4bd4b4cbe8752ce76eace135328",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.13",
"size": 44023,
"upload_time": "2024-01-11T18:18:16",
"upload_time_iso_8601": "2024-01-11T18:18:16.775411Z",
"url": "https://files.pythonhosted.org/packages/8f/55/0c46d3f66cdfa90a0c95ea312b4efaae4603ba1565bddd852eecb4f000aa/hikari_crescent-0.6.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-11 18:18:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hikari-crescent",
"github_project": "hikari-crescent",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hikari-crescent"
}
JSON
