Added the MessageEntity type “date_time”, allowing to show a formatted date and time to the user. (#225)

Author: SpEcHiDe

docs/source/topics/text-formatting.rst

@@ -17,6 +17,8 @@ Pyrogram uses a custom Markdown dialect for text formatting which adds some uniq
 texts easier in both Markdown and HTML. You can send sophisticated text messages and media captions using a
 variety of decorations that can also be nested in order to combine multiple styles together.
 
+`The official BOT API style HTML formatting is also supported <https://core.telegram.org/bots/api#html-style>`__
+
 
 -----
 
@@ -40,7 +42,97 @@ list of the basic styles currently supported by Pyrogram.
 - spoiler
 - `text URL <https://telegramplayground.github.io/pyrogram/>`_
 - `user text mention <tg://user?id=123456789>`_
+- :emoji:`👍`
+
+
+HTML Style
+----------
+
+To strictly use this mode, pass :obj:`~pyrogram.enums.HTML` to the *parse_mode* parameter when using
+:meth:`~pyrogram.Client.send_message`. The following tags are currently supported:
+
+.. code-block:: text
+
+    <b>bold</b>, <strong>bold</strong>
+
+    <i>italic</i>, <em>italic</em>
+
+    <u>underline</u>
+
+    <s>strike</s>, <del>strike</del>, <strike>strike</strike>
+
+    <tg-spoiler>spoiler</tg-spoiler>
+
+    <a href="https://telegramplayground.github.io/pyrogram/">text URL</a>
+
+    <a href="tg://user?id=123456789">inline mention</a>
+
+    <code>inline fixed-width code</code>
+
+    <tg-emoji emoji-id="5469770542288478598">👍</tg-emoji>
+
+    <pre>
+        <code class="language-python">
+            pre-formatted fixed-width code block written in the Python programming language
+        </code>
+    </pre>
+
+**Example**:
 
+.. code-block:: python
+
+    from pyrogram.enums import ParseMode
+
+    await app.send_message(
+        chat_id="me",
+        text=(
+            "<b>bold</b>, <strong>bold</strong>"
+            "<i>italic</i>, <em>italic</em>"
+            "<u>underline</u>, <ins>underline</ins>"
+            "<s>strike</s>, <strike>strike</strike>, <del>strike</del>"
+            "<tg-spoiler>spoiler</tg-spoiler>\n\n"
+
+            "<b>bold <i>italic bold <s>italic bold strike <tg-spoiler>italic bold strike spoiler</tg-spoiler></s> <u>underline italic bold</u></i> bold</b>\n\n"
+
+            "<a href=\"https://telegramplayground.github.io/pyrogram/\">inline URL</a> "
+            "<a href=\"tg://user?id=23122162\">inline mention of a user</a>\n"
+            "<tg-emoji emoji-id=5469770542288478598>👍</tg-emoji> "
+            "<code>inline fixed-width code</code> "
+            "<pre>pre-formatted fixed-width code block</pre>\n\n"
+            "</pre><code class='language-python'>"
+            "for i in range(10):\n"
+            "    print(i)"
+            "</code></pre>\n\n"
+
+            "<blockquote>Block quotation started"
+            "Block quotation continued"
+            "The last line of the block quotation</blockquote>"
+            "<blockquote expandable>Expandable block quotation started"
+            "Expandable block quotation continued"
+            "Expandable block quotation continued"
+            "Hidden by default part of the block quotation started"
+            "Expandable block quotation continued"
+            "The last line of the block quotation</blockquote>"
+        ),
+        parse_mode=ParseMode.HTML
+    )
+
+.. note::
+
+    All ``<``, ``>`` and ``&`` symbols that are not a part of a tag or an HTML entity must be replaced with the
+    corresponding HTML entities (``<`` with ``&lt;``, ``>`` with ``&gt;`` and ``&`` with ``&amp;``). You can use this
+    snippet to quickly escape those characters:
+
+    .. code-block:: python
+
+        text = "<my & text>"
+        text = text.replace("<", "&lt;").replace("&", "&amp;")
+
+        print(text)
+
+    .. code-block:: text
+
+        &lt;my &amp; text>
 
 
 Markdown Style
@@ -107,11 +199,12 @@ To strictly use this mode, pass :obj:`~pyrogram.enums.ParseMode.MARKDOWN` to the
             "~~strike~~, "
             "||spoiler||, "
             "[URL](https://telegramplayground.github.io/pyrogram/), "
+            "![👍](tg://emoji?id=5469770542288478598)"
             "`code`, "
-            "```"
+            "```py"
             "for i in range(10):\n"
             "    print(i)"
-            "```"
+            "```\n"
 
             ">blockquote\n"
 
@@ -135,96 +228,6 @@ To strictly use this mode, pass :obj:`~pyrogram.enums.ParseMode.MARKDOWN` to the
         parse_mode=ParseMode.MARKDOWN
     )
 
