Add support for processing edited messages

In the recent updates, the Telegram API added support for processing
the edits users make to messages your bot knows about. This commit adds
support for that, in the `@bot.message_edited` decorator and the
`component.add_message_edited_hook()` method.

Fixes: GH-63

Author: Pietro Albini

botogram/bot.py

@@ -67,6 +67,8 @@ def __init__(self, api_connection):
         # Initialize the list of update processors
         self._update_processors = {}
         self.register_update_processor("message", messages.process_message)
+        self.register_update_processor("edited_message",
+                                       messages.process_edited_message)
 
         self._bot_id = str(uuid.uuid4())
 
@@ -135,6 +137,11 @@ def __(func):
             return func
         return __
 
+    def message_edited(self, func):
+        """Add a message edited hook"""
+        self._main_component.add_message_edited_hook(func)
+        return func
+
     def command(self, name, hidden=False):
         """Register a new command"""
         def __(func):

botogram/components.py

@@ -31,6 +31,7 @@ def __new__(cls, *args, **kwargs):
         self.__memory_preparers = []
         self.__timers = []
         self.__chat_unavailable_hooks = []
+        self.__messages_edited_hooks = []
 
         self._component_id = str(uuid.uuid4())
 
@@ -148,6 +149,14 @@ def add_chat_unavailable_hook(self, func):
         hook = hooks.ChatUnavailableHook(func, self)
         self.__chat_unavailable_hooks.append(hook)
 
+    def add_message_edited_hook(self, func):
+        """Add a new edited message hook"""
+        if not callable(func):
+            raise ValueError("A message edited hook must be callable")
+
+        hook = hooks.MessageEditedHook(func, self)
+        self.__messages_edited_hooks.append(hook)
+
     def _add_no_commands_hook(self, func):
         """Register an hook which will be executed when no commands matches"""
         if not callable(func):
@@ -170,6 +179,7 @@ def _get_chains(self):
             "memory_preparers": [self.__memory_preparers],
             "tasks": [self.__timers],
             "chat_unavalable_hooks": [self.__chat_unavailable_hooks],
+            "messages_edited": [self.__messages_edited_hooks],
         }
 
     def _get_commands(self):

botogram/hooks.py

@@ -200,6 +200,15 @@ def call(self, bot, chat_id, reason):
                          reason=reason)
 
 
+class MessageEditedHook(Hook):
+    """Underlying hook for @bot.message_edited"""
+
+    def _call(self, bot, update):
+        message = update.edited_message
+        return bot._call(self.func, self.component_id, chat=message.chat,
+                         message=message)
+
+
 class TimerHook(Hook):
     """Underlying hook for a timer"""
 

botogram/messages.py

@@ -21,3 +21,19 @@ def process_message(bot, chains, update):
 
     bot.logger.debug("No hook actually processed the #%s update." %
                      update.update_id)
+
+
+def process_edited_message(bot, chains, update):
+    """Process an edited message"""
+    for hook in chains["messages_edited"]:
+        bot.logger.debug("Processing edited message in update #%s with the "
+                         "hook %s..." % (update.update_id, hook.name))
+
+        result = hook.call(bot, update)
+        if result is True:
+            bot.logger.debug("Update %s was just processed by the %s hook." %
+                             (update.update_id, hook.name))
+            return
+
+    bot.logger.debug("No hook actually processed the #%s update." %
+                     update.update_id)

botogram/objects/messages.py

@@ -319,6 +319,7 @@ def from_(self):
         "migrate_to_chat_id": int,
         "migrate_from_chat_id": int,
         "pinned_message": _itself,
+        "edit_date": int,
     }
     replace_keys = {
         "from": "sender",

botogram/objects/updates.py

@@ -21,7 +21,8 @@ class Update(BaseObject):
         "update_id": int,
     }
     optional = {
-        "message": Message
+        "message": Message,
+        "edited_message": Message,
     }
     _check_equality_ = "update_id"
 

docs/api/bot.rst

@@ -163,6 +163,31 @@ components.
       :param bool multiple: If the function should be called multiple times on
          multiple matches.
 
+   .. py:decoratormethod:: message_edited
+
+      All the functions decorated with this method will be called when an user
+      edits a message the bot knows about. This allows you, for example, to
+      update the preview of a message if the user edits the request, or to
+      enforce a no-edits policy on groups by banning whoever edits a message.
+
+      You can :ref:`request the following arguments <bot-structure-hooks-args>`
+      in the decorated functions:
+
+      * **chat**: the chat in which the message was originally sent (instance
+        of :py:class:`~botogram.Chat`)
+
+      * **message**: the edited message (instance of
+        :py:class:`~botogram.Message`)
+
+      .. code-block:: python
+
+         @bot.message_edited
+         def no_edits(chat, message):
+             message.reply("You can't edit messages! Bye.")
+             chat.ban(message.sender)
+
+      .. versionadded:: 0.3
+
    .. py:decoratormethod:: command(name, [hidden=False])
 
       This decorator register a new command, and calls the decorated function

docs/api/components.rst

@@ -127,6 +127,37 @@ about how to create them in the ":ref:`custom-components`" chapter.
       :param bool multiple: If the function should be called multiple times on
          multiple matches.
 
+   .. py:method:: add_message_edited_hook(func)
+
+      All the functions provided to this method will be called when an user
+      edits a message the bot knows about. This allows you, for example, to
+      update the preview of a message if the user edits the request, or to
+      enforce a no-edits policy on groups by banning whoever edits a message.
+
+      You can :ref:`request the following arguments <bot-structure-hooks-args>`
+      in the provided functions:
+
+      * **chat**: the chat in which the message was orignally sent (instance of
+        :py:class:`~botogram.Chat`)
+      * **message**: the edited message (instance of
+        :py:class:`~botogram.Message`)
+
+      .. code-block:: python
+
+         class NoEditsComponent(botogram.Component):
+             component_name = "noedits"
+
+             def __init__(self):
+                 self.add_message_edited_hook(self.no_edits)
+
+             def no_edits(self, chat, message):
+                 message.reply("You can't edit messages! Bye.")
+                 chat.ban(message.sender)
+
+      :param callable func: The function you want to use.
+
+      .. versionadded:: 0.3
+
    .. py:method:: add_command(name, func, [hidden=False])
 
       This function registers a new command, and calls the provided function

docs/changelog.rst

@@ -45,6 +45,11 @@ New features
    * New argument ``hidden`` on :py:meth:`botogram.Bot.command`
    * New argument ``hidden`` on :py:meth:`botogram.Component.add_command`
 
+* Add support for processing edited messages:
+
+   * New decorator :py:meth:`botogram.Bot.message_edited`
+   * New method :py:meth:`botogram.Component.add_message_edited_hook`
+
 * Added new attribute :py:attr:`botogram.Message.pinned_message`
 * Added new attribute :py:attr:`botogram.Sticker.emoji`
 * Added new attribute :py:attr:`botogram.Chat.admins`