root/session.py

# coding: utf-8
# Copyright (C) 2007, Stefan Schwarzer
#
# Permission is hereby granted, free of charge, to any person
# obtaining a copy of this software and associated documentation files
# (the "Software"), to deal in the Software without restriction,
# including without limitation the rights to use, copy, modify, merge,
# publish, distribute, sublicense, and/or sell copies of the Software,
# and to permit persons to whom the Software is furnished to do so,
# subject to the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

import cgi
import urllib
import urlparse

# Websourcebrowser modules
import coding
import config


class SessionError(Exception):
    pass


class Session(object):
    def __init__(self, params, defaults=None):
        """
        Initialize the `Session` instance by providing a list of
        parameter names as argument `params`. If the list is empty,
        raise a `SessionError`.

        If the argument `defaults` is given, it must be a mapping from
        parameter names to their default string values. If the mapping
        contains a name, which isn't in the list `params`, raise a
        `SessionError`.
        """
        if not params:
            raise SessionError("parameter list must not be empty")
        self.params = params
        if defaults is None:
            defaults = {}
        for name in defaults:
            if name not in params:
                raise SessionError("default name isn't present in params list")
        self.defaults = defaults

    def get_from_url(self, url):
        """
        Return a dictionary of decoded query parameters (similar to
        the result of `cgi.parse_qs`) from the URL `url`:

        >>> s = Session(['a'])
        >>> s.get_from_url("http://localhost/page?a=Test%20string&b=1")
        {'a': u'Test string'}

        Only the parameters in the list attribute `params` are
        examined. That means, if `params` isn't defined, the
        dictionary will be empty.

        If one of the parameter names isn't present in the URL at all,
        the parameter name will not occur in the dictionary, unless
        the name is present in the `defaults` dictionary (see
        `__init__` method).
        """
        query_string = urlparse.urlparse(url)[4]
        query_mapping = cgi.parse_qs(query_string)
        result = {}
        # use only key/value pairs qualified in `params`
        for param in self.params:
            # ignore params which are not in the URL
            if param in query_mapping:
                value = query_mapping[param]
                # make sure each string is a unicode string
                for index, item in enumerate(value):
                    value[index] = coding.decode(item)
                # turn one-element lists into scalars
                if len(value) == 1:
                    value = value[0]
                result[param] = value
        # try to use a default if a parameter wasn't set
        for param in self.defaults:
            if param not in result:
                result[param] = self.defaults[param]
        return result

    def add_to_url(self, url, params):
        """
        Return an updated URL so that the parameter values from the
        dictionary `params` is included in the query string of the
        original URL. Only parameters from the instance variable
        `params` are considered.

        Example of method usage:

        >>> s = Session(['a'])
        >>> s.add_to_url("/page", {'a': u"Test"})
        '/page?a=Test'

        If a parameter is set to its default value, don't include it
        in the URL.
        """
        parsed_url = list(urlparse.urlparse(url))
        query_string = urlparse.urlparse(url)[4]
        query_mapping = cgi.parse_qs(query_string)
        # use only key/value pairs qualified in `params`
        for param in self.params:
            if param in params:
                value = params[param]
                # don't include defaults
                if (param in self.defaults) and (self.defaults[param] == value):
                    continue
                # make sure the value is a list
                if isinstance(value, basestring):
                    value = [value]
                # if necessary, encode unicode values
                for index, item in enumerate(value):
                    if isinstance(item, unicode):
                        value[index] = coding.encode(item)
                query_mapping[param] = value
        query_string = urllib.urlencode(query_mapping, doseq=True)
        parsed_url[4] = query_string
        return urlparse.urlunparse(parsed_url).replace("+", "%20")


# define the default session, i. e. one with all the usual query
#  parameters, including parameter conversion
class DefaultSession(Session):
    def __init__(self):
        super(DefaultSession, self).__init__(
          ['anchor', 'dir_levels', 'frames'],
          defaults={'anchor': "", 'frames': "yes"})

    def get_from_url(self, url):
        # `config.dir_levels` is only known after parsing the command
        # line, and we don't want depend on the position of the
        # import of the `session` module
        self.defaults['dir_levels'] = str(config.dir_levels)
        params = super(DefaultSession, self).get_from_url(url)
        try:
            int_dir_levels = int(params['dir_levels'])
            if int_dir_levels >= 1:
                params['dir_levels'] = int_dir_levels
        except ValueError:
            params['dir_levels'] = int(self.defaults['dir_levels'])
        return params

    def add_to_url(self, url, params):
        # don't modify the dictionary which was passed in as argument
        params = params.copy()
        if 'dir_levels' in params:
            params['dir_levels'] = str(params['dir_levels'])
        return super(DefaultSession, self).add_to_url(url, params)


default_session = DefaultSession()