Add support for sending geographic locations

Added and documented the following methods:

* botogram.Bot.send_location
* botogram.User.send_location
* botogram.Chat.send_location
* botogram.Message.reply_with_location

Author: Pietro Albini

botogram/frozenbot.py

@@ -159,6 +159,12 @@ def send_file(self, chat, path, reply_to=None, extra=None):
         obj = objects.Chat({"id": chat, "type": ""}, self.api)
         obj.send_file(path, reply_to, extra)
 
+    def send_location(self, chat, latitude, longitude, reply_to=None,
+                      extra=None):
+        """Send a generic file in a chat"""
+        obj = objects.Chat({"id": chat, "type": ""}, self.api)
+        obj.send_location(latitude, longitude, reply_to, extra)
+
     # Let's process the messages
 
     def process(self, update):

botogram/objects/mixins.py

@@ -98,6 +98,15 @@ def send_file(self, path, reply_to=None, extra=None):
         files = {"document": open(path, "rb")}
         self._api.call("sendDocument", args, files)
 
+    @_require_api
+    def send_location(self, latitude, longitude, reply_to=None, extra=None):
+        """Send a geographic location"""
+        args = self._get_call_args(reply_to, extra)
+        args["latitude"] = latitude
+        args["longitude"] = longitude
+
+        self._api.call("sendLocation", args)
+
 
 class MessageMixin:
     """Add some methods for messages"""
@@ -141,6 +150,11 @@ def reply_with_file(self, path, extra=None):
         """Reply with a generic file to the current chat"""
         self.chat.send_file(path, self.message_id, extra)
 
+    @_require_api
+    def reply_with_location(self, latitude, longitude, extra=None):
+        """Reply with a geographic location to the current chat"""
+        self.chat.send_location(latitude, longitude, self.message_id, extra)
+
 
 class FileMixin:
     """Add some methods for files"""

docs/api/bot.rst

@@ -399,3 +399,26 @@ components.
       :param str path: The path to the file
       :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
+
+   .. py:method:: send_location(chat, latitude, longitude, [reply_to=None, extra=None])
+
+      This method sends a geographic location to a specific chat. The chat must
+      be identified by its ID, and Telegram applies some restrictions on the
+      chats allowed to receive your locations: only users who sent you a
+      message in the past are allowed, and also the group chats your bot is
+      currently in.
+
+      If the location you're sending is in reply to another message, set
+      *reply_to* to the ID of the other :py:class:`~botogram.Message`.  *extra*
+      is an optional object which specifies additional reply interface options
+      on the recipient's end, and can be one of the following types:
+
+      * :py:class:`botogram.ReplyKeyboardMarkup`
+      * :py:class:`botogram.ReplyKeyboardHide`
+      * :py:class:`botogram.ForceReply`
+
+      :param int chat: The ID of the chat which should receive the location
+      :param float latitude: The latitude of the location
+      :param float longitude: The longitude of the location
+      :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

docs/api/telegram.rst

@@ -155,6 +155,23 @@ Available Classes
       :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
 
+   .. py:method:: send_location(latitude, longitude, [reply_to=None, extra=None])
+
+      Send the geographic location to the user. If the location you're sending
+      is in reply to another message, set *reply_to* to the ID of the other
+      :py:class:`~botogram.Message`.  *extra* is an optional object which
+      specifies additional reply interface options on the recipient's end, and
+      can be one of the following types:
+
+      * :py:class:`botogram.ReplyKeyboardMarkup`
+      * :py:class:`botogram.ReplyKeyboardHide`
+      * :py:class:`botogram.ForceReply`
+
+      :param float latitude: The latitude of the location
+      :param float longitude: The longitude of the location
+      :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
+
 
 .. py:class:: botogram.Chat
 
@@ -288,6 +305,23 @@ Available Classes
       :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
 
+   .. py:method:: send_location(latitude, longitude, [reply_to=None, extra=None])
+
+      Send the geographic location to the chat. If the location you're sending
+      is in reply to another message, set *reply_to* to the ID of the other
+      :py:class:`~botogram.Message`.  *extra* is an optional object which
+      specifies additional reply interface options on the recipient's end, and
+      can be one of the following types:
+
+      * :py:class:`botogram.ReplyKeyboardMarkup`
+      * :py:class:`botogram.ReplyKeyboardHide`
+      * :py:class:`botogram.ForceReply`
+
+      :param float latitude: The latitude of the location
+      :param float longitude: The longitude of the location
+      :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
+
 
 .. py:class:: botogram.Message
 
@@ -563,6 +597,20 @@ Available Classes
       :param str path: The path to the file
       :param object extra: An extra reply interface object to attach
 
+   .. py:method:: reply_with_location(latitude, longitude, [extra=None])
+
+      Send the geographic location to the user. *extra* is an optional object
+      which specifies additional reply interface options on the recipient's
+      end, and can be one of the following types:
+
+      * :py:class:`botogram.ReplyKeyboardMarkup`
+      * :py:class:`botogram.ReplyKeyboardHide`
+      * :py:class:`botogram.ForceReply`
+
+      :param float latitude: The latitude of the location
+      :param float longitude: The longitude of the location
+      :param object extra: An extra reply interface object to attach
+
 
 .. py:class:: botogram.Photo