Add support for sending generic files

Added and documented the following methods:

 * botogram.Bot.send_file
 * botogram.User.send_file
 * botogram.Chat.send_file
 * botogram.Message.reply_with_file

Author: Pietro Albini

botogram/frozenbot.py

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

botogram/objects/mixins.py

@@ -124,6 +124,26 @@ def send_voice(self, path, duration=None, title=None, reply_to=None,
 
         self._api.call("sendVoice", args, files)
 
+    @_require_api
+    def send_file(self, path, reply_to=None, extra=None):
+        """Send a generic file"""
+        # Convert instances of Message to ids in reply_to
+        if hasattr(reply_to, "message_id"):
+            reply_to = reply_to.message_id
+
+        # Get the correct chat_id
+        chat_id = self.username if self.type == "channel" else self.id
+
+        args = {"chat_id": chat_id}
+        if reply_to is not None:
+            args["reply_to_message_id"] = reply_to
+        if extra is not None:
+            args["reply_markup"] = extra.serialize()
+
+        files = {"document": open(path, "rb")}
+
+        self._api.call("sendDocument", args, files)
+
 
 class MessageMixin:
     """Add some methods for messages"""
@@ -162,6 +182,11 @@ def reply_with_voice(self, path, duration=None, extra=None):
         """Reply with a voice message to the current message"""
         self.chat.send_voice(path, duration, self.message_id, extra)
 
+    @_require_api
+    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)
+
 
 class FileMixin:
     """Add some methods for files"""

docs/api/bot.rst

@@ -379,3 +379,25 @@ components.
       :param int duration: The message duration, in seconds
       :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_file(chat, path, [reply_to=None, extra=None])
+
+      This method sends a generic file to a specific chat. The chat must be
+      identified by its ID, and Telegram applies some restrictions on the chats
+      allowed to receive your photo: only users who sent you a message in the
+      past are allowed, and also the group chats your bot is currently in.
+
+      You must provide the *path* to the file. If the file 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 file
+      :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

docs/api/telegram.rst

@@ -142,6 +142,22 @@ 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_file(path, [reply_to=None, extra=None])
+
+      Send the generic file found in the *path* to the user. If the file 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 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:class:: botogram.Chat
 
@@ -262,6 +278,22 @@ 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_file(path, [reply_to=None, extra=None])
+
+      Send the generic file found in the *path* to the chat. If the file 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 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:class:: botogram.Message
 
@@ -524,6 +556,21 @@ Available Classes
       :param int duration: The message duration, in seconds
       :param object extra: An extra reply interface object to attach
 
+   .. py:method:: send_file(path, [extra=None])
+
+      Reply with the generic file found in the *path* to the chat. If the file
+      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 str path: The path to the file
+      :param object extra: An extra reply interface object to attach
+
 
 .. py:class:: botogram.Photo