From 55479633115e3337f959f338ccd2e5d4d1585bf4 Mon Sep 17 00:00:00 2001 From: Anton Trotsenko <37223374+antos07@users.noreply.github.com> Date: Wed, 2 Apr 2025 22:16:55 +0200 Subject: [PATCH] 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 | 1 + aiogram/utils/formatting.py | 86 ++++++++++++++++++++++++++++- tests/test_utils/test_formatting.py | 28 ++++++++++ 3 files changed, 114 insertions(+), 1 deletion(-) create mode 100644 CHANGES/1657.feature.rst diff --git a/CHANGES/1657.feature.rst b/CHANGES/1657.feature.rst new file mode 100644 index 00000000..cbb7c51b --- /dev/null +++ b/CHANGES/1657.feature.rst @@ -0,0 +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 929afc07..88fa82b0 100644 --- a/aiogram/utils/formatting.py +++ b/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 diff --git a/tests/test_utils/test_formatting.py b/tests/test_utils/test_formatting.py index dbe07d17..ffaef31e 100644 --- a/tests/test_utils/test_formatting.py +++ b/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, World!"