Add support for moderating group chats

The Bot API 2.0 update added support for moderating group chats from
your bot, and this commit adds support for that in botogram. There are
two new methods introduced in this commit (along with their docs):

 - botogram.Chat.ban()
 - botogram.Chat.unban()

Fixes: GH-56

Author: Pietro Albini

botogram/objects/chats.py

@@ -216,6 +216,38 @@ def leave(self):
                 raise exc from None
             raise
 
+    @mixins._require_api
+    def ban(self, user):
+        """Ban an user from the group"""
+        # Check if the chat is a group
+        if self.type not in ("group", "supergroup"):
+            raise RuntimeError("This chat is not a group or a supergroup!")
+
+        # Accept also an instance of `User`
+        if isinstance(user, User):
+            user = user.id
+
+        self._api.call("kickChatMember", {
+            "chat_id": self.id,
+            "user_id": user,
+        })
+
+    @mixins._require_api
+    def unban(self, user):
+        """Unban an user from the supergroup"""
+        # Check if the chat is a supergroup
+        if self.type != "supergroup":
+            raise RuntimeError("This chat is nota group or a supergroup!")
+
+        # Accept also an instance of `User`
+        if isinstance(user, User):
+            user = user.id
+
+        self._api.call("unbanChatMember", {
+            "chat_id": self.id,
+            "user_id": user,
+        })
+
 
 class ChatMember(BaseObject):
     """Telegram API representation of a chat member

docs/api/telegram.rst

@@ -531,6 +531,67 @@ about its business.
 
       .. versionadded:: 0.3
 
+   .. py:method:: ban(user)
+
+      Ban the provided user from this group chat. You can either provide the
+      user ID or an instance of :py:class:`~botogram.User`. This method is the
+      cornerstone of :ref:`moderating group chats <manage-chats>`, since it
+      allows your bot to punish misbehaving users.
+
+      While on normal group chats a banned user can rejoin the chat if it's
+      added by one of its members or he uses a join link, on supergroups you
+      need to explicitly :py:meth:`~botogram.Chat.unban` he to let him rejoin.
+
+      Remember your bot must be an administrator of the chat in order to this
+      method to work properly.
+
+      .. code-block:: python
+
+         # This command bans the user who sent the message you replied to
+
+         @bot.command("ban")
+         def ban_user(chat, message, args):
+             """Ban that user"""
+             # Some needed filtering and error handling
+             if message.reply_to_message is None:
+                 message.reply("You must reply to a message the user wrote!")
+             if message.sender not in chat.admins:
+                 message.reply("You must be an admin of the group!")
+             if message.reply_to_message.sender in chat.admins:
+                 message.reply("You can't ban another admin!")
+
+             chat.ban(message.reply_to_message.sender)
+
+      :param int user: The user you want to ban (user ID or
+                       :py:class:`~botogram.User`)
+
+      .. versionadded:: 0.3
+
+   .. py:method:: unban(user)
+
+      Unban the user from this group chat. This does nothing on normal group
+      chats, but it removes the user from the group's blacklist if the chat is
+      a supergroup. This method can be handy if you want to remove the ban you
+      given to an user.
+
+      Remember your bot must be an administrator of the chat in order to this
+      method to work properly.
+
+      .. code-block:: python
+
+         @bot.timer(60)
+         def unban_all(shared, bot):
+             # This unbans all the users in the shared memory
+             for chat_id, user_id in shared["banned_users"].items():
+                 bot.chat(chat_id).unban(user_id)
+
+             shared["banned_users"] = {}
+
+      :param int user: The user you want to unban (user ID or
+                       :py:class:`~botogram.User`)
+
+      .. 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/0.3.rst

@@ -48,6 +48,11 @@ New features
    * New decorator :py:meth:`botogram.Bot.message_edited`
    * New method :py:meth:`botogram.Component.add_message_edited_hook`
 
+* Added support for moderating groups:
+
+   * New method :py:meth:`botogram.Chat.ban`
+   * New method :py:meth:`botogram.Chat.unban`
+
 * Added support for sending contacts:
 
    * New method :py:meth:`botogram.User.send_contact`

docs/groups-management.rst

@@ -0,0 +1,167 @@
+.. Copyright (c) 2016 Pietro Albini <[email protected]>
+   Released under the MIT license
+
+.. _groups-management:
+
+======================
+Moderating group chats
+======================
+
+Group chats are an awesome way to communicate with your circle of friends, but
+you can also use them to discuss with other users in public groups.
+Unfortunately, there are people who just want to spam their own groups or post
+inappropriate content and, without some moderators always online, a public
+group will get messy sooner or later.
+
+Telegram bots are able to moderate groups easily, so you can programmatically
+ban and unban users of the groups your bot is an administrator of.
+
+.. versionadded:: 0.3
+
+.. _groups-management-preparation:
+
+Allowing your bot to moderate groups
+====================================
+
+Bots can't moderate groups by default, but they need to be authorized to do so.
+How to authorize them is specific to the client you use, but take the following
+advices:
+
+* If you're trying to add your bot as administrator to a **group**, you need to
+  disable the "Everyone is an admin" setting of it, and then explicitly mark
+  your bot as administrator.
+
+* If you're trying to add your bot as administrator to a **supergroup**, just
+  add it to the administrators list.
+
+Keep in mind your bot might lose its status of administrator during the
+conversion from a group to a supergroup, so if you converted a group check if
+your bot is still an administrator of it.
+
+.. _groups-management-ban:
+
+Banning nasty users
+===================
+
+Nobody wants users joining a public groups just to spam their own group but, if
+there isn't a moderator always online, a spammer can join in the middle of the
+night, and multiple users might see their message before a moderator gets
+online to ban him.
+
+As an example, with the aid of :py:class:`~botogram.ParsedText` you can detect
+all the posted URLs, and ban all the user who sends a ``telegram.me`` link,
+with :py:meth:`botogram.Chat.ban`. Unfortunately bots can't delete messages
+yet, but they can mention all the administrators of the group, so they can
+erase that message later:
+
+.. code-block:: python
+   :emphasize-lines: 15,16
+
+   @bot.process_message
+   def ban_telegram_links(chat, message):
+       # Don't do anything if there is no text message
+       if message.text is None:
+           return
+
+       # Check all the links in the message
+       for link in message.parsed_text.filter("link"):
+           # Match both HTTP and HTTPS links
+           if "://telegram.me" in link.url:
+               break
+       else:
+           return
+
+       # Ban the sender of the message
+       chat.ban(message.sender)
+
+       # Tell all the admins of the chat to delete the message
+       admins = " ".join("@"+a.username for a in chat.admins if a.username)
+       if admins:
+           message.reply("%s! Please delete this message!" % admins)
+       return
+
+.. _groups-management-unban:
+
+Unbanning users from supergroups
+================================
+
+If an user is banned from a group chat, he can rejoin the group if he uses a
+join link or it's added by another member. Instead, when an user is banned from
+a supergroup he's put in a blacklist, and he needs to be explicitly removed
+from it if he want to join the supergroup again.
+
+The following example is a working tempban code, which stores when the user was
+banned in :ref:`the shared memory <shared-memory>`, with a :ref:`timer
+<tasks-repeated>` to unban the user later. The actual unban is executed via the
+:py:meth:`botogram.Chat.unban` method:
+
+.. code-block:: python
+   :emphasize-lines: 60
+
+   import time
+
+   # This means `/tempban 1` bans the user for 60 seconds
+   BAN_DURATION_MULTIPLIER = 60
+
+   @bot.prepare_memory
+   def prepare_memory(shared):
+       shared["bans"] = {}
+
+   @bot.command("tempban")
+   def tempban_command(shared, chat, message, args):
+       """Tempban an user from the group"""
+       # Handle some possible errors
+       if message.sender not in chat.admins:
+           message.reply("You're not an admin of this chat!")
+           return
+       if not message.reply_to_message:
+           message.reply("You must reply to a message the user sent!")
+           return
+       if message.reply_to_message.sender in chat.admins:
+           message.reply("You can't ban another admin!")
+           return
+
+       # Get the exact ban duration
+       try:
+           length = int(args[0])
+       except (IndexError, TypeError):
+           message.reply("You must provide the length of the ban!")
+           return
+
+       # Store the ban in the shared memory
+       with shared.lock("bans-change"):
+           bans = shared["bans"]
+           if chat.id not in bans:
+               bans[chat.id] = {}
+
+           # Calculate the expiry time and store it
+           expiry = time.time()+length*BAN_DURATION_MULTIPLIER
+           bans[chat.id][message.reply_to_message.sender.id] = expiry
+           shared["bans"] = bans
+
+       # Let's finally ban this guy!
+       chat.ban(message.reply_to_message.sender)
+
+   @bot.timer(BAN_DURATION_MULTIPLIER)
+   def unban_timer(bot, shared):
+       """Unban the users"""
+       now = time.time()
+
+       # Everything is locked so no there are no races
+       with shared.lock("bans-change"):
+           global_bans = shared["bans"]
+
+           # Here .copy() is used because we're changing the dicts in-place
+           for chat_id, bans in global_bans.copy().items():
+               for user, expires in bans.copy().items():
+                   # Unban the user if his ban expired
+                   if expires <= now:
+                       continue
+                   bot.chat(chat_id).unban(user)
+                   del global_bans[chat_id][user]
+
+               # Cleaning up is not such a bad thing...
+               if not global_bans[chat_id]:
+                   del global_bans[chat_id]
+
+           shared["bans"] = global_bans

docs/index.rst

@@ -55,6 +55,7 @@ Narrative documentation
    bot-creation
    bot-structure
    unavailable-chats
+   groups-management
    shared-memory
    tasks
    custom-components