-HTML Style
-----------
-
-To strictly use this mode, pass :obj:`~pyrogram.enums.HTML` to the *parse_mode* parameter when using
-:meth:`~pyrogram.Client.send_message`. The following tags are currently supported:
-
-.. code-block:: text
-
-    <b>bold</b>, <strong>bold</strong>
-
-    <i>italic</i>, <em>italic</em>
-
-    <u>underline</u>
-
-    <s>strike</s>, <del>strike</del>, <strike>strike</strike>
-
-    <spoiler>spoiler</spoiler>
-
-    <a href="https://telegramplayground.github.io/pyrogram/">text URL</a>
-
-    <a href="tg://user?id=123456789">inline mention</a>
-
-    <code>inline fixed-width code</code>
-
-    <emoji id="12345678901234567890">🔥</emoji>
-
-    <pre language="py">
-    pre-formatted
-      fixed-width
-        code block
-    </pre>
-
-**Example**:
-
-.. code-block:: python
-
-    from pyrogram.enums import ParseMode
-
-    await app.send_message(
-        chat_id="me",
-        text=(
-            "<b>bold</b>, <strong>bold</strong>"
-            "<i>italic</i>, <em>italic</em>"
-            "<u>underline</u>, <ins>underline</ins>"
-            "<s>strike</s>, <strike>strike</strike>, <del>strike</del>"
-            "<spoiler>spoiler</spoiler>\n\n"
-
-            "<b>bold <i>italic bold <s>italic bold strike <spoiler>italic bold strike spoiler</spoiler></s> <u>underline italic bold</u></i> bold</b>\n\n"
-
-            "<a href=\"https://telegramplayground.github.io/pyrogram/\">inline URL</a> "
-            "<a href=\"tg://user?id=23122162\">inline mention of a user</a>\n"
-            "<emoji id=5368324170671202286>👍</emoji> "
-            "<code>inline fixed-width code</code> "
-            "<pre>pre-formatted fixed-width code block</pre>\n\n"
-            "<pre language='py'>"
-            "for i in range(10):\n"
-            "    print(i)"
-            "</pre>\n\n"
-
-            "<blockquote>Block quotation started"
-            "Block quotation continued"
-            "The last line of the block quotation</blockquote>"
-            "<blockquote expandable>Expandable block quotation started"
-            "Expandable block quotation continued"
-            "Expandable block quotation continued"
-            "Hidden by default part of the block quotation started"
-            "Expandable block quotation continued"
-            "The last line of the block quotation</blockquote>"
-        ),
-        parse_mode=ParseMode.HTML
-    )
-
-.. note::
-
-    All ``<``, ``>`` and ``&`` symbols that are not a part of a tag or an HTML entity must be replaced with the
-    corresponding HTML entities (``<`` with ``&lt;``, ``>`` with ``&gt;`` and ``&`` with ``&amp;``). You can use this
-    snippet to quickly escape those characters:
-
-    .. code-block:: python
-
-        import html
-
-        text = "<my text>"
-        text = html.escape(text)
-
-        print(text)
-
-    .. code-block:: text
-
-        &lt;my text&gt;
 
 Different Styles
 ----------------
@@ -272,6 +275,13 @@ Result:
 Nested and Overlapping Entities
 -------------------------------
 
+.. warning::
+
+    The Markdown style is not recommended for complex text formatting.
+
+    If you want to use complex text formatting such as nested entities, overlapping entities use the HTML style instead.
+
+
 You can also style texts with more than one decoration at once by nesting entities together. For example, you can send
 a text message with both :bold-underline:`bold and underline` styles, or a text that has both :strike-italic:`italic and
 strike` styles, and you can still combine both Markdown and HTML together.

pyrogram/enums/message_entity_type.py

@@ -86,5 +86,8 @@ class MessageEntityType(AutoName):
     BANK_CARD = raw.types.MessageEntityBankCard
     "Bank card text"
 
+    DATE_TIME = raw.types.MessageEntityFormattedDate
+    "Formatted date and time"
+
     UNKNOWN = raw.types.MessageEntityUnknown
     "Unknown message entity type"

pyrogram/parser/__init__.py

@@ -1,5 +1,6 @@
 #  Pyrogram - Telegram MTProto API Client Library for Python
-#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
+#  Copyright (C) 2017-2024 Dan <https://github.com/delivrance>
+#  Copyright (C) 2026-present <https://github.com/TelegramPlayGround>
 #
 #  This file is part of Pyrogram.
 #

pyrogram/parser/html.py

