Add Logging and Notification Messages to Flask Web Projects

Grab the Prerequisites

To hit the ground running, you’ll build up on an existing Flask project with a database. That way, you don’t need to create a Flask project from scratch. Instead, you can focus on the main objectives of this tutorial, like adding an error page and displaying helpful messages to your users.

The code that you need is already in place for you. All you need to do is download the source code by clicking the link below:

Alternatively, you can follow the Flask project with a database tutorial. Either way, you should end up with a folder structure that looks like this:

rp_flask_board/
├── board/
│   │
│   ├── static/
│   │   └── styles.css
│   │
│   ├── templates/
│   │   │
│   │   ├── pages/
│   │   │   ├── about.html
│   │   │   └── home.html
│   │   │
│   │   ├── posts/
│   │   │   ├── create.html
│   │   │   └── posts.html
│   │   │
│   │   ├── _navigation.html
│   │   └── base.html
│   │
│   ├── __init__.py
│   ├── database.py
│   ├── pages.py
│   ├── posts.py
│   └── schema.sql
│
└── board.sqlite

Once you’ve got the folder structure for your Flask project in place, you can read on to prepare the development environment that you’ll need to work on your web app.

Prepare Your Development Environment

Before you continue working on your Flask project, it’s a good idea to create and activate a virtual environment. That way, you’re installing any project dependencies not system-wide but only in your project’s virtual environment.

Select your operating system below and use your platform-specific command to set up a virtual environment:

• Windows
• Linux + macOS

PS> python -m venv venv
PS> .\venv\Scripts\activate
(venv) PS>

$ python -m venv venv
$ source venv/bin/activate
(venv) $

With the commands shown above, you create and activate a virtual environment named venv by using Python’s built-in venv module. The parenthesized (venv) in front of the prompt indicates that you’ve successfully activated the virtual environment.

If you haven’t done so already, make sure to install Flask before continuing with this tutorial:

(venv) $ python -m pip install Flask==3.0.0

Other than Flask, you’ll work with python-dotenv. Go ahead and install python-dotenv with the command below:

(venv) $ python -m pip install python-dotenv==1.0.0

With the help of python-dotenv, you’ll be able to read key-value pairs from an external file and keep sensitive information out of your code base.

After following the steps above, you can verify that your Flask application is running without errors. Execute the following command in the directory containing the app.py file:

(venv) $ python -m flask --app board run --port 8000 --debug

When you run this application, a web server will start on port 8000. If you open a browser and navigate to http://localhost:8000, then you should see the Home page of your project:

Perfect, your app is running flawlessly! You can use the menu to navigate from one page to another. But what happens if you end up on a page that doesn’t exist?

Explore the Current Error Page

Flask comes with an error page that the development server displays when you enter a wrong URL. But it looks rather basic. You can check it out when you enter a page URL that doesn’t exist. For example, type http://localhost:8000/creat instead of create:

When a user enters a nonexistent page URL for your web app, then they’ll see a generic error page. Running into an error is never nice. However, you can still make it a better experience for the users of your Flask web project.

Create an Error Handler

When you end up on a URL that doesn’t exist, then Flask returns a 404 HTTP response status code with the generic website that you saw in the previous section. That’s quite similar to when you enter an existing URL for a page of your Flask project, except in that case, Flask finds the corresponding view and returns the rendered template.

To work with your custom error page, you can add an error handler to your project. An error handler is basically a view for a specific error type. That means you can implement an error handler for a 404 error similarly to regular views.

Create a new file named errors.py in your board/ folder and add the code below:

from flask import render_template

def page_not_found(e):
    return render_template("errors/404.html"), 404

You can make the name of the view function whatever you like. However, it’s important that you respond with the correct response status code when you render the template. When a page doesn’t exist, then the error code must be 404.

It’s also a good idea to use the error code as the filename for the template that you render for your custom error page. Here, you’re rendering a 404.html template.

Design the 404 Error Template

Your page_not_found() error handler wants to render a template named 404.html. Go ahead and create the 404.html template inside an errors/ subfolder in templates/ and add the code below:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>{% block title %}{% endblock title %}</title>
  <link rel="stylesheet" href="{{ url_for('static', filename='styles.css') }}">
</head>
<body>
<h1>Page not found</h1>
<p>Please go to one of the pages below:</p>
  {% include("_navigation.html") %}
</body>
</html>

Just like with the templates of other pages in your Flask web project, you could make 404.html a child template of base.html. But it’s also reasonable to switch the styling a bit for error pages like this one.

Here, you’re displaying the navigation at the end of the page instead of at the top. Still, you use the same style sheet to display cohesive styling even when a user runs into an error. Before anyone can admire your error page, you must register the error handler in your Flask project.

Register the Error Handler

To work with custom error pages, you must register the error handler in your project’s application factory. Open __init__.py and add the highlighted code below:

 1import os
 2from dotenv import load_dotenv
 3from flask import Flask
 4
 5from board import (
 6    database,
 7    errors,
 8    pages,
 9    posts,
10)
11
12load_dotenv()
13
14def create_app():
15    app = Flask(__name__)
16    app.config.from_prefixed_env()
17
18    database.init_app(app)
19
20    app.register_blueprint(pages.bp)
21    app.register_blueprint(posts.bp)
22    app.register_error_handler(404, errors.page_not_found)
23    print(f"Current Environment: {os.getenv('ENVIRONMENT')}")
24    print(f"Using Database: {app.config.get('DATABASE')}")
25    return app

