Add support for fetching an user's avatar history

This commits adds support for obtaining the current avatar and all the
past ones for an user, with the botogram.User.avatar_history() method.

Author: Pietro Albini

botogram/objects/__init__.py

@@ -44,6 +44,24 @@ def avatar(self):
 
         return self._avatar
 
+    @mixins._require_api
+    def avatar_history(self):
+        """Get all the avatars of the user"""
+        avatars = []
+
+        while True:
+            chunk = self._api.call("getUserProfilePhotos", {
+                "user_id": self.id,
+                "offset": len(avatars),
+                "limit": 1,
+            }, expect=UserProfilePhotos)
+
+            avatars += chunk.photos
+            if len(avatars) >= chunk.total_count:
+                break
+
+        return avatars
+
 
 class Chat(BaseObject, mixins.ChatMixin):
     """Telegram API representation of a chat

docs/api/telegram.rst

@@ -74,6 +74,14 @@ Available Classes
 
       .. versionadded:: 0.2
 
+   .. py:method:: avatar_history()
+
+      Get the user's avatar history. This returns a list of the current and all
+      the past avatars for the user, represented as :py:class:`~botogram.Photo`
+      objects. If the user has no avatars this returns an empty list.
+
+      .. 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

@@ -71,6 +71,105 @@ def test_user_avatar_with_no_photos(api, mock_req):
     assert user.avatar is None
 
 
+def test_user_avatar_history(api, mock_req):
+    mock_req({
+        "getUserProfilePhotos": {
+            "ok": True,
+            "result": {
+                "total_count": 3,
+                "photos": [
+                    [
+                        {
+                            "file_id": "aaaaaa",
+                            "width": 50,
+                            "height": 50,
+                            "file_size": 128,
+                        },
+                    ],
+                    [
+                        {
+                            "file_id": "bbbbbb",
+                            "width": 50,
+                            "height": 50,
+                            "file_size": 128,
+                        },
+                    ],
+                    [
+                        {
+                            "file_id": "cccccc",
+                            "width": 50,
+                            "height": 50,
+                            "file_size": 128,
+                        },
+                    ],
+                ],
+            },
+        },
+    })
+
+    # 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_history()  # Access the avatar without an API wrapper
+
+    # Now use an API
+    user = botogram.objects.User({"id": 123, "first_name": "Bob"}, api)
+
+    files = [avatar.file_id for avatar in user.avatar_history()]
+    assert files == ["aaaaaa", "bbbbbb", "cccccc"]
+
+
+def test_user_avatar_history_multiple_requests(api, mock_req):
+    mock_req({
+        "getUserProfilePhotos": {
+            "ok": True,
+            "result": {
+                # This is the double of the avatars provided with this request
+                # This simulates if the user has more than 100 avatars
+                "total_count": 4,
+                "photos": [
+                    [
+                        {
+                            "file_id": "aaaaaa",
+                            "width": 50,
+                            "height": 50,
+                            "file_size": 128,
+                        },
+                    ],
+                    [
+                        {
+                            "file_id": "bbbbbb",
+                            "width": 50,
+                            "height": 50,
+                            "file_size": 128,
+                        },
+                    ],
+                ],
+            },
+        },
+    })
+
+    user = botogram.objects.User({"id": 123, "first_name": "Bob"}, api)
+
+    files = [avatar.file_id for avatar in user.avatar_history()]
+    assert files == ["aaaaaa", "bbbbbb", "aaaaaa", "bbbbbb"]
+
+
+def test_user_avatar_history_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_history() == []
+
+
 def test_photo_object():
     # The Photo object is custom-made, so it's better to ensure all it's
     # working as expected