Add the Chat.admins dynamic attribute

This new attribute returns the list of the administrators of the group
chat, fetching it from a new API introduced by the Bot API 2.1 update.

Issue: GH-64

Author: Pietro Albini

botogram/objects/chats.py

@@ -93,6 +93,22 @@ class Chat(BaseObject, mixins.ChatMixin):
     }
     _check_equality_ = "id"
 
+    def _to_user(self):
+        """Convert this Chat object to an User object"""
+        if self.type != "private":
+            raise TypeError("This method works only on private chats!")
+
+        # Be sure to cache the instance
+        if not hasattr(self, "_cache_user"):
+            self._cache_user = User({
+                "id": self.id,
+                "first_name": self.first_name,
+                "last_name": self.last_name,
+                "username": self.username,
+            }, self._api)
+
+        return self._cache_user
+
     @property
     def name(self):
         """Get the full name of the chat"""
@@ -107,6 +123,27 @@ def name(self):
 
         return result
 
+    @property
+    def admins(self):
+        """Get a list of the admins of the chat"""
+        # If this is a private chat, return the current user since Telegram
+        # doesn't support `getChatAdministrators` for private chats
+        if self.type == "private":
+            return [self._to_user()]
+        elif self.type == "channel":
+            raise TypeError("Not available on channels")
+
+        # Be sure to cache the list of the admins
+        if not hasattr(self, "_cache_admins"):
+            members = self._api.call("getChatAdministrators",
+                                     {"chat_id": self.id},
+                                     expect=multiple(ChatMember))
+            self._cache_admins = tuple(member.user for member in members)
+
+        # The list of admins is saved as a tuple, so it's not mutable, but it's
+        # returned as a list (the tuple thing is an implementation detail)
+        return list(self._cache_admins)
+
     def leave(self):
         """Leave this chat"""
         if self.type not in ("group", "supergroup"):
@@ -122,6 +159,19 @@ def leave(self):
             raise
 
 
+class ChatMember(BaseObject):
+    """Telegram API representation of a chat member
+
+    https://core.telegram.org/bots/api#chatmember
+    """
+
+    required = {
+        "user": User,
+        "status": str,
+    }
+    _check_equality_ = "user"
+
+
 class UserProfilePhotos(BaseObject):
     """Telegram API representation of an user's profile photos
 

docs/api/telegram.rst

@@ -370,6 +370,43 @@ about its business.
 
       .. versionadded:: 0.2
 
+   .. py:attribute:: admins
+
+      The list of the administrators of the group (or supergroup), represented
+      as a list of :py:class:`~botogram.User`. If the chat is a private chat, a
+      list containing only the chat partner is returned. Instead, a
+      ``TypeError`` is raised if the chat is a channel.
+
+      Please remember the content of this attribute is fetched from Telegram
+      the first time you access it (so it might be slow), but it's cached right
+      after, so the following accesses will involve no network communication.
+
+      .. code-block:: python
+         :emphasize-lines: 14,15,16
+
+         # This hook bans a member of the group if an admin replies to one of
+         # its messages with "#ban"
+
+         @bot.process_message
+         def ban_users(chat, message):
+            # Allow only groups
+            if message.type not in ("group", "supergroup"):
+                return
+
+            # Allow only replies with text in the reply
+            if message.text is None or message.reply_to_message is None:
+                return
+
+            # Allow only admins to ban people
+            if message.sender not in chat.admins:
+                return
+
+            # Match the text and ban the original message sender
+            if message.text == "#ban":
+                chat.ban(message.reply_to_message.sender)
+
+      .. versionadded:: 0.3
+
    .. py:method:: leave()
 
       Kick the bot from this chat. This method is available only on groups and

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 attribute :py:attr:`botogram.Chat.admins`
 * Added new method :py:meth:`botogram.Chat.leave`
 * Every method which sends something to a chat now returns the sent
   :py:class:`~botogram.Message`