Add get_avatar_field() function.

This function is designed to replace avatar_url() and
avatar_url_from_dict() over time.

There are a few things new about it:

    * We make the parameters more explicit, rather than
      passing in an opaque dictionary or requiring a
      UserProfile object.  (A lot of our callers want
      to use `values()` for efficiency sake, since we
      are often doing bulk user operations.)

    * We start to support the client_gravatar option.

zerver/lib/avatar.py

@@ -7,6 +7,7 @@ from typing import Any, Dict, Optional, Text
 
 from zerver.lib.avatar_hash import gravatar_hash, user_avatar_path_from_ids
 from zerver.lib.upload import upload_backend, MEDIUM_AVATAR_SIZE
+from zerver.models import UserProfile
 from six.moves import urllib
 
 def avatar_url(user_profile, medium=False):
@@ -22,6 +23,13 @@ def avatar_url(user_profile, medium=False):
 
 def avatar_url_from_dict(userdict, medium=False):
     # type: (Dict[str, Any], bool) -> Text
+    '''
+    DEPRECATED: We should start using
+                get_avatar_field to populate users,
+                particulary for codepaths where the
+                client can compute gravatar URLS
+                on the client side.
+    '''
     url = _get_unversioned_avatar_url(
         userdict['id'],
         userdict['avatar_source'],
@@ -31,6 +39,56 @@ def avatar_url_from_dict(userdict, medium=False):
     url += '&version=%d' % (userdict['avatar_version'],)
     return url
 
+def get_avatar_field(user_id,
+                     realm_id,
+                     email,
+                     avatar_source,
+                     avatar_version,
+                     medium,
+                     client_gravatar):
+    # type: (int, int, Text, Text, int, bool, bool) -> Optional[Text]
+    '''
+    Most of the parameters to this function map to fields
+    by the same name in UserProfile (avatar_source, realm_id,
+    email, etc.).
+
+    Then there are these:
+
+        medium - This means we want a medium-sized avatar. This can
+            affect the "s" parameter for gravatar avatars, or it
+            can give us something like foo-medium.png for
+            user-uploaded avatars.
+
+        client_gravatar - If the client can compute their own
+            gravatars, this will be set to True, and we'll avoid
+            computing them on the server (mostly to save bandwidth).
+    '''
+
+    if client_gravatar:
+        '''
+        If our client knows how to calculate gravatar hashes, we
+        will return None and let the client compute the gravatar
+        url.
+        '''
+        if settings.ENABLE_GRAVATAR:
+            if avatar_source == UserProfile.AVATAR_FROM_GRAVATAR:
+                return None
+
+    '''
+    If we get this far, we'll compute an avatar URL that may be
+    either user-uploaded or a gravatar, and then we'll add version
+    info to try to avoid stale caches.
+    '''
+    url = _get_unversioned_avatar_url(
+        user_profile_id=user_id,
+        avatar_source=avatar_source,
+        realm_id=realm_id,
+        email=email,
+        medium=medium,
+    )
+    url += '&version=%d' % (avatar_version,)
+    return url
+
 def get_gravatar_url(email, avatar_version, medium=False):
     # type: (Text, int, bool) -> Text
     url = _get_unversioned_gravatar_url(email, medium)

zerver/tests/test_upload.py

@@ -3,7 +3,10 @@ from django.conf import settings
 from django.test import TestCase, override_settings
 from unittest import skip
 
-from zerver.lib.avatar import avatar_url
+from zerver.lib.avatar import (
+    avatar_url,
+    get_avatar_field,
+)
 from zerver.lib.bugdown import url_filename
 from zerver.lib.realm_icon import realm_icon_url
 from zerver.lib.test_classes import ZulipTestCase, UploadSerializeMixin
@@ -558,6 +561,51 @@ class FileUploadTest(UploadSerializeMixin, ZulipTestCase):
 
 class AvatarTest(UploadSerializeMixin, ZulipTestCase):
 
+    def test_get_avatar_field(self):
+        # type: () -> None
+        with self.settings(AVATAR_SALT="salt"):
+            url = get_avatar_field(
+                user_id=17,
+                realm_id=5,
+                email='foo@example.com',
+                avatar_source=UserProfile.AVATAR_FROM_USER,
+                avatar_version=2,
+                medium=True,
+                client_gravatar=False,
+            )
+
+        self.assertEqual(
+            url,
+            '/user_avatars/5/fc2b9f1a81f4508a4df2d95451a2a77e0524ca0e-medium.png?x=x&version=2'
+        )
+
+        url = get_avatar_field(
+            user_id=9999,
+            realm_id=9999,
+            email='foo@example.com',
+            avatar_source=UserProfile.AVATAR_FROM_GRAVATAR,
+            avatar_version=2,
+            medium=True,
+            client_gravatar=False,
+        )
+
+        self.assertEqual(
+            url,
+            'https://secure.gravatar.com/avatar/b48def645758b95537d4424c84d1a9ff?d=identicon&s=500&version=2'
+        )
+
+        url = get_avatar_field(
+            user_id=9999,
+            realm_id=9999,
+            email='foo@example.com',
+            avatar_source=UserProfile.AVATAR_FROM_GRAVATAR,
+            avatar_version=2,
+            medium=True,
+            client_gravatar=True,
+        )
+
+        self.assertEqual(url, None)
+
     def test_avatar_url(self):
         # type: () -> None
         """Verifies URL schemes for avatars and realm icons."""