Add Bot.chat and deprecate Bot.send*

The Bot API 2.1 update introduced a new API call to get all information
about a chat from its ID, which can be used to recreate a Chat object.

Because of that, all the send* methods on the Bot class were retundant,
since you can do `bot.chat(123).send("Message")`. Because of that, all
those methods are now deprecated, and they will be removed in botogram
1.0.

Fixes: GH-65

Author: Pietro Albini

botogram/frozenbot.py

@@ -128,6 +128,12 @@ def init_shared_memory(self, func):
     # This class also contains methods to send messages to users
     # They're defined dynamically out of the class body, see below
 
+    # Get a chat from its ID
+
+    def chat(self, id):
+        """Get an instance of botogram.Chat based on its ID"""
+        return self.api.call("getChat", {"chat_id": id}, expect=objects.Chat)
+
     # Edit messages already sent
 
     def _edit_create_fake_message_object(self, chat, message):
@@ -267,6 +273,8 @@ def hide_commands(self):
 
 for _proxy in _proxied_sends:
     @utils.wraps(_proxy)
+    @utils.deprecated("0.1", "1.0", "Use Bot.chat(id).%s() instead."
+                      % _proxy.__name__)
     def _wrapper(self, chat, *args, __proxy=_proxy, **kwargs):
         # String chats are channels
         if type(chat) == str:

docs/api/bot.rst

@@ -359,6 +359,24 @@ components.
 
       .. versionadded:: 0.3
 
+   .. py:method:: chat(id)
+
+      Get the :py:class:`~botogram.Chat` object of the chat with the ID you
+      provided to this method. You can use this to get information about a chat
+      you know about, or to send messages to other chats:
+
+      .. code-block:: python
+
+         BROADCAST_TO = [123, 321, 132]  # List of chat IDs
+
+         @bot.command("broadcast")
+         def broadcast_command(bot, chat, message, args):
+             """Broadcast a message to multiple chats"""
+             to_send = " ".join(args)
+
+             for chat_id in BROADCAST_TO:
+                 bot.chat(chat_id).send(to_send)
+
    .. py:method:: send(chat, message[, preview=True, reply_to=None, syntax=None, extra=None, notify=True])
 
       This method sends a message to a specific chat. The chat must be
@@ -396,6 +414,8 @@ components.
 
          Now the method returns the sent message
 
+      .. deprecated:: 0.3 it will be removed in botogram 1.0
+
    .. py:method:: send_photo(chat, path[, caption="", reply_to=None, extra=None, notify=True])
 
       This method sends a photo to a specific chat. The chat must be identified
@@ -427,6 +447,8 @@ components.
 
          Now the method returns the sent message
 
+      .. deprecated:: 0.3 it will be removed in botogram 1.0
+
    .. py:method:: send_audio(chat, path, [duration=None, performer=None, title=None, reply_to=None, extra=None, notify=True])
 
       This method sends an audio track to a specific chat. The chat must be
@@ -463,6 +485,8 @@ components.
 
          Now the method returns the sent message
 
+      .. deprecated:: 0.3 it will be removed in botogram 1.0
+
    .. py:method:: send_voice(chat, path, [duration=None, reply_to=None, extra=None, notify=True])
 
       This method sends a voice message to a specific chat. The chat must be
@@ -497,6 +521,8 @@ components.
 
          Now the method returns the sent message
 
+      .. deprecated:: 0.3 it will be removed in botogram 1.0
+
    .. py:method:: send_video(chat, path, [duration=None, caption=None, reply_to=None, extra=None, notify=True])
 
       This method sends a video to a specific chat. The chat must be identified
@@ -532,6 +558,8 @@ components.
 
          Now the method returns the sent message
 
+      .. deprecated:: 0.3 it will be removed in botogram 1.0
+
    .. py:method:: send_file(chat, path, [reply_to=None, extra=None, notify=True])
 
       This method sends a generic file to a specific chat. The chat must be
@@ -564,6 +592,8 @@ components.
 
          Now the method returns the sent message
 
+      .. deprecated:: 0.3 it will be removed in botogram 1.0
+
    .. py:method:: send_location(chat, latitude, longitude, [reply_to=None, extra=None, notify=True])
 
       This method sends a geographic location to a specific chat. The chat must
@@ -597,6 +627,8 @@ components.
 
          Now the method returns the sent message
 
+      .. deprecated:: 0.3 it will be removed in botogram 1.0
+
    .. py:method:: send_sticker(sticker, [reply_to=None, extra=None, notify=True])
 
       This method sends a sticker to a specific chat chat (in webp format). The
@@ -629,6 +661,8 @@ components.
 
          Now the method returns the sent message
 
+      .. deprecated:: 0.3 it will be removed in botogram 1.0
+
    .. py:attribute:: hide_commands
 
       This attribute is now deprecated, use the ``hidden`` argument of the

docs/changelog.rst

@@ -57,6 +57,7 @@ New features
 * Added new attribute :py:attr:`botogram.Chat.members_count`
 * Added new method :py:meth:`botogram.Chat.status_of`
 * Added new method :py:meth:`botogram.Chat.leave`
+* Added new method :py:meth:`botogram.Bot.chat`
 * Every method which sends something to a chat now returns the sent
   :py:class:`~botogram.Message`
 * Multiple instances of the same bot are now properly handled (as errors)
@@ -95,6 +96,14 @@ Deprecated features will be removed in botogram 1.0!
 * ``Message.new_chat_participant`` is now deprecated
 * ``Message.left_chat_participant`` is now deprecated
 * ``Bot.hide_commands`` is now deprecated
+* ``Bot.send`` is now deprecated
+* ``Bot.send_photo`` is now deprecated
+* ``Bot.send_audio`` is now deprecated
+* ``Bot.send_voice`` is now deprecated
+* ``Bot.send_video`` is now deprecated
+* ``Bot.send_file`` is now deprecated
+* ``Bot.send_location`` is now deprecated
+* ``Bot.send_sticker`` is now deprecated
 
 .. _issue 67: https://github.com/pietroalbini/botogram/issues/67