From 2c607a3b8e0584fa20ce38095c9158f623501cee Mon Sep 17 00:00:00 2001
From: Helmut Grohne <helmut@subdivi.de>
Date: Wed, 30 Nov 2011 20:28:22 +0100
Subject: documentation update

 * added a number of internal links (L{...})
 * some fixes
 * some additions
---
 wsgitools/digest.py | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

(limited to 'wsgitools/digest.py')

diff --git a/wsgitools/digest.py b/wsgitools/digest.py
index ded5e8d..6781e94 100644
--- a/wsgitools/digest.py
+++ b/wsgitools/digest.py
@@ -144,7 +144,7 @@ class AbstractTokenGenerator:
         @type username: str
         @type algo: str
         @param algo: currently the only value supported by
-                AuthDigestMiddleware is "md5"
+                L{AuthDigestMiddleware} is "md5"
         @rtype: str or None
         @returns: a valid token or None to signal that authentication should
                 fail
@@ -203,6 +203,7 @@ class HtdigestTokenGenerator(AbstractTokenGenerator):
         """
         @type realm: str
         @type htdigestfile: str
+        @param htdigestfile: path to the .htdigest file
         @type ignoreparseerrors: bool
         @param ignoreparseerrors: passed to readhtdigest
         @raises IOError:
@@ -241,11 +242,13 @@ class HtdigestTokenGenerator(AbstractTokenGenerator):
 
 __all__.append("UpdatingHtdigestTokenGenerator")
 class UpdatingHtdigestTokenGenerator(HtdigestTokenGenerator):
-    """Behaves like HtdigestTokenGenerator, checks the htdigest file
+    """Behaves like L{HtdigestTokenGenerator}, checks the htdigest file
     for changes on each invocation.
     """
     def __init__(self, realm, htdigestfile, ignoreparseerrors=False):
         assert isinstance(htdigestfile, str)
+        # Need to stat the file before calling parent ctor to detect
+        # modifications.
         try:
             self.statcache = os.stat(htdigestfile)
         except OSError, err:
@@ -256,6 +259,8 @@ class UpdatingHtdigestTokenGenerator(HtdigestTokenGenerator):
         self.ignoreparseerrors = ignoreparseerrors
 
     def __call__(self, user, algo="md5"):
+        # The interface does not permit raising exceptions, so all we can do is
+        # fail by returning None.
         try:
             statcache = os.stat(self.htdigestfile)
         except OSError:
@@ -358,8 +363,7 @@ class StatelessNonceStore(NonceStoreBase):
 
     def checknonce(self, nonce, count=1, ident=None):
         """
-        Do a check for whether the provided string is a nonce and increase usage
-        count on returning True.
+        Check whether the provided string is a nonce.
         @type nonce: str
         @type count: int
         @type ident: None or str
@@ -488,9 +492,9 @@ __all__.append("LazyDBAPI2Opener")
 class LazyDBAPI2Opener:
     """
     Connects to database on first request. Otherwise it behaves like a dbapi2
-    connection. This may be usefull in combination with scgi.forkpool, because
-    this way each worker child opens a new database connection when the first
-    request is to be answered.
+    connection. This may be usefull in combination with L{scgi.forkpool},
+    because this way each worker child opens a new database connection when
+    the first request is to be answered.
     """
     def __init__(self, function, *args, **kwargs):
         """
@@ -525,7 +529,8 @@ __all__.append("DBAPI2NonceStore")
 class DBAPI2NonceStore(NonceStoreBase):
     """
     A dbapi2-backed nonce store implementation suitable for usage with forking
-    wsgi servers such as scgi.forkpool.
+    wsgi servers such as L{scgi.forkpool}.
+
     >>> import sqlite3
     >>> db = sqlite3.connect(":memory:")
     >>> db.cursor().execute("CREATE TABLE nonces (key, value);") and None
@@ -676,9 +681,10 @@ class AuthDigestMiddleware(AuthenticationMiddleware):
                 L{AuthTokenGenerator} class.
         @type maxage: int
         @param maxage: deprecated, see L{MemoryNonceStore} or
-                L{StatelessNonceStore}
+                L{StatelessNonceStore} and pass an instance to store
         @type maxuses: int
-        @param maxuses: deprecated, see L{MemoryNonceStore}
+        @param maxuses: deprecated, see L{MemoryNonceStore} and pass an
+                instance to store
         @type store: L{NonceStoreBase}
         @param store: a nonce storage implementation object. Usage of this
                 parameter will override maxage and maxuses.
-- 
cgit v1.2.3