Support for polls (#126)

* Add support and documentation for polls

* Add changelog

* Add @bot.process_poll hook

* Add @bot.process_poll documentation

* Add dummy method comment in documentation

Author: matteob99

botogram/bot.py

@@ -92,6 +92,7 @@ def __init__(self, api_connection):
         self.register_update_processor("edited_channel_post",
                                        messages.process_channel_post_edited)
         self.register_update_processor("callback_query", callbacks.process)
+        self.register_update_processor("poll", messages.process_poll_update)
 
         self._bot_id = str(uuid.uuid4())
 
@@ -142,6 +143,11 @@ def process_message(self, func):
         self._main_component.add_process_message_hook(func)
         return func
 
+    def poll_update(self, func):
+        """Add a poll update hook"""
+        self._main_component.add_poll_update_hook(func)
+        return func
+
     def message_equals(self, string, ignore_case=True):
         """Add a message equals hook"""
         def __(func):

botogram/components.py

@@ -47,6 +47,7 @@ def __new__(cls, *args, **kwargs):
         self.__messages_edited_hooks = []
         self.__channel_post_hooks = []
         self.__channel_post_edited_hooks = []
+        self.__poll_update_hooks = []
 
         self._component_id = str(uuid.uuid4())
 
@@ -75,6 +76,14 @@ def add_process_message_hook(self, func):
         hook = hooks.ProcessMessageHook(func, self)
         self.__processors.append(hook)
 
+    def add_poll_update_hook(self, func):
+        """Add a poll update hook"""
+        if not callable(func):
+            raise ValueError("A poll update hook must be callable")
+
+        hook = hooks.PollUpdateHook(func, self)
+        self.__poll_update_hooks.append(hook)
+
     def add_message_equals_hook(self, string, func, ignore_case=True):
         """Add a message equals hook"""
         if not callable(func):
@@ -220,6 +229,7 @@ def _get_chains(self):
         ]
         return {
             "messages": messages,
+            "poll_updates": [self.__poll_update_hooks],
             "memory_preparers": [self.__memory_preparers],
             "tasks": [self.__timers],
             "chat_unavalable_hooks": [self.__chat_unavailable_hooks],

botogram/frozenbot.py

@@ -111,6 +111,10 @@ def process_message(self, func):
         """Register a message processor hook"""
         raise FrozenBotError("Can't add hooks to a bot at runtime")
 
+    def poll_update(self, func):
+        """Register a poll update hook"""
+        raise FrozenBotError("Can't add hooks to a bot at runtime")
+
     def message_equals(self, string, ignore_case=True):
         """Add a message equals hook"""
         raise FrozenBotError("Can't add hooks to a bot at runtime")

botogram/hooks.py

@@ -81,6 +81,13 @@ class ProcessMessageHook(Hook):
     pass
 
 
+class PollUpdateHook(Hook):
+    """Underlying hook for @bot.poll_update"""
+
+    def _call(self, bot, update):
+        return bot._call(self.func, self.component_id, poll=update.poll)
+
+
 class MemoryPreparerHook(Hook):
     """Underlying hook for @bot.prepare_memory"""
 

botogram/messages.py

@@ -81,3 +81,19 @@ def process_channel_post_edited(bot, chains, update):
 
     bot.logger.debug("No hook actually processed the #%s update." %
                      update.update_id)
+
+
+def process_poll_update(bot, chains, update):
+    """Process a poll update"""
+    for hook in chains["poll_updates"]:
+        bot.logger.debug("Processing poll update 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/__init__.py

@@ -25,6 +25,7 @@
                        Video, VideoNote, Contact, Location, Venue
 from .messages  import Message
 from .markup    import ReplyKeyboardMarkup, ReplyKeyboardHide, ForceReply
+from .polls     import Poll, PollOption
 from .updates   import Update, Updates
 from .mixins import Album
 
@@ -56,6 +57,10 @@
     "ReplyKeyboardHide",
     "ForceReply",
 
+    # Polls-related objects
+    "Poll",
+    "PollOption",
+
     # Updates-related objects
     "Update",
     "Updates",

botogram/objects/messages.py

@@ -26,6 +26,7 @@
 from .chats import User, Chat
 from .media import Audio, Voice, Document, Photo, Sticker, Video, VideoNote, \
     Contact, Location, Venue
+from .polls import Poll
 
 
 _url_protocol_re = re.compile(r"^https?:\/\/|s?ftp:\/\/|mailto:", re.I)
@@ -350,6 +351,7 @@ def from_(self):
         "contact": Contact,
         "location": Location,
         "venue": Venue,
+        "poll": Poll,
         "new_chat_member": User,
         "left_chat_member": User,
         "new_chat_title": str,

botogram/objects/mixins.py

@@ -336,6 +336,16 @@ def send_contact(self, phone, first_name, last_name=None, *, reply_to=None,
 
         return self._api.call("sendContact", args, expect=_objects().Message)
 
+    @_require_api
+    def send_poll(self, question, *kargs, reply_to=None, extra=None,
+                  attach=None, notify=True):
+        """Send a poll"""
+        args = self._get_call_args(reply_to, extra, attach, notify)
+        args["question"] = question
+        args["options"] = json.dumps(list(kargs))
+
+        return self._api.call("sendPoll", args, expect=_objects().Message)
+
     @_require_api
     def delete_message(self, message):
         """Delete a message from chat"""
@@ -543,6 +553,11 @@ def reply_with_album(self, *args, **kwargs):
         """Reply with an album to the current message"""
         return self.chat.send_album(*args, reply_to=self, **kwargs)
 
+    @_require_api
+    def reply_with_poll(self, *args, **kwargs):
+        """Reply with a poll to the current message"""
+        return self.chat.send_poll(*args, reply_to=self, **kwargs)
+
     @_require_api
     def delete(self):
         """Delete the message"""
@@ -551,6 +566,27 @@ def delete(self):
             "message_id": self.id,
         })
 
+    @_require_api
+    def stop_poll(self, extra=None, attach=None):
+        """Stops a poll"""
+        args = dict()
+        args["chat_id"] = self.chat.id
+        args["message_id"] = self.id
+
+        if extra is not None:
+            _deprecated_message(
+                "The extra parameter", "1.0", "use the attach parameter", -3
+            )
+            args["reply_markup"] = json.dumps(extra.serialize())
+        if attach is not None:
+            if not hasattr(attach, "_serialize_attachment"):
+                raise ValueError("%s is not an attachment" % attach)
+            args["reply_markup"] = json.dumps(attach._serialize_attachment(
+                self.chat
+            ))
+        return self._api.call("stopPoll", args,
+                              expect=_objects().Poll)
+
 
 class FileMixin:
     """Add some methods for files"""

botogram/objects/polls.py

@@ -0,0 +1,37 @@
+# Copyright (c) 2015-2019 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, multiple
+
+
+class PollOption(BaseObject):
+    required = {
+        "text": str,
+        "voter_count": int,
+    }
+
+
+class Poll(BaseObject):
+    required = {
+        "id": str,
+        "question": str,
+        "options": multiple(PollOption),
+        "is_closed": bool,
+    }

botogram/objects/updates.py

@@ -22,6 +22,7 @@
 
 from .callbacks import CallbackQuery
 from .messages import Message
+from .polls import Poll
 
 
 class Update(BaseObject):
@@ -41,6 +42,7 @@ class Update(BaseObject):
         "channel_post": Message,
         "edited_channel_post": Message,
         "callback_query": CallbackQuery,
+        "poll": Poll,
     }
     _check_equality_ = "update_id"