Typing for handlers and add hello world to index page of docs

aiogram/dispatcher/handler/base.py

@@ -6,11 +6,17 @@ from aiogram.api.types import TelegramObject
 
 
 class BaseHandlerMixin:
+    """
+    Typed mixin. Do nothing.
+    """
     event: TelegramObject
     data: Dict[str, Any]
 
 
 class _HandlerBotMixin(BaseHandlerMixin):
+    """
+    Mixin adds bot attribute
+    """
     @property
     def bot(self) -> Bot:
         if "bot" in self.data:
@@ -19,7 +25,9 @@ class _HandlerBotMixin(BaseHandlerMixin):
 
 
 class BaseHandler(_HandlerBotMixin, ABC):
-    event: TelegramObject
+    """
+    Base class for all class-based handlers
+    """
 
     def __init__(self, event: TelegramObject, **kwargs: Any) -> None:
         self.event = event

aiogram/dispatcher/handler/message.py

@@ -1,7 +1,7 @@
 from abc import ABC
 from typing import Optional
 
-from aiogram.api.types import Message
+from aiogram.api.types import Message, User, Chat
 from aiogram.dispatcher.filters import CommandObject
 from aiogram.dispatcher.handler.base import BaseHandler, BaseHandlerMixin
 
@@ -10,11 +10,11 @@ class MessageHandler(BaseHandler, ABC):
     event: Message
 
     @property
-    def from_user(self):
+    def from_user(self) -> User:
         return self.event.from_user
 
     @property
-    def chat(self):
+    def chat(self) -> Chat:
         return self.event.chat
 
 

docs/index.md

@@ -32,6 +32,48 @@ Documentation for version 3.0 [WIP] [^1]
     - [Russian language](https://t.me/aiogram_ru)
 
 
+## Example
+
+Simple usage
+```python3 
+from aiogram import Bot, Dispatcher, types
+from aiogram.dispatcher.handler import MessageHandler
+
+TOKEN = "42:TOKEN"
+dp = Dispatcher()
+
+
+@dp.message_handler(commands=["start"])
+class MyHandler(MessageHandler):
+    """
+    This handler receive messages with /start command
+    """
+
+    async def handle(self):
+        await self.bot.send_message(
+            chat_id=self.chat.id, text=f"<b>Hello, {self.from_user.full_name}!</b>"
+        )
+
+
+@dp.message_handler(content_types=[types.ContentType.ANY])
+async def echo_handler(message: types.Message, bot: Bot):
+    """
+    Handler will forward received message back to the sender
+    """
+    await bot.forward_message(
+        from_chat_id=message.chat.id, chat_id=message.chat.id, message_id=message.message_id
+    )
+
+
+def main():
+    bot = Bot(TOKEN, parse_mode="HTML")
+    dp.run_polling(bot)
+
+
+if __name__ == "__main__":
+    main()
+```
+
 ## Task list for 3.0
 
 - [ ] Telegram API features