From 93374eaaace42da6c89663f09fcbbf2afcb3637c Mon Sep 17 00:00:00 2001 From: Helmut Grohne Date: Tue, 14 Oct 2008 13:48:02 +0200 Subject: added epydoc markup to doc strings --- wsgitools/filters.py | 101 ++++++++++++++++++++++++++------------------------- 1 file changed, 51 insertions(+), 50 deletions(-) (limited to 'wsgitools/filters.py') diff --git a/wsgitools/filters.py b/wsgitools/filters.py index 943f56b..b0bf8e1 100644 --- a/wsgitools/filters.py +++ b/wsgitools/filters.py @@ -2,7 +2,7 @@ This module contains a generic way to create middelwares that filter data. The work is mainly done by the L{WSGIFilterMiddleware} class. One can write filters by extending the L{BaseWSGIFilter} class and passing this class -(not an instance) to the C{WSGIFilterMiddleware} constructor. +(not an instance) to the L{WSGIFilterMiddleware} constructor. """ __all__ = [] @@ -19,10 +19,10 @@ __all__.append("CloseableIterator") class CloseableIterator: """Concatenating iterator with close attribute.""" 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 + """If close_function is not C{None}, it will be the C{close} attribute + of the created iterator object. Further parameters specify iterators that are to be concatenated. - @type close_function: a function or None + @type close_function: a function or C{None} """ if close_function is not None: self.close = close_function @@ -46,10 +46,10 @@ __all__.append("CloseableList") class CloseableList(list): """A list with a close attribute.""" 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 + """If close_function is not C{None}, it will be the C{close} attribute + of the created list object. Other parameters are passed to the list constructor. - @type close_function: a function or None + @type close_function: a function or C{None} """ if close_function is not None: self.close = close_function @@ -64,17 +64,17 @@ class BaseWSGIFilter: """Generic WSGI filter class to be used with L{WSGIFilterMiddleware}. For each request a filter object gets created. - The environment is then passed through filter_environ. - Possible exceptions are filtered by filter_exc_info. - After that for each (header, value) tuple filter_header is used. - The resulting list is filtered through filter_headers. - Any data is filtered through filter_data. - In order to possibly append data the append_data method is invoked. - When the request has finished handle_close is invoked. + The environment is then passed through L{filter_environ}. + Possible exceptions are filtered by L{filter_exc_info}. + After that for each C{(header, value)} tuple L{filter_header} is used. + The resulting list is filtered through L{filter_headers}. + Any data is filtered through L{filter_data}. + In order to possibly append data the L{append_data} method is invoked. + When the request has finished L{handle_close} is invoked. All methods do not modify the passed data by default. Passing the - BaseWSGIFilter class to a WSGIFilterMiddleware will result in not modifying - the request at all. + L{BaseWSGIFilter} class to a L{WSGIFilterMiddleware} will result in not + modifying requests at all. """ def __init__(self): """This constructor does nothing and can safely be overwritten. It is @@ -83,28 +83,28 @@ 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 C{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 - start_response from the wrapped wsgi application. Either None or such a - tuple must be returned.""" + """Receives either C{None} or a tuple passed as third argument to + C{start_response} from the wrapped wsgi application. Either C{None} or + such a tuple must be returned.""" return exc_info 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. + """Receives a status string passed as first argument to + C{start_response} from the wrapped wsgi application. A valid HTTP status + string must be 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 + """This function is invoked for each C{(headername, headervalue)} tuple + in the second argument to the C{start_response} from the wrapped wsgi + application. Such a value or C{None} for discarding the header must be returned. @type headername: str @type headervalue: str @@ -112,15 +112,15 @@ class BaseWSGIFilter: """ 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. + """A list of headers passed as the second argument to the + C{start_response} from the wrapped wsgi application is passed to this + function and such a 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 + """For each string that is either written by the C{write} callable or returned from the wrapped wsgi application this method is invoked. It must return a string. @type data: str @@ -140,14 +140,14 @@ class BaseWSGIFilter: __all__.append("WSGIFilterMiddleware") class WSGIFilterMiddleware: - """This wsgi middleware can be used with specialized BaseWSGIFilters to + """This wsgi middleware can be used with specialized L{BaseWSGIFilter}s to modify wsgi requests and/or reponses.""" def __init__(self, app, filterclass): """ @param app: is a wsgi application. @type filterclass: L{BaseWSGIFilter}s subclass - @param filterclass: is a subclass of BaseWSGIFilter or some class that - implements the interface.""" + @param filterclass: is a subclass of L{BaseWSGIFilter} or some class + that implements the interface.""" self.app = app self.filterclass = filterclass def __call__(self, environ, start_response): @@ -184,8 +184,8 @@ class WSGIFilterMiddleware: + list(reqfilter.append_data())) ret = iter(ret) def late_append_data(): - """Invoke reqfilter.append_data() after filter_data() has seen all - data.""" + """Invoke C{reqfilter.append_data()} after C{filter_data()} has seen + all data.""" for data in reqfilter.append_data(): yield data return CloseableIterator(modified_close, @@ -197,8 +197,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. + """Returns a function creating L{RequestLogWSGIFilter}s on given log + file. log has to be a file-like object. @type log: file-like """ return lambda:cls(log) @@ -263,13 +263,13 @@ __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 + eight bytes long, defaults to C{"?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.""" + something like C{["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 + """Returns a function creating L{TimerWSGIFilter}s with a given pattern beeing a string of exactly eight bytes. @type pattern: str """ @@ -298,7 +298,8 @@ class EncodeWSGIFilter(BaseWSGIFilter): """ @classmethod def creator(cls, charset): - """Returns a function creating EncodeWSGIFilters with a given charset. + """Returns a function creating L{EncodeWSGIFilter}s with a given + charset. @type charset: str """ return lambda:cls(charset) @@ -330,7 +331,7 @@ class GzipWSGIFilter(BaseWSGIFilter): @classmethod def creator(cls, flush=True): """ - Returns a function creating GzipWSGIFilters. + Returns a function creating L{GzipWSGIFilter}s. @type flush: bool @param flush: whether or not the filter should always flush the buffer """ @@ -392,28 +393,28 @@ class GzipWSGIFilter(BaseWSGIFilter): return [data] class ReusableWSGIInputFilter(BaseWSGIFilter): - """Make environ["wsgi.input"] readable multiple times. Although this is not - required by the standard it is sometimes desirable to read wsgi.input + """Make C{environ["wsgi.input"]} readable multiple times. Although this is + not required by the standard it is sometimes desirable to read C{wsgi.input} multiple times. This filter will therefore replace that variable with a - StringIO instance which provides a seek method. + C{StringIO} instance which provides a C{seek} method. """ @classmethod def creator(cls, maxrequestsize): """ - Returns a function creating ReusableWSGIInputFilters with desired + Returns a function creating L{ReusableWSGIInputFilter}s with desired maxrequestsize being set. If there is more data than maxrequestsize is - available in wsgi.input the rest will be ignored. (It is up to the + available in C{wsgi.input} the rest will be ignored. (It is up to the adapter to eat this data.) @type maxrequestsize: int @param maxrequestsize: is the maximum number of bytes to store in the - StringIO + C{StringIO} """ return lambda:cls(maxrequestsize) def __init__(self, maxrequestsize=65536): """ReusableWSGIInputFilters constructor. @type maxrequestsize: int @param maxrequestsize: is the maximum number of bytes to store in the - StringIO, see creator + C{StringIO}, see L{creator} """ BaseWSGIFilter.__init__(self) self.maxrequestsize = maxrequestsize -- cgit v1.2.3