Merge branch 'feature/venues'

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,

botogram/objects/mixins.py

@@ -155,6 +155,20 @@ def send_location(self, latitude, longitude, reply_to=None, extra=None,
         return self._api.call("sendLocation", args,
                               expect=_objects().Message)
 
+    @_require_api
+    def send_venue(self, latitude, longitude, title, address, foursquare=None,
+                   reply_to=None, extra=None, notify=True):
+        """Send a venue"""
+        args = self._get_call_args(reply_to, extra, notify)
+        args["latitude"] = latitude
+        args["longitude"] = longitude
+        args["title"] = title
+        args["address"] = address
+        if foursquare is not None:
+            args["foursquare_id"] = foursquare
+
+        self._api.call("sendVenue", args, expect=_objects().Message)
+
     @_require_api
     def send_sticker(self, sticker, reply_to=None, extra=None, notify=True):
         """Send a sticker"""
@@ -262,6 +276,11 @@ def reply_with_location(self, *args, **kwargs):
         """Reply with a geographic location to the current chat"""
         return self.chat.send_location(*args, reply_to=self, **kwargs)
 
+    @_require_api
+    def reply_with_venue(self, *args, **kwargs):
+        """Reply with a venue to the current message"""
+        return self.chat.send_venue(*args, reply_to=self, **kwargs)
+
     @_require_api
     def reply_with_sticker(self, *args, **kwargs):
         """Reply with a sticker to the current message"""

docs/api/telegram.rst

@@ -290,6 +290,36 @@ about its business.
 
          Now the method returns the sent message
 
+   .. py:method:: send_venue(latitude, longitude, title, address, [foursquare=None, reply_to=None, extra=None, notify=True])
+
+      Send a venue to the user. A venue is made of its geographic coordinates
+      (latitude and longitude), its title and address, and optionally the
+      venue's Foursquare ID, if you want to integrate with that. Users will
+      then see the venue in the map, along with the information you provided.
+
+      You can use this, for example, if you want to recommend to your bot's
+      users a place to go to dinner tonight:
+
+      .. code-block:: python
+
+         @bot.command("whereshouldigo")
+         def whereshouldigo_command(chat, message, args):
+             message.sender.send("Here there is an unique place to go to dinner tonight!")
+             message.sender.send_venue(35, -45, "The Abyss", "Atlantic Ocean")
+
+      :param float latitude: The latitude of the venue
+      :param float longitude: The longitude of the venue
+      :param str title: The name of the venue
+      :param str address: The address of the venue
+      :param str foursquare: The Foursquare ID of the venue
+      :param int reply_to: The ID of the :py:class:`~botogram.Message` this one is replying to
+      :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.3
+
    .. py:method:: send_sticker(sticker, [reply_to=None, extra=None, notify=True])
 
       Send the sticker to the user (in webp format). If the sticker you're
@@ -791,6 +821,36 @@ about its business.
 
          Now the method returns the sent message
 
+   .. py:method:: send_venue(latitude, longitude, title, address, [foursquare=None, reply_to=None, extra=None, notify=True])
+
+      Send a venue to the chat. A venue is made of its geographic coordinates
+      (latitude and longitude), its title and address, and optionally the
+      venue's Foursquare ID, if you want to integrate with that. Users will
+      then see the venue in the map, along with the information you provided.
+
+      You can use this, for example, if you want to recommend to your bot's
+      users a place to go to dinner tonight:
+
+      .. code-block:: python
+
+         @bot.command("whereshouldigo")
+         def whereshouldigo_command(chat, message, args):
+             chat.send("Here there is an unique place to go to dinner tonight!")
+             chat.send_venue(35, -45, "The Abyss", "Atlantic Ocean")
+
+      :param float latitude: The latitude of the venue
+      :param float longitude: The longitude of the venue
+      :param str title: The name of the venue
+      :param str address: The address of the venue
+      :param str foursquare: The Foursquare ID of the venue
+      :param int reply_to: The ID of the :py:class:`~botogram.Message` this one is replying to
+      :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.3
+
    .. py:method:: send_sticker(sticker, [reply_to=None, extra=None, notify=True])
 
       Send the sticker to the chat (in webp format). If the sticker you're
@@ -1083,6 +1143,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
@@ -1421,6 +1488,36 @@ about its business.
 
          Now the method returns the sent message
 
+   .. py:method:: reply_with_venue(latitude, longitude, title, address, [foursquare=None, extra=None, notify=True])
+
+      Reply to this message with a venue. A venue is made of its geographic
+      coordinates (latitude and longitude), its title and address, and
+      optionally the venue's Foursquare ID, if you want to integrate with that.
+      Users will then see the venue in the map, along with the information you
+      provided.
+
+      You can use this, for example, if you want to recommend to your bot's
+      users a place to go to dinner tonight:
+
+      .. code-block:: python
+
+         @bot.command("whereshouldigo")
+         def whereshouldigo_command(chat, message, args):
+             message.reply("Here there is an unique place to go to dinner tonight!")
+             message.reply_with_venue(35, -45, "The Abyss", "Atlantic Ocean")
+
+      :param float latitude: The latitude of the venue
+      :param float longitude: The longitude of the venue
+      :param str title: The name of the venue
+      :param str address: The address of the venue
+      :param str foursquare: The Foursquare ID of the venue
+      :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.3
+
    .. py:method:: reply_with_sticker(sticker, [reply_to=None, extra=None, notify=True])
 
       Reply with the sticker (in webp format) to the chat. *extra* is an
@@ -1820,6 +1917,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,14 @@ 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`
+   * New method :py:meth:`botogram.User.send_venue`
+   * New method :py:meth:`botogram.Chat.send_venue`
+   * New method :py:meth:`botogram.Message.reply_with_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`