@@ -1,5 +1,6 @@
 #  Pyrogram - Telegram MTProto API Client Library for Python
-#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
+#  Copyright (C) 2017-2024 Dan <https://github.com/delivrance>
+#  Copyright (C) 2026-present <https://github.com/TelegramPlayGround>
 #
 #  This file is part of Pyrogram.
 #
@@ -51,19 +52,34 @@ def handle_starttag(self, tag, attrs):
             entity = raw.types.MessageEntityBold
         elif tag in ["i", "em"]:
             entity = raw.types.MessageEntityItalic
-        elif tag == "u":
+        elif tag in ["u", "ins"]:
             entity = raw.types.MessageEntityUnderline
         elif tag in ["s", "del", "strike"]:
             entity = raw.types.MessageEntityStrike
         elif tag == "blockquote":
             entity = raw.types.MessageEntityBlockquote
             extra["collapsed"] = bool("expandable" in attrs.keys())
-        elif tag == "code":
-            entity = raw.types.MessageEntityCode
         elif tag == "pre":
             entity = raw.types.MessageEntityPre
             extra["language"] = attrs.get("language", "")
-        elif tag == "spoiler":
+        elif tag == "code":
+            entity = raw.types.MessageEntityCode
+            _class = attrs.get("class", "")
+            active_pres = self.tag_entities.get("pre", [])
+            # Check if this <code> block is nested inside an active <pre>
+            if active_pres:
+                if _class.startswith("language-"):
+                    # Update the language of the currently open <pre> entity
+                    active_pres[-1].language = _class[9:] # 9 is the length of "language-"
+                    
+                # Return early to intentionally skip creating a nested CODE entity.
+                # (When handle_endtag hits </code>, it will safely ignore it).
+                return
+            # If not inside a <pre>, treat it as a standard inline code block
+            entity = raw.types.MessageEntityCode
+        elif tag in ["spoiler", "tg-spoiler"]:
+            entity = raw.types.MessageEntitySpoiler
+        elif tag == "span" and attrs.get("class", "") == "tg-spoiler":
             entity = raw.types.MessageEntitySpoiler
         elif tag == "a":
             url = attrs.get("href", "")
@@ -80,6 +96,15 @@ def handle_starttag(self, tag, attrs):
             entity = raw.types.MessageEntityCustomEmoji
             custom_emoji_id = int(attrs.get("id"))
             extra["document_id"] = custom_emoji_id
+        elif tag == "tg-emoji":
+            entity = raw.types.MessageEntityCustomEmoji
+            custom_emoji_id = int(attrs.get("emoji-id"))
+            extra["document_id"] = custom_emoji_id
+        elif tag == "tg-time":
+            entity = raw.types.MessageEntityFormattedDate
+            extra["date"] = int(attrs.get("unix"))
+            date_time_format = attrs.get("format", "")
+            extra = utils.parse_date_time_format_tl(extra, date_time_format)
         else:
             return
 
@@ -176,18 +201,15 @@ def parse_one(entity):
             elif entity_type == MessageEntityType.PRE:
                 name = entity_type.name.lower()
                 language = getattr(entity, "language", "") or ""
-                start_tag = f'<{name} language="{language}">' if language else f"<{name}>"
-                end_tag = f"</{name}>"
-            elif entity_type == MessageEntityType.BLOCKQUOTE:
-                name = entity_type.name.lower()
-                start_tag = f"<{name}>"
-                end_tag = f"</{name}>"
+                start_tag = f'<pre><code class="language-{language}">' if language else f"<{name}>"
+                end_tag = f"</code></pre>" if language else f"</{name}>"
             elif entity_type == MessageEntityType.EXPANDABLE_BLOCKQUOTE:
                 name = "blockquote"
                 start_tag = f"<{name} expandable>"
                 end_tag = f"</{name}>"
             elif entity_type in (
                 MessageEntityType.CODE,
+                MessageEntityType.BLOCKQUOTE,
                 MessageEntityType.SPOILER,
             ):
                 name = entity_type.name.lower()
@@ -203,8 +225,13 @@ def parse_one(entity):
                 end_tag = "</a>"
             elif entity_type == MessageEntityType.CUSTOM_EMOJI:
                 custom_emoji_id = entity.custom_emoji_id
-                start_tag = f'<emoji id="{custom_emoji_id}">'
+                start_tag = f'<tg-emoji emoji-id="{custom_emoji_id}">'
                 end_tag = "</emoji>"
+            elif entity_type == MessageEntityType.DATE_TIME:
+                date = entity.unix_time
+                dtf = entity.date_time_format
+                start_tag = f'<tg-time unix="{date}" format="{dtf}">'
+                end_tag = "</tg-time>"
             else:
                 return