Add support for fetching an user's avatar

This commit adds support for obtaining the current avatar for an user
with the botogram.User.avatar attribute.

Because executing a request for every User object when 99% of the times
you don't need the avatar really kills performances, the content of the
attribute is dynamically loaded the first time you access it.

Author: Pietro Albini

botogram/objects/__init__.py

@@ -25,6 +25,25 @@ class User(BaseObject, mixins.ChatMixin):
         "username": str,
     }
 
+    @property
+    @mixins._require_api
+    def avatar(self):
+        """Get the avatar of the user"""
+        # This is lazy loaded and cached, so it won't affect performances if
+        # you don't need avatars
+        if not hasattr(self, "_avatar"):
+            avatars = self._api.call("getUserProfilePhotos", {
+                "user_id": self.id,
+                "limit": 1,
+            }, expect=UserProfilePhotos)
+
+            # If the user has no avatars just use None
+            self._avatar = None
+            if len(avatars.photos):
+                self._avatar = avatars.photos[0]  # Take the most recent one
+
+        return self._avatar
+
 
 class Chat(BaseObject, mixins.ChatMixin):
     """Telegram API representation of a chat
@@ -234,7 +253,7 @@ class UserProfilePhotos(BaseObject):
 
     required = {
         "total_count": int,
-        "photos": multiple(multiple(PhotoSize)),
+        "photos": multiple(Photo),
     }
 
 

docs/api/telegram.rst

@@ -62,6 +62,18 @@ Available Classes
 
       *This attribute can be None if it's not provided by Telegram.*
 
+   .. py:attribute:: avatar
+
+      This attribute contains the user's avatar, represented as a
+      :py:class:`~botogram.Photo` object. If the user has no avatar, this
+      attribute will be ``None``.
+
+      In order to improve performances, this attribute's content is dynamically
+      requested to Telegram the first time you access it, so there will be some
+      delay.
+
+      .. versionadded:: 0.2
+
    .. py:method:: send(message, [preview=True, reply_to=None, syntax=None, extra=None])
 
       Send the textual *message* to the user. You may optionally stop clients

tests/test_objects.py

@@ -10,6 +10,67 @@
 import botogram.objects
 
 
+def test_user_avatar(api, mock_req):
+    mock_req({
+        "getUserProfilePhotos": {
+            "ok": True,
+            "result": {
+                "total_count": 1,
+                "photos": [
+                    [
+                        {
+                            "file_id": "aaaaaa",
+                            "width": 50,
+                            "height": 50,
+                            "file_size": 128,
+                        },
+                        {
+                            "file_id": "bbbbbb",
+                            "width": 25,
+                            "height": 25,
+                            "file_size": 64,
+                        },
+                    ],
+                ],
+            },
+        },
+    })
+
+    # First of all, make sure the API wrapper is required to fetch avatars
+    user = botogram.objects.User({"id": 123, "first_name": "Bob"})
+    with pytest.raises(RuntimeError):
+        user.avatar  # Access the avatar without an API wrapper
+
+    # Now use an API
+    user = botogram.objects.User({"id": 123, "first_name": "Bob"}, api)
+
+    # Be sure the avatar isn't loaded yet
+    assert not hasattr(user, "_avatar")
+
+    # Now fetch the avatar
+    avatar = user.avatar
+    assert avatar.file_id == "aaaaaa"
+
+    # And be sure it's cached
+    assert hasattr(user, "_avatar")
+    assert user._avatar == avatar
+
+
+def test_user_avatar_with_no_photos(api, mock_req):
+    mock_req({
+        "getUserProfilePhotos": {
+            "ok": True,
+            "result": {
+                "total_count": 0,
+                "photos": [],
+            },
+        },
+    })
+
+    user = botogram.objects.User({"id": 123, "first_name": "Bob"}, api)
+    assert user.avatar is None
+
+
 def test_photo_object():
     # The Photo object is custom-made, so it's better to ensure all it's
     # working as expected