Support for animations (#129)

* Add _get_file_args function in ChatMixin

(cherry picked from commit 54b8b6c)

* Better syntax for _get_file_args()

(cherry picked from commit e344f4c)

* Fix PEP-8

(cherry picked from commit 79530ec)

* Support for animations / new methods send_gif and reply_with_gif

* Add Animation in objects/__init__.py

* Add documentation and changelog

* Fix indentation error

* Fix (stupid) import error

Author: MarcoBuster

botogram/objects/__init__.py

@@ -22,12 +22,12 @@
 
 from .chats     import User, Chat, UserProfilePhotos, Permissions
 from .media     import PhotoSize, Photo, Audio, Voice, Document, Sticker, \
-                       Video, VideoNote, Contact, Location, Venue
+                       Video, VideoNote, Animation, Contact, Location, Venue
 from .messages  import Message
 from .markup    import ReplyKeyboardMarkup, ReplyKeyboardHide, ForceReply
 from .polls     import Poll, PollOption
 from .updates   import Update, Updates
-from .mixins import Album
+from .mixins    import Album
 
 __all__ = [
     # Chats-related objects
@@ -44,6 +44,7 @@
     "Sticker",
     "Video",
     "VideoNote",
+    "Animation",
     "Contact",
     "Location",
     "Venue",

botogram/objects/media.py

@@ -187,6 +187,27 @@ class Video(BaseObject, mixins.FileMixin):
     _check_equality_ = "file_id"
 
 
+class Animation(BaseObject, mixins.FileMixin):
+    """Telegram API representation of an animation
+
+    https://core.telegram.org/bots/api#animation
+    """
+
+    required = {
+        "file_id": str,
+        "width": int,
+        "height": int,
+        "duration": int,
+    }
+    optional = {
+        "thumb": PhotoSize,
+        "file_name": str,
+        "mime_type": str,
+        "file_size": int,
+    }
+    _check_equality_ = "file_id"
+
+
 class Contact(BaseObject):
     """Telegram API representation of a contact
 

botogram/objects/messages.py

@@ -25,7 +25,7 @@
 from .. import utils
 from .chats import User, Chat
 from .media import Audio, Voice, Document, Photo, Sticker, Video, VideoNote, \
-    Contact, Location, Venue
+    Animation, Contact, Location, Venue
 from .polls import Poll
 
 
@@ -347,6 +347,7 @@ def from_(self):
         "sticker": Sticker,
         "video": Video,
         "video_note": VideoNote,
+        "animation": Animation,
         "caption": str,
         "contact": Contact,
         "location": Location,

botogram/objects/mixins.py

@@ -241,6 +241,37 @@ def send_video_note(self, path=None, file_id=None, duration=None,
         return self._api.call("sendVideoNote", args, files,
                               expect=_objects().Message)
 
+    @_require_api
+    def send_gif(self, path=None, file_id=None, url=None, duration=None,
+                 width=None, height=None, caption=None, thumb=None,
+                 reply_to=None, extra=None, attach=None,
+                 notify=True, syntax=None):
+        """Send an animation"""
+        args = self._get_call_args(reply_to, extra, attach, notify)
+        if duration is not None:
+            args["duration"] = duration
+        if caption is not None:
+            args["caption"] = caption
+            if syntax is not None:
+                syntax = syntaxes.guess_syntax(caption, syntax)
+                args["parse_mode"] = syntax
+        if width is not None:
+            args["width"] = width
+        if height is not None:
+            args["height"] = height
+
+        files = dict()
+        args["animation"], files["animation"] = self._get_file_args(path,
+                                                                    file_id,
+                                                                    url)
+        if files["animation"] is None:
+            del files["animation"]
+        if thumb is not None:
+            files["thumb"] = thumb
+
+        return self._api.call("sendAnimation", args, files,
+                              expect=_objects().Message)
+
     @_require_api
     def send_file(self, path=None, file_id=None, url=None, thumb=None,
                   reply_to=None, extra=None, attach=None,
@@ -523,6 +554,10 @@ def reply_with_video_note(self, *args, **kwargs):
         """Reply with a video note to the current message"""
         return self.chat.send_video_note(*args, reply_to=self, **kwargs)
 
+    @_require_api
+    def reply_with_gif(self, *args, **kwargs):
+        return self.chat.send_gif(*args, reply_to=self, **kwargs)
+
     @_require_api
     def reply_with_file(self, *args, **kwargs):
         """Reply with a generic file to the current chat"""

docs/api/telegram.rst

@@ -363,6 +363,41 @@ about its business.
 
       .. versionadded:: 0.6
 
+   .. py:method:: send_gif([path=None, file_id=None, duration=None, width=None, height=None, caption=None, thumb=None, reply_to=None, attach=None, extra=None, notify=True])
+
+      Send an animation to the user. You can specify the animation by passing its *path*,
+      its *url*, or its Telegram *file_id*. Only one of these arguments must be passed.
+
+      You may optionally specify the *duration*, the *width* and the *height* of the GIF.
+      If the GIF track 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.
+
+      The *notify* parameter is for defining if your message should trigger
+      a notification on the client side (yes by default).
+
+      :param str path: The path to the animation
+      :param str file_id: The Telegram *file_id* of the animation
+      :param int duration: The animation duration, in seconds
+      :param str width: The animation width, in pixels
+      :param str height: The animation height, in pixels
+      :param str caption: The caption of the video
+      :param str thumb: The path to the thumb
+      :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.
+      :returns: The message you sent
+      :rtype: ~botogram.Message
+
+      .. deprecated:: 0.4
+
+         The *extra* parameter is now deprecated
+
+      .. versionadded:: 0.7
+
    .. py:method:: send_file([path=None, file_id=None, url=None, thumb=None, reply_to=None, attach=None, extra=None, notify=True, caption=None, syntax=None])
 
       Send a generic file to the user. You can specify the file by passing its *path*,
@@ -1210,6 +1245,41 @@ about its business.
 
       .. versionadded:: 0.6
 
+   .. py:method:: send_gif([path=None, file_id=None, duration=None, width=None, height=None, caption=None, thumb=None, reply_to=None, attach=None, extra=None, notify=True])
+
+      Send an animation to the user. You can specify the animation by passing its *path*,
+      its *url*, or its Telegram *file_id*. Only one of these arguments must be passed.
+
+      You may optionally specify the *duration*, the *width* and the *height* of the GIF.
+      If the GIF track 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.
+
+      The *notify* parameter is for defining if your message should trigger
+      a notification on the client side (yes by default).
+
+      :param str path: The path to the animation
+      :param str file_id: The Telegram *file_id* of the animation
+      :param int duration: The animation duration, in seconds
+      :param str width: The animation width, in pixels
+      :param str height: The animation height, in pixels
+      :param str caption: The caption of the video
+      :param str thumb: The path to the thumb
+      :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.
+      :returns: The message you sent
+      :rtype: ~botogram.Message
+
+      .. deprecated:: 0.4
+
+         The *extra* parameter is now deprecated
+
+      .. versionadded:: 0.7
+
    .. py:method:: send_file([path=None, file_id=None, url=None, thumb=None, reply_to=None, attach=None, extra=None, notify=True, caption=None, syntax=None])
 
       Send a generic file to the chat. You can specify the video by passing its *path*,
@@ -1728,6 +1798,14 @@ about its business.
       file.
 
       *This attribute can be None if it's not provided by Telegram.*
+
+   .. py:attribute:: animation
+
+      A :py:class:`~botogram.Animation~ object, for when this message is an animation
+      file.
+
+      *This attribute can be None if it's not provided by Telegram.*
+
    .. py:attribute:: caption
 
       A caption for when this message is a photo or video file.
@@ -2137,7 +2215,7 @@ about its business.
 
    .. py:method:: reply_with_video_note([path=None, file_id=None, duration=None, length=None, thumb=None, attach=None, extra=None, notify=True])
 
-      Reply with the  video note to the user. You can specify the video note by passing its *path*,
+      Reply with the video note to the user. You can specify the video note by passing its *path*,
       or its Telegram *file_id*. Only one of these arguments must be passed.
 
       You may optionally specify the *duration* and the *length* of the video.
@@ -2168,6 +2246,41 @@ about its business.
 
       .. versionadded:: 0.6
 
+   .. py:method:: reply_with_gif([path=None, file_id=None, duration=None, width=None, height=None, caption=None, thumb=None, attach=None, extra=None, notify=True])
+
+      Reply with an animation to the message. You can specify the animation by passing its *path*,
+      its *url*, or its Telegram *file_id*. Only one of these arguments must be passed.
+
+      You may optionally specify the *duration*, the *width* and the *height* of the GIF.
+      If the GIF track 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.
+
+      The *notify* parameter is for defining if your message should trigger
+      a notification on the client side (yes by default).
+
+      :param str path: The path to the animation
+      :param str file_id: The Telegram *file_id* of the animation
+      :param int duration: The animation duration, in seconds
+      :param str width: The animation width, in pixels
+      :param str height: The animation height, in pixels
+      :param str caption: The caption of the video
+      :param str thumb: The path to the thumb
+      :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.
+      :returns: The message you sent
+      :rtype: ~botogram.Message
+
+      .. deprecated:: 0.4
+
+         The *extra* parameter is now deprecated
+
+      .. versionadded:: 0.7
+
    .. py:method:: reply_with_file(path, [thumb=None, attach=None, extra=None, notify=True])
 
       Reply with the generic file found in the *path* to the chat. If the file
@@ -2709,6 +2822,60 @@ about its business.
       :param str path: The file name path locating where the video note should be saved.
 
 
+.. py:class:: botogram.Animation
+
+   This class represents an animation file.
+
+   .. py:attribute:: file_id
+
+      The string ID of the file.
+
+   .. py:attribute:: length
+
+      The integer length of the animation as defined by the sender.
+
+   .. py:attribute:: width
+
+      The integer width of the video as defined by the sender.
+
+   .. py:attribute:: height
+
+      The integer height of the video as defined by the sender.
+
+   .. py:attribute:: thumb
+
+      A :py:class:`~botogram.PhotoSize` object representing a thumbnail image of
+      the animation as defined by the sender.
+
+      *This attribute can be None if it's not provided by Telegram.*
+
+   .. py:attribute:: file_name
+
+      The original animation filename as defined by the sender.
+
+      *This attribute can be None if it's not provided by Telegram.*
+
+   .. py:attribute:: mime_type
+
+      The MIME type of the file as defined by the sender.
+
+      *This attribute can be None if it's not provided by Telegram.*
+
+   .. py:attribute:: file_size
+
+      The integer size of the animation file
+
+      *This attribute can be None if it's not provided by Telegram.*
+
+   .. py:method:: save(path)
+
+      Save the animation to a file located by *path*. Be aware that Telegram can
+      not provide the name of the original file sent by its sender. This should
+      be generated as part of the path.
+
+      :param str path: The file name path locating where the video note should be saved.
+
+
 .. py:class:: botogram.Voice
 
    This class represents a voice message.

docs/changelog/0.7.rst

@@ -19,6 +19,15 @@ Release description not yet written.
 New features
 ------------
 
+
+* Added support for animations (GIFs)
+
+    * New :py:class:`botogram.Animation` class
+    * New attribute :py:attr:`botogram.Message.animation`
+    * New method :py:meth:`botogram.Chat.send_gif`
+    * New method :py:meth:`botogram.User.send_gif`
+    * New method :py:meth:`botogram.Message.reply_with_gif`
+
 * Added support for polls
 
    * New :py:class:`botogram.Poll`