Add support for receiving callbacks

Author: pietroalbini

botogram/bot.py

@@ -25,6 +25,7 @@
 import requests.exceptions
 
 from . import api
+from . import callbacks
 from . import objects
 from . import runner
 from . import defaults
@@ -87,6 +88,7 @@ def __init__(self, api_connection):
                                        messages.process_channel_post)
         self.register_update_processor("edited_channel_post",
                                        messages.process_channel_post_edited)
+        self.register_update_processor("callback_query", callbacks.process)
 
         self._bot_id = str(uuid.uuid4())
 
@@ -178,6 +180,13 @@ def __(func):
             return func
         return __
 
+    def callback(self, name):
+        """Register a new callback"""
+        def __(func):
+            self._main_component.add_callback(name, func)
+            return func
+        return __
+
     def timer(self, interval):
         """Register a new timer"""
         def __(func):

botogram/callbacks.py

@@ -0,0 +1,43 @@
+# Copyright (c) 2015-2017 The Botogram Authors (see AUTHORS)
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+#   The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+#   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+#   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+
+
+def parse_callback_data(data):
+    """Parse the callback data generated by botogram and return it"""
+    if "\0" in data:
+        name, custom = data.split("\0", 1)
+        return name, custom
+    else:
+        return data, None
+
+
+def process(bot, chains, update):
+    """Process a callback sent to the bot"""
+    for hook in chains["callbacks"]:
+        bot.logger.debug("Processing 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/components.py

@@ -37,6 +37,7 @@ def __new__(cls, *args, **kwargs):
         self = super(Component, cls).__new__(cls)
 
         self.__commands = {}
+        self.__callbacks = {}
         self.__processors = []
         self.__no_commands = []
         self.__before_processors = []
@@ -132,6 +133,19 @@ def add_command(self, name, func, hidden=False, order=0, _from_main=False):
         command = commands.Command(hook)
         self.__commands[name] = command
 
+    def add_callback(self, name, func):
+        """Add a new callback"""
+        if name in self.__callbacks:
+            raise NameError("The callback %s already exists" % name)
+
+        if not callable(func):
+            raise ValueError("A callback must be callable")
+
+        hook = hooks.CallbackHook(func, self, {
+            "name": name,
+        })
+        self.__callbacks[name] = hook
+
     def add_timer(self, interval, func):
         """Register a new timer"""
         if not callable(func):
@@ -212,7 +226,11 @@ def _get_chains(self):
             "chat_unavalable_hooks": [self.__chat_unavailable_hooks],
             "messages_edited": [self.__messages_edited_hooks],
             "channel_post": [self.__channel_post_hooks],
-            "channel_post_edited": [self.__channel_post_edited_hooks]
+            "channel_post_edited": [self.__channel_post_edited_hooks],
+            "callbacks": [[
+                self.__callbacks[name]
+                for name in sorted(self.__callbacks.keys())
+            ]],
         }
 
     def _get_commands(self):

botogram/frozenbot.py

@@ -124,6 +124,10 @@ def command(self, name, hidden=False):
         """Register a new command"""
         raise FrozenBotError("Can't add commands to a bot at runtime")
 
+    def callback(self, name, hidden=False):
+        """Register a new callback"""
+        raise FrozenBotError("Can't add callbacks to a bot at runtime")
+
     def timer(self, interval):
         """Register a new timer"""
         raise FrozenBotError("Can't add timers to a bot at runtime")

botogram/hooks.py

@@ -19,6 +19,8 @@
 
 import re
 
+from .callbacks import parse_callback_data
+
 
 class Hook:
     """Base class for all the hooks"""
@@ -206,6 +208,31 @@ def _call(self, bot, update):
         return True
 
 
+class CallbackHook(Hook):
+    """Underlying hook for @bot.callback"""
+
+    def _after_init(self, args):
+        self._name = "%s:%s" % (self.component.component_name, args["name"])
+
+    def _call(self, bot, update):
+        if not update.callback_query:
+            return
+        q = update.callback_query
+
+        name, data = parse_callback_data(q._data)
+        print(name, self._name)
+        if name != self._name:
+            return
+
+        bot._call(
+            self.func, self.component_id, query=q, chat=q.message.chat,
+            message=q.message, data=data,
+        )
+
+        update.callback_query._maybe_send_noop()
+        return True
+
+
 class ChatUnavailableHook(Hook):
     """Underlying hook for @bot.chat_unavailable"""
 

botogram/objects/callbacks.py

@@ -0,0 +1,86 @@
+# Copyright (c) 2015-2017 The Botogram Authors (see AUTHORS)
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+#   The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+#   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+#   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+#   DEALINGS IN THE SOFTWARE.
+
+from .base import BaseObject
+from .messages import User, Message
+from .mixins import _require_api
+
+
+class CallbackQuery(BaseObject):
+    """Telegram API representation of a callback query
+
+    https://core.telegram.org/bots/api#callbackquery
+    """
+
+    required = {
+        "id": str,
+        "from": User,
+        "message": Message,
+        "chat_instance": str,
+    }
+    optional = {
+        "inline_message_id": str,
+        "data": str,
+        "game_short_name": str,
+    }
+    replace_keys = {
+        "from": "sender",
+        "data": "_data",
+    }
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+        self._answered = False
+
+    @_require_api
+    def notify(self, text, alert=False, cache=0):
+        """Send a notification or an alert to the user"""
+        self._answered = True
+
+        self._api.call("answerCallbackQuery", {
+            "callback_query_id": self.id,
+            "text": text,
+            "show_alert": alert,
+            "cache_time": cache,
+        })
+
+    @_require_api
+    def open_url(self, url, cache=0):
+        """Tell the user's client to open an URL"""
+        self._answered = True
+
+        self._api.call("answerCallbackQuery", {
+            "callback_query_id": self.id,
+            "url": url,
+            "cache_time": cache,
+        })
+
+    @_require_api
+    def _maybe_send_noop(self):
+        """Internal function to hide the spinner if needed"""
+        if self._answered:
+            return
+
+        # Only call this if the query wasn't answered before
+        self._api.call("answerCallbackQuery", {
+            "callback_query_id": self.id,
+            "cache_time": 0
+        })

botogram/objects/updates.py

@@ -20,6 +20,7 @@
 
 from .base import BaseObject, multiple
 
+from .callbacks import CallbackQuery
 from .messages import Message
 
 
@@ -36,7 +37,8 @@ class Update(BaseObject):
         "message": Message,
         "edited_message": Message,
         "channel_post": Message,
-        "edited_channel_post": Message
+        "edited_channel_post": Message,
+        "callback_query": CallbackQuery,
     }
     _check_equality_ = "update_id"
 

tests/test_callbacks.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2015-2017 The Botogram Authors (see AUTHORS)
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+#   The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+#   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+#   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+#   DEALINGS IN THE SOFTWARE.
+
+from botogram.callbacks import parse_callback_data
+
+
+def test_parse_callback_data():
+    assert parse_callback_data("test") == ("test", None)
+    assert parse_callback_data("test:something") == ("test:something", None)
+    assert parse_callback_data("test\0wow") == ("test", "wow")