Add support and documentation for polls

Author: MarcoBuster

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)
@@ -348,6 +349,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

@@ -343,6 +343,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"""
@@ -505,6 +515,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"""
@@ -513,6 +528,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,
+    }

docs/api/telegram.rst

@@ -1375,7 +1375,6 @@ about its business.
       The *notify* parameter defines if your message should
       trigger the notification on the client side (yes by default).
 
-
       .. code-block:: python
         @bot.command("my_cats")
         def my_cats(chat):
@@ -1394,12 +1393,36 @@ about its business.
       :param album: The :py:class:`~botogram.Album` send to the chat
       :param int reply_to: The ID of the :py:class:`~botogram.Message` this one is replying to.
       :param bool notify: If you want to trigger a notification on the client
-
       :returns: The messages you sent
       :rtype: list of :py:class:`~botogram.Message`
 
       .. versionadded:: 0.6
 
+   .. py:method:: send_poll(question, *options, [reply_to=None, extra=None, attach=None, notify=True])
+
+      Send a poll to the chat. A Telegram poll is made by a question and a list of options
+      (you can specify them as arguments).
+
+      .. code-block:: python
+
+         @bot.command("latest_poll")
+         def latest_poll(chat, message, args):
+             chat.send("This is our last poll, please answer honestly!")
+             chat.send_poll("What's your favorite color?", "Red", "Green", "Blue")
+             # Or, alternate syntax:
+             chat.send_poll("What's your favorite color?", *["Red", "Green", "Blue"])
+
+      :param str question: Poll question, 1-255 characters
+      :param *str options: List of answer options, 2-10 string of 1-100 characters each
+      :param int reply_to: The ID of the :py:class:`~botogram.Message` this one is replying to
+      :param object attach: An extra thing to attach to the message
+      :param object extra: An extra reply interface object to attach
+      :param bool notify: If you want to trigger a notification on the client
+      :returns: The message you sent
+      :rtype: ~botogram.Message
+
+      .. versionadded:: 0.7
+
    .. py:method:: delete_message(message)
 
       Delete the message with the provided ID or :py:class:`~botogram.Message` object.
@@ -2214,22 +2237,20 @@ about its business.
 
       .. versionadded:: 0.3
 
-
    .. py:method:: reply_with_album([album=None, notify=True])
 
-      Send album to the chat. This method returns an instance of :py:class:`~botogram.Album` or sends the :py:class:`~botogram.Album` provided by the album variable.
+      Reply to this message with an album. This method returns an instance of :py:class:`~botogram.Album` or sends the :py:class:`~botogram.Album` provided by the album variable.
       The *notify* parameter defines if your message should
       trigger the notification on the client side (yes by default).
 
-
       .. code-block:: python
         @bot.command("my_cats")
         def my_cats(message):
             album = botogram.Album()
             album.add_photo('tiger.jpg', caption='<b>Tiger</b>, the father', syntax='HTML')
             album.add_photo(url='https://http.cat/100.jpg', caption='Simba, the cat-mother of the year!')
             album.add_photo(file_id='some file ID here', caption='...and Sassy the daughter')
-             message.reply_with_album(album)
+            message.reply_with_album(album)
 
         @bot.command("my_dogs")
         def my_dogs(message):
@@ -2238,14 +2259,57 @@ about its business.
                  album.add_photo('shilla.jpg', caption='Shilla is so jealous!')
 
       :param album: The :py:class:`~botogram.Album` send to the chat
-
       :param bool notify: If you want to trigger a notification on the client
-
       :returns: The messages you sent
       :rtype: list of :py:class:`~botogram.Message`
 
       .. versionadded:: 0.6
 
+   .. py:method:: reply_with_poll(question, *options, [extra=None, attach=None, notify=True])
+
+      Reply to this message with a poll. A Telegram poll is made by a question and a list of options
+      (you can specify them as arguments).
+
+      .. code-block:: python
+
+         @bot.command("latest_poll")
+         def latest_poll(chat, message, args):
+             chat.send("This is our last poll, please answer honestly!")
+             message.reply_with_poll("What's your favorite color?", "Red", "Green", "Blue")
+             # Or, alternate syntax:
+             message.reply_with_poll("What's your favorite color?", *["Red", "Green", "Blue"])
+
+      :param str question: Poll question, 1-255 characters
+      :param *str options: List of answer options, 2-10 string of 1-100 characters each
+      :param object attach: An extra thing to attach to the message
+      :param object extra: An extra reply interface object to attach
+      :param bool notify: If you want to trigger a notification on the client
+      :returns: The message you sent
+      :rtype: ~botogram.Message
+
+      .. versionadded:: 0.7
+
+   .. py:method:: stop_poll([extra=None, attach=None])
+
+      Stop a poll sent by a bot.
+
+      .. code-block:: python
+         import time
+
+         @bot.command("quiz")
+         def latest_quiz(chat, message, args):
+             chat.send("Please answer within 10 seconds!")
+             msg = chat.send_poll("What's the capital of Italy?", "Milan", "Rome", "New York")
+             time.sleep(10)
+             poll = msg.stop_poll()
+             chat.send("{n} correct answers!".format(n=poll.options[1].voter_count))
+
+      :param object attach: An extra thing to attach to the message
+      :param object extra: An extra reply interface object to attach
+      :returns: The stopped poll with the final results
+      :rtype: ~botogram.Poll
+
+      .. versionadded:: 0.7
 
 .. py:class:: botogram.Photo
 
@@ -2700,7 +2764,6 @@ about its business.
 
 .. py:class:: botogram.Album
 
-
    This object represents an album (a group of photos and videos).
 
    .. py:method:: add_photo([path=None, url=None, file_id=None, caption=None, syntax=None])
@@ -2733,6 +2796,40 @@ about its business.
    .. versionadded:: 0.6
 
 
+.. py:class:: botogram.Poll
+
+   This class represents a poll.
+
+   .. py:attribute:: id
+
+      The unique poll string identifier.
+
+   .. py:attribute:: question
+
+      The poll question.
+
+   .. py:attribute:: options
+
+      A list of :py:class:`~botogram.PollOption` identifying the poll options.
+
+   .. py:attribute:: is_closed
+
+      A boolean indicating if the poll is closed.
+
+
+.. py:class:: botogram.PollOption
+
+   This class represents a :py:class:`~botogram.Poll` option.
+
+   .. py:attribute:: text
+
+      The poll option text.
+
+   .. py:attribute:: voter_count
+
+      Number of users that voted for this option.
+
+
 .. py:class:: botogram.Update
 
    This class represents an update received by the bot. You should not need to