# telegram-click-aio [](https://github.com/markusressel/telegram-click-aio/graphs/contributors) [](/LICENSE) [](https://codeclimate.com/github/markusressel/telegram-click-aio)  [](https://pypi.org/project/telegram-click-aio/)
[Click](https://github.com/pallets/click/)
inspired command-line interface creation toolkit for
[aiogram](https://github.com/aiogram/aiogram), optimized for asyncio.
Note that this library can **only** be used with asyncio. If you are looking for a non-asyncio and [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) compatible variant have a look at [telegram-click](https://github.com/markusressel/telegram-click)!
<p align="center">
<img src="https://raw.githubusercontent.com/markusressel/telegram-click/master/screenshots/demo1.png" width="400"> <img src="https://raw.githubusercontent.com/markusressel/telegram-click/master/screenshots/demo2.png" width="400">
</p>
# Features
* [x] POSIX style argument parsing
* [x] Quoted arguments (`/command "Hello World"`)
* [x] Named arguments (`/command --text "Hello World"`)
* [x] Value Separator (`/command --text=myvalue` )
* [x] Flags (`/command --yes`)
* [x] Multiple combined Flags (`/command -Syu`)
* [x] Optional arguments
* [x] Type conversion including support for custom types
* [x] Argument input validation
* [x] Automatic help messages
* [x] Show help messages when a command was used with invalid arguments
* [x] List all available commands with a single method
* [x] Permission handling
* [x] Set up permissions for each command separately
* [x] Limit command execution to private chats or group admins
* [x] Combine permissions using logical operators
* [x] Create custom permission handlers
* [x] Error handling
* [x] Automatically send error and help messages if something goes wrong
* [x] Write custom error handlers
# How to use
Install this library as a dependency to use it in your project.
```shell
pip install telegram-click-aio
```
Then annotate your command handler functions with the `@command` decorator
of this library:
```python
from aiogram import Bot
from aiogram.types import Message
from telegram_click_aio.decorator import command
from telegram_click_aio.argument import Argument
class MyBot:
[...]
@command(name='start', description='Start bot interaction')
async def _start_command_callback(self, message: Message):
# do something
pass
@command(name='age',
description='Set age',
arguments=[
Argument(name='age',
description='The new age',
type=int,
validator=lambda x: x > 0,
example='25')
])
async def _age_command_callback(self, bot: Bot, message: Message, age: int):
await bot.send_message(message.chat.id, "New age: {}".format(age))
```
## Arguments
**telegram-click-aio** parses arguments using a custom tokenizer:
* space acts as an argument delimiter, except when quoted (supporting both `"` and `'`)
* argument keys are prefixed with `--`, `—` (long dash) or `-` (for single character keys)
* quoted arguments are never considered as argument keys, even when prefixed with `--` or `—`
* flags can be combined in a single argument (f.ex. `-AxZ`)
The behaviour should be pretty intuitive. If it's not, let's discuss and improve it!
### Naming
Arguments can have multiple names to allow for abbreviated names. The
first name you specify for an argument will be used for the
callback parameter name (normalized to snake-case). Because of this
it is advisable to specify a full word argument name as the first one.
### Types
Since all user input initially is of type `str` there needs to be a type
conversion if the expected type is not a `str`. For basic types like
`bool`, `int`, `float` and `str` converters are built in to this library.
If you want to use other types you have to specify how to convert the
`str` input to your type using the `converter` attribute of the
`Argument` constructor:
```python
from telegram_click_aio.argument import Argument
Argument(name='age',
description='The new age',
type=MyType,
converter=lambda x: MyType(x),
validator=lambda x: x > 0,
example='25')
```
### Flags
Technically you can use the `Argument` class to specify a flag, but since
many of its parameters are implicit for a flag the `Flag` class can be used
instead:
```python
from telegram_click_aio.argument import Flag
Flag(name='flag',
description='My boolean flag')
```
## Permission handling
If a command should only be executable when a specific criteria is met
you can specify those criteria using the `permissions` parameter:
```python
from aiogram.types import Message
from telegram_click_aio.decorator import command
from telegram_click_aio.permission import GROUP_ADMIN
@command(name='permission',
description='Needs permission',
permissions=GROUP_ADMIN)
async def _permission_command_callback(self, message: Message):
```
Multiple permissions can be combined using `&`, `|` and `~` (not) operators.
If a user does not have permission to use a command it will not be displayed
when this user generate a list of commands.
### Integrated permission handlers
| Name | Description |
|-----------------------|--------------------------------------------|
| `PRIVATE_CHAT` | The command can only be executed in a private chat |
| `NORMAL_GROUP_CHAT` | The command can only be executed in a normal group |
| `SUPER_GROUP_CHAT` | The command can only be executed in a supergroup |
| `GROUP_CHAT` | The command can only be executed in either a normal or a supergroup |
| `USER_ID` | Only users whose user id is specified have permission |
| `USER_NAME` | Only users whose username is specified have permission |
| `GROUP_CREATOR` | Only the group creator has permission |
| `GROUP_ADMIN` | Only the group admin has permission |
| `NOBODY` | Nobody has permission (useful for callbacks triggered via code instead of user interaction f.ex. "unknown command" handler) |
| `ANYBODY` | Anybody has permission (this is the default) |
### Custom permissions
If none of the integrated permissions suit your needs you can simply write
your own permission handler by extending the `Permission` base class
and pass an instance of the `MyPermission` class to the list of `permissions`:
```python
from aiogram.types import Message
from telegram_click_aio.decorator import command
from telegram_click_aio.permission.base import Permission
from telegram_click_aio.permission import GROUP_ADMIN
class MyPermission(Permission):
async def evaluate(self, message: Message) -> bool:
from_user = message.from_user
return from_user.id in [12345, 32435]
@command(name='permission', description='Needs permission',
permissions=MyPermission() & GROUP_ADMIN)
async def _permission_command_callback(self, message: Message):
```
### Show "Permission denied" message
This behaviour is defined by the error handler. The `DefaultErrorHandler` silently ignores
command messages from users without permission. To change this simply define your own,
customized `ErrorHandler` class as shown in the [example.py](example.py).
## Targeted commands
Telegram supports the `@` notation to target commands at specific bot
usernames:
```
/start # unspecified
/start@myAwesomeBot # targeted at self
/start@someOtherBot # targeted at other bot
```
When using a `MessageHandler` instead of a `CommandHandler`
it is possible to catch even commands that are targeted at other bots.
By default only messages without a target, and messages that are targeted
directly at your bot are processed.
To control this behaviour specify the `command_target` parameter:
```python
from aiogram.types import Message
from telegram_click_aio.decorator import command
from telegram_click_aio import CommandTarget
from telegram_click_aio.permission import NOBODY
@command(name="commands",
description="List commands supported by this bot.",
permissions=NOBODY,
command_target=CommandTarget.UNSPECIFIED | CommandTarget.SELF)
async def _unknown_command_callback(self, message: Message):
```
You can combine `CommandTarget`'s using logical operators like in the
example above.
## Hidden commands
In rare cases it can be useful to hide a command from the help output.
To do this you can use the `hidden` parameter on the `@command` decorator
by either passing `True` or `False`, or a callable like f.ex. this one:
```python
async def hide_whois_if_admin(message: Message):
user_id = message.from_user.id
return user_id not in [123456]
```
This function is evaluated on each message and therefore provides
the `message` object from **aiogram**, which
allows you to make decisions based on chat and user properties
among other things.
## Error handling
**telegram-click-aio** automatically handles errors in most situations.
Errors are divided into three categories:
* Permission errors
* Input validation errors
* Command execution errors
The `DefaultErrorHandler` will handle these categories in the following way:
* Permission errors will be silently ignored.
* Input validation errors like
* an argument can not be parsed correctly
* an invalid value is passed for an argument
will send the exception message, as well as a help message of the command the user was trying to use.
* On command execution errors the user will be notified that his
command has crashed, without any specific error message.
To modify the behaviour for each of those categories, define an `ErrorHandler` and
pass an instance of it to the `error_handler` parameter of the `@command` decorator,
like shown in the [example.py](example.py).
# Contributing
GitHub is for social coding: if you want to write code, I encourage contributions through pull requests from forks
of this repository. Create GitHub tickets for bugs and new features and comment on the ones that you are interested in.
# License
```text
telegram-click-aio
Copyright (c) 2020 Markus Ressel
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
Raw data
{
"_id": null,
"home_page": "https://github.com/markusressel/telegram-click-aio",
"name": "telegram-click-aio",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Markus Ressel",
"author_email": "mail@markusressel.de",
"download_url": "https://files.pythonhosted.org/packages/95/6c/feb1166f0987963da55a83679d7f03b23fab2e9f99fe82ab80012d48eb2b/telegram_click_aio-2.0.0.tar.gz",
"platform": null,
"description": "# telegram-click-aio [](https://github.com/markusressel/telegram-click-aio/graphs/contributors) [](/LICENSE) [](https://codeclimate.com/github/markusressel/telegram-click-aio)  [](https://pypi.org/project/telegram-click-aio/)\n\n[Click](https://github.com/pallets/click/) \ninspired command-line interface creation toolkit for \n[aiogram](https://github.com/aiogram/aiogram), optimized for asyncio.\n\nNote that this library can **only** be used with asyncio. If you are looking for a non-asyncio and [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) compatible variant have a look at [telegram-click](https://github.com/markusressel/telegram-click)!\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/markusressel/telegram-click/master/screenshots/demo1.png\" width=\"400\"> <img src=\"https://raw.githubusercontent.com/markusressel/telegram-click/master/screenshots/demo2.png\" width=\"400\"> \n</p>\n\n# Features\n* [x] POSIX style argument parsing\n * [x] Quoted arguments (`/command \"Hello World\"`)\n * [x] Named arguments (`/command --text \"Hello World\"`)\n * [x] Value Separator (`/command --text=myvalue` )\n * [x] Flags (`/command --yes`)\n * [x] Multiple combined Flags (`/command -Syu`)\n * [x] Optional arguments\n * [x] Type conversion including support for custom types\n * [x] Argument input validation\n* [x] Automatic help messages\n * [x] Show help messages when a command was used with invalid arguments\n * [x] List all available commands with a single method\n* [x] Permission handling\n * [x] Set up permissions for each command separately\n * [x] Limit command execution to private chats or group admins\n * [x] Combine permissions using logical operators\n * [x] Create custom permission handlers\n* [x] Error handling\n * [x] Automatically send error and help messages if something goes wrong\n * [x] Write custom error handlers\n \n# How to use\n\nInstall this library as a dependency to use it in your project.\n\n```shell\npip install telegram-click-aio\n```\n\nThen annotate your command handler functions with the `@command` decorator\nof this library:\n\n```python\nfrom aiogram import Bot\nfrom aiogram.types import Message\nfrom telegram_click_aio.decorator import command\nfrom telegram_click_aio.argument import Argument\n\nclass MyBot:\n\n [...]\n \n @command(name='start', description='Start bot interaction')\n async def _start_command_callback(self, message: Message):\n # do something\n pass\n \n @command(name='age', \n description='Set age',\n arguments=[\n Argument(name='age',\n description='The new age',\n type=int,\n validator=lambda x: x > 0,\n example='25')\n ])\n async def _age_command_callback(self, bot: Bot, message: Message, age: int):\n await bot.send_message(message.chat.id, \"New age: {}\".format(age))\n```\n\n## Arguments\n\n**telegram-click-aio** parses arguments using a custom tokenizer:\n* space acts as an argument delimiter, except when quoted (supporting both `\"` and `'`)\n* argument keys are prefixed with `--`, `\u2014` (long dash) or `-` (for single character keys)\n* quoted arguments are never considered as argument keys, even when prefixed with `--` or `\u2014`\n* flags can be combined in a single argument (f.ex. `-AxZ`)\n\nThe behaviour should be pretty intuitive. If it's not, let's discuss and improve it!\n\n### Naming\n\nArguments can have multiple names to allow for abbreviated names. The\nfirst name you specify for an argument will be used for the \ncallback parameter name (normalized to snake-case). Because of this\nit is advisable to specify a full word argument name as the first one.\n\n### Types\n\nSince all user input initially is of type `str` there needs to be a type\nconversion if the expected type is not a `str`. For basic types like\n`bool`, `int`, `float` and `str` converters are built in to this library.\nIf you want to use other types you have to specify how to convert the \n`str` input to your type using the `converter` attribute of the \n`Argument` constructor:\n\n```python\nfrom telegram_click_aio.argument import Argument\n\nArgument(name='age',\n description='The new age',\n type=MyType,\n converter=lambda x: MyType(x),\n validator=lambda x: x > 0,\n example='25')\n```\n\n### Flags\n\nTechnically you can use the `Argument` class to specify a flag, but since \nmany of its parameters are implicit for a flag the `Flag` class can be used\ninstead:\n\n```python\nfrom telegram_click_aio.argument import Flag\n\nFlag(name='flag',\n description='My boolean flag')\n```\n\n## Permission handling\n\nIf a command should only be executable when a specific criteria is met \nyou can specify those criteria using the `permissions` parameter:\n\n```python\nfrom aiogram.types import Message\nfrom telegram_click_aio.decorator import command\nfrom telegram_click_aio.permission import GROUP_ADMIN\n\n@command(name='permission', \n description='Needs permission',\n permissions=GROUP_ADMIN)\nasync def _permission_command_callback(self, message: Message):\n```\n\nMultiple permissions can be combined using `&`, `|` and `~` (not) operators.\n\nIf a user does not have permission to use a command it will not be displayed\nwhen this user generate a list of commands.\n\n### Integrated permission handlers\n\n| Name | Description |\n|-----------------------|--------------------------------------------|\n| `PRIVATE_CHAT` | The command can only be executed in a private chat |\n| `NORMAL_GROUP_CHAT` | The command can only be executed in a normal group |\n| `SUPER_GROUP_CHAT` | The command can only be executed in a supergroup |\n| `GROUP_CHAT` | The command can only be executed in either a normal or a supergroup |\n| `USER_ID` | Only users whose user id is specified have permission |\n| `USER_NAME` | Only users whose username is specified have permission |\n| `GROUP_CREATOR` | Only the group creator has permission |\n| `GROUP_ADMIN` | Only the group admin has permission |\n| `NOBODY` | Nobody has permission (useful for callbacks triggered via code instead of user interaction f.ex. \"unknown command\" handler) |\n| `ANYBODY` | Anybody has permission (this is the default) |\n\n### Custom permissions\n\nIf none of the integrated permissions suit your needs you can simply write \nyour own permission handler by extending the `Permission` base class \nand pass an instance of the `MyPermission` class to the list of `permissions`:\n\n```python\nfrom aiogram.types import Message\nfrom telegram_click_aio.decorator import command\nfrom telegram_click_aio.permission.base import Permission\nfrom telegram_click_aio.permission import GROUP_ADMIN\n\nclass MyPermission(Permission):\n async def evaluate(self, message: Message) -> bool:\n from_user = message.from_user\n return from_user.id in [12345, 32435]\n \n@command(name='permission', description='Needs permission',\n permissions=MyPermission() & GROUP_ADMIN)\nasync def _permission_command_callback(self, message: Message):\n```\n\n### Show \"Permission denied\" message\n\nThis behaviour is defined by the error handler. The `DefaultErrorHandler` silently ignores \ncommand messages from users without permission. To change this simply define your own, \ncustomized `ErrorHandler` class as shown in the [example.py](example.py).\n\n## Targeted commands\n\nTelegram supports the `@` notation to target commands at specific bot\nusernames:\n\n```\n/start # unspecified\n/start@myAwesomeBot # targeted at self\n/start@someOtherBot # targeted at other bot\n```\n\nWhen using a `MessageHandler` instead of a `CommandHandler`\nit is possible to catch even commands that are targeted at other bots.\nBy default only messages without a target, and messages that are targeted \ndirectly at your bot are processed.\n\nTo control this behaviour specify the `command_target` parameter:\n\n```python\nfrom aiogram.types import Message\nfrom telegram_click_aio.decorator import command\nfrom telegram_click_aio import CommandTarget\nfrom telegram_click_aio.permission import NOBODY\n\n@command(name=\"commands\",\n description=\"List commands supported by this bot.\",\n permissions=NOBODY,\n command_target=CommandTarget.UNSPECIFIED | CommandTarget.SELF)\nasync def _unknown_command_callback(self, message: Message):\n```\n\nYou can combine `CommandTarget`'s using logical operators like in the \nexample above.\n\n## Hidden commands\n\nIn rare cases it can be useful to hide a command from the help output.\nTo do this you can use the `hidden` parameter on the `@command` decorator\nby either passing `True` or `False`, or a callable like f.ex. this one:\n```python\nasync def hide_whois_if_admin(message: Message):\n user_id = message.from_user.id\n return user_id not in [123456]\n```\n\nThis function is evaluated on each message and therefore provides\nthe `message` object from **aiogram**, which\nallows you to make decisions based on chat and user properties\namong other things.\n\n## Error handling\n\n**telegram-click-aio** automatically handles errors in most situations.\n\nErrors are divided into three categories:\n* Permission errors\n* Input validation errors\n* Command execution errors\n\nThe `DefaultErrorHandler` will handle these categories in the following way:\n\n* Permission errors will be silently ignored.\n* Input validation errors like\n * an argument can not be parsed correctly\n * an invalid value is passed for an argument\n \n will send the exception message, as well as a help message of the command the user was trying to use.\n* On command execution errors the user will be notified that his \n command has crashed, without any specific error message. \n\nTo modify the behaviour for each of those categories, define an `ErrorHandler` and \npass an instance of it to the `error_handler` parameter of the `@command` decorator,\nlike shown in the [example.py](example.py).\n\n# Contributing\n\nGitHub is for social coding: if you want to write code, I encourage contributions through pull requests from forks\nof this repository. Create GitHub tickets for bugs and new features and comment on the ones that you are interested in.\n\n\n# License\n```text\ntelegram-click-aio\nCopyright (c) 2020 Markus Ressel\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Click inspired command interface toolkit for aiogram",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/markusressel/telegram-click-aio"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a6c40f19e41269afb81d59380d8ccd27246c639d803f1d48bb9326ab68eac89e",
"md5": "9a867aea5904510720fc47e263e373ff",
"sha256": "d45e50212570f1f74f0206353567851bcf6eefc5125a963a1bce85599ef7ae25"
},
"downloads": -1,
"filename": "telegram_click_aio-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a867aea5904510720fc47e263e373ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 28091,
"upload_time": "2023-09-02T15:25:43",
"upload_time_iso_8601": "2023-09-02T15:25:43.513525Z",
"url": "https://files.pythonhosted.org/packages/a6/c4/0f19e41269afb81d59380d8ccd27246c639d803f1d48bb9326ab68eac89e/telegram_click_aio-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "956cfeb1166f0987963da55a83679d7f03b23fab2e9f99fe82ab80012d48eb2b",
"md5": "211a85a1043fa17d02ea2d92964aca7d",
"sha256": "a2fd204695aceeb05911dea4325082421fa539d165acd0df7bf57e226eb213a5"
},
"downloads": -1,
"filename": "telegram_click_aio-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "211a85a1043fa17d02ea2d92964aca7d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20718,
"upload_time": "2023-09-02T15:25:45",
"upload_time_iso_8601": "2023-09-02T15:25:45.096648Z",
"url": "https://files.pythonhosted.org/packages/95/6c/feb1166f0987963da55a83679d7f03b23fab2e9f99fe82ab80012d48eb2b/telegram_click_aio-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-02 15:25:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "markusressel",
"github_project": "telegram-click-aio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "telegram-click-aio"
}
JSON
