Update docs

docs/dispatcher/flags.rst

@@ -54,8 +54,9 @@ Via filters
 Use in middlewares
 ==================
 
-.. automodule:: aiogram.flags.getter
+.. automodule:: aiogram.dispatcher.flags
-    :members:
+    :members: extract_flags, get_flag, check_flags
+
 
 Example in middlewares
 ----------------------

docs/locale/en/LC_MESSAGES/dispatcher/flags.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: aiogram \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2022-10-01 22:51+0300\n"
+"POT-Creation-Date: 2023-01-07 23:33+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -59,20 +59,71 @@ msgstr ""
 msgid "Use in middlewares"
 msgstr ""
 
-#: aiogram.flags.getter:1 of
+#: aiogram.dispatcher.flags.check_flags:1 of
-msgid "FlagDecorator(flag: aiogram.dispatcher.flags.Flag)"
+msgid "Check flags via magic filter"
 msgstr ""
 
-#: ../../dispatcher/flags.rst:61
+#: aiogram.dispatcher.flags.check_flags aiogram.dispatcher.flags.extract_flags
+#: aiogram.dispatcher.flags.get_flag of
+msgid "Parameters"
+msgstr ""
+
+#: aiogram.dispatcher.flags.check_flags:3
+#: aiogram.dispatcher.flags.extract_flags:3 aiogram.dispatcher.flags.get_flag:3
+#: of
+msgid "handler object or data"
+msgstr ""
+
+#: aiogram.dispatcher.flags.check_flags:4 of
+msgid "instance of the magic"
+msgstr ""
+
+#: aiogram.dispatcher.flags.check_flags aiogram.dispatcher.flags.extract_flags
+#: aiogram.dispatcher.flags.get_flag of
+msgid "Returns"
+msgstr ""
+
+#: aiogram.dispatcher.flags.check_flags:5 of
+msgid "the result of magic filter check"
+msgstr ""
+
+#: aiogram.dispatcher.flags.extract_flags:1 of
+msgid "Extract flags from handler or middleware context data"
+msgstr ""
+
+#: aiogram.dispatcher.flags.extract_flags:4 of
+msgid "dictionary with all handler flags"
+msgstr ""
+
+#: aiogram.dispatcher.flags.get_flag:1 of
+msgid "Get flag by name"
+msgstr ""
+
+#: aiogram.dispatcher.flags.get_flag:4 of
+msgid "name of the flag"
+msgstr ""
+
+#: aiogram.dispatcher.flags.get_flag:5 of
+msgid "default value (None)"
+msgstr ""
+
+#: aiogram.dispatcher.flags.get_flag:6 of
+msgid "value of the flag or default"
+msgstr ""
+
+#: ../../dispatcher/flags.rst:62
 msgid "Example in middlewares"
 msgstr ""
 
-#: ../../dispatcher/flags.rst:74
+#: ../../dispatcher/flags.rst:75
 msgid "Use in utilities"
 msgstr ""
 
-#: ../../dispatcher/flags.rst:76
+#: ../../dispatcher/flags.rst:77
 msgid ""
 "For example you can collect all registered commands with handler "
 "description and then it can be used for generating commands help"
 msgstr ""
+
+#~ msgid "FlagDecorator(flag: aiogram.dispatcher.flags.Flag)"
+#~ msgstr ""

docs/locale/en/LC_MESSAGES/utils/keyboard.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: aiogram \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2022-10-14 19:29+0300\n"
+"POT-Creation-Date: 2023-01-07 23:24+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -21,7 +21,22 @@ msgstr ""
 msgid "Keyboard builder"
 msgstr ""
 
-#: ../../utils/keyboard.rst:6
+#: ../../utils/keyboard.rst:5
+msgid "Keyboard builder helps to dynamically generate markup."
+msgstr ""
+
+#: ../../utils/keyboard.rst:9
+msgid ""
+"Note that if you have static markup, it's best to define it explicitly "
+"rather than using builder, but if you have dynamic markup configuration, "
+"feel free to use builder as you wish."
+msgstr ""
+
+#: ../../utils/keyboard.rst:14
+msgid "Usage example"
+msgstr ""
+
+#: ../../utils/keyboard.rst:29
 msgid "Base builder"
 msgstr ""
 
@@ -80,7 +95,7 @@ msgstr ""
 msgid "When too much buttons is passed it will be separated to many rows"
 msgstr ""
 
-#: ../../utils/keyboard.rst:12
+#: ../../utils/keyboard.rst:35
 msgid "Inline Keyboard"
 msgstr ""
 
