From f97367b3ee3aae442fac3a21745f38a252688aca Mon Sep 17 00:00:00 2001 From: Alex Root Junior Date: Tue, 12 Oct 2021 01:11:53 +0300 Subject: [PATCH] More docs --- CHANGES/724.feature | 2 +- Makefile | 1 + aiogram/dispatcher/fsm/storage/base.py | 51 ++++++ aiogram/dispatcher/fsm/storage/memory.py | 9 + aiogram/dispatcher/fsm/storage/redis.py | 42 ++++- aiogram/utils/keyboard.py | 15 ++ docs/_static/fsm_example.png | Bin 0 -> 90830 bytes docs/dispatcher/filters/index.rst | 6 +- docs/dispatcher/filters/magic_data.rst | 34 ++++ docs/dispatcher/filters/magic_filters.rst | 8 +- .../dispatcher/finite_state_machine/index.rst | 119 +++++++++++++ .../finite_state_machine/storages.rst | 17 +- docs/dispatcher/index.rst | 2 +- docs/utils/i18n.rst | 4 +- docs/utils/keyboard.rst | 47 ++++-- examples/finite_state_machine.py | 158 ++++++++++-------- 16 files changed, 415 insertions(+), 100 deletions(-) create mode 100644 docs/_static/fsm_example.png create mode 100644 docs/dispatcher/filters/magic_data.rst create mode 100644 docs/dispatcher/finite_state_machine/index.rst diff --git a/CHANGES/724.feature b/CHANGES/724.feature index 1ed4c862..052a25fb 100644 --- a/CHANGES/724.feature +++ b/CHANGES/724.feature @@ -1,6 +1,6 @@ Implemented new filter named :code:`MagicData(magic_data)` that helps to filter event by data from middlewares or other filters -For example you bor is running with argument named :code:`config` that contains the application config then you can filter event by value from this config: +For example your bot is running with argument named :code:`config` that contains the application config then you can filter event by value from this config: .. code_block: python3 diff --git a/Makefile b/Makefile index 887766bf..09033e7c 100644 --- a/Makefile +++ b/Makefile @@ -72,6 +72,7 @@ lint: $(py) black --check --diff $(code_dir) $(py) flake8 $(code_dir) $(py) mypy $(package_dir) + # TODO: wemake-python-styleguide .PHONY: reformat reformat: diff --git a/aiogram/dispatcher/fsm/storage/base.py b/aiogram/dispatcher/fsm/storage/base.py index 2fdc22e5..f4830e0f 100644 --- a/aiogram/dispatcher/fsm/storage/base.py +++ b/aiogram/dispatcher/fsm/storage/base.py @@ -20,28 +20,76 @@ class StorageKey: class BaseStorage(ABC): + """ + Base class for all FSM storages + """ + @abstractmethod @asynccontextmanager async def lock(self, bot: Bot, key: StorageKey) -> AsyncGenerator[None, None]: + """ + Isolate events with lock. + Will be used as context manager + + :param bot: instance of the current bot + :param key: storage key + :return: An async generator + """ yield None @abstractmethod async def set_state(self, bot: Bot, key: StorageKey, state: StateType = None) -> None: + """ + Set state for specified key + + :param bot: instance of the current bot + :param key: storage key + :param state: new state + """ pass @abstractmethod async def get_state(self, bot: Bot, key: StorageKey) -> Optional[str]: + """ + Get key state + + :param bot: instance of the current bot + :param key: storage key + :return: current state + """ pass @abstractmethod async def set_data(self, bot: Bot, key: StorageKey, data: Dict[str, Any]) -> None: + """ + Write data (replace) + + :param bot: instance of the current bot + :param key: storage key + :param data: new data + """ pass @abstractmethod async def get_data(self, bot: Bot, key: StorageKey) -> Dict[str, Any]: + """ + Get current data for key + + :param bot: instance of the current bot + :param key: storage key + :return: current data + """ pass async def update_data(self, bot: Bot, key: StorageKey, data: Dict[str, Any]) -> Dict[str, Any]: + """ + Update date in the storage for key (like dict.update) + + :param bot: instance of the current bot + :param key: storage key + :param data: partial data + :return: new data + """ current_data = await self.get_data(bot=bot, key=key) current_data.update(data) await self.set_data(bot=bot, key=key, data=current_data) @@ -49,4 +97,7 @@ class BaseStorage(ABC): @abstractmethod async def close(self) -> None: # pragma: no cover + """ + Close storage (database connection, file or etc.) + """ pass diff --git a/aiogram/dispatcher/fsm/storage/memory.py b/aiogram/dispatcher/fsm/storage/memory.py index 823ad894..19b43fa9 100644 --- a/aiogram/dispatcher/fsm/storage/memory.py +++ b/aiogram/dispatcher/fsm/storage/memory.py @@ -17,6 +17,15 @@ class MemoryStorageRecord: class MemoryStorage(BaseStorage): + """ + Default FSM storage, stores all data in :class:`dict` and loss everything on shutdown + + .. warning:: + + Is not recommended using in production in due to you will lose all data + when your bot restarts + """ + def __init__(self) -> None: self.storage: DefaultDict[StorageKey, MemoryStorageRecord] = defaultdict( MemoryStorageRecord diff --git a/aiogram/dispatcher/fsm/storage/redis.py b/aiogram/dispatcher/fsm/storage/redis.py index 94553a67..b722984a 100644 --- a/aiogram/dispatcher/fsm/storage/redis.py +++ b/aiogram/dispatcher/fsm/storage/redis.py @@ -18,6 +18,13 @@ class KeyBuilder(ABC): @abstractmethod def build(self, key: StorageKey, part: Literal["data", "state", "lock"]) -> str: + """ + This method should be implemented in subclasses + + :param key: contextual key + :param part: part of the record + :return: key to be used in Redis queries + """ pass @@ -30,9 +37,21 @@ class DefaultKeyBuilder(KeyBuilder): """ def __init__( - self, prefix: str = "fsm", with_bot_id: bool = False, with_destiny: bool = False + self, + *, + prefix: str = "fsm", + separator: str = ":", + with_bot_id: bool = False, + with_destiny: bool = False, ) -> None: + """ + :param prefix: prefix for all records + :param separator: separator + :param with_bot_id: include Bot id in the key + :param with_destiny: include destiny key + """ self.prefix = prefix + self.separator = separator self.with_bot_id = with_bot_id self.with_destiny = with_destiny @@ -44,10 +63,14 @@ class DefaultKeyBuilder(KeyBuilder): if self.with_destiny: parts.append(key.destiny) parts.append(part) - return ":".join(parts) + return self.separator.join(parts) class RedisStorage(BaseStorage): + """ + Redis storage required :code:`aioredis` package installed (:code:`pip install aioredis`) + """ + def __init__( self, redis: Redis, @@ -56,6 +79,13 @@ class RedisStorage(BaseStorage): data_ttl: Optional[int] = None, lock_kwargs: Optional[Dict[str, Any]] = None, ) -> None: + """ + :param redis: Instance of Redis connection + :param key_builder: builder that helps to convert contextual key to string + :param state_ttl: TTL for state records + :param data_ttl: TTL for data records + :param lock_kwargs: Custom arguments for Redis lock + """ if key_builder is None: key_builder = DefaultKeyBuilder() if lock_kwargs is None: @@ -70,6 +100,14 @@ class RedisStorage(BaseStorage): def from_url( cls, url: str, connection_kwargs: Optional[Dict[str, Any]] = None, **kwargs: Any ) -> "RedisStorage": + """ + Create an instance of :class:`RedisStorage` with specifying the connection string + + :param url: for example :code:`redis://user:password@host:port/db` + :param connection_kwargs: see :code:`aioredis` docs + :param kwargs: arguments to be passed to :class:`RedisStorage` + :return: an instance of :class:`RedisStorage` + """ if connection_kwargs is None: connection_kwargs = {} pool = ConnectionPool.from_url(url, **connection_kwargs) diff --git a/aiogram/utils/keyboard.py b/aiogram/utils/keyboard.py index 34d660b0..48e9e0da 100644 --- a/aiogram/utils/keyboard.py +++ b/aiogram/utils/keyboard.py @@ -36,6 +36,12 @@ MAX_BUTTONS = 100 class KeyboardBuilder(Generic[ButtonType]): + """ + Generic keyboard builder that helps to adjust your markup with defined shape of lines. + + Works both of InlineKeyboardMarkup and ReplyKeyboardMarkup. + """ + def __init__( self, button_type: Type[ButtonType], markup: Optional[List[List[ButtonType]]] = None ) -> None: @@ -257,6 +263,10 @@ def repeat_last(items: Iterable[T]) -> Generator[T, None, None]: class InlineKeyboardBuilder(KeyboardBuilder[InlineKeyboardButton]): + """ + Inline keyboard builder inherits all methods from generic builder + """ + if TYPE_CHECKING: @no_type_check @@ -275,6 +285,7 @@ class InlineKeyboardBuilder(KeyboardBuilder[InlineKeyboardButton]): ... def as_markup(self, **kwargs: Any) -> InlineKeyboardMarkup: + """Construct an InlineKeyboardMarkup""" ... def __init__(self, markup: Optional[List[List[InlineKeyboardButton]]] = None) -> None: @@ -290,6 +301,10 @@ class InlineKeyboardBuilder(KeyboardBuilder[InlineKeyboardButton]): class ReplyKeyboardBuilder(KeyboardBuilder[KeyboardButton]): + """ + Reply keyboard builder inherits all methods from generic builder + """ + if TYPE_CHECKING: @no_type_check diff --git a/docs/_static/fsm_example.png b/docs/_static/fsm_example.png new file mode 100644 index 0000000000000000000000000000000000000000..f306950eac6a04d31882ad6a70fec308367c5edb GIT binary patch literal 90830 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 N%JS-u^W@Cl{SV45Je~jm literal 0 HcmV?d00001 diff --git a/docs/dispatcher/filters/index.rst b/docs/dispatcher/filters/index.rst index 26de26a4..5a841c1f 100644 --- a/docs/dispatcher/filters/index.rst +++ b/docs/dispatcher/filters/index.rst @@ -19,8 +19,8 @@ Here is list of builtin filters: content_types text exception - -Or you can do :ref:`✨ some magic ` + magic_filters + magic_data Own filters specification ========================= @@ -35,7 +35,7 @@ Filters can be: - Any awaitable object -- Subclass of :ref:`BaseFilter ` +- Subclass of :class:`aiogram.dispatcher.filters.base.BaseFilter` - Instances of :ref:`MagicFilter ` diff --git a/docs/dispatcher/filters/magic_data.rst b/docs/dispatcher/filters/magic_data.rst new file mode 100644 index 00000000..72cf2433 --- /dev/null +++ b/docs/dispatcher/filters/magic_data.rst @@ -0,0 +1,34 @@ +==== +MagicData +==== + +.. autoclass:: aiogram.dispatcher.filters.magic_data.MagicData + :members: + :member-order: bysource + :undoc-members: False + +Can be imported: + +- :code:`from aiogram.dispatcher.filters.magic_data import MagicData` +- :code:`from aiogram.dispatcher.filters import MagicData` +- :code:`from aiogram.filters import MagicData` + +Or used from filters factory by passing corresponding arguments to handler registration line + +Usage +===== + +#. :code:`magic_data=F.event.from_user.id == F.config.admin_id` (Note that :code:`config` should be passed from middleware) + + +Allowed handlers +================ + +Allowed update types for this filter: + +- :code:`message` +- :code:`edited_message` +- :code:`channel_post` +- :code:`edited_channel_post` +- :code:`inline_query` +- :code:`callback_query` diff --git a/docs/dispatcher/filters/magic_filters.rst b/docs/dispatcher/filters/magic_filters.rst index 3a0dd8b7..f60dca5d 100644 --- a/docs/dispatcher/filters/magic_filters.rst +++ b/docs/dispatcher/filters/magic_filters.rst @@ -24,7 +24,7 @@ and memorize the attributes chain and the action which should be checked on dema So that's mean you can chain attribute getters, describe simple data validations and then call the resulted object passing single object as argument, for example make attributes chain :code:`F.foo.bar.baz` then add -action ':code:`F.foo.bar.baz == 'spam'` and then call the resulted object - :code:`(F.foo.bar.baz == 'spam')(obj)` +action ':code:`F.foo.bar.baz == 'spam'` and then call the resulted object - :code:`(F.foo.bar.baz == 'spam').resolve(obj)` .. _magic-filter-possible-actions: @@ -125,9 +125,9 @@ Can be used only with string attributes. .. code-block:: python - F.text__lower == 'test' # lambda message: message.text.lower() == 'test' - F.text__upper.in_('FOO', 'BAR') # lambda message: message.text.upper() in {'FOO', 'BAR'} - F.text__len == 5 # lambda message: len(message.text) == 5 + F.text.lower() == 'test' # lambda message: message.text.lower() == 'test' + F.text.upper().in_('FOO', 'BAR') # lambda message: message.text.upper() in {'FOO', 'BAR'} + F.text.len() == 5 # lambda message: len(message.text) == 5 Usage in *aiogram* diff --git a/docs/dispatcher/finite_state_machine/index.rst b/docs/dispatcher/finite_state_machine/index.rst new file mode 100644 index 00000000..4971fae1 --- /dev/null +++ b/docs/dispatcher/finite_state_machine/index.rst @@ -0,0 +1,119 @@ +==================== +Finite State Machine +==================== + + A finite-state machine (FSM) or finite-state automaton (FSA, plural: automata), finite automaton, + or simply a state machine, is a mathematical model of computation. + + It is an abstract machine that can be in exactly one of a finite number of states at any given time. + The FSM can change from one state to another in response to some inputs; + the change from one state to another is called a transition. + + An FSM is defined by a list of its states, its initial state, + and the inputs that trigger each transition. + + .. raw:: html + +
+ + Source: `WikiPedia `_ + +Usage example +============= + +Not all functionality of the bot can be implemented as single handler, +for example you will need to collect some data from user in separated steps you will need to use FSM. + + +.. image:: ../../_static/fsm_example.png + :alt: FSM Example + +Let's see how to do that step-by-step + +Step by step +------------ + +Before handle any states you will need to specify what kind of states you want to handle + +.. literalinclude:: ../../../examples/finite_state_machine.py + :language: python + :linenos: + :lineno-start: 15 + :lines: 15-18 + +And then write handler for each state separately from the start of dialog + +Here is dialog can be started only via command :code:`/start`, so lets handle it and make transition user to state :code:`Form.name` + +.. literalinclude:: ../../../examples/finite_state_machine.py + :language: python + :linenos: + :lineno-start: 21 + :lines: 21-27 + +After that you will need to save some data to the storage and make transition to next step. + +.. literalinclude:: ../../../examples/finite_state_machine.py + :language: python + :linenos: + :lineno-start: 48 + :lines: 48-63 + +At the next steps user can make different answers, it can be `yes`, `no` or any other + +Handle :code:`yes` and soon we need to handle :code:`Form.language` state + +.. literalinclude:: ../../../examples/finite_state_machine.py + :language: python + :linenos: + :lineno-start: 77 + :lines: 77-84 + +Handle :code:`no` + +.. literalinclude:: ../../../examples/finite_state_machine.py + :language: python + :linenos: + :lineno-start: 66 + :lines: 66-74 + +And handle any other answers + +.. literalinclude:: ../../../examples/finite_state_machine.py + :language: python + :linenos: + :lineno-start: 87 + :lines: 87-89 + +All possible cases of `like_bots` step was covered, let's implement finally step + +.. literalinclude:: ../../../examples/finite_state_machine.py + :language: python + :linenos: + :lineno-start: 92 + :lines: 92-102 + +And now you have covered all steps from the image, but you can make possibility to cancel conversation, lets do that via command or text + +.. literalinclude:: ../../../examples/finite_state_machine.py + :language: python + :linenos: + :lineno-start: 30 + :lines: 30-45 + +Complete example +---------------- +.. literalinclude:: ../../../examples/finite_state_machine.py + :language: python + :linenos: + + +Read more +========= + +.. toctree:: + + storages + + +.. _wiki: https://en.wikipedia.org/wiki/Finite-state_machine diff --git a/docs/dispatcher/finite_state_machine/storages.rst b/docs/dispatcher/finite_state_machine/storages.rst index f2fefe41..b730a77f 100644 --- a/docs/dispatcher/finite_state_machine/storages.rst +++ b/docs/dispatcher/finite_state_machine/storages.rst @@ -9,7 +9,7 @@ MemoryStorage ------------- .. autoclass:: aiogram.dispatcher.fsm.storage.memory.MemoryStorage - :members: __init__, from_url + :members: __init__ :member-order: bysource RedisStorage @@ -19,5 +19,20 @@ RedisStorage :members: __init__, from_url :member-order: bysource +Keys inside storage can be customized via key builders: + +.. autoclass:: aiogram.dispatcher.fsm.storage.redis.KeyBuilder + :members: + :member-order: bysource + +.. autoclass:: aiogram.dispatcher.fsm.storage.redis.DefaultKeyBuilder + :members: + :member-order: bysource + + Writing own storages ==================== + +.. autoclass:: aiogram.dispatcher.fsm.storage.base.BaseStorage + :members: + :member-order: bysource diff --git a/docs/dispatcher/index.rst b/docs/dispatcher/index.rst index 163fee1b..1d0f469e 100644 --- a/docs/dispatcher/index.rst +++ b/docs/dispatcher/index.rst @@ -22,5 +22,5 @@ Dispatcher is subclass of router and should be always is root router. dispatcher class_based_handlers/index filters/index - filters/magic_filters middlewares + finite_state_machine/index diff --git a/docs/utils/i18n.rst b/docs/utils/i18n.rst index 2c36c85d..773ac99b 100644 --- a/docs/utils/i18n.rst +++ b/docs/utils/i18n.rst @@ -126,7 +126,7 @@ Deal with Babel =============== Step 1: Extract messages -------------------- +------------------------ .. code-block:: bash @@ -148,7 +148,7 @@ is template where messages will be extracted and `messages` is translation domai Step 2: Init language ----------------- +--------------------- .. code-block:: bash diff --git a/docs/utils/keyboard.rst b/docs/utils/keyboard.rst index 98681e9f..e117de4f 100644 --- a/docs/utils/keyboard.rst +++ b/docs/utils/keyboard.rst @@ -2,23 +2,40 @@ Keyboard builder ================ -Inline Keyboard -=============== - -.. autoclass:: aiogram.utils.keyboard.InlineKeyboardBuilder - :members: __init__, buttons, copy, export, add, row, adjust, button, as_markup - :undoc-members: True - -Reply Keyboard -============== - -.. autoclass:: aiogram.utils.keyboard.ReplyKeyboardBuilder - :members: __init__, buttons, copy, export, add, row, adjust, button, as_markup - :undoc-members: True - - Base builder ============ .. autoclass:: aiogram.utils.keyboard.ReplyKeyboardBuilder :members: __init__, buttons, copy, export, add, row, adjust, button, as_markup :undoc-members: True + +Inline Keyboard +=============== + +.. autoclass:: aiogram.utils.keyboard.InlineKeyboardBuilder + :noindex: + + .. method:: button(text: str, url: Optional[str] = None, login_url: Optional[LoginUrl] = None, callback_data: Optional[Union[str, CallbackData]] = None, switch_inline_query: Optional[str] = None, switch_inline_query_current_chat: Optional[str] = None, callback_game: Optional[CallbackGame] = None, pay: Optional[bool] = None, **kwargs: Any) -> aiogram.utils.keyboard.InlineKeyboardBuilder + :noindex: + + Add new inline button to markup + + .. method:: as_markup() -> aiogram.types.inline_keyboard_markup.InlineKeyboardMarkup + :noindex: + + Construct an InlineKeyboardMarkup + +Reply Keyboard +============== + +.. autoclass:: aiogram.utils.keyboard.ReplyKeyboardBuilder + :noindex: + + .. method:: button(text: str, request_contact: Optional[bool] = None, request_location: Optional[bool] = None, request_poll: Optional[KeyboardButtonPollType] = None, **kwargs: Any) -> aiogram.utils.keyboard.ReplyKeyboardBuilder + :noindex: + + Add new button to markup + + .. method:: as_markup() -> aiogram.types.reply_keyboard_markup.ReplyKeyboardMarkup + :noindex: + + Construct an ReplyKeyboardMarkup diff --git a/examples/finite_state_machine.py b/examples/finite_state_machine.py index 2be912a0..0a540a0e 100644 --- a/examples/finite_state_machine.py +++ b/examples/finite_state_machine.py @@ -2,40 +2,34 @@ import asyncio import logging import sys from os import getenv +from typing import Any, Dict -from aiogram import Bot, Dispatcher, F -from aiogram.dispatcher.filters import Command +from aiogram import Bot, Dispatcher, F, Router, html from aiogram.dispatcher.fsm.context import FSMContext from aiogram.dispatcher.fsm.state import State, StatesGroup from aiogram.types import KeyboardButton, Message, ReplyKeyboardMarkup, ReplyKeyboardRemove -from aiogram.utils.keyboard import KeyboardBuilder -from aiogram.utils.markdown import hbold -GENDERS = ["Male", "Female", "Helicopter", "Other"] - -dp = Dispatcher() +form_router = Router() -# States class Form(StatesGroup): - name = State() # Will be represented in storage as 'Form:name' - age = State() # Will be represented in storage as 'Form:age' - gender = State() # Will be represented in storage as 'Form:gender' + name = State() + like_bots = State() + language = State() -@dp.message(Command(commands=["start"])) -async def cmd_start(message: Message, state: FSMContext): - """ - Conversation's entry point - """ - # Set state +@form_router.message(commands={"start"}) +async def command_start(message: Message, state: FSMContext) -> None: await state.set_state(Form.name) - await message.answer("Hi there! What's your name?") + await message.answer( + "Hi there! What's your name?", + reply_markup=ReplyKeyboardRemove(), + ) -@dp.message(Command(commands=["cancel"])) -@dp.message(F.text.lower() == "cancel") -async def cancel_handler(message: Message, state: FSMContext): +@form_router.message(commands={"cancel"}) +@form_router.message(F.text.casefold() == "cancel") +async def cancel_handler(message: Message, state: FSMContext) -> None: """ Allow user to cancel any action """ @@ -44,64 +38,86 @@ async def cancel_handler(message: Message, state: FSMContext): return logging.info("Cancelling state %r", current_state) - # Cancel state and inform user about it await state.clear() - # And remove keyboard (just in case) - await message.answer("Cancelled.", reply_markup=ReplyKeyboardRemove()) - - -@dp.message(Form.name) -async def process_name(message: Message, state: FSMContext): - """ - Process user name - """ - await state.update_data(name=message.text) - await state.set_state(Form.age) - await message.answer("How old are you?") - - -# Check age. Age gotta be digit -@dp.message(Form.age, ~F.text.isdigit()) -async def process_age_invalid(message: Message): - """ - If age is invalid - """ - return await message.answer("Age gotta be a number.\nHow old are you? (digits only)") - - -@dp.message(Form.age) -async def process_age(message: Message, state: FSMContext): - # Update state and data - await state.set_state(Form.gender) - await state.update_data(age=int(message.text)) - - # Configure ReplyKeyboardMarkup - constructor = KeyboardBuilder(KeyboardButton) - constructor.add(*(KeyboardButton(text=text) for text in GENDERS)).adjust(2) - markup = ReplyKeyboardMarkup( - resize_keyboard=True, selective=True, keyboard=constructor.export() - ) - await message.reply("What is your gender?", reply_markup=markup) - - -@dp.message(Form.gender) -async def process_gender(message: Message, state: FSMContext): - data = await state.update_data(gender=message.text) - await state.clear() - - # And send message await message.answer( - ( - f'Hi, nice to meet you, {hbold(data["name"])}\n' - f'Age: {hbold(data["age"])}\n' - f'Gender: {hbold(data["gender"])}\n' - ), + "Cancelled.", reply_markup=ReplyKeyboardRemove(), ) +@form_router.message(Form.name) +async def process_name(message: Message, state: FSMContext) -> None: + await state.update_data(name=message.text) + await state.set_state(Form.like_bots) + await message.answer( + f"Nice to meet you, {html.quote(message.text)}!\nDid you like to write bots?", + reply_markup=ReplyKeyboardMarkup( + keyboard=[ + [ + KeyboardButton(text="Yes"), + KeyboardButton(text="No"), + ] + ], + resize_keyboard=True, + ), + ) + + +@form_router.message(Form.like_bots, F.text.casefold() == "no") +async def process_dont_like_write_bots(message: Message, state: FSMContext) -> None: + data = await state.get_data() + await state.clear() + await message.answer( + "Not bad not terrible.\nSee you soon.", + reply_markup=ReplyKeyboardRemove(), + ) + await show_summary(message=message, data=data, positive=False) + + +@form_router.message(Form.like_bots, F.text.casefold() == "yes") +async def process_like_write_bots(message: Message, state: FSMContext) -> None: + await state.set_state(Form.language) + + await message.reply( + "Cool! I'm too!\nWhat programming language did you use for it?", + reply_markup=ReplyKeyboardRemove(), + ) + + +@form_router.message(Form.like_bots) +async def process_unknown_write_bots(message: Message, state: FSMContext) -> None: + await message.reply("I don't understand you :(") + + +@form_router.message(Form.language) +async def process_language(message: Message, state: FSMContext) -> None: + data = await state.update_data(language=message.text) + await state.clear() + text = ( + "Thank for all! Python is in my hearth!\nSee you soon." + if message.text.casefold() == "python" + else "Thank for information!\nSee you soon." + ) + await message.answer(text) + await show_summary(message=message, data=data) + + +async def show_summary(message: Message, data: Dict[str, Any], positive: bool = True) -> None: + name = data["name"] + language = data.get("language", "") + text = f"I'll keep in mind that, {html.quote(name)}, " + text += ( + f"you like to write bots with {html.quote(language)}." + if positive + else "you don't like to write bots, so sad..." + ) + await message.answer(text=text, reply_markup=ReplyKeyboardRemove()) + + async def main(): bot = Bot(token=getenv("TELEGRAM_TOKEN"), parse_mode="HTML") + dp = Dispatcher() + dp.include_router(form_router) await dp.start_polling(bot)