From 2c607a3b8e0584fa20ce38095c9158f623501cee Mon Sep 17 00:00:00 2001 From: Helmut Grohne Date: Wed, 30 Nov 2011 20:28:22 +0100 Subject: documentation update * added a number of internal links (L{...}) * some fixes * some additions --- wsgitools/authentication.py | 4 ++-- wsgitools/digest.py | 26 ++++++++++++++++---------- wsgitools/filters.py | 3 +-- wsgitools/scgi/asynchronous.py | 4 ++-- wsgitools/scgi/forkpool.py | 8 ++++++-- 5 files changed, 27 insertions(+), 18 deletions(-) diff --git a/wsgitools/authentication.py b/wsgitools/authentication.py index 0c69f95..6f5d07b 100644 --- a/wsgitools/authentication.py +++ b/wsgitools/authentication.py @@ -82,7 +82,7 @@ class AuthenticationMiddleware: """Generates a WWW-Authenticate header. Subclasses must implement this method. - @type exception: AuthenticationRequired + @type exception: L{AuthenticationRequired} @param exception: reason for generating the header @rtype: (str, str) @returns: the header as (part_before_colon, part_after_colon) @@ -93,7 +93,7 @@ class AuthenticationMiddleware: """Generate an error page after failed authentication. Apart from the exception parameter, this method behaves like a WSGI application. - @type exception: AuthenticationRequired + @type exception: L{AuthenticationRequired} @param exception: reason for the authentication failure """ status = "401 Authorization required" 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. diff --git a/wsgitools/filters.py b/wsgitools/filters.py index e455cbe..7ae1b69 100644 --- a/wsgitools/filters.py +++ b/wsgitools/filters.py @@ -383,8 +383,7 @@ class GzipWSGIFilter(BaseWSGIFilter): def __init__(self, flush=True): """ @type flush: bool - @param flush: when true does not pump data necessarily immediately but - accumulate to get a better compression ratio + @param flush: whether or not the filter should always flush the buffer """ BaseWSGIFilter.__init__(self) self.flush = flush diff --git a/wsgitools/scgi/asynchronous.py b/wsgitools/scgi/asynchronous.py index e1dbcc6..6b69c73 100644 --- a/wsgitools/scgi/asynchronous.py +++ b/wsgitools/scgi/asynchronous.py @@ -218,8 +218,8 @@ class SCGIServer(asyncore.dispatcher): @type reusesocket: None or socket.socket @param reusesocket: If a socket is passed, do not create a socket. Instead use given socket as listen socket. The passed socket - must be set up for accepting tcp connections (i.e. AF_INET, - SOCK_STREAM with bind and listen called). + must be set up for accepting tcp connections (i.e. C{AF_INET}, + C{SOCK_STREAM} with bind and listen called). """ if reusesocket is None: asyncore.dispatcher.__init__(self) diff --git a/wsgitools/scgi/forkpool.py b/wsgitools/scgi/forkpool.py index 8ccd579..39c9dfd 100644 --- a/wsgitools/scgi/forkpool.py +++ b/wsgitools/scgi/forkpool.py @@ -163,6 +163,10 @@ class SCGIServer: """state: 0 means idle and 1 means working. These values are also sent as strings '0' and '1' over the socket.""" def __init__(self, pid, sock, state): + """ + @type pid: int + @type state: int + """ self.pid = pid self.sock = sock self.state = state @@ -192,8 +196,8 @@ class SCGIServer: @type reusesocket: None or socket.socket @param reusesocket: If a socket is passed, do not create a socket. Instead use given socket as listen socket. The passed socket - must be set up for accepting tcp connections (i.e. AF_INET, - SOCK_STREAM with bind and listen called). + must be set up for accepting tcp connections (i.e. C{AF_INET}, + C{SOCK_STREAM} with bind and listen called). """ assert hasattr(error, "write") self.wsgiapp = wsgiapp -- cgit v1.2.3