@@ -88,23 +103,23 @@ msgstr ""
 msgid "Inline keyboard builder inherits all methods from generic builder"
 msgstr ""
 
-#: ../../utils/keyboard.rst:20
+#: ../../utils/keyboard.rst:43
 msgid "Add new inline button to markup"
 msgstr ""
 
-#: ../../utils/keyboard.rst:25
+#: ../../utils/keyboard.rst:48
 msgid "Construct an InlineKeyboardMarkup"
 msgstr ""
 
-#: ../../utils/keyboard.rst:28
+#: ../../utils/keyboard.rst:51
 msgid "Reply Keyboard"
 msgstr ""
 
-#: ../../utils/keyboard.rst:36
+#: ../../utils/keyboard.rst:59
 msgid "Add new button to markup"
 msgstr ""
 
-#: ../../utils/keyboard.rst:41
+#: ../../utils/keyboard.rst:64
 msgid "Construct an ReplyKeyboardMarkup"
 msgstr ""
 

docs/locale/uk_UA/LC_MESSAGES/dispatcher/flags.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: aiogram \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2022-10-01 22:51+0300\n"
+"POT-Creation-Date: 2023-01-07 23:33+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -27,16 +27,17 @@ msgid ""
 "in-middlewares>`_ or special `utilities <#use-in-utilities>`_ to make "
 "classification of the handlers."
 msgstr ""
-"Маркери це, так звані мітки для обробників, які можна використовувати `міддлварах <#use-"
+"Маркери це, так звані мітки для обробників, які можна використовувати "
-"in-middlewares>`_ або в спеціальних `утилітах <#use-in-utilities>`_ щоб "
+"`міддлварах <#use-in-middlewares>`_ або в спеціальних `утилітах <#use-in-"
-"провести класифікацію обробників."
+"utilities>`_ щоб провести класифікацію обробників."
 
 #: ../../dispatcher/flags.rst:8
 msgid ""
 "Flags can be added to the handler via `decorators <#via-decorators>`_, "
 "`handlers registration <#via-handler-registration-method>`_ or `filters "
 "<via-filters>`_."
-msgstr "Маркери можна додати до обробника через `декоратори <#via-decorators>`_, "
+msgstr ""
+"Маркери можна додати до обробника через `декоратори <#via-decorators>`_, "
 "`реєстрацію обробників <#via-handler-registration-method>`_ або `фільтри "
 "<via-filters>`_."
 
@@ -64,20 +65,71 @@ msgstr "Через фільтри"
 msgid "Use in middlewares"
 msgstr "Використовувати в міддлварах"
 
-#: aiogram.flags.getter:1 of
+#: aiogram.dispatcher.flags.check_flags:1 of
-msgid "FlagDecorator(flag: aiogram.dispatcher.flags.Flag)"
+msgid "Check flags via magic filter"
 msgstr ""
 
-#: ../../dispatcher/flags.rst:61
+#: aiogram.dispatcher.flags.check_flags aiogram.dispatcher.flags.extract_flags
+#: aiogram.dispatcher.flags.get_flag of
+msgid "Parameters"
+msgstr ""
+
+#: aiogram.dispatcher.flags.check_flags:3
+#: aiogram.dispatcher.flags.extract_flags:3 aiogram.dispatcher.flags.get_flag:3
+#: of
+msgid "handler object or data"
+msgstr ""
+
+#: aiogram.dispatcher.flags.check_flags:4 of
+msgid "instance of the magic"
+msgstr ""
+
+#: aiogram.dispatcher.flags.check_flags aiogram.dispatcher.flags.extract_flags
+#: aiogram.dispatcher.flags.get_flag of
+msgid "Returns"
+msgstr ""
+
+#: aiogram.dispatcher.flags.check_flags:5 of
+msgid "the result of magic filter check"
+msgstr ""
+
+#: aiogram.dispatcher.flags.extract_flags:1 of
+msgid "Extract flags from handler or middleware context data"
+msgstr ""
+
+#: aiogram.dispatcher.flags.extract_flags:4 of
+msgid "dictionary with all handler flags"
+msgstr ""
+
+#: aiogram.dispatcher.flags.get_flag:1 of
+msgid "Get flag by name"
+msgstr ""
+
+#: aiogram.dispatcher.flags.get_flag:4 of
+msgid "name of the flag"
+msgstr ""
+
+#: aiogram.dispatcher.flags.get_flag:5 of
+msgid "default value (None)"
+msgstr ""
+
+#: aiogram.dispatcher.flags.get_flag:6 of
+msgid "value of the flag or default"
+msgstr ""
+
+#: ../../dispatcher/flags.rst:62
 msgid "Example in middlewares"
 msgstr "Приклад в міддлварах"
 
