Clever Harold Session Support
------------------------------

Clever Harold includes WSGI_ middleware that reuses the session support
from your web server.  The framework attempts to import and configure
session support from these locations, in this order:

- Apache/mod_python
- Flup
- Paste


Configuration
=============

When you use ``paster init-harold`` to create a Clever Harold project,
the script will include session support in your project configuration
file -- there's nothing else for you to do.

To create a separate Session middleware in your project configuration
file, add a section like this::

    [filter:my_session_filter]
    use = egg:CleverHarold#session

You can force the selection of a session provider in your project
configuration file with a ``provider`` parameter, which will override
the default selection algorithm::

    [filter:my_session_filter]
    use = egg:CleverHarold#session
    provider = harold.session.lib:FlupSession

For details on using the Session type directly in a WSGI_ stack, refer to the
`Session API documentation`_.


Use
===

To make use of the session support in your programs, either add a
parameter named ``session`` to your callable, or reference it from the
``environ`` dictionary.  Both methods are shown here::


    def whoami(name, session):
        count = session.get('count', 0) + 1
        session['count'] = count
        return 'Hello, %s, you have been here %s times' % (name, count)
    
    def whoareyou(name, environ):
        session = environ['harold.session']
        count = session.get('count', 0) + 1
        session['count'] = count
        return 'Hello, %s, you have been here %s times' % (name, count)

        
You can use the session support in your templates in exactly the same
manner.  Here are the two methods::

    <html xmlns:py="http://purl.org/kid/ns#">
        <div py:def="main()">
            Visit Count: $${session['count']}
        </div>
    </html>


    <html xmlns:py="http://purl.org/kid/ns#">
        <div py:def="main()">
            Visit Count: $${environ['harold.session']['count']}
        </div>
    </html>

Further Reading
---------------

- WSGI_ Specification
- `Session API Documentation`_


.. _WSGI: http://www.python.org/dev/peps/pep-0333/
.. _Session API Documentation: http://trac.cleverharold.org/wiki/SessionApiDocs
