epydoc update

1 files changed, 92 insertions, 21 deletions

diff --git a/wsgitools/filters.py b/wsgitools/filters.py
index 759b20c..509ffde 100644
--- a/wsgitools/filters.py
+++ b/wsgitools/filters.py
@@ -14,12 +14,16 @@ class CloseableIterator:
     def __init__(self, close_function, *iterators):
         """If close_function is not None, it will be the close attribute of
         the created iterator object. Further parameters specify iterators
-        that are to be concatenated."""
+        that are to be concatenated.
+        @type close_function: a function or None
+        """
         if close_function is not None:
             self.close = close_function
         self.iterators = map(iter, iterators)
     def __iter__(self):
-        """iterator interface"""
+        """iterator interface
+        @rtype: gen()
+        """
         return self
     def next(self):
         """iterator interface"""
@@ -37,11 +41,14 @@ class CloseableList(list):
     def __init__(self, close_function, *args):
         """If close_function is not None, it will be the close attribute of
         the created list object. Other parameters are passed to the list
-        constructor."""
+        constructor.
+        @type close_function: a function or None
+        """
         if close_function is not None:
             self.close = close_function
         list.__init__(self, *args)
     def __iter__(self):
+        """iterator interface"""
         return CloseableIterator(getattr(self, "close", None),
                                  list.__iter__(self))
 
@@ -69,7 +76,10 @@ class BaseWSGIFilter:
         pass
     def filter_environ(self, environ):
         """Receives a dict with the environment passed to the wsgi application
-        and a dict must be returned. The default is to return the same dict."""
+        and a dict must be returned. The default is to return the same dict.
+        @type environ: {str: str}
+        @rtype: {str: str}
+        """
         return environ
     def filter_exc_info(self, exc_info):
         """Receives either None or a tuple passed as third argument to
@@ -79,28 +89,42 @@ class BaseWSGIFilter:
     def filter_status(self, status):
         """Receives a status string passed as first argument to start_response
         from the wrapped wsgi application. A valid HTTP status string must be
-        returned."""
+        returned.
+        @type status: str
+        @rtype: str
+        """
         return status
     def filter_header(self, headername, headervalue):
         """This function is invoked for each (headername, headervalue) tuple in
         the second argument to the start_response from the wrapped wsgi
         application. Such a value or None for discarding the header must be
-        returned."""
+        returned.
+        @type headername: str
+        @type headervalue: str
+        @rtype: (str, str)
+        """
         return (headername, headervalue)
     def filter_headers(self, headers):
         """A list of headers passed as the second argument to the start_response
         from the wrapped wsgi application is passed to this function and such a
-        list must also be returned."""
+        list must also be returned.
+        @type headers: [(str, str)]
+        @rtype: [(str, str)]
+        """
         return headers
     def filter_data(self, data):
         """For each string that is either written by the write callable or
         returned from the wrapped wsgi application this method is invoked. It
-        must return a string."""
+        must return a string.
+        @type data: str
+        @rtype: str
+        """
         return data
     def append_data(self):
         """This function can be used to append data to the response. A list of
         strings or some kind of iterable yielding strings has to be returned.
         The default is to return an empty list.
+        @rtype: gen([str])
         """
         return []
     def handle_close(self):
@@ -114,12 +138,16 @@ class WSGIFilterMiddleware:
     def __init__(self, app, filterclass):
         """
         @param app: is a wsgi application.
+        @type filterclass: BaseWSGIFilters subclass
         @param filterclass: is a subclass of BaseWSGIFilter or some class that
                     implements the interface."""
         self.app = app
         self.filterclass = filterclass
     def __call__(self, environ, start_response):
-        """wsgi interface"""
+        """wsgi interface
+        @type environ: {str, str}
+        @rtype: gen([str])
+        """
         assert isinstance(environ, dict)
         reqfilter = self.filterclass()
         environ = reqfilter.filter_environ(environ)
