Add support for sending 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 sending it
in chats and as a reply.

Fixes: GH-58

Author: Pietro Albini

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"""
@@ -261,6 +275,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
@@ -1428,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

docs/changelog/0.3.rst

@@ -63,6 +63,9 @@ New features
 
    * 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`