From 62bce34b49411b8222f3c1768c3c5398405b8d98 Mon Sep 17 00:00:00 2001
From: Alex Root Junior <jroot.junior@gmail.com>
Date: Tue, 3 Dec 2019 00:37:53 +0200
Subject: [PATCH] Add docs for class-based handlers

---
 aiogram/__init__.py                           |  3 ++-
 aiogram/dispatcher/handler/__init__.py        |  4 +++
 aiogram/dispatcher/handler/base.py            |  4 +--
 .../dispatcher/class_based_handlers/basics.md | 25 +++++++++++++++++++
 .../class_based_handlers/message.md           | 25 +++++++++++++++++++
 mkdocs.yml                                    |  4 ++-
 6 files changed, 61 insertions(+), 4 deletions(-)
 create mode 100644 docs/dispatcher/class_based_handlers/basics.md
 create mode 100644 docs/dispatcher/class_based_handlers/message.md

diff --git a/aiogram/__init__.py b/aiogram/__init__.py
index 006e66ee..9af0a993 100644
--- a/aiogram/__init__.py
+++ b/aiogram/__init__.py
@@ -1,7 +1,7 @@
 from .api import methods, types
 from .api.client import session
 from .api.client.bot import Bot
-from .dispatcher import filters
+from .dispatcher import filters, handler
 from .dispatcher.dispatcher import Dispatcher
 from .dispatcher.router import Router
 
@@ -23,6 +23,7 @@ __all__ = (
     "Dispatcher",
     "Router",
     "filters",
+    "handler",
 )
 
 __version__ = "3.0.0a0"
diff --git a/aiogram/dispatcher/handler/__init__.py b/aiogram/dispatcher/handler/__init__.py
index e69de29b..1762b5bc 100644
--- a/aiogram/dispatcher/handler/__init__.py
+++ b/aiogram/dispatcher/handler/__init__.py
@@ -0,0 +1,4 @@
+from .base import BaseHandler, BaseHandlerMixin
+from .message import MessageHandler
+
+__all__ = ("BaseHandler", "BaseHandlerMixin", "MessageHandler")
diff --git a/aiogram/dispatcher/handler/base.py b/aiogram/dispatcher/handler/base.py
index bfc16575..a576b0b6 100644
--- a/aiogram/dispatcher/handler/base.py
+++ b/aiogram/dispatcher/handler/base.py
@@ -13,7 +13,7 @@ class BaseHandlerMixin:
     data: Dict[str, Any]
 
 
-class HandlerBotMixin(BaseHandlerMixin):
+class _HandlerBotMixin(BaseHandlerMixin):
     @property
     def bot(self) -> Bot:
         if "bot" in self.data:
@@ -21,7 +21,7 @@ class HandlerBotMixin(BaseHandlerMixin):
         return Bot.get_current()
 
 
-class BaseHandler(HandlerBotMixin, ABC):
+class BaseHandler(_HandlerBotMixin, ABC):
     event: TelegramObject
     filters: Union[List["FilterType"], Tuple["FilterType"]]
 
diff --git a/docs/dispatcher/class_based_handlers/basics.md b/docs/dispatcher/class_based_handlers/basics.md
new file mode 100644
index 00000000..529def4d
--- /dev/null
+++ b/docs/dispatcher/class_based_handlers/basics.md
@@ -0,0 +1,25 @@
+# Overview
+
+A handler is a async callable which takes a event with contextual data and returns a response.
+In `aiogram` this can be more than just an async function, these allow you to use classes which can be used as Telegram event handlers to structure your event handlers and reuse code by harnessing inheritance and mixins.
+
+There are some base class based handlers what you need to use in your own handlers:
+
+- [BaseHandler](#basehandler)
+- [MessageHandler](message.md)
+
+
+## BaseHandler
+
+Base handler is abstract class and should be used in all other class-based handlers.
+
+Import: `#!python3 from aiogram.hanler import BaseHandler`
+
+By default you will need to override only method `#!python3 async def handle(self) -> Any: ...`
+
+The list of filters can be specified in attribute `#!python3 filters: Union[List["FilterType"], Tuple["FilterType"]]` or you can combine that attribute with filters specified in event registerer (via decorator or observer method)
+
+This class is also have an default initializer and you don't need to change it. 
+Initializer accepts current event and all contextual data and which can be accessed from the handler through attributes: `event: TelegramEvent` and `data: Dict[Any, str]`
+
+If instance of the bot is specified in context data or current context it can be accessed through `bot` class attribute.
diff --git a/docs/dispatcher/class_based_handlers/message.md b/docs/dispatcher/class_based_handlers/message.md
new file mode 100644
index 00000000..90866506
--- /dev/null
+++ b/docs/dispatcher/class_based_handlers/message.md
@@ -0,0 +1,25 @@
+# MessageHandler
+
+There is base class for message handlers.
+
+## Simple usage:
+```pyhton3
+from aiogram.handlers import MessageHandler
+
+...
+
+@router.message_handler()
+class MyTestMessageHandler(MessageHandler):
+    filters = [Text(text="test")]
+
+    async def handle() -> Any:
+        return SendMessage(chat_id=self.chat.id, text="PASS")
+
+```
+
+## Extension
+
+This base handler is subclass of [BaseHandler](basics.md#basehandler) with some extensions:
+
+- `self.chat` is alias for `self.event.chat`
+- `self.from_user` is alias for `self.event.from_user`
diff --git a/mkdocs.yml b/mkdocs.yml
index 40e3b506..4785f845 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -225,7 +225,9 @@ nav:
       - Filters:
           - dispatcher/filters/index.md
           - dispatcher/filters/text.md
-
+      - Class based handlers:
+          - dispatcher/class_based_handlers/basics.md
+          - dispatcher/class_based_handlers/message.md
   - Build reports:
       - reports.md
       - Tests result: /reports/tests