Add support for Message.parse_text

This new attribute contains a list of all the parsed entities contained
in the message (if they're provided by Telegram). This allows, for
example, to get all the usernames contained in the message, or generate
a render of the message including bold, italics and so.

Fixes: GH-59

Author: Pietro Albini

botogram/objects/messages.py

@@ -16,6 +16,211 @@
                    Location
 
 
+def _require_message(func):
+    """Decorator which forces the object to have an attached message"""
+    @utils.wraps(func)
+    def __(self, *args, **kwargs):
+        if not hasattr(self, "_message") or self._message is None:
+            raise RuntimeError("A message must be attached to this object")
+        return func(self, *args, **kwargs)
+    return __
+
+
+class ParsedTextEntity(BaseObject):
+    """Telegram API representation of an entity in a text message
+
+    This was originally called MessageEntity by Telegram
+    https://core.telegram.org/bots/api#messageentity
+    """
+
+    required = {
+        "type": str,
+        "offset": int,
+        "length": int,
+    }
+    optional = {
+        "url": str,
+    }
+    replace_keys = {
+        "url": "_url",  # Dynamically implemented
+
+        # Private attributes, use the ``text`` one
+        "offset": "_offset",
+        "length": "_length",
+    }
+
+
+    def __init__(self, data, api=None, message=None):
+        super().__init__(data, api)
+
+        self._message = message
+
+    def __str__(self):
+        return self.text
+
+    def __repr__(self):
+        if self._message is not None:
+            return '<ParsedTextEntity %s: "%s">' % (self.type, self.text)
+        else:
+            return '<ParsedTextEntity %s from %s to %s>' % (
+                self.type,
+                self._offset,
+                self._offset + self._length
+            )
+
+    def __len__(self):
+        return self._length
+
+    def set_message(self, message):
+        """Set the message instance related to this object"""
+        self._message = message
+
+    @property
+    @_require_message
+    def text(self):
+        """Get the text of the message"""
+        if self._message.text is None:
+            raise ValueError("The message must have a text")
+
+        start = self._offset
+        stop = start + self._length
+
+        if stop > len(self._message.text):
+            raise ValueError("The message is too short!")
+
+        return self._message.text[start:stop]
+
+    @property
+    @_require_message
+    def url(self):
+        """Get the URL attached to the message"""
+        # Use the provided if available
+        if self._url is not None:
+            return self._url
+
+        if self.type == "url":
+            # Standard URLs
+            return self.text
+        elif self.type == "mention":
+            # telegram.me URLs
+            return "https://telegram.me/%s" % self.text[1:]
+        elif self.type == "email":
+            # mailto: URL
+            return "mailto:%s" % self.text
+        else:
+            # Sorry!
+            return None
+
+class ParsedText:
+    """Collection of ParsedTextEntity.
+
+    This is a list-like object, and mimics the List<MessageEntity> Telegram
+    object, but increases its functionalities.
+    """
+
+    def __init__(self, data, api=None, message=None):
+        self._api = api
+        # Accept only list of entites
+        if not isinstance(data, list):
+            raise ValueError("You must provide a list of ParsedTextEntity")
+
+        # Create ParsedTextEntity instances from the data
+        self._original_entities = []
+        for entity in data:
+            parsed = ParsedTextEntity(entity, api, message)
+            self._original_entities.append(parsed)
+
+        # Original entities are separated from the exposed entities because
+        # plaintext entities are calculated and added to the exposend entities
+        self._entities = None
+
+        self.set_message(message)
+
+    def __repr__(self):
+        return '<ParsedText %s>' % repr(self._calculate_entities())
+
+    def set_api(self, api):
+        """Change the API instance"""
+        self._api = api
+
+    def set_message(self, message):
+        """Change the message instance"""
+        if message is not None and message.text is None:
+            raise ValueError("The message must have some text")
+
+        self._message = message
+        for entity in self._original_entities:
+            entity.set_message(message)
+
+        # Refresh the calculated entities list
+        self._entities = None
+
+    def serialize(self):
+        """Serialize this object"""
+        result = []
+        for entity in self._original_entities:
+            result.append(entity.serialize())
+
+        return result
+
+    @_require_message
+    def _calculate_entities(self):
+        """Calculate the correct list of entities"""
+        # Return the cached result if possible; the cached result is nullified
+        # when a new instance of Message is attached
+        if self._entities is not None:
+            return self._entities
+
+        offset = 0
+        self._entities = []
+        for entity in self._original_entities:
+            # If there was some text before the current entity, add an extra
+            # plaintext entity
+            if offset < entity._offset:
+                self._entities.append(ParsedTextEntity({
+                    "type": "plain",
+                    "offset": offset,
+                    "length": entity._offset - offset,
+                }, self._api, self._message))
+
+            self._entities.append(entity)
+            offset = entity._offset + entity._length
+
+        # Then add the last few bits as plaintext if they're present
+        if offset < len(self._message.text):
+            self._entities.append(ParsedTextEntity({
+                "type": "plain",
+                "offset": offset,
+                "length": len(self._message.text) - offset,
+            }, self._api, self._message))
+
+        return self._entities
+
+    def filter(self, *types, exclude=False):
+        """Get only some types of entities"""
+        result = []
+        for entity in self._calculate_entities():
+            # If the entity type is in the allowed ones and exclude is False OR
+            # if the entity type isn't in the allowed ones and exclude is True
+            if (entity.type in types) ^ exclude:
+                result.append(entity)
+
+        return result
+
+    # Provide a basic list-like interface; you can always mutate this object to
+    # a list with list(self) if you need more advanced methods
+
+    def __iter__(self):
+        return iter(self._calculate_entities())
+
+    def __getitem__(self, index):
+        return self._calculate_entities()[index]
+
+    def __contains__(self, key):
+        # This checks if a given type is in the entities list
+        return key in (entity.type for entity in self._entities)
+
+
 class Message(BaseObject, mixins.MessageMixin):
     """Telegram API representation of a message
 
@@ -35,6 +240,7 @@ def from_(self):
         "chat": Chat,
     }
     optional = {
+        "entities": ParsedText,
         "forward_from": User,
         "forward_date": int,
         "reply_to_message": _itself,
@@ -62,8 +268,22 @@ def from_(self):
     }
     replace_keys = {
         "from": "sender",
+        "entities": "parsed_text",
     }
 
+    def __init__(self, data, api=None):
+        super().__init__(data, api)
+
+        # Create the parsed_text instance even if there are no entities in the
+        # current text
+        if self.text is not None and self.parsed_text is None:
+            self.parsed_text = ParsedText([], api, self)
+
+        # Be sure to set this as the Message instance in the parsed text
+        # The instance is needed to calculate the content of each entity
+        if self.parsed_text is not None:
+            self.parsed_text.set_message(self)
+
     @property
     @utils.deprecated("Message.new_chat_participant", "1.0",
                       "Rename property to Message.new_chat_member")

docs/api/telegram.rst

@@ -595,6 +595,101 @@ about its business.
 
          Now the method returns the sent message
 
+.. py:class:: botogram.ParsedText
+
+   This class contains the parsed representation of the text of a received
+   message. This allows you to work with the rich-formatted text the user sent,
+   in addition to the plaintext provided by the :py:class:`~botogram.Message`
+   class.
+
+   This class behaves as a list of :py:class:`~botogram.ParsedTextEntity`, so
+   you can access its items as you would do with any other list (indexed
+   access, iteration...), but it also provides some other utility tools.
+
+   .. versionadded:: 0.3
+
+   .. describe:: type in parsed
+
+      Check if a given entity type is contained in the message. For example,
+      with the following code you can check if the user sent links in his
+      message:
+
+      .. code-block:: python
+
+         if "url" in message.parsed_text:
+             chat.send("Hey, you sent me a link!")
+
+   .. py:method:: filter(\*types, [exclude=False])
+
+      This method returns a list of all the
+      :py:class:`~botogram.ParsedTextEntity` in a message of a given
+      type. This allows you to get only some types of entities, and exclude the
+      other ones in a simple way. You can also just **exclude** from the result
+      the types you provide.
+
+      .. code-block:: python
+
+         # Get only the URLs
+         urls = message.parsed_text.filter("url")
+
+         # Get usernames and hashtags
+         usernames_hashtags = message.parsed_text.filter("mention", "hashtag")
+
+         # Exclude plaintext
+         entities = message.parsed_text.filter("plaintext", exclude=True)
+
+.. py:class:: botogram.ParsedTextEntity
+
+   This class represent a single entity contained in a text message.
+
+   .. versionadded:: 0.3
+
+   .. describe:: str(entity)
+
+      An handy alias for the :py:attr:`~botogram.ParsedTextEntity.text`
+      attribute.
+
+   .. describe:: len(entity)
+
+      Return the length of the entity.
+
+   .. py:attribute:: type
+
+      The type of the entity. This can be one of those:
+
+      * **plain**: a plain string (with no formatting or special meaning)
+
+      * **mention**: a mention to another user (for example ``@pietroalbini``)
+
+      * **hashtag**: an hashtag (for example ``#pythonftw``)
+
+      * **bot_command**: a command sent to a bot (for example ``/help``)
+
+      * **url**: a textual URL (for example ``https://pietroalbini.io``)
+
+      * **email**: an email address (for example ``[email protected]``)
+
+      * **bold**: a bold-formatted text
+
+      * **italic**: an italic-formatted text
+
+      * **code**: a monospace-formatted text
+
+      * **pre**: a monospace-formatted block
+
+      * **text_link**: a link with a label
+
+   .. py:attribute:: text
+
+      Return the plaintext content of the entity. In pair with the type you can
+      recreate the original formatting of the entity.
+
+   .. 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.
+
 .. py:class:: botogram.Message
 
    This class represents messages received by and sent from your bot. Messages
@@ -658,6 +753,15 @@ about its business.
 
       *This attribute can be None if it's not provided by Telegram.*
 
+   .. py:attribute:: parsed_text
+
+      The :py:class:`~botogram.ParsedText` representation of the text of this
+      message.
+
+      *This attribute is None if the text attribute is also None.*
+
+      .. versionaddedd: 0.3
+
    .. py:attribute:: audio
 
       An :py:class:`~botogram.Audio` object, for when this message is an audio

docs/changelog.rst

@@ -34,6 +34,12 @@ New features
   * New method :py:meth:`botogram.Bot.edit_message`
   * New method :py:meth:`botogram.Bot.edit_caption`
 
+* Added support for working with parsed text in a message:
+
+   * New attribute :py:attr:`botogram.Message.parsed_text`
+   * New class :py:class:`botogram.ParsedText`
+   * New class :py:class:`botogram.ParsedTextEntity`
+
 * Added new attribute :py:attr:`botogram.Message.pinned_message`
 * Every method which sends something to a chat now returns the sent
   :py:class:`~botogram.Message`