Add support for text mentions in ParsedTextEntity

Support for text mentions was added in the Bot API 2.1 update, and this
commit brings support in the ParsedTextEntity.

Issue: GH-61

Author: Pietro Albini

botogram/objects/messages.py

@@ -44,6 +44,7 @@ class ParsedTextEntity(BaseObject):
     }
     optional = {
         "url": str,
+        "user": User,
     }
     replace_keys = {
         "url": "_url",  # Dynamically implemented
@@ -59,10 +60,12 @@ class ParsedTextEntity(BaseObject):
         "bot_command": "command",
         "text_link": "link",
         "url": "link",
+        "text_mention": "mention",
     }
     replace_types_inverse = {
         "command": "bot_command",
         "link": "text_link",
+        "mention": "text_mention",
     }
 
     def __init__(self, data, api=None, message=None):
@@ -120,9 +123,14 @@ def type(self, value):
                 self._type = "url"
             else:
                 self._type = "text_link"
-            return
 
-        if value in self.replace_types_inverse:
+        elif value == "mention":
+            if self.user is not None:
+                self._type = "text_mention"
+            else:
+                self._type = "mention"
+
+        elif value in self.replace_types_inverse:
             self._type = self.replace_types_inverse[value]
         else:
             self._type = value
@@ -153,8 +161,16 @@ def url(self):
             # Standard URLs
             url = self.text
         elif self.type == "mention":
+            # Detect the correct username
+            if self.user is not None and self.user.username is not None:
+                username = self.user.username
+            elif self.text.startswith("@"):
+                username = self.text[1:]
+            else:
+                return None
+
             # telegram.me URLs
-            return "https://telegram.me/%s" % self.text[1:]
+            return "https://telegram.me/%s" % username
         elif self.type == "email":
             # mailto: URL
             return "mailto:%s" % self.text

docs/api/telegram.rst

@@ -906,13 +906,14 @@ about its business.
 
       * **plain**: a plain string (with no formatting or special meaning)
 
-      * **mention**: a mention to another user (for example ``@pietroalbini``)
+      * **mention**: a mention to another user (can contain the username or the
+        full name, for example ``@pietroalbini`` or ``Pietro``)
 
       * **hashtag**: an hashtag (for example ``#pythonftw``)
 
       * **command**: a command sent to a bot (for example ``/help``)
 
-      * **url**: a link (the text can contain its label)
+      * **link** a link (the text can contain its label)
 
       * **email**: an email address (for example ``[email protected]``)
 
@@ -932,8 +933,14 @@ about its business.
    .. py:attribute:: url
 
       The attached URL for the entity. This includes the raw URL for the
-      **url** and **text_link** types, the ``telegram.me`` link for the
-      **mention** type, and the ``mailto:`` link for **email** type.
+      **url** type, the ``telegram.me`` link for the **mention** type (if the
+      user has an username), and the ``mailto:`` link for **email** type.
+
+   .. py:attribute:: user
+
+      The :py:class:`~botogram.User` mentioned in this entity. This isn't
+      always provided by Telegram, currently only if the mentioned user doesn't
+      have an username.
 
 .. py:class:: botogram.Message
 

tests/test_objects_messages.py

@@ -8,6 +8,7 @@
 import pytest
 
 import botogram.objects.messages
+import botogram.objects.chats
 
 
 def get_dummy_message(text):
@@ -127,6 +128,39 @@ def test_parsed_text_entity_type():
     entity.type = "link"
     assert entity._type == "text_link"
 
+    ############################################
+    #  A mention (which mutates as "mention")  #
+    ############################################
+
+    msg = get_dummy_message("@test_image")
+    entity.set_message(msg)
+
+    # Getter
+    entity._type = "mention"
+    assert entity.type == "mention"
+
+    # Setter
+    entity.type = "mention"
+    assert entity._type == "mention"
+
+    #################################################
+    #  A mention (which mutates as "text_mention")  #
+    #################################################
+
+    msg = get_dummy_message("@test_image")
+    entity.user = botogram.objects.chats.User({"id": 1, "first_name": "Test"})
+    entity.set_message(msg)
+
+    # Getter
+    entity._type = "text_mention"
+    assert entity.type == "mention"
+
+    # Setter
+    entity.type = "mention"
+    assert entity._type == "text_mention"
+
+    entity.user = None
+
 
 def test_parsed_text_entity_url():
     # Basic entity
@@ -142,12 +176,25 @@ def test_parsed_text_entity_url():
     entity.set_message(msg)
     assert entity.url == "https://www.example.com"
 
-    # Mention entity
+    # Mention entity with @usernames
     msg = get_dummy_message("@a_botogram_users_group")
     entity.type = "mention"
     entity.set_message(msg)
     assert entity.url == "https://telegram.me/a_botogram_users_group"
 
+    # Text mention entities without usernames
+    msg = get_dummy_message("A botogram users group!")
+    entity.user = botogram.objects.chats.User({"id": 1, "first_name": "Test"})
+    entity.type = "mention"
+    entity.set_message(msg)
+    assert entity.url is None
+
+    # Text mention entities with usernames
+    entity.user.username = "test_username"
+    assert entity.url == "https://telegram.me/test_username"
+
+    entity.user = None
+
     # Email entity
     msg = get_dummy_message("[email protected]")
     entity.type = "email"