clarify some things

- cleanup docstrings
- more comments
- rename cookie_cache to cache, since it's not a cache of cookies

jupyterhub/services/auth.py

@@ -19,10 +19,11 @@ from tornado.log import app_log
 from tornado.web import HTTPError
 
 from traitlets.config import Configurable
-from traitlets import Unicode, Integer, Instance, default
+from traitlets import Unicode, Integer, Instance, default, observe
 
 from ..utils import url_path_join
 
+
 class _ExpiringDict(dict):
     """Dict-like cache for Hub API requests
 
@@ -125,8 +126,14 @@ class HubAuth(Configurable):
     cookie_name = Unicode('jupyterhub-services',
         help="""The name of the cookie I should be looking for"""
     ).tag(config=True)
-    cookie_cache_max_age = Integer(300,
+    cookie_cache_max_age = Integer(help="DEPRECATED. Use cache_max_age")
-        help="""The maximum time (in seconds) to cache the Hub's response for cookie authentication.
+    @observe('cookie_cache_max_age')
+    def _deprecated_cookie_cache(self, change):
+        warnings.warn("cookie_cache_max_age is deprecated in JupyterHub 0.8. Use cache_max_age instead.")
+        self.cache_max_age = change.new
+
+    cache_max_age = Integer(300,
+        help="""The maximum time (in seconds) to cache the Hub's responses for authentication.
 
         A larger value reduces load on the Hub and occasional response lag.
         A smaller value reduces propagation time of changes on the Hub (rare).
@@ -134,10 +141,10 @@ class HubAuth(Configurable):
         Default: 300 (five minutes)
         """
     ).tag(config=True)
-    cookie_cache = Instance(_ExpiringDict, allow_none=False)
+    cache = Instance(_ExpiringDict, allow_none=False)
-    @default('cookie_cache')
+    @default('cache')
-    def _cookie_cache(self):
+    def _default_cache(self):
-        return _ExpiringDict(self.cookie_cache_max_age)
+        return _ExpiringDict(self.cache_max_age)
 
     def _check_hub_authorization(self, url, cache_key=None, use_cache=True):
         """Identify a user with the Hub
@@ -145,20 +152,19 @@ class HubAuth(Configurable):
         Args:
             url (str): The API URL to check the Hub for authorization
                        (e.g. http://127.0.0.1:8081/hub/api/authorizations/token/abc-def)
-            cache_key (str): The for checking the cache
+            cache_key (str): The key for checking the cache
             use_cache (bool): Specify use_cache=False to skip cached cookie values (default: True)
 
         Returns:
             user_model (dict): The user model, if a user is identified, None if authentication fails.
-        An HTTPError is raised if 
-        Verify the response for authorizing a user
 
-        Raises an error if the response failed, otherwise returns the json
+        Raises an HTTPError if the request failed for a reason other than no such user.
         """
         if use_cache:
             if cache_key is None:
                 raise ValueError("cache_key is required when using cache")
-            cached = self.cookie_cache.get(cache_key)
+            # check for a cached reply, so we don't check with the Hub if we don't have to
+            cached = self.cache.get(cache_key)
             if cached is not None:
                 return cached
 
@@ -177,6 +183,7 @@ class HubAuth(Configurable):
             raise HTTPError(500, msg)
 
         data = None
+        print(r.status_code)
         if r.status_code == 404:
             app_log.warning("No Hub user identified for request")
         elif r.status_code == 403:
@@ -194,7 +201,7 @@ class HubAuth(Configurable):
 
         if use_cache:
             # cache result
-            self.cookie_cache[cache_key] = data
+            self.cache[cache_key] = data
         return data