-#: ../../dispatcher/flags.rst:74
+#: ../../dispatcher/flags.rst:75
 msgid "Use in utilities"
 msgstr "Використання в утилітах"
 
-#: ../../dispatcher/flags.rst:76
+#: ../../dispatcher/flags.rst:77
 msgid ""
 "For example you can collect all registered commands with handler "
 "description and then it can be used for generating commands help"
-msgstr "Наприклад, ви можете зібрати всі зареєстровані команди з описом обробника, а потім його можна використовувати для створення довідки щодо команд"
+msgstr ""
+"Наприклад, ви можете зібрати всі зареєстровані команди з описом "
+"обробника, а потім його можна використовувати для створення довідки щодо "
+"команд"

docs/locale/uk_UA/LC_MESSAGES/utils/keyboard.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version:  aiogram\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2022-10-14 19:29+0300\n"
+"POT-Creation-Date: 2023-01-07 23:24+0200\n"
 "PO-Revision-Date: 2022-10-13 21:54+0300\n"
 "Last-Translator: \n"
 "Language-Team: \n"
@@ -20,7 +20,24 @@ msgstr ""
 msgid "Keyboard builder"
 msgstr "Конструктор клавіатури"
 
-#: ../../utils/keyboard.rst:6
+#: ../../utils/keyboard.rst:5
+msgid "Keyboard builder helps to dynamically generate markup."
+msgstr "Конструктор клавіатури допомагає динамічно генерувати розмітку"
+
+#: ../../utils/keyboard.rst:9
+msgid ""
+"Note that if you have static markup, it's best to define it explicitly "
+"rather than using builder, but if you have dynamic markup configuration, "
+"feel free to use builder as you wish."
+msgstr "Зауважте, що якщо у вас є статична розмітка, найкраще визначити її явно, "
+"а не використовувати конструктор, але якщо у вас є конфігурація динамічної розмітки, "
+"сміливо використовуйте конструктор на свій розсуд."
+
+#: ../../utils/keyboard.rst:14
+msgid "Usage example"
+msgstr "Приклад використання"
+
+#: ../../utils/keyboard.rst:29
 msgid "Base builder"
 msgstr "Базовий конструктор"
 
@@ -88,7 +105,7 @@ msgstr ""
 "Коли передано занадто багато кнопок, вони будуть розділені на багато "
 "рядків"
 
-#: ../../utils/keyboard.rst:12
+#: ../../utils/keyboard.rst:35
 msgid "Inline Keyboard"
 msgstr "Клавіатура під повідомленням(Inline Keyboard)"
 
@@ -98,22 +115,22 @@ msgstr ""
 "Конструктор клавіатури під повідомленням успадковує всі методи від "
 "універсального конструктора"
 
-#: ../../utils/keyboard.rst:20
+#: ../../utils/keyboard.rst:43
 msgid "Add new inline button to markup"
 msgstr "Додавання нової кнопки до розмітки"
 
-#: ../../utils/keyboard.rst:25
+#: ../../utils/keyboard.rst:48
 msgid "Construct an InlineKeyboardMarkup"
 msgstr "Створення InlineKeyboardMarkup"
 
-#: ../../utils/keyboard.rst:28
+#: ../../utils/keyboard.rst:51
 msgid "Reply Keyboard"
 msgstr "Клавіатура відповідей"
 
-#: ../../utils/keyboard.rst:36
+#: ../../utils/keyboard.rst:59
 msgid "Add new button to markup"
 msgstr "Додавання нової кнопки до розмітки"
 
-#: ../../utils/keyboard.rst:41
+#: ../../utils/keyboard.rst:64
 msgid "Construct an ReplyKeyboardMarkup"
 msgstr "Створення ReplyKeyboardMarkup"

docs/utils/keyboard.rst

@@ -2,6 +2,29 @@
 Keyboard builder
 ================
 
+Keyboard builder helps to dynamically generate markup.
+
+.. note::
+
+    Note that if you have static markup, it's best to define it explicitly rather than using builder,
+    but if you have dynamic markup configuration, feel free to use builder as you wish.
+
+
+Usage example
+=============
+
+.. code-block:: python
+
+    builder = InlineKeyboardBuilder()
+
+    for index in range(1, 11):
+        builder.button(text=f"Set {index}", callback_data=f"set:{index}")
+
+    builder.adjust(3, 2)
+
+    await message.answer("Some text here", reply_markup=builder.as_markup())
+
+
 Base builder
 ============
 .. autoclass:: aiogram.utils.keyboard.ReplyKeyboardBuilder