Add the Chat.status_of(user) method

This new method returns the current status of an user in a group chat.
List of possible status is available in the documentation. Support for
this was introduced in the Bot API 2.1 update.

Issue: GH-64

botogram/objects/chats.py

@@ -179,6 +179,29 @@ def members_count(self):
                                                        expect=int)
         return self._cache_members_count
 
+    def status_of(self, user):
+        """Check the status of a member of the group"""
+        if self.type in ("private", "channel"):
+            raise TypeError("Not available in private chats or channels")
+
+        # Convert Users to IDs
+        if isinstance(user, User):
+            user = user.id
+
+        # Initialize the cache
+        if not hasattr(self, "_cache_status_of"):
+            self._cache_status_of = {}
+
+        # Populate the cache for new users
+        if user not in self._cache_status_of:
+            member = self._api.call("getChatMember", {
+                "chat_id": self.id,
+                "user_id": user,
+            }, expect=ChatMember)
+            self._cache_status_of[user] = member.status
+
+        return self._cache_status_of[user]
+
     def leave(self):
         """Leave this chat"""
         if self.type not in ("group", "supergroup"):

docs/api/telegram.rst

@@ -452,6 +452,42 @@ about its business.
 
       .. versionadded:: 0.3
 
+   .. py:method:: status_of(user)
+
+      Return the status of the provided user (either an instance of
+      :py:class:`~botogram.User` or an ID) in the group chat. A ``TypeError``
+      is raised if the current chat is a private conversation or a channel.
+
+      Currently available statuses:
+
+      * **creator**: this user created the group in the first place
+      * **administrator**: the user is an admin appointed by the group creator
+      * **member**: the user is a normal member of the group
+      * **left**: the user left the group in the past or never joined it
+      * **kicked**: the user was kicked by an administrator out of the group
+
+      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: 6,7
+
+         @bot.command("status_of")
+         def status_of_command(chat, message, args):
+             if len(args) != 1:
+                 message.reply("You must provide just the ID of the user!")
+
+             status = chat.status_of(int(args[0]))
+             chat.send("*%s*" % status)
+
+      :param user: the user you want to check the status of (either
+                   :py:class:`~botogram.User` or the user ID as an ``int``)
+      :returns: the status of the user
+      :rtype: str
+
+      .. versionaddedd:: 0.3
+
    .. py:method:: leave()
 
       Kick the bot from this chat. This method is available only on groups and

docs/changelog.rst

@@ -50,6 +50,7 @@ New features
 * Added new attribute :py:attr:`botogram.Chat.admins`
 * Added new attribute :py:attr:`botogram.Chat.creator`
 * 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`
 * Every method which sends something to a chat now returns the sent
   :py:class:`~botogram.Message`