Formatting tools (#1172)

* Added base implementation of formatting utility

* Refactored and added docs

* Added changelog

* Coverage

docs/api/methods/set_sticker_set_thumb.rst

@@ -1,44 +0,0 @@
-##################
-setStickerSetThumb
-##################
-
-Returns: :obj:`bool`
-
-.. automodule:: aiogram.methods.set_sticker_set_thumb
-    :members:
-    :member-order: bysource
-    :undoc-members: True
-
-
-Usage
-=====
-
-As bot method
--------------
-
-.. code-block::
-
-    result: bool = await bot.set_sticker_set_thumb(...)
-
-
-Method as object
-----------------
-
-Imports:
-
-- :code:`from aiogram.methods.set_sticker_set_thumb import SetStickerSetThumb`
-- alias: :code:`from aiogram.methods import SetStickerSetThumb`
-
-With specific bot
-~~~~~~~~~~~~~~~~~
-
-.. code-block:: python
-
-    result: bool = await bot(SetStickerSetThumb(...))
-
-As reply into Webhook in handler
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: python
-
-    return SetStickerSetThumb(...)

docs/utils/formatting.rst

@@ -0,0 +1,199 @@
+.. _formatting-tool
+
+==========
+Formatting
+==========
+
+Make your message formatting flexible and simple
+
+This instrument works on top of Message entities instead of using HTML or Markdown markups,
+you can easily construct your message and sent it to the Telegram without the need to
+remember tag parity (opening and closing) or escaping user input.
+
+Usage
+=====
+
+Basic scenario
+--------------
+
+Construct your message and send it to the Telegram.
+
+.. code-block:: python
+
+    content = Text("Hello, ", Bold(message.from_user.full_name), "!")
+    await message.answer(**content.as_kwargs())
+
+Is the same as the next example, but without usage markup
+
+.. code-block:: python
+
+    await message.answer(
+        text=f"Hello, <b>{html.quote(message.from_user.full_name)}!",
+        parse_mode=ParseMode.HTML
+    )
+
+Literally when you execute :code:`as_kwargs` method the Text object is converted
+into text :code:`Hello, Alex!` with entities list :code:`[MessageEntity(type='bold', offset=7, length=4)]`
+and passed into dict which can be used as :code:`**kwargs` in API call.
+
+The complete list of elements is listed `on this page below <#available-elements>`_.
+
+Advanced scenario
+-----------------
+
+On top of base elements can be implemented content rendering structures,
+so, out of the box aiogram has a few already implemented functions that helps you to format
+your messages:
+
+.. autofunction:: aiogram.utils.formatting.as_line
+
+.. autofunction:: aiogram.utils.formatting.as_list
+
+.. autofunction:: aiogram.utils.formatting.as_marked_list
+
+.. autofunction:: aiogram.utils.formatting.as_numbered_list
+
+.. autofunction:: aiogram.utils.formatting.as_section
+
+.. autofunction:: aiogram.utils.formatting.as_marked_section
+
+.. autofunction:: aiogram.utils.formatting.as_numbered_section
+
+.. autofunction:: aiogram.utils.formatting.as_key_value
+
+and lets complete them all:
+
+.. code-block:: python
+
+    content = as_list(
+        as_marked_section(
+            Bold("Success:"),
+            "Test 1",
+            "Test 3",
+            "Test 4",
+            marker="✅ ",
+        ),
+        as_marked_section(
+            Bold("Failed:"),
+            "Test 2",
+            marker="❌ ",
+        ),
+        as_marked_section(
+            Bold("Summary:"),
+            as_key_value("Total", 4),
+            as_key_value("Success", 3),
+            as_key_value("Failed", 1),
+            marker="  ",
+        ),
+        HashTag("#test"),
+        sep="\n\n",
+    )
+
+Will be rendered into:
+
+  **Success:**
+
+  ✅ Test 1
+
+  ✅ Test 3
+
+  ✅ Test 4
+
+  **Failed:**
+
+  ❌ Test 2
+
+  **Summary:**
+
+   **Total**: 4
+
+   **Success**: 3
+
+   **Failed**: 1
+
+  #test
+
+
+Or as HTML:
+
+.. code-block:: html
+
+    <b>Success:</b>
+    ✅ Test 1
+    ✅ Test 3
+    ✅ Test 4
+
+    <b>Failed:</b>
+    ❌ Test 2
+
+    <b>Summary:</b>
+      <b>Total:</b> 4
+      <b>Success:</b> 3
+      <b>Failed:</b> 1
+
+    #test
+
+Available methods
+=================
+
+.. autoclass:: aiogram.utils.formatting.Text
+    :members:
+    :show-inheritance:
+    :member-order: bysource
+    :special-members: __init__
+
+
+Available elements
+==================
+
+.. autoclass:: aiogram.utils.formatting.Text
+    :show-inheritance:
+    :noindex:
+
+.. autoclass:: aiogram.utils.formatting.HashTag
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.CashTag
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.BotCommand
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.Url
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.Email
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.PhoneNumber
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.Bold
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.Italic
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.Underline
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.Strikethrough
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.Spoiler
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.Code
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.Pre
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.TextLink
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.TextMention
+    :show-inheritance:
+
+.. autoclass:: aiogram.utils.formatting.CustomEmoji
+    :show-inheritance:

docs/utils/index.rst

@@ -9,3 +9,4 @@ Utils
     chat_action
     web_app
     callback_answer
+    formatting