From 5f05dfc664b1273bbfa93e0a2ee63d1e005a7990 Mon Sep 17 00:00:00 2001 From: Oleg A Date: Sat, 6 Jul 2024 20:33:01 +0300 Subject: [PATCH] docs: migration feeding updates (#1531) --- .editorconfig | 3 +++ docs/dispatcher/dispatcher.rst | 22 ++++++++++++++++------ docs/migration_2_to_3.rst | 33 +++++++++++++++++++-------------- 3 files changed, 38 insertions(+), 20 deletions(-) diff --git a/.editorconfig b/.editorconfig index f726e25b..1ad65bb7 100644 --- a/.editorconfig +++ b/.editorconfig @@ -15,5 +15,8 @@ indent_size = 2 [**.{md,txt,rst}] trim_trailing_whitespace = false +[**.rst] +indent_size = 2 + [Makefile] indent_style = tab diff --git a/docs/dispatcher/dispatcher.rst b/docs/dispatcher/dispatcher.rst index 0b650109..6fc4dbc7 100644 --- a/docs/dispatcher/dispatcher.rst +++ b/docs/dispatcher/dispatcher.rst @@ -2,7 +2,7 @@ Dispatcher ########## -Dispatcher is root :obj:`Router` and in code Dispatcher can be used directly for routing updates or attach another routers into dispatcher. +Dispatcher is root :class:`~aiogram.dispatcher.router.Router` and in code Dispatcher can be used directly for routing updates or attach another routers into dispatcher. Here is only listed base information about Dispatcher. All about writing handlers, filters and etc. you can find in next pages: @@ -39,16 +39,26 @@ Example: router1 = Router() dp.include_router(router1) + +.. _Handling updates: + Handling updates ================ -All updates can be propagated to the dispatcher by :obj:`Dispatcher.feed_update(bot=..., update=...)` method: +All updates can be propagated to the dispatcher by :meth:`~aiogram.dispatcher.dispatcher.Dispatcher.feed_update` method: .. code-block:: python - bot = Bot(...) - dp = Dispatcher() + from aiogram import Bot, Dispatcher - ... + async def update_handler(update: Update, bot: Bot, dispatcher: Dispatcher): + result = await dp.feed_update(bot, update) - result = await dp.feed_update(bot=bot, update=incoming_update) +Also you can feed raw update (dictionary) object to the dispatcher by :meth:`~aiogram.dispatcher.dispatcher.Dispatcher.feed_raw_update` method: + +.. code-block:: python + + from aiogram import Bot, Dispatcher + + async def update_handler(raw_update: dict[str, Any], bot: Bot, dispatcher: Dispatcher): + result = await dp.feed_raw_update(bot, raw_update) diff --git a/docs/migration_2_to_3.rst b/docs/migration_2_to_3.rst index 2650cc38..8b0e6229 100644 --- a/docs/migration_2_to_3.rst +++ b/docs/migration_2_to_3.rst @@ -1,3 +1,7 @@ +.. |Bot| replace:: :class:`~aiogram.client.bot.Bot` +.. |Dispatcher| replace:: :class:`~aiogram.dispatcher.dispatcher.Dispatcher` +.. |Router| replace:: :class:`~aiogram.dispatcher.router.Router` + ========================== Migration FAQ (2.x -> 3.0) ========================== @@ -33,24 +37,26 @@ Dependencies Dispatcher ========== -- The :class:`Dispatcher` class no longer accepts a `Bot` instance in its initializer. - Instead, the `Bot` instance should be passed to the dispatcher only for starting polling +- The |Dispatcher| class no longer accepts a |Bot| instance in its initializer. + Instead, the |Bot| instance should be passed to the dispatcher only for starting polling or handling events from webhooks. This approach also allows for the use of multiple bot instances simultaneously ("multibot"). -- :class:`Dispatcher` now can be extended with another Dispatcher-like - thing named :class:`Router` (:ref:`Read more » `). -- With routes, you can easily modularize your code and potentially share these modules between projects. +- |Dispatcher| now can be extended with another Dispatcher-like thing named |Router|. + With routes, you can easily modularize your code and potentially share these modules between projects. + (:ref:`Read more » `.) - Removed the **_handler** suffix from all event handler decorators and registering methods. (:ref:`Read more » `) -- The Executor has been entirely removed; you can now use the Dispatcher directly to start poll the API or handle webhooks from it. +- The :class:`Executor` has been entirely removed; you can now use the |Dispatcher| directly to start poll the API or handle webhooks from it. - The throttling method has been completely removed; you can now use middlewares to control the execution context and implement any throttling mechanism you desire. -- Removed global context variables from the API types, Bot and Dispatcher object, +- Removed global context variables from the API types, |Bot| and |Dispatcher| object. From now on, if you want to access the current bot instance within handlers or filters, you should accept the argument :code:`bot: Bot` and use it instead of :code:`Bot.get_current()`. In middlewares, it can be accessed via :code:`data["bot"]`. -- To skip pending updates, you should now call the :class:`aiogram.methods.delete_webhook.DeleteWebhook` method directly, rather than passing :code:`skip_updates=True` to the start polling method. - +- To skip pending updates, you should now call the :class:`~aiogram.methods.delete_webhook.DeleteWebhook` method directly, rather than passing :code:`skip_updates=True` to the start polling method. +- To feed updates to the |Dispatcher|, instead of method :meth:`process_update`, + you should use method :meth:`~aiogram.dispatcher.dispatcher.Dispatcher.feed_update`. + (:ref:`Read more » `) Filtering events @@ -128,11 +134,10 @@ Finite State machine you will need to specify the state if you want to use it. - Added the possibility to change the FSM strategy. For example, if you want to control the state for each user based on chat topics rather than - the user in a chat, you can specify this in the Dispatcher. + the user in a chat, you can specify this in the |Dispatcher|. - Now :class:`aiogram.fsm.state.State` and :class:`aiogram.fsm.state.StateGroup` don't have helper methods like :code:`.set()`, :code:`.next()`, etc. - -- Instead, you should set states by passing them directly to + Instead, you should set states by passing them directly to :class:`aiogram.fsm.context.FSMContext` (:ref:`Read more » `) - The state proxy is deprecated; you should update the state data by calling :code:`state.set_data(...)` and :code:`state.get_data()` respectively. @@ -155,8 +160,8 @@ Webhook Telegram API Server =================== -- The `server` parameter has been moved from the `Bot` instance to `api` in `BaseSession`. -- The constant `aiogram.bot.api.TELEGRAM_PRODUCTION` has been moved to `aiogram.client.telegram.PRODUCTION`. +- The :obj:`server` parameter has been moved from the |Bot| instance to :obj:`api` parameter of the :class:`~aiogram.client.session.base.BaseSession`. +- The constant :obj:`aiogram.bot.api.TELEGRAM_PRODUCTION` has been moved to :obj:`aiogram.client.telegram.PRODUCTION`. Telegram objects transformation (to dict, to json, from json)