After importing errors in line 7, you can call .register_error_handler() in your application factory. The first argument is the error status code you want to register, which is 404. This status code must match the status code returned by the second argument, which is your page_not_found view.

Now that you’ve registered the 404 error, you can check out the error for any nonexistent URL of your project. For example, go to http://localhost:8000/hei:

The error page looks much better than the generic error page. You also give the user the opportunity to choose one of your existing pages once they run into the error. Adding a custom error page enhances the user experience of your app tremendously. In the next section, you’ll continue to improve the user experience by showing a notification message to the user when they submit a form.

Find a Spot for Notifications

First, you need to find a spot on your pages where you want to display notification messages when they appear. When they appear, it’s important that the users notice them. That’s why the top of the page is usually a good location to place your notification messages.

In your Flask project, the perfect spot is the header that you can find in the base template. Navigate to your templates/ folder, open base.html, and add three message containers inside the <header> element:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Message Board - {% block title %}{% endblock title %}</title>
  <link rel="stylesheet" href="{{ url_for('static', filename='styles.css') }}">
</head>
<body>
<h1>Message Board</h1>
{% include("_navigation.html") %}
<section>
  <header>
    {% block header %}{% endblock header %}
    <div class="flash success">Everything worked!</div>
    <div class="flash error">Oh no, something went wrong.</div>
  </header>
  <main>
    {% block content %}<p>No messages.</p>{% endblock content %}
  <main>
</section>
</body>
</html>

The header Jinja block displays the headline of the page that you’re currently on. Placing any incoming notification messages underneath looks like a good choice!

In this tutorial, you’ll work with two message types:

• Success: A friendly notification that reassures the user that everything worked fine.
• Error: An informative notification to indicate that something went wrong.

Besides the success and error categories, you often use warning and info messages. Feel free to add any message category that you want to the list above. Later, you’ll learn how you can show any of them in Flask.

Style Your Notifications

With both notification elements in place, you can start styling them. Following the colors of most traffic lights, the success notification should be green, and the error notification should be red. Hop over to your CSS file in your static/ folder and add the CSS declarations below:

/* ... */

.flash {
  padding: 20px;
  margin: 20px;
}

.flash.error {
  background-color: #ffa7ae;
  color: #a02a36;
}

.flash.success {
  background-color: #96faad;
  color: #1c7530;
}

All of your notifications share the .flash class. Thanks to the padding and margins, the text inside the notification element will have enough space, and the elements won’t collide with any other content. Then, you add specific colors to the text and the background of your notification categories.

Open your browser, visit http://localhost:8000/, and check out how your notification messages look:

Nice! Now that you’ve styled the notification messages, you can continue to display dynamic notifications with Flask.

Leverage Flask’s Notification System

Displaying notification messages to users is vital for the look and feel of web applications. That’s why Flask comes with a message flashing system that you can leverage as a developer.

To display a notification message with Flask, you need to call the flash() function in suitable views. In your project, it’s a good idea to display notification messages after the user submits a form.

You can find the logic to handle forms in posts.py. Open the file and add the highlighted code below:

 1from flask import (
 2    Blueprint,
 3    flash,
 4    redirect,
 5    render_template,
 6    request,
 7    url_for,
 8)
 9
10from board.database import get_db
11
12bp = Blueprint("posts", __name__)
13
14@bp.route("/create", methods=("GET", "POST"))
15def create():
16    if request.method == "POST":
17        author = request.form["author"] or "Anonymous"
18        message = request.form["message"]
19
20        if message:
21            db = get_db()
22            db.execute(
23                "INSERT INTO post (author, message) VALUES (?, ?)",
24                (author, message),
25            )
26            db.commit()
27            flash(f"Thanks for posting, {author}!", category="success")
28            return redirect(url_for("posts.posts"))
29        else:
30            flash("You need to post a message.", category="error")
31
32    return render_template("posts/create.html")
33
34# ...

After importing the flash object in line 3, you call flash() in line 27 and line 30.

In line 27, you call flash() with the category argument set to "success", thanking the user for posting a message. You only do so when the user actually submits a message. If the user didn’t submit a message, then you call flash() with category set to "error".

Before you can see the messages in action, you need to make an adjustment in base.html to work with Flask’s flash system:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Message Board - {% block title %}{% endblock title %}</title>
  <link rel="stylesheet" href="{{ url_for('static', filename='styles.css') }}">
</head>
<body>
<h1>Message Board</h1>
{% include("_navigation.html") %}
<section>
  <header>
    {% block header %}{% endblock header %}
    {% for category, message in get_flashed_messages(with_categories=true) %}
      <div class="flash {{ category }}">{{ message }}</div>
    {% endfor %}
  </header>
  <main>
    {% block content %}<p>No messages.</p>{% endblock content %}
  <main>
</section>
</body>
</html>

To receive messages from your Flask view, you use get_flashed_messages(). By default, you’d only receive the message text from Flask. If you also pass in the with_categories argument and set it to true, then Flask also sends the message category along. Having category and message present enables you to set the notification message text and CSS class dynamically.

To see the notification messages in action, hop over to http://localhost:8000/create and post a message:

As long as a posted message contains text, you receive the success notification. Next, try posting a message without text:

Just as expected, you receive a red error notification message when you leave the message input empty when sending the form. To prevent users from accidentally posting empty messages, you can consider setting a required HTML attribute.

However, keeping this potential erroneous situation in for the moment enables you to explore another user experience enhancement. This time, the enhancement is all for you as the admin of the Flask project.