Repository: aiogram/aiogram

Issue:
Add as_caption_kwargs() method to aiogram.utils.formatting.Text
### aiogram version

3.x

### Problem

Methods like `Bot.send_document() ` use `caption` and `caption_enteties` parameters instead of `text` and `entities`. That results in repeating `Text(...).as_kwargs(text_key="caption", entities_key="caption_entities")` calls.

### Possible solution

I suggest introducing a shortcut method `as_caption_kwargs()` or something like that 

### Alternatives

_No response_

### Code example

```python3

```

### Additional information

_No response_


Discussion:
Feel free to contribute, you can add it and submit a pull request with the following changes.

---

I don't like adding every possible option because the API has more than just the parameter you suggested and other parameters may be added later to the API, but I don't mind adding them.

Other variants:
https://github.com/aiogram/aiogram/blob/3702b2a74457a6afd8c23c97dcf8a677c34d4e4d/aiogram/methods/send_gift.py#L32-L33
https://github.com/aiogram/aiogram/blob/3702b2a74457a6afd8c23c97dcf8a677c34d4e4d/aiogram/methods/send_poll.py#L42-L43
https://github.com/aiogram/aiogram/blob/3702b2a74457a6afd8c23c97dcf8a677c34d4e4d/aiogram/methods/send_poll.py#L56-L57




Patch:
diff --git a/CHANGES/1657.feature.rst b/CHANGES/1657.feature.rst
new file mode 100644
index 0000000000..cbb7c51bd3
--- /dev/null
+++ b/CHANGES/1657.feature.rst
@@ -0,0 +1,1 @@
+Add different shortcut methods for ``aiogram.utils.formatting.Text.as_kwargs()``
diff --git a/aiogram/utils/formatting.py b/aiogram/utils/formatting.py
index 929afc072a..88fa82b04e 100644
--- a/aiogram/utils/formatting.py
+++ b/aiogram/utils/formatting.py
@@ -110,7 +110,7 @@ def as_kwargs(
         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 @@ def as_kwargs(
             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


Test patch:
diff --git a/tests/test_utils/test_formatting.py b/tests/test_utils/test_formatting.py
index dbe07d1726..ffaef31e37 100644
--- a/tests/test_utils/test_formatting.py
+++ b/tests/test_utils/test_formatting.py
@@ -172,6 +172,34 @@ def test_as_kwargs_custom(self):
         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>!"