{"id":18365497,"url":"https://github.com/altvod/aiokilogram","last_synced_at":"2025-04-06T16:31:28.625Z","repository":{"id":51136801,"uuid":"429587784","full_name":"altvod/aiokilogram","owner":"altvod","description":"Convenience tools and wrappers for aiogram","archived":false,"fork":false,"pushed_at":"2023-02-01T23:03:15.000Z","size":37,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-22T03:31:37.476Z","etag":null,"topics":["aiogram","python","telegram","telegram-bot"],"latest_commit_sha":null,"homepage":"","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/altvod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-18T21:41:20.000Z","updated_at":"2023-12-05T21:59:01.000Z","dependencies_parsed_at":"2023-02-17T11:55:26.705Z","dependency_job_id":null,"html_url":"https://github.com/altvod/aiokilogram","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altvod%2Faiokilogram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altvod%2Faiokilogram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altvod%2Faiokilogram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altvod%2Faiokilogram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/altvod","download_url":"https://codeload.github.com/altvod/aiokilogram/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247512653,"owners_count":20950896,"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":["aiogram","python","telegram","telegram-bot"],"created_at":"2024-11-05T23:13:49.035Z","updated_at":"2025-04-06T16:31:28.364Z","avatar_url":"https://github.com/altvod.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aiokilogram\n\nConvenience tools and wrappers for `aiogram`,\nthe asynchronous Telegram Bot API framework.\n\n\n## Installation\n\n```bash\npip install aiokilogram\n```\n\n\n## Basic Examples\n\n### Class-Based Command Handlers\n\nThe `aiokilogram` toolkit is centered around the notion of class-based\ncommand handlers. Basically this means that you can group several commands\nas methods in a class and assign them to message and callback patterns\nat class level.\n\nA simplistic bit will look something like this:\n\n```python\nimport asyncio\nimport os\nfrom aiokilogram.bot import KiloBot\nfrom aiokilogram.settings import BaseGlobalSettings\nfrom aiokilogram.handler import CommandHandler\nfrom aiokilogram.registration import register_message_handler\n\nclass TestCommandHandler(CommandHandler):\n    @register_message_handler(commands={'hello'})\n    async def test_handler(self, event) -\u003e None:\n        await self.send_text(user_id=event.from_user.id, text=f'This is a test reply')\n\ndef run_bot():\n    bot = KiloBot(\n        global_settings=BaseGlobalSettings(tg_bot_token=os.environ['TG_BOT_TOKEN']),\n        handler_classes=[TestCommandHandler],\n    )\n    asyncio.run(bot.run())\n\nif __name__ == '__main__':\n    run_bot()\n```\n\nFor more info you can take a look at a [boilerplate bot with buttons](boilerplate/button.py)\nand [simple boilerplate bot](boilerplate/simple.py)\n\nSet the `TG_BOT_TOKEN` env variable to run them.\n\n\n### Action Buttons\n\nThe package also provides a simplified mechanism of using buttons and \nbinding handlers to their callbacks.\nThis is useful when you want your buttons to contain a combination of\nseveral parameters and don't want to implement their serialization,\ndeserialization and callback bindings each time.\n\nThe idea is simple.\n\n1. Define an action (a `CallbackAction` subclass) using a combination of fields:\n```python\nfrom enum import Enum\nfrom aiokilogram.action import CallbackAction, StringActionField, EnumActionField\n\nclass ActionType(Enum):\n    show_recipe = 'show_recipe'\n    like_recipe = 'like_recipe'\n\nclass SingleRecipeAction(CallbackAction):\n    action_type = EnumActionField(enum_cls=ActionType)\n    recipe_title = StringActionField()\n```\n\n2. Create a page containing action buttons:\n```python\nfrom aiokilogram.page import ActionMessageButton, MessagePage, MessageBody, MessageKeyboard\n\npage = MessagePage(\n    body=MessageBody(text='Main Recipe Menu'),\n    keyboard=MessageKeyboard(buttons=[\n        ActionMessageButton(\n            text='Button Text',\n            action=SingleRecipeAction(\n                action_type=ActionType.show_recipe,\n                recipe_title='Fantastic Menemen',\n            ),\n        ),\n        # ...\n    ])\n)\n```\n\n3. Send it as a response to some command in your handler class:\n```python\n    await self.send_message_page(user_id=event.from_user.id, page=page)\n```\n\n4. Define and register a handler method for this action where you deserialize the \n   action parameters and somehow use them in your logic:\n```python\nclass MyHandler(CommandHandler):\n    @register_callback_query_handler(action=SingleRecipeAction)\n    async def do_single_recipe_action(self, query: types.CallbackQuery) -\u003e None:\n        action = SingleRecipeAction.deserialize(query.data)\n        if 'soup' in action.recipe_title.lower():\n            do_soup_stuff()  # whatever\n        # ...\n```\nor you can be more precise and limit the binding to specific values\nof the action's fields:\n```python\n    @register_callback_query_handler(\n        action=SingleRecipeAction.when(action_type=ActionType.like_recipe),\n    )\n```\n\n\nSee [boilerplate bot with buttons](boilerplate/button.py)\n\nSet the `TG_BOT_TOKEN` env variable to run it.\n\n\n### Error handling\n\nGeneric error (exception) handling in bots can be implemented via `ErrorHandler`s\nat class or method level.\n\nFirst, define an error handler:\n\n```python\nfrom aiokilogram.errors import DefaultErrorHandler\n\nclass MyErrorHandler(DefaultErrorHandler):\n    def make_message(self, err: Exception):\n        # Any custom logic can go here.\n        # This method can return either a `str`, a `MessagePage` or `None`.\n        # In case of `None` no message is sent and the exception is re-raised.\n        return 'This is my error message'\n```\n\nThen add it either to the message handler class:\n\n```python\nclass MyCommandHandler(CommandHandler):\n    error_handler = MyErrorHandler()\n```\n\nto handle errors in all methods registered via the\n`register_message_handler` and `register_callback_query_handler` decorators.\n\nOr you can do it at method-level:\n\n```python\n    @register_message_handler(commands={'my_command'}, error_handler=MyErrorHandler())\n    async def my_command_handler(self, event: types.Message) -\u003e None:\n        pass  # do whatever you do...\n```\n\nSee [boilerplate bot with error handling](boilerplate/errors.py)\n\nSet the `TG_BOT_TOKEN` env variable to run it.\n\n\n## Links\n\nHomepage on GitHub: https://github.com/altvod/aiokilogram\n\nProject's page on PyPi: https://pypi.org/project/aiokilogram/\n\n`aiogram`'s homepage on GitHub: https://github.com/aiogram/aiogram\n\nTelegram Bot API: https://core.telegram.org/bots/api\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltvod%2Faiokilogram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faltvod%2Faiokilogram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltvod%2Faiokilogram/lists"}