Added documentation for new settings

CHANGELOG.rst

@@ -1,8 +1,12 @@
 Changelog
 =========
 
-* 2.2.2 (Not released):
+* 3.0 (Not released):
+    * Added the ability to hide usernames/emails from avatar URLs.
+    * Added the ability to use a Facebook Graph avatar as a backup.
+    * Added a setting to disable the avatar cache.
     * Fixed issue where cache was not invalidated after updating avatar
+    * Renamed the ``avatar.util`` module to ``avatar.utils``.
 
 * 2.2.1 (January 11, 2016)
     * Added AVATAR_GRAVATAR_FIELD setting to define the user field to get the gravatar email.

avatar/conf.py

@@ -28,7 +28,7 @@ class AvatarConf(AppConf):
     AUTO_GENERATE_SIZES = (DEFAULT_SIZE,)
     FACEBOOK_BACKUP = False
     FACEBOOK_GET_ID = None
-    DISABLE_CACHE = False
+    CACHE_ENABLED = True
     RANDOMIZE_HASHES = False
 
     def configure_auto_generate_avatar_sizes(self, value):

avatar/models.py

@@ -25,6 +25,7 @@ except ImportError:
 
 avatar_storage = get_storage_class(settings.AVATAR_STORAGE)()
 
+
 def avatar_path_handler(instance=None, filename=None, size=None, ext=None):
     tmppath = [settings.AVATAR_STORAGE_DIR]
     if settings.AVATAR_HASH_USERDIRNAMES:

avatar/templatetags/avatar_tags.py

@@ -36,13 +36,6 @@ def avatar_url(user, size=settings.AVATAR_DEFAULT_SIZE):
     if avatar:
         return avatar.avatar_url(size)
 
-    if settings.AVATAR_FACEBOOK_BACKUP:
-        fb_id = get_facebook_id(user)
-        if fb_id:
-            return 'https://graph.facebook.com/{fb_id}/picture?type=square&width={size}&height={size}'.format(
-                fb_id=fb_id, size=size
-            )
-
     if settings.AVATAR_GRAVATAR_BACKUP:
         params = {'s': str(size)}
         if settings.AVATAR_GRAVATAR_DEFAULT:
@@ -51,6 +44,13 @@ def avatar_url(user, size=settings.AVATAR_DEFAULT_SIZE):
             settings.AVATAR_GRAVATAR_FIELD))).hexdigest(), urlencode(params))
         return urljoin(settings.AVATAR_GRAVATAR_BASE_URL, path)
 
+    if settings.AVATAR_FACEBOOK_BACKUP:
+        fb_id = get_facebook_id(user)
+        if fb_id:
+            return 'https://graph.facebook.com/{fb_id}/picture?type=square&width={size}&height={size}'.format(
+                fb_id=fb_id, size=size
+            )
+
     return get_default_avatar_url()
 
 

avatar/util.py

@@ -52,7 +52,7 @@ def cache_result(default_size=settings.AVATAR_DEFAULT_SIZE):
     ``size`` value.
     """
 
-    if settings.AVATAR_DISABLE_CACHE:
+    if not settings.AVATAR_CACHE_ENABLED:
         def decorator(func):
             return func
         return decorator

docs/index.txt

@@ -103,6 +103,54 @@ AVATAR_AUTO_GENERATE_SIZES
     upload. This can save rendering time later on if you pre-generate the
     resized versions. Defaults to ``(80,)``
 
+AVATAR_CACHE_ENABLED
+    Set to ``False`` if you completely disable avatar caching. Defaults to ``True``.
+
+AVATAR_DEFAULT_URL
+    The default URL to default to if ``AVATAR_GRAVATAR_BACKUP`` is set to False
+    and there is no ``Avatar`` instance found in the system for the given user.
+
+AVATAR_EXPOSE_USERNAMES
+    Puts the User's username field in the URL path when ``True``. Set to ``False`` to
+    use the User's primary key instead, preventing their email from being searchable on the web.
+    Defaults to ``True``.
+
+AVATAR_FACEBOOK_BACKUP
+    A bool determining whether to default to Facebook Graph service if no ``Avatar`` instance
+    is found in the system for the given user. ``AVATAR_GRAVATAR_BACKUP`` takes precedence, so
+    if you set this to ``True`` then you must set ``AVATAR_GRAVATAR_BACKUP`` to False. You
+    must also set the ``AVATAR_FACEBOOK_GET_ID`` setting.
+    Defaults to ``False``.
+
+AVATAR_FACEBOOK_GET_ID
+    A callable or string path to a callable that will return the user's Facebook ID. The
+    callable should take a ``User`` object and return a string. If you want to use this
+    then make sure ``AVATAR_FACEBOOK_BACKUP`` is ``True`` and ``AVATAR_GRAVATAR_BACKUP`` is
+    ``False``. Defaults to ``None``.
+
+AVATAR_GRAVATAR_BACKUP
+    A bool determining whether to default to the Gravatar service if no
+    ``Avatar`` instance is found in the system for the given user. Defaults to
+    ``True``.
+
+AVATAR_GRAVATAR_DEFAULT
+    A string determining the style of the default Gravatar. Available options
+    listed in the
+    `Gravatar documentation <https://en.gravatar.com/site/implement/images/#default-image>`_.
+    Ex. 'retro'. Defaults to ``None``.
+
+AVATAR_GRAVATAR_FIELD
+    The name of the user's field containing the gravatar email. For example, if you set
+    this to ``gravatar`` then django-avatar will get the user's gravatar in ``user.gravatar``.
+    Defaults to ``email``.
+
+AVATAR_MAX_SIZE
+    File size limit for avatar upload. Default is ``1024 * 1024`` (1 MB).
+
+AVATAR_PATH_HANDLER
+    Path to a method for avatar file path handling. Default is
+    ``avatar.models.avatar_path_handler``.
+
 AVATAR_RESIZE_METHOD
     The method to use when resizing images, based on the options available in
     PIL. Defaults to ``Image.ANTIALIAS``.
@@ -112,33 +160,6 @@ AVATAR_STORAGE_DIR
     non-filesystem storage device, this will simply be appended to the beginning
     of the file name.
 
-AVATAR_GRAVATAR_BACKUP
-    A boolean determining whether to default to the Gravatar service if no
-    ``Avatar`` instance is found in the system for the given user. Defaults to
-    True.
-
-AVATAR_GRAVATAR_DEFAULT
-    A string determining the style of the default Gravatar. Available options
-    listed in the
-    `Gravatar documentation <https://en.gravatar.com/site/implement/images/#default-image>`_.
-    Ex. 'retro'. Defaults to None.
-
-AVATAR_DEFAULT_URL
-    The default URL to default to if ``AVATAR_GRAVATAR_BACKUP`` is set to False
-    and there is no ``Avatar`` instance found in the system for the given user.
-
-AVATAR_GRAVATAR_FIELD
-    The name of the user's field containing the gravatar email. For example, if you set
-    this to ``gravatar`` then django-avatar will get the user's gravatar in ``user.gravatar``.
-    Defaults to ``email``.
-
-AVATAR_MAX_SIZE
-    File size limit for avatar upload. Default is ``1024 * 1024`` (1mb).
-
-AVATAR_PATH_HANDLER
-    Path to a method for avatar file path handling. Default is
-    ``avatar.models.avatar_path_handler``.
-
 Management Commands
 -------------------