Flask Flashing Messages

Posted on with tags: flask

Flask includes message flashing functionality as a core feature. The Flask documentation has two sentences which summarize the functionality well.

The flashing system basically makes it possible to record a message at the end of a request and access it on the next (and only the next) request. This is usually combined with a layout template to expose the message.

The Flask Web Development book describes Message Flashing on Pages 53-55. The Flask documentation also has a webpage titled Message Flashing, which also includes code examples.

You can call function flash in a view function like this.

from flask import flash

# inside view function
flash('Log in successfully')

The base template calls get_flashed_messages function and renders the messages. The code below renders the messages as an un-ordered list.

{% with messages = get_flashed_messages() %}
  {% if messages %}
    <ul class="flashes">
    {% for message in messages %}
      <li>{{ message }}</li>
    {% endfor %}
  {% endif %}
{% endwith %}

Flashing messages also support categories. You can pass a second argument category to flash method. The above example code is modified to be like this.

flash('Log in failed', 'error')
{% with messages = get_flashed_messages(with_categories=True) %}
  {% if messages %}
    <ul class="flashes">
    {% for category, message in messages %}
      <li class="{{ category }}">{{ message }}</li>
    {% endfor %}
  {% endif %}
{% endwith %}

The interesting part of the above code is that the function get_flashed_messages is available to all template html files. How does it happen? Let’s take a look at Flask source code.

The flask/__init__.py file has those two lines of code (Lines 36 and 37).

from .helpers import flash
from .helpers import get_flashed_messages

The actual functions are defined on Lines 399 and 429 of helpers.py file.
The code of of those two functions are not long. The message_flashed variable in flash function is a signal, which I will discuss in a future article. The key _flashes of session dictionary has a value which is a list. The list values are tuples. Here is an example [('message', 'log in'), ('error', 'log out')].

def flash(message, category="message"):
    """ ... """
    flashes = session.get("_flashes", [])
    flashes.append((category, message))
    session["_flashes"] = flashes
        current_app._get_current_object(), message=message, 
def get_flashed_messages(with_categories=False, category_filter=()):
    """ ....  """
    flashes = _request_ctx_stack.top.flashes
    if flashes is None:
        _request_ctx_stack.top.flashes = flashes = (
            session.pop("_flashes") if "_flashes" in session else []
    if category_filter:
        flashes = list(filter(lambda f: f[0] in category_filter, flashes))
    if not with_categories:
        return [x[1] for x in flashes]
    return flashes

The purpose of putting flashes on the top of _request_ctx_stack.top is that,

further calls in the same request to the function will return the same messages.

How does Jinja2 know get_flashed_messages function? The code is in create_jinja_environment method of Flask class (Line 761 of app.py). The function is added to the Jinja2 environment globals along with other functions and variables.

def create_jinja_environment(self):
    rv = self.jinja_environment(self, **options)
        # request, session and g are normally added with the
        # context processor for efficiency reasons but for imported
        # templates we also want the proxies in there.
    rv.filters["tojson"] = json.tojson_filter
    return rv