# -*- coding: utf-8 -*-

"""
Flash Messages
==============

One-time notification of users in web applications.

The common use case for flash messages is to issue informational, warning or
error messages after a POST request has been made and to show them after a
subsequent HTTP redirect.  The latter is done to ensure a POST request
(modifying data on the server) isn't sent again when the user reloads a page.
If the page to (which the user is redirected to) is reloaded, the message
won't be shown again.

A session object is used to store one or more messages.  This implementation
utilizes ``collections.defaultdict`` (which was introduced in Python 2.5) and
the Werkzeug_ WSGI toolkit.

In the actual snippet code, the import ``request`` object is expected to be a
``werkzeug.wrappers.BaseRequest`` (or subclass) wrapper_ instance, provided as
`context local`_, and needs to have a ``werkzeug.contrib.sessions`` session
store attached to it as attribute named ``session``.  All this can also be
adapted to work with other components, such as the Beaker_ session middleware
or the Paste_ or WebOb_ WSGI toolkits.

To retrieve waiting flash messages and remove them from the session object
afterwards::

    import flash
    flash_messages = flash.get_messages(True)

They can be then passed on to a template engine.  An example of how to show
waiting messages in a Genshi_ (layout) template::

    <ul id="flash" py:if="flash_messages">
      <py:for each="category, messages in flash_messages.iteritems()">
        <li py:for="message in messages" class="${category}">${message}</li>
      </py:for>
    </ul><!-- /#flash -->

Cascading Stylesheets (CSS) and some nice icons can then be used to style the
messages according to their respective types.

.. _Werkzeug:       http://werkzeug.pocoo.org/
.. _wrapper:        http://werkzeug.pocoo.org/documentation/wrappers
.. _context local:  http://werkzeug.pocoo.org/documentation/local
.. _Beaker:         http://beaker.groovie.org/
.. _Paste:          http://pythonpaste.org/
.. _WebOb:          http://pythonpaste.org/webob/
.. _Genshi:         http://genshi.edgewall.org/

:Copyright: 2008 Jochen Kupperschmidt
:Date: 16-May-2008
:License: MIT
"""

from collections import defaultdict

from example_application import request


def get_messages(clear=False):
    """Return messages as dictionary with categories as keys."""
    messages = request.session.get('flash', {})
    if clear:
        clear_messages()
    return messages

def clear_messages():
    """Clear all messages."""
    request.session['flash'] = defaultdict(list)

def _set_message(category, message):
    """Set a message."""
    if not 'flash' in request.session:
        request.session['flash'] = defaultdict(list)
    request.session['flash'][category].append(message)
    request.session.modified = True

def set_error(message):
    """Set an error message."""
    _set_message('error', message)

def set_warning(message):
    """Set a warning message."""
    _set_message('warning', message)

def set_notice(message):
    """Set a notice message."""
    _set_message('notice', message)