From 0b08dacfcfced7fef1b4818a73c3f43a97fe8c8f Mon Sep 17 00:00:00 2001
From: Helmut Grohne <helmut@subdivi.de>
Date: Sun, 15 Apr 2007 18:14:57 +0200
Subject: added docstrings

---
 wsgitools/filters.py     | 13 +++++++++++++
 wsgitools/middlewares.py |  6 ++++++
 wsgitools/scgi.py        | 11 +++++++++++
 3 files changed, 30 insertions(+)

diff --git a/wsgitools/filters.py b/wsgitools/filters.py
index 1d6154f..fa42550 100644
--- a/wsgitools/filters.py
+++ b/wsgitools/filters.py
@@ -148,6 +148,8 @@ class RequestLogWSGIFilter(BaseWSGIFilter):
     """This filter logs all requests in the apache log file format."""
     @classmethod
     def creator(cls, log):
+        """Returns a function creating RequestLogWSGIFilters on given log file.
+        log has to be a file-like object."""
         return lambda:cls(log)
     def __init__(self, log=sys.stdout):
         self.log = log
@@ -189,8 +191,16 @@ class RequestLogWSGIFilter(BaseWSGIFilter):
 
 __all__.append("TimerWSGIFilter")
 class TimerWSGIFilter(BaseWSGIFilter):
+    """Replaces a specific string in the data returned from the filtered wsgi
+    application with the time the request took. The string has to be exactly
+    eight bytes long, defaults to "?GenTime" and must be an element of the
+    iterable returned by the filtered application. If the application returns
+    something like ["spam?GenTime", "?GenTime spam", "?GenTime"] only the last
+    occurance get's replaced."""
     @classmethod
     def creator(cls, pattern):
+        """Returns a function creating TimerWSGIFilters with a given pattern
+        beeing a string of exactly eight bytes."""
         return lambda:cls(pattern)
     def __init__(self, pattern="?GenTime"):
         self.pattern = pattern
@@ -206,6 +216,8 @@ class EncodeWSGIFilter(BaseWSGIFilter):
     """Encodes all body data (no headers) with given charset."""
     @classmethod
     def creator(cls, charset):
+        """Returns a function creating EncodeWSGIFilters with a given charset.
+        """
         return lambda:cls(charset)
     def __init__(self, charset="utf-8"):
         self.charset = charset
@@ -213,6 +225,7 @@ class EncodeWSGIFilter(BaseWSGIFilter):
         """BaseWSGIFilter interface"""
         return data.encode(self.charset)
     def filter_header(self, header, value):
+        """BaseWSGIFilter interface"""
         if header.lower() != "content-type":
             return (header, value)
         return (header, "%s; charset=%s" % (value, self.charset))
diff --git a/wsgitools/middlewares.py b/wsgitools/middlewares.py
index 17afd76..5ff610f 100644
--- a/wsgitools/middlewares.py
+++ b/wsgitools/middlewares.py
@@ -11,10 +11,12 @@ except ImportError:
 
 __all__.append("SubdirMiddleware")
 class SubdirMiddleware:
+    """Middleware choosing wsgi applications based on a dict."""
     def __init__(self, default, mapping={}):
         self.default = default
         self.mapping = mapping
     def __call__(self, environ, start_response):
+        """wsgi interface"""
         app = None
         script = environ["PATH_INFO"]
         path_info = ""
@@ -219,9 +221,13 @@ class CachingMiddleware:
 
 __all__.append("DictAuthChecker")
 class DictAuthChecker:
+    """Verifies usernames and passwords by looking them up in a dict."""
     def __init__(self, users):
+        """users is a dict mapping usernames to password."""
         self.users = users
     def __call__(self, username, password):
+        """check_function interface taking username and password and resulting
+        in a bool."""
         return username in self.users and self.users[username] == password
 
 __all__.append("BasicAuthMiddleware")
diff --git a/wsgitools/scgi.py b/wsgitools/scgi.py
index 477acf9..c12a296 100644
--- a/wsgitools/scgi.py
+++ b/wsgitools/scgi.py
@@ -168,7 +168,16 @@ class SCGIConnection(asyncore.dispatcher):
 
 __all__.append("SCGIServer")
 class SCGIServer(asyncore.dispatcher):
+    """SCGI Server for WSGI applications. It does not use multiple processes or
+    multiple threads."""
     def __init__(self, wsgiapp, port, interface="localhost", error=sys.stderr):
+        """wsgiapp is the wsgi application to be run.
+        port is an int representing the TCP port number to be used.
+        interface is a string specifying the network interface to bind which
+                  defaults to "localhost" making the server inaccessible over
+                  network.
+        error is a file-like object being passed as wsgi.error in the environ
+              parameter defaulting to stderr."""
         asyncore.dispatcher.__init__(self)
         self.wsgiapp = wsgiapp
         self.error = error
@@ -185,5 +194,7 @@ class SCGIServer(asyncore.dispatcher):
             SCGIConnection(self, conn, addr)
 
     def run(self):
+        """Runs the server. It will not return and you can invoke
+        asyncore.loop() instead achieving the same effect."""
         asyncore.loop()
 
-- 
cgit v1.2.3