Add support for processing venues

A Venue is a new kind of message introduced in the Bot API 2.0 update,
which can be sent only by bots. This commit adds support for receiving
and processing it.

Issue: GH-58

Author: Pietro Albini

botogram/objects/__init__.py

@@ -10,7 +10,7 @@
 
 from .chats     import User, Chat, UserProfilePhotos
 from .media     import PhotoSize, Photo, Audio, Voice, Document, Sticker, \
-                       Video, Contact, Location
+                       Video, Contact, Location, Venue
 from .messages  import Message
 from .markup    import ReplyKeyboardMarkup, ReplyKeyboardHide, ForceReply
 from .updates   import Update, Updates
@@ -32,6 +32,7 @@
     "Video",
     "Contact",
     "Location",
+    "Venue",
 
     # Messages-related objects
     "Message",

botogram/objects/media.py

@@ -207,3 +207,23 @@ def __eq__(self, other):
         return isinstance(other, Location) and \
             self.longitude == other.longitude and \
             self.latitude == other.latitude
+
+
+class Venue(BaseObject):
+    """Telegram API representation of a venue
+
+    https://core.telegram.orgf/bots/api#venue
+    """
+
+    required = {
+        "location": Location,
+        "title": str,
+        "address": str,
+    }
+    optional = {
+        "foursquare_id": str,
+    }
+    replace_keys = {
+        "foursquare_id": "foursquare",
+    }
+    _check_equality_ = "location"

botogram/objects/messages.py

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

docs/api/telegram.rst

@@ -1083,6 +1083,13 @@ about its business.
 
       *This attribute can be None if it's not provided by Telegram.*
 
+   .. py:attribute:: venue
+
+      If the user sent a :py:class:`~botogram.Venue` with this message, the
+      attribute contains its representation.
+
+      *This attribute can be None if the message isn't a venue.*
+
    .. py:attribute:: new_chat_member
 
       A :py:class:`~botogram.User` object representing a new member of a group
@@ -1820,6 +1827,36 @@ about its business.
       The float latitude as defined by the sender.
 
 
+.. py:class:: botogram.Venue
+
+   This object represents a venue (a location with attached a title and an
+   address). A venue may also have a Foursquare ID attached.
+
+   .. py:attribute:: location
+
+      The :py:class:`~botogram.Location` of the venue. You can use this to get
+      the exact geographic coordinates of the venue.
+
+   .. py:attribute:: title
+
+      The name of the venue. The value might not match the venue sometimes,
+      because it's supplied by the user/bot who sent the venue.
+
+   .. py:attribute:: address
+
+      The address of the venue. The value might not match the venue sometimes,
+      because it's supplied by the user/bot who sent the venue.
+
+   .. py:attribute:: foursquare
+
+      The ID of the venue on Foursquare. You can use this to get more
+      information about the venue from the Foursquare API. The ID might not
+      match the venue sometimes because it's supplied by the user/bot who sent
+      the venue.
+
+      *This value can be None if the venue doesn't have a Foursquare ID.*
+
+
 .. py:class:: botogram.Update
 
    This class represents an update received by the bot. You should not need to

docs/changelog/0.3.rst

@@ -59,6 +59,11 @@ New features
    * New method :py:meth:`botogram.Chat.send_contact`
    * New method :py:meth:`botogram.Message.reply_with_contact`
 
+* Added support for venues:
+
+   * New class :py:class:`botogram.Venue`
+   * New attrinute :py:attr:`botogram.Message.venue`
+
 * 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`