Merge branch 'develop' into feature/groups

Author: Tishka17

.flake8

@@ -16,6 +16,8 @@ ignore=
     A002,
     # A003 class attribute "id" is shadowing a python builtin
     A003,
+    # A005 A module is shadowing a Python builtin module
+    A005,
     # D100 Missing docstring in public module
     D100,
     # D101 Missing docstring in public class

.github/workflows/setup.yml

@@ -6,8 +6,12 @@ name: CI
 on:
   push:
     branches: [develop]
+    paths-ignore:
+      - "docs/**"
   pull_request:
     branches: [develop]
+    paths-ignore:
+      - "docs/**"
 
 jobs:
   cpython:
@@ -21,22 +25,24 @@ jobs:
           - "3.9"
           - "3.10"
           - "3.11"
+          - "3.12"
 
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python ${{ matrix.python-version }} on ${{ matrix.os }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install . -r requirements_dev.txt
+          pip install diagrams
 
       - name: Run flake8
         run: |
-          python -m flake8 src/aiogram_dialog tests
+          python -m flake8 src/aiogram_dialog tests example
 
       - name: Run tests
         run: |

README.md

@@ -57,7 +57,7 @@ Each window consists of:
 
 
 ```python
-from aiogram.filters.state import StatesGroup, State
+from aiogram.fsm.state import StatesGroup, State
 from aiogram_dialog.widgets.text import Format, Const
 from aiogram_dialog.widgets.kbd import Button
 from aiogram_dialog import Window
@@ -84,7 +84,7 @@ Window(
 Window itself can do nothing, just prepares message. To use it you need dialog:
 
 ```python
-from aiogram.filters.state import StatesGroup, State
+from aiogram.fsm.state import StatesGroup, State
 from aiogram_dialog import Dialog, Window
 
 
@@ -122,7 +122,7 @@ For example in `/start` command handler:
 async def user_start(message: Message, dialog_manager: DialogManager):
     await dialog_manager.start(MySG.first, mode=StartMode.RESET_STACK)
 
-dp.message.register(user_start, F.text == "/start")
+dp.message.register(user_start, CommandStart())
 ```
 
 > **Info:** Always set `mode=StartMode.RESET_STACK` in your top level start command. Otherwise, dialogs are stacked just as they do

docs/conf.py

@@ -14,11 +14,12 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import datetime
 
 # -- Project information -----------------------------------------------------
 
 project = 'aiogram-dialog'
-copyright = '2021, Tishka17'
+copyright = f'{datetime.date.today().year}, Tishka17'
 author = 'Tishka17'
 master_doc = 'index'
 
@@ -29,6 +30,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx_copybutton',
 ]
 autodoc_type_aliases = {
 }
@@ -42,15 +44,13 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 html_theme = 'furo'
 
-
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

docs/helper_tools/index.rst

@@ -6,7 +6,7 @@ State diagram
 
 You can generate image with your states and transitions.
 
-Firstly you need to install [graphviz](https://graphviz.org/download/) into your system.
+Firstly you need to install `graphviz <https://graphviz.org/download/>`_ into your system.
 Check installation instructions on official site.
 
 Install library with tools extras:
@@ -78,4 +78,4 @@ Just run ``aiogram-dialog-preview`` command passing path to ``Dispatcher``/``Rou
 
 .. literalinclude:: ./web_preview.sh
 
-See console output to get URL and error logs
+See console output to get URL and error logs

docs/how_are_messages_updated/example.py

@@ -0,0 +1,10 @@
+async def open_next_window(event, widget, manager: DialogManager):
+    manager.show_mode = ShowMode.SEND
+    await manager.next()
+
+
+async def switch_to_another_window(event, widget, manager: DialogManager):
+    await manager.switch_to(
+        state=SomeStatesSG.SomeState,
+        show_mode=ShowMode.SEND,
+    )

docs/how_are_messages_updated/index.rst

@@ -0,0 +1,17 @@
+How are messages updated
+=====================
+
+ShowMode
+********************
+
+Currently, to manage the update of the dialog, we use the feature called ShowMode.
+
+When we need to change show mode we can just use show_mode setter on DialogManager or pass it in DialogManager methods (.start, .update, .switch_to, etc.)
+
+.. literalinclude:: ./example.py
+
+.. important::
+
+    ShowMode changes only for the next update and then returns to AUTO mode.
+
+.. autoclass:: aiogram_dialog.api.entities.modes.ShowMode(Enum)

docs/index.rst

@@ -2,15 +2,17 @@ aiogram-dialog
 =============================================
 
 .. toctree::
-   :caption: Contents:
+    :maxdepth: 3
+    :caption: Contents:
 
-   overview/index
-   quickstart/index
-   widgets/index
-   transitions/index
-   helper_tools/index
-   migration
-   faq
+    overview/index
+    quickstart/index
+    widgets/index
+    transitions/index
+    how_are_messages_updated/index
+    helper_tools/index
+    migration
+    faq
 
 .. toctree::
     :hidden:

docs/quickstart/index.rst

@@ -8,7 +8,7 @@ Install library:
 .. literalinclude:: ./install.sh
 
 Let's assume that you have created your aiogram bot with dispatcher and states storage as you normally do. When we setup our ``DialogRegistry`` to use that dispatcher.
-It is important you have proper storage because **aiogram_dialog** uses ``FSMContext`` internally to store it state:
+It is important you have proper storage because **aiogram_dialog** uses ``FSMContext`` internally to store its state:
 
 .. literalinclude:: ./bot.py
 

docs/resources/toggle.gif

@@ -105,3 +105,21 @@ To close a dialog you have to methods:
 Parent dialog has no access to the context of child one. But you can pass some data as a result to ``done()`` method and then process it in ``on_process_result`` callback of parent dialog.
 
 .. literalinclude:: ./done.py
+
+LaunchMode
+=================
+
+**LaunchMode** is a mode for launching new dialogs. It helps manage the dialog stack and ensures dialogs are handled appropriately based on their type.
+
+.. literalinclude:: ./launchmode.py
+
+.. autoclass:: aiogram_dialog.api.entities.launch_mode.LaunchMode(Enum)
+
+StartMode
+=================
+
+**StartMode** is a mode for starting new dialog. It defines how the current stack should be handled when initiating a new dialog.
+
+.. literalinclude:: ./startmode.py
+
+.. autoclass:: aiogram_dialog.api.entities.modes.StartMode(Enum)

docs/transitions/index.rst

@@ -0,0 +1,4 @@
+dialog = Dialog(
+    Window(...),
+    launch_mode=LaunchMode.SINGLE_TOP,
+)

docs/transitions/launchmode.py

@@ -0,0 +1,2 @@
+async def start(message: Message, dialog_manager: DialogManager):
+    await dialog_manager.start(..., mode=StartMode.RESET_STACK)

docs/transitions/startmode.py

@@ -9,7 +9,7 @@ You can create custom widgets if your are not satisfied with existing ones.
 If you are making Keyboard widget it is important to create ``InlineKeyboardButton`` instances on each rendering instead of reusing same instance. This is because dialogs modify ``callback_data`` in it.
 
 
-* :ref:`SwitchInlineQueryCurrentChat<_switch_inline_query_current_chat>` - opens inline query in current chat
+* :ref:`SwitchInlineQueryCurrentChat<switch_inline_query_current_chat>` - opens inline query in current chat
 
 .. toctree::
     :hidden:

docs/widgets/custom_widgets/index.rst

@@ -19,7 +19,7 @@ Also there are 2 general types:
 * ``Whenable`` can be hidden or shown depending on data or some conditions. Currently all widgets are whenable.
   See: :ref:`Hiding widgets<hiding_widgets>`
 * ``Actionable`` is any widget with action (currently only any type of keyboard). It has ``id`` and can be found by that id.
-  It recommended for all stateful widgets (e.g Checkboxes) to have unique id within dialog.
+  It's recommended for all stateful widgets (e.g Checkboxes) to have unique id within dialog.
   Buttons with different behavior also must have different ids.
 
 .. note::
@@ -30,12 +30,12 @@ Also there are 2 general types:
   * ``hello world``, ``my:item``, ``птичка`` - invalid ids
 
 .. toctree::
+    :maxdepth: 1
+
     passing_data/index
     text/index
     keyboard/index
     input/index
     media/index
     hiding/index
     custom_widgets/index
-
-

docs/widgets/index.rst

@@ -0,0 +1,32 @@
+from aiogram.fsm.state import State, StatesGroup
+from aiogram.types import ContentType, Message
+from aiogram_dialog import (
+    Dialog,
+    Window,
+    DialogManager,
+)
+from aiogram_dialog.widgets.input import MessageInput
+from aiogram_dialog.widgets.text import Const
+
+
+class Main(StatesGroup):
+    document = State()
+
+
+async def document_handler(
+        message: Message,
+        message_input: MessageInput,
+        manager: DialogManager,
+):
+    manager.dialog_data["document"] = message.document
+    await message.answer(f"Your document has been verified!")
+    await manager.done()
+
+
+dialog = Dialog(
+    Window(
+        Const("Submit your document for verification:"),
+        MessageInput(document_handler, content_types=[ContentType.DOCUMENT]),
+        state=Main.document,
+    ),
+)

docs/widgets/input/message_input/example.py

@@ -2,3 +2,14 @@
 
 MessageInput
 *************
+
+The **MessageInput** widget allows you to process incoming messages in the context of a dialog.
+
+You can use filters like in `aiogram <https://docs.aiogram.dev/en/latest/dispatcher/filters/index.html>`_ to divide logic into multiple inputs.
+
+Code example:
+
+.. literalinclude:: ./example.py
+
+.. autoclass:: aiogram_dialog.widgets.input.base.MessageInput
+   :special-members: __init__

docs/widgets/input/message_input/index.rst

@@ -0,0 +1,63 @@
+from typing import Any
+
+from aiogram.fsm.state import State, StatesGroup
+from aiogram.types import Message
+from aiogram_dialog import (
+    Dialog,
+    DialogManager,
+    Window,
+)
+from aiogram_dialog.widgets.input import TextInput
+from aiogram_dialog.widgets.kbd import Next
+from aiogram_dialog.widgets.text import Const, Jinja
+
+
+class SG(StatesGroup):
+    age = State()
+    country = State()
+    result = State()
+
+
+async def error(
+        message: Message,
+        dialog_: Any,
+        manager: DialogManager,
+        error_: ValueError
+):
+    await message.answer("Age must be a number!")
+
+
+async def getter(dialog_manager: DialogManager, **kwargs):
+    return {
+        "age": dialog_manager.find("age").get_value(),
+        "country": dialog_manager.find("country").get_value(),
+    }
+
+
+dialog = Dialog(
+    Window(
+        Const("Enter your country:"),
+        TextInput(id="country", on_success=Next()),
+        state=SG.country,
+    ),
+    Window(
+        Const("Enter your age:"),
+        TextInput(
+            id="age",
+            on_error=error,
+            on_success=Next(),
+            type_factory=int,
+        ),
+        state=SG.age,
+    ),
+    Window(
+        Jinja(
+            "<b>You entered</b>:\n\n"
+            "<b>age</b>: {{age}}\n"
+            "<b>country</b>: {{country}}\n"
+        ),
+        state=SG.result,
+        getter=getter,
+        parse_mode="html",
+    ),
+)

docs/widgets/input/text_input/example.py

@@ -3,6 +3,19 @@
 TextInput
 *************
 
+The **TextInput** widget automatically saving and validating text for later processing in the dialog.
+
+Parameters:
+
+* ``type_factory``: allows for input validation and automatic conversion to the specified type.
+* ``on_success``: for handling successful input.
+* ``on_error``:  for error handling, will work if ``type_factory`` throws ValueError.
+* ``filter``: support `aiogram <https://docs.aiogram.dev/en/latest/dispatcher/filters/index.html>`_ filters.
+
+Code example:
+
+.. literalinclude:: ./example.py
+
 .. autoclass:: aiogram_dialog.widgets.input.text.OnSuccess
    :special-members: __call__