Add a new Chat.leave() method

This method allows the bot to kick itself out of a group, for example
if the group members are spamming him with too much messages. Support
for it was introduced in the Bot API 2.1 update.

Author: Pietro Albini

botogram/objects/chats.py

@@ -6,6 +6,7 @@
     Released under the MIT license
 """
 
+from .. import api
 from .base import BaseObject, multiple
 from . import mixins
 
@@ -104,6 +105,20 @@ def name(self):
 
         return result
 
+    def leave(self):
+        """Leave this chat"""
+        if self.type not in ("group", "supergroup"):
+            raise TypeError("This method can only be called in groups and "
+                            "supergroups")
+
+        try:
+            self._api.call("leaveChat", {"chat_id": self.id})
+        except api.APIError as e:
+            if e.error_code == 403 and "not a member" in e.description:
+                exc = RuntimeError("The bot isn't a member of this group")
+                raise exc from None
+            raise
+
 
 class UserProfilePhotos(BaseObject):
     """Telegram API representation of an user's profile photos

docs/api/telegram.rst

@@ -370,6 +370,25 @@ about its business.
 
       .. versionadded:: 0.2
 
+   .. py:method:: leave()
+
+      Kick the bot from this chat. This method is available only on groups and
+      supergroups, and the bot must be a member of the chat.
+
+      This method might be handy if the other members of the group are abusing
+      your bot, or spamming it with too much messages. Keep in mind though, an
+      admin of the chat can re-add your bot at any time, so if you want to
+      forget about it you need to store the chat ID somewhere and leave the
+      group as soon as your bot joins it.
+
+      .. code-block:: python
+
+         @bot.command("bye")
+         def bye_command(chat):
+             chat.leave()
+
+      .. versionadded:: 0.3
+
    .. py:method:: send(message, [preview=True, reply_to=None, syntax=None, extra=None, notify=True])
 
       Send the textual *message* to the chat. You may optionally stop clients

docs/changelog.rst

@@ -47,6 +47,7 @@ New features
 
 * Added new attribute :py:attr:`botogram.Message.pinned_message`
 * Added new attribute :py:attr:`botogram.Sticker.emoji`
+* Added new method :py:meth:`botogram.Chat.leave`
 * 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)