From 9adc2f91bdf4cfb48190fdb86e14f15736fbb8d6 Mon Sep 17 00:00:00 2001 From: Alex Root Junior Date: Wed, 27 Nov 2019 01:27:08 +0200 Subject: [PATCH] Add base documentation of Dispatcher (not ready, not fully documented) --- docs/assets/images/nested_routers_example.png | Bin 0 -> 40109 bytes .../assets/images/update_propagation_flow.png | Bin 0 -> 66141 bytes docs/dispatcher/dispatcher.md | 64 ++++++++ docs/dispatcher/filters/base_filter.md | 0 docs/dispatcher/filters/index.md | 7 + docs/dispatcher/index.md | 13 ++ docs/dispatcher/observer.md | 54 +++++++ docs/dispatcher/router.md | 137 ++++++++++++++++++ mkdocs.yml | 11 +- 9 files changed, 285 insertions(+), 1 deletion(-) create mode 100644 docs/assets/images/nested_routers_example.png create mode 100644 docs/assets/images/update_propagation_flow.png create mode 100644 docs/dispatcher/dispatcher.md create mode 100644 docs/dispatcher/filters/base_filter.md create mode 100644 docs/dispatcher/filters/index.md create mode 100644 docs/dispatcher/index.md create mode 100644 docs/dispatcher/observer.md create mode 100644 docs/dispatcher/router.md diff --git a/docs/assets/images/nested_routers_example.png b/docs/assets/images/nested_routers_example.png new file mode 100644 index 0000000000000000000000000000000000000000..8ccd824f8a26dfb988893425254c93340554265e GIT binary patch literal 40109 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 None: + await SendMessage(chat_id=message.from_user.id, text=message.text) +``` + + +## Including routers +Example: +```python3 +dp = Dispatcher() +router1 = Router() +dp.include_router(router1) +``` + + +## Handling updates +All updates can be propagated to the dispatcher by `feed_update` method: + +``` +bot = Bot(...) +dp = Dispathcher() + +... + +async for result in dp.feed_update(bot=bot, update=incoming_update): + print(result) +``` + +**Method specification**: + +| Argument | Type | Description | +| --- | --- | --- | +| `bot` | `Bot` | Bot instance related with current update object | +| `update` | `Update` | Update object | +| `**kwargs` | `Any` | Context related data. Will be propagated to handlers, filters and middlewares | + +### Polling +... + +### Webhook +... diff --git a/docs/dispatcher/filters/base_filter.md b/docs/dispatcher/filters/base_filter.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/dispatcher/filters/index.md b/docs/dispatcher/filters/index.md new file mode 100644 index 00000000..10ad50ec --- /dev/null +++ b/docs/dispatcher/filters/index.md @@ -0,0 +1,7 @@ +# Overview + + +## Writing own filters + + +## Builtin filters diff --git a/docs/dispatcher/index.md b/docs/dispatcher/index.md new file mode 100644 index 00000000..115b4aa8 --- /dev/null +++ b/docs/dispatcher/index.md @@ -0,0 +1,13 @@ +# Overview + +Dispatcher is needed for handling incoming updates from Telegram. With dispatcher you can do: + +- Handle incoming updates; +- Filter incoming events before it will be processed by specific handler; +- Modify event and related data in middlewares; +- Separate bot functionality between different handlers, modules and packages + +Manually dispatcher has the router role and can include another routers. + +Dispatcher is also separated into two entities - Router and Dispatcher. +Dispatcher is subclass of router and should be always is root router. diff --git a/docs/dispatcher/observer.md b/docs/dispatcher/observer.md new file mode 100644 index 00000000..fc7ff170 --- /dev/null +++ b/docs/dispatcher/observer.md @@ -0,0 +1,54 @@ +# Observer + +Observer is used for filtering and handling different events. That is part of internal API with some public methods and is recommended to don't use methods is not listed here. + +In `aiogram` framework is available two variants of observer: + +1. [EventObserver](#eventobserver) +1. [TelegramEventObserver](#telegrameventobserver) + + +## EventObserver +Reference: `#!python3 aiogram.dispatcher.event.observer.EventObserver` + +That is base observer for all events. + +### Base registering method +Method: `.register(callback, filter1, filter2, ...)` + +| Argument | Type | Description | +| --- | --- | --- | +| `callback` | `#!python3 Callable[[Any], Awaitable[Any]]` | Event handler | +| `*filters` | `#!python3 Union[Callable[[Any], Any], Callable[[Any], Awaitable[Any]], BaseFilter]` | Ordered filters set | + +Will return original callback. + + +### Decorator-style registering method + +Usage: +```python3 +@(filter1, filter2, ...) +async def handler(*args, **kwargs): + pass +``` + +## TelegramEventObserver +Is subclass of [EventObserver](#eventobserver) with some differences. +In this handler can be bounded filters which can be used as keyword arguments instead of writing full references when you register new handlers. + +### Registering bound filters + +Bound filter should be subclass of [BaseFilter](filters/base_filter.md) + +`#!python3 .bind_filter(MyFilter)` + +### Registering handlers +Method: `EventObserver.register(callback, filter1, filter2, ..., bound_filter=value, ...)` +In this method is added bound filters keywords interface. + +| Argument | Type | Description | +| --- | --- | --- | +| `callback` | `#!python3 Callable[[Any], Awaitable[Any]]` | Event handler | +| `*filters` | `#!python3 Union[Callable[[Any], Any], Callable[[Any], Awaitable[Any]], BaseFilter]` | Ordered filters set | +| `**bound_filters` | `#!python3 Any` | Bound filters | diff --git a/docs/dispatcher/router.md b/docs/dispatcher/router.md new file mode 100644 index 00000000..f22136c1 --- /dev/null +++ b/docs/dispatcher/router.md @@ -0,0 +1,137 @@ +# Router +Imports: + +- Recommended: `#!python3 from aiogram import Dispatcher` +- Real location: `#!python3 from aiogram.dispatcher.dispatcher import Dispatcher` + +Router does not accept any arguments in initializer so that's mean you can simply create instance: +```python3 +router = Router() +``` + +Router can route update and it nested update types like messages, callback query, polls and all other event types. + +## Event observers +Here is used event-observer pattern. (Read more on [observer page >>](observer.md)) + +Event handlers can be registered in observer by two ways: + +1. By observer method - `#!python3 router..register(handler, )` +1. By decorator - `#!python3 @router.()` + +!!! warning + + All handlers is always should be an asynchronous. + Name of handler function is not important. Event argument name is also is not important but is recommended to don't overlap the name with contextual data in due to function can not accept two arguments with the same name. + +Here is list of available observers and examples how to register handlers (In examples used only @decorator-style): + +### Update +```python3 +@router.update_handler(): +async def message_handler(update: types.Update) -> Any: pass +``` +Should be used for handling [updates](../api/types/update.md). By default Router is already have an update handler which route all event types to another observers. + +### Message +```python3 +@router.message_handler(): +async def message_handler(message: types.Message) -> Any: pass +``` +Is useful for handling [message](../api/types/message.md) + +### Edited message +```python3 +@router.edited_message_handler(): +async def edited_message_handler(edited_message: types.Message) -> Any: pass +``` +Is useful for handling [edited messages](../api/types/message.md) + +### Channel post +```python3 +@router.channel_post_handler(): +async def channel_post_handler(channel_post: types.Message) -> Any: pass +``` +Is useful for handling [channel posts](../api/types/message.md) + +### Edited channel post +```python3 +@router.edited_channel_post_handler(): +async def edited_channel_post_handler(edited_channel_post: types.Message) -> Any: pass +``` +Is useful for handling [edited channel posts](../api/types/message.md) + +### Inline query +```python3 +@router.inline_query_handler(): +async def inline_query_handler(inline_query: types.Message) -> Any: pass +``` +Is useful for handling [inline query](../api/types/inline_query.md) + +### Chosen inline query +```python3 +@router.chosen_inline_result_handler(): +async def chosen_inline_result_handler(chosen_inline_result: types.ChosenInlineResult) -> Any: pass +``` +Is useful for handling [chosen inline query](../api/types/chosen_inline_result.md) + +### Callback query +```python3 +@router.callback_query_handler(): +async def callback_query_handler(callback_query: types.CallbackQuery) -> Any: pass +``` +Is useful for handling [callback query's](../api/types/callback_query.md) + +### Shipping query +```python3 +@router.shipping_query_handler(): +async def shipping_query_handler(shipping_query: types.ShippingQuery) -> Any: pass +``` +Is useful for handling [shipping query](../api/types/shipping_query.md) + +### Pre checkout query +```python3 +@router.pre_checkout_query_handler(): +async def pre_checkout_query_handler(pre_checkout_query: types.PreCheckoutQuery) -> Any: pass +``` +Is useful for handling [pre-checkout query](../api/types/pre_checkout_query.md) + +### Poll +```python3 +@router.poll_handler(): +async def poll_handler(poll: types.Poll) -> Any: pass +``` +Is useful for handling [polls](../api/types/poll.md) + + +## Nested routers + +!!! warning + Routers by the way can be nested to an another routers with some limitations: + + 1. Router **CAN NOT** include itself + 1. Routers **CAN NOT** be used for circular including (router 1 include router 2, router 2 include router 3, router 3 include router 1) + + +Example: +```python3 +# module_1.py +router1 = Router() +router2 = Router() + +router2.include_router(router1) +``` + + +## How it works? + +For example dispatcher has 2 routers, last one router is also have one nested router: + +[![nested routers example](../assets/images/nested_routers_example.png)](../assets/images/nested_routers_example.png) +_(Click on image to zoom it)_ + +In this case update propagation flow will have form: + +[![update propagation flow](../assets/images/update_propagation_flow.png)](../assets/images/update_propagation_flow.png) +_(Click on image to zoom it)_ + diff --git a/mkdocs.yml b/mkdocs.yml index c7aac235..06186614 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,7 +17,7 @@ theme: logo: 'assets/images/logo.png' extra: - version: 3.0.0a0 + version: 3.0.0a0 plugins: - search @@ -217,6 +217,15 @@ nav: - api/types/callback_game.md - api/types/game_high_score.md - api/sending_files.md + - Dispatcher: + - dispatcher/index.md + - dispatcher/router.md + - dispatcher/dispatcher.md + - dispatcher/observer.md + - Filters: + - dispatcher/filters/index.md + - dispatcher/filters/base_filter.md + - Build reports: - reports.md - Tests result: /reports/tests