Merge branch 'release/0.3.0'

Author: s3rius

.pre-commit-config.yaml

@@ -49,7 +49,7 @@ repos:
         language: system
         types: [python]
         pass_filenames: false
-        args: [taskiq_aiogram]
+        args: [taskiq_aiogram, example]
 
       - id: yesqa
         name: Remove usless noqa

README.md

@@ -22,41 +22,47 @@ startup and shutdown events, you have to manually define your executor.
 For example:
 
 ```python
-from aiogram import Bot, Dispatcher, executor
-# Your taskiq broker
-from your_project.tkq import broker
+import asyncio
+import logging
+import sys
 
+from aiogram import Bot, Dispatcher
 
-bot = Bot(token="API_TOKEN")
+# Your taskiq broker
+from your_project.tkq import broker
 
-dispatcher = Dispatcher(bot)
+dp = Dispatcher()
+bot = Bot(token="TOKEN")
 
 
-async def setup_taskiq(_: Dispatcher):
+@dp.startup()
+async def setup_taskiq(bot: Bot, *_args, **_kwargs):
     # Here we check if it's a clien-side,
     # Becuase otherwise you're going to
     # create infinite loop of startup events.
     if not broker.is_worker_process:
-        print("Setting up taskiq")
+        logging.info("Setting up taskiq")
         await broker.startup()
 
 
-async def shutdown_taskiq(_: Dispatcher):
+@dp.shutdown()
+async def shutdown_taskiq(bot: Bot, *_args, **_kwargs):
     if not broker.is_worker_process:
-        print("Shutting down taskiq")
+        logging.info("Shutting down taskiq")
         await broker.shutdown()
 
-# Here we defined our executor.
-bot_executor = executor.Executor(dispatcher=dispatcher)
-bot_executor.on_startup([setup_taskiq])
-bot_executor.on_shutdown([shutdown_taskiq])
+
+async def main():
+    await dp.start_polling(bot)
+
 
 if __name__ == "__main__":
-    bot_executor.start_polling()
+    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
+    asyncio.run(main())
 
 ```
 
-The only thing that left is to add one line to your broker definition.
+The only thing that left is to add few lines to your broker definition.
 
 
 ```python
@@ -69,39 +75,53 @@ broker = MyBroker()
 # This line is going to initialize everything.
 taskiq_aiogram.init(
     broker,
-    # Here we define path to your executor.
-    # This format is similar to uvicorn or gunicorn.
-    "your_project.__main__:bot_executor",
-    pooling=True,
-    webhook=False,
+    "your_project.__main__:dp",
+    "your_project.__main__:bot",
 )
 ```
 
-Aiogram defines startup events for pooling and webhooks separately. So you need to
-explicitly specify which mode suites you. BTW, by default aiogram adds handler events to
-both, so setting only pooling to True should be enought for almost any case.
-
 That's it.
 
-Let's create some tasks!
+Let's create some tasks! I created task in a separate module,
+named `tasks.py`.
 
 ```python
-# Sometimes python imports wrong task names.
-# If that happens, please set a task_name explicitly.
+from aiogram import Bot
+from your_project.tkq import broker
+
 @broker.task(task_name="my_task")
 async def my_task(chat_id: int, bot: Bot = TaskiqDepends()) -> None:
     print("I'm a task")
     await asyncio.sleep(4)
     await bot.send_message(chat_id, "task completed")
 
+```
+
+Now let's call our new task somewhere in bot commands.
 
-@dispatcher.message_handler(commands=["task"])
-async def send_task(message: types.Message):
-    await message.reply("Sending a task")
+```python
+from aiogram import types
+from aiogram.filters import Command
+
+from tasks import my_task
+
+
+@dp.message(Command("task"))
+async def message(message: types.Message):
     await my_task.kiq(message.chat.id)
 
 ```
 
-And it works!
+To start the worker, please type:
+
+```
+taskiq worker your_project.tkq:broker --fs-discover
+```
+
+We use `--fs-discover` to find all tasks.py modules recursively
+and import all tasks into broker.
+
+
+Now we can fire the task and see everything in action.
 
 ![Showcase.jpg](https://raw.githubusercontent.com/taskiq-python/taskiq-aiogram/master/imgs/showcase.jpg)

example/README.md

@@ -0,0 +1,9 @@
+# Simple example
+
+This is an example from README.md. It runs a bot with a simple command `/task`.
+To run the example:
+
+1. Install requirements, using command `pip install -r example/requirements.txt`;
+1. Replace `TOKEN` in `__main__.py` with your actual token;
+2. Start taskiq workers, by running `taskiq worker example.tkq:broker --fs-discover`;
+3. Start the bot, by running `python example`.

example/__init__.py

@@ -0,0 +1,44 @@
+import asyncio
+import logging
+import sys
+from typing import Any
+
+from aiogram import Bot, Dispatcher, types
+from aiogram.filters import Command
+
+from example.tasks import my_task
+from example.tkq import broker
+
+dp = Dispatcher()
+bot = Bot(token="TOKEN")
+
+
+@dp.startup()
+async def setup_taskiq(bot: Bot, *_args: Any, **_kwargs: Any) -> None:
+    # Here we check if it's a clien-side,
+    # Becuase otherwise you're going to
+    # create infinite loop of startup events.
+    if not broker.is_worker_process:
+        logging.info("Setting up taskiq")
+        await broker.startup()
+
+
+@dp.shutdown()
+async def shutdown_taskiq(bot: Bot, *_args: Any, **_kwargs: Any) -> None:
+    if not broker.is_worker_process:
+        logging.info("Shutting down taskiq")
+        await broker.shutdown()
+
+
+@dp.message(Command("task"))
+async def message(message: types.Message) -> None:
+    await my_task.kiq(message.chat.id)
+
+
+async def main() -> None:
+    await dp.start_polling(bot)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
+    asyncio.run(main())

example/__main__.py

@@ -0,0 +1,5 @@
+aiogram
+
+taskiq
+taskiq_redis
+taskiq_aiogram

example/requirements.txt

@@ -0,0 +1,13 @@
+import asyncio
+
+from aiogram import Bot
+from taskiq import TaskiqDepends
+
+from example.tkq import broker
+
+
+@broker.task(task_name="my_task")
+async def my_task(chat_id: int, bot: Bot = TaskiqDepends()) -> None:
+    print("I'm a task")
+    await asyncio.sleep(4)
+    await bot.send_message(chat_id, "task completed")

example/tasks.py

@@ -0,0 +1,11 @@
+from taskiq_redis import ListQueueBroker
+
+from taskiq_aiogram import init
+
+broker = ListQueueBroker("redis://localhost")
+
+init(
+    broker,
+    "example.__main__:dp",
+    "example.__main__:bot",
+)