Merge branch 'renyhp/stickers'

Author: pietroalbini

botogram/objects/mixins.py

@@ -273,12 +273,34 @@ def send_venue(self, latitude, longitude, title, address, foursquare=None,
         self._api.call("sendVenue", args, expect=_objects().Message)
 
     @_require_api
-    def send_sticker(self, sticker, reply_to=None, extra=None, attach=None,
-                     notify=True):
+    def send_sticker(self, sticker=None, reply_to=None, extra=None,
+                     attach=None, notify=True, *,
+                     path=None, file_id=None, url=None):
         """Send a sticker"""
+        if sticker is not None:
+            if path is not None:
+                raise TypeError("The sticker argument is overridden by " +
+                                "the path one")
+            path = sticker
+            _deprecated_message(
+                "The sticker parameter", "1.0", "use the path parameter", -3
+            )
+
         args = self._get_call_args(reply_to, extra, attach, notify)
+        if path is not None and file_id is None and url is None:
+            files = {"sticker": open(path, "rb")}
+        elif file_id is not None and path is None and url is None:
+            files = None
+            args["sticker"] = file_id
+        elif url is not None and file_id is None and path is None:
+            args["sticker"] = url
+            files = None
+        elif path is None and file_id is None and url is None:
+            raise TypeError("path or file_id or URL is missing")
+        else:
+            raise TypeError("Only one among path, file_id and URL must be " +
+                            "passed")
 
-        files = {"sticker": open(sticker, "rb")}
         return self._api.call("sendSticker", args, files,
                               expect=_objects().Message)
 

docs/api/telegram.rst

@@ -412,11 +412,12 @@ about its business.
 
       .. versionadded:: 0.3
 
-   .. py:method:: send_sticker(sticker, [reply_to=None, attach=None, extra=None, notify=True])
+   .. py:method:: send_sticker([sticker=None, reply_to=None, attach=None, extra=None, notify=True, path=None, file_id=None, url=None])
 
-      Send the sticker to the user (in webp format). If the sticker you're
-      sending is in reply to another message, set *reply_to* to the ID of the
-      other :py:class:`~botogram.Message`.
+      Send the sticker to the user (in webp format). You can specify the sticker by
+      passing its *path*, its *url*, or its Telegram *file_id*. Only one of these 
+      arguments must be passed. If the sticker you're sending is in reply to another message,
+      set *reply_to* to the ID of the other :py:class:`~botogram.Message`.
 
       The *attach* parameter allows you to attach extra things like
       :ref:`buttons <buttons>` to the message.
@@ -429,12 +430,19 @@ about its business.
       :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.
+      :param str path: The path to the webp-formatted sticker
+      :param str file_id: The Telegram *file_id* of the sticker
+      :param str url: The URL to the webp-formatted sticker
       :returns: The message you sent
       :rtype: ~botogram.Message
 
       .. deprecated:: 0.4
 
          The *extra* parameter is now deprecated
+         
+     .. deprecated:: 0.6
+
+         The *sticker* parameter is now deprecated
 
       .. versionchanged:: 0.3
 
@@ -1053,11 +1061,12 @@ about its business.
 
       .. versionadded:: 0.3
 
-   .. py:method:: send_sticker(sticker, [reply_to=None, attach=None, extra=None, notify=True])
+   .. py:method:: send_sticker([sticker=None, reply_to=None, attach=None, extra=None, notify=True, file_id=None, url=None])
 
-      Send the sticker to the chat (in webp format). If the sticker you're
-      sending is in reply to another message, set *reply_to* to the ID of the
-      other :py:class:`~botogram.Message`.
+      Send the sticker to the chat (in webp format). You can specify the sticker by
+      passing its *path*, its *url*, or its Telegram *file_id*. Only one of these 
+      arguments must be passed. If the sticker you're sending is in reply to another message,
+      set *reply_to* to the ID of the other :py:class:`~botogram.Message`.
 
       The *attach* parameter allows you to attach extra things like
       :ref:`buttons <buttons>` to the message.
@@ -1070,12 +1079,19 @@ about its business.
       :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.
+      :param str path: The path to the webp-formatted sticker
+      :param str file_id: The Telegram *file_id* of the sticker
+      :param str url: The URL to the webp-formatted sticker
       :returns: The message you sent
       :rtype: ~botogram.Message
 
       .. deprecated:: 0.4
 
          The *extra* parameter is now deprecated
+         
+     .. deprecated:: 0.6
+
+         The *sticker* parameter is now deprecated
 
       .. versionchanged:: 0.3
 

docs/changelog/0.6.rst

@@ -32,3 +32,15 @@ New features
   * New argument ``syntax`` in :py:meth:`botogram.User.send_video`
   * New argument ``syntax`` in :py:meth:`botogram.User.send_voice`
   * New argument ``syntax`` in :py:meth:`botogram.Message.edit_caption`
+  
+* Added support for sending stickers by ID or URL
+  
+  * New arguments ``path``, ``file_id`` and ``url`` in :py:meth:`botogram.Chat.send_sticker`
+  * New arguments ``path``, ``file_id`` and ``url`` in :py:meth:`botogram.User.send_sticker`
+  
+Deprecated features
+-------------------
+
+Deprecated features will be removed in botogram 1.0!
+
+* The ``sticker`` parameter in :py:meth:`botogram.Chat.send_sticker` and :py:meth:`botogram.User.send_sticker` is now deprecated