Source code for uw.web.wsgi.parameter

"""Environment parameter support.

This module includes classes and procedures for building handlers which extract
information from the Web request and store it in convenient form for use by a
contained request handler.
"""

import cgi
from http.cookies import SimpleCookie
from wsgiref.util import request_uri
from functools import partial

def set_param (environ, name=None, value=None):
    """Set a parameter value in the environment, or ensure presence.

    If the environment does not contain a 'params' entry, it is created.
    If name is not None, then environ['params'][name] is set to value.
    It is an error for value to be not None if name is None.
    """
    if not 'params' in environ:
        environ['params'] = {}
    if name is not None:
        environ['params'][name] = value
    elif value is not None:
        raise ValueError

def get_params (environ):
    """Get the parameters from the provided CGI environment.

    This simply returns the 'params' entry, or an empty dictionary if it is
    not present.
    """
    return environ.get ('params', {})

class ParamHandler (object):
    """A chained handler class to store values in the parameters.

    The constructor takes a nested handler, a parameter name param_name, and a
    parameter value extractor get_param_value.  When the constructed handler is
    called, it extracts the parameter value from the environment using
    get_param_value and saves it in the parameters under the name param_name.
    Then it chains to the nested handler.
    """

    def __init__ (self, handler, param_name, get_param_value):
        self.__handler = handler
        self.__param_name = param_name
        self.__get_param_value = get_param_value

    @property
    def handler (self):
        """The nested handler.

        This is the handler which is called when this handler is called
        after the parameter value has been stored in the parameters.
        """
        return self.__handler

    @property
    def param_name (self):
        """The parameter name.

        This is the name under which the parameter value is stored in the
        parameters.
        """
        return self.__param_name

    @property
    def get_param_value (self):
        """The parameter calculator.

        This is the function which computes the parameter value, given a CGI
        environment.
        """
        return self.__get_param_value

    def __call__ (self, environ, start_response):
        set_param (environ, self.param_name, self.get_param_value (environ))
        return self.handler (environ, start_response)

def use_environ_param (handler):
    """Wrap a handler; extract the environment as a parameter.

    Returns a handler which saves the environment itself in the 'environ'
    parameter before chaining to the provided handler.
    """
    return ParamHandler (handler, 'environ', lambda environ: environ)

def use_request_uri_param (handler, include_query=False):
    """Wrap a handler; extract request URI as a parameter.

    Returns a handler which stores the request URI in the 'request_uri'
    parameter before chaining to the provided handler.  By default the
    query string is not included.
    """
    return ParamHandler (handler, 'request_uri',
     partial (request_uri, include_query=include_query))

def get_form_fields (environ):
    """Extract submitted HTML form results from the WSGI environment.

    Parameters:

    environ -- the WSGI environment.

    Builds a cgi.FieldStorage from the wsgi.input environment entry.  Normally
    form.get_form_fields will be more useful than this function.
    """
    return cgi.FieldStorage (fp=environ['wsgi.input'],
     environ=environ, keep_blank_values=1)

def use_form_param (handler):
    """Wrap a handler; extract form variable values as a parameter.

    Returns a handler which constructs a cgi.FieldStorage and saves it in
    the 'form' parameter before chaining to the provided handler.

    It is probably more useful to use form.use_form_param instead.
    """
    return ParamHandler (handler, 'form', get_form_fields)

def use_remote_user_param (handler):
    """Wrap a handler; extract $REMOTE_USER as a parameter.

    Returns a handler which saves the remote user in the 'remote_user'
    parameter before chaining to the provided handler.
    """
    return ParamHandler (handler, 'remote_user',
     lambda environ: environ.get ('REMOTE_USER'))

def get_cookies (environ):
    """Get the cookie values from the provided CGI environment.

    Creates a Cookie.SimpleCookie and loads it with the value of the
    HTTP_COOKIE environment variable.
    """
    result = SimpleCookie ()
    if 'HTTP_COOKIE' in environ:
        result.load (environ['HTTP_COOKIE'])
    return result

def use_cookies (handler):
    """Wrap a handler; extract the cookies as a parameter.

    Return a handler which stores the cookies from the HTTP_COOKIE environment
    entry in a Cookie.SimpleCookie object before chaining to the provided
    handler.
    """
    return ParamHandler (handler, 'cookies', get_cookies)