Add different shortcut methods for Text.as_kwargs() (#1657)

* Add different shortcut methods for Text.as_kwargs()

New methods:
- as_caption_kwargs()
- as_poll_question_kwargs()
- as_poll_explanation_kwargs()
- as_gift_text_kwargs()

* Add changelog

* Fix not passing linter checks

CHANGES/1657.feature.rst

@@ -0,0 +1 @@
+Add different shortcut methods for ``aiogram.utils.formatting.Text.as_kwargs()``

aiogram/utils/formatting.py

@@ -110,7 +110,7 @@ class Text(Iterable[NodeType]):
         parse_mode_key: str = "parse_mode",
     ) -> Dict[str, Any]:
         """
-        Render elements tree as keyword arguments for usage in the API call, for example:
+        Render element tree as keyword arguments for usage in an API call, for example:
 
         .. code-block:: python
 
@@ -132,6 +132,90 @@ class Text(Iterable[NodeType]):
             result[parse_mode_key] = None
         return result
 
+    def as_caption_kwargs(self, *, replace_parse_mode: bool = True) -> Dict[str, Any]:
+        """
+        Shortcut for :meth:`as_kwargs` for usage with API calls that take
+        ``caption`` as a parameter.
+
+        .. code-block:: python
+
+            entities = Text(...)
+            await message.answer_photo(**entities.as_caption_kwargs(), photo=phot)
+
+        :param replace_parse_mode: Will be passed to :meth:`as_kwargs`.
+        :return:
+        """
+        return self.as_kwargs(
+            text_key="caption",
+            entities_key="caption_entities",
+            replace_parse_mode=replace_parse_mode,
+        )
+
+    def as_poll_question_kwargs(self, *, replace_parse_mode: bool = True) -> Dict[str, Any]:
+        """
+        Shortcut for :meth:`as_kwargs` for usage with
+        method :class:`aiogram.methods.send_poll.SendPoll`.
+
+        .. code-block:: python
+
+            entities = Text(...)
+            await message.answer_poll(**entities.as_poll_question_kwargs(), options=options)
+
+        :param replace_parse_mode: Will be passed to :meth:`as_kwargs`.
+        :return:
+        """
+        return self.as_kwargs(
+            text_key="question",
+            entities_key="question_entities",
+            parse_mode_key="question_parse_mode",
+            replace_parse_mode=replace_parse_mode,
+        )
+
+    def as_poll_explanation_kwargs(self, *, replace_parse_mode: bool = True) -> Dict[str, Any]:
+        """
+        Shortcut for :meth:`as_kwargs` for usage with
+        method :class:`aiogram.methods.send_poll.SendPoll`.
+
+        .. code-block:: python
+
+            question_entities = Text(...)
+            explanation_entities = Text(...)
+            await message.answer_poll(
+                **question_entities.as_poll_question_kwargs(),
+                options=options,
+                **explanation_entities.as_poll_explanation_kwargs(),
+            )
+
+        :param replace_parse_mode: Will be passed to :meth:`as_kwargs`.
+        :return:
+        """
+        return self.as_kwargs(
+            text_key="explanation",
+            entities_key="explanation_entities",
+            parse_mode_key="explanation_parse_mode",
+            replace_parse_mode=replace_parse_mode,
+        )
+
+    def as_gift_text_kwargs(self, *, replace_parse_mode: bool = True) -> Dict[str, Any]:
+        """
+        Shortcut for :meth:`as_kwargs` for usage with
+        method :class:`aiogram.methods.send_gift.SendGift`.
+
+        .. code-block:: python
+
+            entities = Text(...)
+            await bot.send_gift(gift_id=gift_id, user_id=user_id, **entities.as_gift_text_kwargs())
+
+        :param replace_parse_mode: Will be passed to :meth:`as_kwargs`.
+        :return:
+        """
+        return self.as_kwargs(
+            text_key="text",
+            entities_key="text_entities",
+            parse_mode_key="text_parse_mode",
+            replace_parse_mode=replace_parse_mode,
+        )
+
     def as_html(self) -> str:
         """
         Render elements tree as HTML markup

tests/test_utils/test_formatting.py

@@ -172,6 +172,34 @@ class TestNode:
         assert "parse_mode" not in result
         assert "custom_parse_mode" in result
 
+    def test_as_caption_kwargs(self):
+        node = Text("Hello, ", Bold("World"), "!")
+        result = node.as_caption_kwargs()
+        assert "caption" in result
+        assert "caption_entities" in result
+        assert "parse_mode" in result
+
+    def test_as_poll_question_kwargs(self):
+        node = Text("Hello, ", Bold("World"), "!")
+        result = node.as_poll_question_kwargs()
+        assert "question" in result
+        assert "question_entities" in result
+        assert "question_parse_mode" in result
+
+    def test_as_poll_explanation_kwargs(self):
+        node = Text("Hello, ", Bold("World"), "!")
+        result = node.as_poll_explanation_kwargs()
+        assert "explanation" in result
+        assert "explanation_entities" in result
+        assert "explanation_parse_mode" in result
+
+    def test_as_as_gift_text_kwargs_kwargs(self):
+        node = Text("Hello, ", Bold("World"), "!")
+        result = node.as_gift_text_kwargs()
+        assert "text" in result
+        assert "text_entities" in result
+        assert "text_parse_mode" in result
+
     def test_as_html(self):
         node = Text("Hello, ", Bold("World"), "!")
         assert node.as_html() == "Hello, <b>World</b>!"