root/test_session.txt

Testing the ``session`` module
==============================

The class ``Session`` has one data attribute: The list ``params``
contains a list of all query parameter names which should be taken
into account. The attribute is set from the first argument of the
constructor.

The method ``get_from_url`` takes a full encoded URL and returns
a dictionary with the parameters from the query string of the URL.

    >>> import session

Testing the constructor
-----------------------

The constructor takes one obligatory and one optional argument. The
first is a list of names (strings) which are part of the session. The
second argument, `defaults` is a mapping from the names to their
default string values.

    >>> s = session.Session([])   #doctest: +ELLIPSIS
    Traceback (most recent call last):
        ...
    SessionError: ...

This is ok::

    >>> s = session.Session(['var'])
    >>> s = session.Session(['var'], {'var': "3"})

Of course, the mapping can only contain names which are in the
parameter list. Otherwise, a `SessionError` will be raised::

    >>> s = session.Session(['var'], {'var2': "7"})
    ... #doctest: +ELLIPSIS
    Traceback (most recent call last):
        ...
    SessionError: ...

Testing the ``get_from_url`` method
-----------------------------------

The keys are usually strings, the values are always unicode strings,
even if a parameter could be converted to a number::

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

URLs without host part work, too::

    >>> s = session.Session(['a'])
    >>> s.get_from_url("/page?a=1&b=2")
    {'a': u'1'}

If the URL contains encoded characters, they are decoded::

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

If one of the parameters isn't in the URL, the corresponding
dictionary key is missing::

    >>> s = session.Session(['a', 'b'])
    >>> s.get_from_url("/page?b=2")
    {'b': u'2'}

Unless there's a default that can be used instead::

    >>> s = session.Session(['a', 'b'], defaults={'a': "abc"})
    >>> params = s.get_from_url("/page?b=2")
    >>> params['a'] == "abc"
    True
    >>> params['b'] == u"2"
    True

If a parameter is given multiple times, a list is used as the
dictionary value::

    >>> s = session.Session(['a'])
    >>> params = s.get_from_url("/page?a=Test&a=1")
    >>> params.keys()
    ['a']
    >>> sorted(params['a'])
    [u'1', u'Test']

Testing the ``add_to_url`` method
---------------------------------

The ``add_to_url`` is the reverse of ``get_from_url``. That is, the
query string of the URL is updated to contain the values from the
passed-in dictionary. The return value is an URL (unicode string).

A simple example::

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

If the parameter is already present in the URL, it's overwritten::

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

Parameters which are not in the instance variable ``params`` are
ignored::

    >>> s = session.Session(['a'])
    >>> s.add_to_url("/page", {'b': '1'})
    '/page'

Parameter values containing special characters are properly encoded::

    >>> s = session.Session(['a'])
    >>> s.add_to_url("/page?a=1", {'a': u'Test & string'})
    '/page?a=Test%20%26%20string'

Parameters which are lists are converted to several "assignments" in
the query string::

    >>> s = session.Session(['a'])
    >>> s.add_to_url("/page?b=1", {'a': [u'1', u"2"]})
    '/page?a=1&a=2&b=1'

(The last test may fail for another Python version since it depends
on dictionary "order" and module implementations.)

If a parameter value matches its default (i. e. compares equal), it's
omitted from the query string of the constructed URL::

    >>> s = session.Session(['a'], defaults={'a': "7"})
    >>> s.add_to_url("/page?c=1", {'a': "7"})
    '/page?c=1'