Added support for live locations (#130)

Author: Francesco Zimbolo

botogram/objects/mixins.py

@@ -274,13 +274,20 @@ def send_file(self, path=None, file_id=None, url=None, reply_to=None,
                               expect=_objects().Message)
 
     @_require_api
-    def send_location(self, latitude, longitude, reply_to=None, extra=None,
-                      attach=None, notify=True):
-        """Send a geographic location"""
+    def send_location(self, latitude, longitude, live_period=None,
+                      reply_to=None, extra=None, attach=None, notify=True):
+        """Send a geographic location, set live_period to a number between 60
+        and 86400 if it's a live location"""
         args = self._get_call_args(reply_to, extra, attach, notify)
         args["latitude"] = latitude
         args["longitude"] = longitude
 
+        if live_period:
+            if live_period < 60 or live_period > 86400:
+                raise ValueError(
+                    "live_period must be a number between 60 and 86400")
+            args["live_period"] = live_period
+
         return self._api.call("sendLocation", args,
                               expect=_objects().Message)
 
@@ -445,6 +452,47 @@ def edit_attach(self, attach):
 
         self._api.call("editMessageReplyMarkup", args)
 
+    @_require_api
+    def edit_live_location(self, latitude, longitude, extra=None, attach=None):
+        """Edit this message's live location position"""
+        args = {"message_id": self.id, "chat_id": self.chat.id}
+        args["latitude"] = latitude
+        args["longitude"] = longitude
+
+        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
+            ))
+
+        self._api.call("editMessageLiveLocation", args)
+
+    @_require_api
+    def stop_live_location(self, extra=None, attach=None):
+        """Stop this message's live location"""
+        args = {"message_id": self.id, "chat_id": self.chat.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
+            ))
+        self._api.call("stopMessageLiveLocation", args)
+
     @_require_api
     def reply(self, *args, **kwargs):
         """Reply to the current message"""

docs/api/telegram.rst

@@ -406,7 +406,7 @@ about its business.
 
          Added support for syntax
 
-   .. py:method:: send_location(latitude, longitude, [reply_to=None, attach=None, extra=None, notify=True])
+   .. py:method:: send_location(latitude, longitude, [live_period=None, reply_to=None, attach=None, extra=None, notify=True])
 
       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
@@ -418,8 +418,12 @@ about its business.
       The *notify* parameter is for defining if your message should trigger
       a notification on the client side (yes by default).
 
+      The *live_period* parameter is for defining if this location must be a live location and needs to be updated over time.
+      Leave to `None` if it is not or set it as a number between 60 and 86400 (seconds) if it is.
+
       :param float latitude: The latitude of the location
       :param float longitude: The longitude of the location
+      :param int live_period: The duration of the live location in seconds, None if it is not a live location.
       :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
@@ -435,6 +439,10 @@ about its business.
 
          Now the method returns the sent message
 
+      .. versionchanged:: 0.7
+
+         Now the method supports live locations
+
    .. py:method:: send_venue(latitude, longitude, title, address, [foursquare=None, reply_to=None, attach=None, extra=None, notify=True])
 
       Send a venue to the user. A venue is made of its geographic coordinates
@@ -1237,9 +1245,9 @@ about its business.
 
          Support text formatting in caption through *syntax*.
 
-   .. py:method:: send_location(latitude, longitude, [reply_to=None, attach=None, extra=None, notify=True])
+   .. py:method:: send_location(latitude, longitude, [live_period=None, reply_to=None, attach=None, extra=None, notify=True])
 
-      Send the geographic location to the chat. If the location you're sending
+      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`.
 
@@ -1249,8 +1257,12 @@ about its business.
       The *notify* parameter is for defining if your message should trigger
       a notification on the client side (yes by default).
 
+      The *live_period* parameter is for defining if this location must be a live location and needs to be updated over time.
+      Leave to `None` if it is not or set it as a number between 60 and 86400 (seconds) if it is.
+
       :param float latitude: The latitude of the location
       :param float longitude: The longitude of the location
+      :param int live_period: The duration of the live location in seconds, None if it is not a live location.
       :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
@@ -1266,6 +1278,10 @@ about its business.
 
          Now the method returns the sent message
 
+      .. versionchanged:: 0.7
+
+         Now the method supports live locations
+
    .. py:method:: send_venue(latitude, longitude, title, address, [foursquare=None, reply_to=None, attach=None, extra=None, notify=True])
 
       Send a venue to the chat. A venue is made of its geographic coordinates
@@ -1895,6 +1911,34 @@ about its business.
 
       .. versionadded:: 0.4
 
+   .. py:method:: edit_live_location(latitude, longitude, [extra=None, attach=None])
+
+      This method allows you to edit the latitude and longitude of a live location you already sent.
+
+      :param float latitude: The new latitude
+      :param float longitude: The new longitude
+      :param object attach: An extra thing to attach to the message.
+      :param object extra: An extra reply interface object to attach.
+
+      .. deprecated:: 0.4
+
+         The *extra* parameter is now deprecated
+
+      .. versionadded:: 0.7
+
+   .. py:method:: stop_live_location([extra=None, attach=None])
+
+      This method allows you to stop a live location and prevent further latitude and longitude edits.
+
+      :param object attach: An extra thing to attach to the message.
+      :param object extra: An extra reply interface object to attach.
+
+      .. deprecated:: 0.4
+
+         The *extra* parameter is now deprecated.
+
+      .. versionadded:: 0.7
+
    .. py:method:: forward_to(to[, notify=True])
 
       Forward this message *to* another chat or user by specifying their ID. One
@@ -2117,7 +2161,7 @@ about its business.
 
          Now the method returns the sent message
 
-   .. py:method:: reply_with_location(latitude, longitude, [attach=None, extra=None, notify=True])
+   .. py:method:: reply_with_location(latitude, longitude, [live_period=None, attach=None, extra=None, notify=True])
 
       Send the geographic location to the user.
 
@@ -2127,8 +2171,13 @@ about its business.
       The *notify* parameter is for defining if your message should trigger
       a notification on the client side (yes by default).
 
+      The *live_period* parameter is for defining if this location must be a live location and needs to be updated over time.
+      Leave to `None` if it is not or set it as a number between 60 and 86400 (seconds) if it is.
+
       :param float latitude: The latitude of the location
       :param float longitude: The longitude of the location
+      :param int live_period: The duration of the live location in seconds, None if it is not a live location.
+      :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 the client notification.
@@ -2143,6 +2192,10 @@ about its business.
 
          Now the method returns the sent message
 
+      .. versionchanged:: 0.7
+
+         Now the method supports live locations
+
    .. py:method:: reply_with_venue(latitude, longitude, title, address, [foursquare=None, attach=None, extra=None, notify=True])
 
       Reply to this message with a venue. A venue is made of its geographic

docs/changelog/0.7.rst

@@ -25,6 +25,13 @@ New features
   * New attribute :py:attr:`~Message.forward_hidden`
   * New attribute :py:attr:`~Message.forward_signature`
 
+* Added support for live locations
+
+  * New parameter `live_period` for :py:meth:`~Chat.send_location` and :py:meth:`~User.send_location`
+  * New parameter `live_period` for :py:meth:`~Message.reply_with_location`
+  * New method :py:meth:`~Message.edit_live_location`
+  * New method :py:meth:`~Message.stop_live_location`
+
 
 Bug fixes
 ---------