@@ -163,15 +191,23 @@ class RequestLogWSGIFilter(BaseWSGIFilter):
     @classmethod
     def creator(cls, log):
         """Returns a function creating RequestLogWSGIFilters on given log file.
-        log has to be a file-like object."""
+        log has to be a file-like object.
+        @type log: file-like
+        """
         return lambda:cls(log)
     def __init__(self, log=sys.stdout):
+        """
+        @type log: file-like
+        """
         assert hasattr(log, "write")
         self.log = log
         self.time = time.strftime("%d/%b/%Y:%T %z")
         self.length = 0
     def filter_environ(self, environ):
-        """BaseWSGIFilter interface"""
+        """BaseWSGIFilter interface
+        @type environ: {str: str}
+        @rtype: {str: str}
+        """
         assert isinstance(environ, dict)
         self.remote = environ.get("REMOTE_ADDR", "?")
         self.user = environ.get("REMOTE_USER", "-")
@@ -182,12 +218,18 @@ class RequestLogWSGIFilter(BaseWSGIFilter):
         self.useragent = environ.get("HTTP_USER_AGENT", "-")
         return environ
     def filter_status(self, status):
-        """BaseWSGIFilter interface"""
+        """BaseWSGIFilter interface
+        @type status: str
+        @rtype: str
+        """
         assert isinstance(status, str)
         self.status = status.split()[0]
         return status
     def filter_data(self, data):
-        """BaseWSGIFilter interface"""
+        """BaseWSGIFilter interface
+        @type data: str
+        @rtype: str
+        """
         self.length += len(data)
         return data
     def handle_close(self):
@@ -218,13 +260,21 @@ class TimerWSGIFilter(BaseWSGIFilter):
     @classmethod
     def creator(cls, pattern):
         """Returns a function creating TimerWSGIFilters with a given pattern
-        beeing a string of exactly eight bytes."""
+        beeing a string of exactly eight bytes.
+        @type pattern: str
+        """
         return lambda:cls(pattern)
     def __init__(self, pattern="?GenTime"):
+        """
+        @type pattern: str
+        """
         self.pattern = pattern
         self.start = time.time()
     def filter_data(self, data):
-        """BaseWSGIFilter interface"""
+        """BaseWSGIFilter interface
+        @type data: str
+        @rtype: str
+        """
         if data == self.pattern:
             return "%8.3g" % (time.time() - self.start)
         return data
@@ -235,15 +285,26 @@ class EncodeWSGIFilter(BaseWSGIFilter):
     @classmethod
     def creator(cls, charset):
         """Returns a function creating EncodeWSGIFilters with a given charset.
+        @type charset: str
         """
         return lambda:cls(charset)
     def __init__(self, charset="utf-8"):
+        """
+        @type charset: str
+        """
         self.charset = charset
     def filter_data(self, data):
-        """BaseWSGIFilter interface"""
+        """BaseWSGIFilter interface
+        @type data: str
+        @rtype: str
+        """
         return data.encode(self.charset)
     def filter_header(self, header, value):
-        """BaseWSGIFilter interface"""
+        """BaseWSGIFilter interface
+        @type header: str
+        @type value: str
+        @rtype (str, str)
+        """
         if header.lower() != "content-type":
             return (header, value)
         return (header, "%s; charset=%s" % (value, self.charset))
@@ -256,7 +317,9 @@ class GzipWSGIFilter(BaseWSGIFilter):
         self.sio = None
         self.gzip = None
     def filter_environ(self, environ):
-        """BaseWSGIFilter interface"""
+        """BaseWSGIFilter interface
+        @type environ: {str: str}
+        """
         assert isinstance(environ, dict)
         if "HTTP_ACCEPT_ENCODING" in environ:
             acceptenc = environ["HTTP_ACCEPT_ENCODING"].split(',')
@@ -267,13 +330,19 @@ class GzipWSGIFilter(BaseWSGIFilter):
                 self.gzip = gzip.GzipFile(fileobj=self.sio, mode="w")
         return environ
     def filter_headers(self, headers):
-        """BaseWSGIFilter interface"""
+        """BaseWSGIFilter interface
+        @type headers: [(str, str)]
+        @rtype: [(str, str)]
+        """
         assert isinstance(headers, list)
         if self.compress:
             headers.append(("Content-encoding", "gzip"))
         return headers
     def filter_data(self, data):
-        """BaseWSGIFilter interface"""
+        """BaseWSGIFilter interface
+        @type data: str
+        @rtype: str
+        """
         if not self.compress:
             return data
         self.gzip.write(data)
@@ -282,7 +351,9 @@ class GzipWSGIFilter(BaseWSGIFilter):
         self.sio.truncate(0)
         return data
     def append_data(self):
-        """BaseWSGIFilter interface"""
+        """BaseWSGIFilter interface
+        @rtype: [str]
+        """
         if not self.compress:
             return []
         self.gzip.close()