Using Docker to run your applications makes everything more reproducible: running the Docker container in your computer and in your deployment service of choice should be identical, so you shouldn't run into unforeseen issues in production.

But oftentimes when running in production, you don't use a single service. Databases, background workers, and caches all need to run as well.

If you're using something like Railway or Render, you'll be used to setting up the different services with the UI:

IMAGE showing a complex project set-up with Render, using various different services

Although it's handy that you can use their UI to set up your services, it does pose a problem: how do you run all these locally, so you can make sure they all play together nicely before deploying?

This is where Docker Compose comes into play.

Creating a Docker container for a Flask app

Before we dive into Docker Compose, let's start by creating a basic Docker container for a Flask application. First, create a new directory for your project and navigate to it:

mkdir flask-docker-compose
cd flask-docker-compose

Create a new file named Dockerfile with the following content:

FROM python:3.12
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

This Dockerfile specifies the base Python image, sets the working directory, installs dependencies, copies the application files, and defines the command to run the Flask app.

Create a requirements.txt file with the following content:

flask

Finally, create an app.py file with a basic Flask application:

from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello, World!"

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

Running the Flask app using Docker

To build and run the Docker container for your Flask app, execute the following commands:

docker build -t flask-app .
docker run -p 5000:5000 flask-app

Open your web browser and navigate to http://localhost:5000. You should see the "Hello, World!" message.

Use Docker Compose to run the Flask app and PostgreSQL

Now that we have a basic Flask app running in a Docker container, let's add PostgreSQL to the mix using Docker Compose.

The Docker Compose code for Flask

Create a new file named docker-compose.yml with the following content:

version: '3'
services:
  web:
    build: .
    ports:
      - "5000:5000"
    depends_on:
      - db
    environment:
      - DATABASE_URL=postgresql://postgres:password@db/myapp
    volumes:
      - .:/app
  db:
    image: postgres
    environment:
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data
volumes:
  postgres_data:

Let's break down the different parts of this Docker Compose file:

Port mapping

The ports section maps the container's port 5000 to the host's port 5000, allowing you to access the Flask app from your local machine.

Healthchecks

Docker Compose allows you to define healthchecks for your services. In this example, we haven't added any specific healthchecks, but you can add them to ensure that your services are running properly.

Environment variables and files

The environment section allows you to set environment variables for your services. In this case, we set the DATABASE_URL for the Flask app to connect to the PostgreSQL database.

If you wanted to use a .env file for your service instead, you'd define the following block in docker-compose.yml:

web:
  build: .
  # ...
  env_file:
    - .env

Your .env file would contain the environment variables you'd like defined in your service:

DATABASE_URL=postgresql://postgres:password@db/myapp
REDIS_URL=redis://redis:6379
SECRET_KEY=your-secret-key

Whether you use environment variables or environment files, to access their values in your Flask app you'd use the os module:

import os
from flask import Flask

app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = os.getenv("DATABASE_URL")
app.config["SECRET_KEY"] = os.getenv("SECRET_KEY")

Docker Compose for Flask + Postgres

To run the Flask app and PostgreSQL using Docker Compose, execute the following command:

docker-compose up

Docker Compose will build the Flask app image and start both the Flask app and PostgreSQL containers.

Local volumes

In the volumes section, we mount the current directory (.) to the /app directory inside the Flask app container. This allows you to make changes to your code and see the changes instantly without rebuilding the container.

We also define a named volume postgres_data for PostgreSQL to persist the database data across container restarts.

Specifying dependencies between services

The depends_on section allows you to specify dependencies between services. In this case, the Flask app depends on the PostgreSQL database, so Docker Compose will start the db service before the web service.

Adding more services to your Docker Compose set-up

Now that we have a basic Flask app and PostgreSQL running with Docker Compose, let"s explore how to add more services like Celery and Flower.

Celery

To add Celery, a distributed task queue, to your Docker Compose setup, update your docker-compose.yml file:

version: '3'
services:
  # ...
  celery:
    build: .
    command: celery -A tasks worker --loglevel=info
    volumes:
      - .:/app
    depends_on:
      - db
      - redis
  redis:
    image: redis

This adds a Celery worker service that depends on the PostgreSQL database and a Redis instance for message brokering.

To run Celery you'll need a tasks.py file (feel free to name it differently, but that's the convention!) with the Celery object definition and the task definitions. For example:

from celery import Celery
import os

app = Celery("tasks", broker=os.getenv("REDIS_URL"))

@app.task
def example_task(param):
    # Perform task logic here
    print(f"Executing task with param: {param}")

Flower

Flower is a web-based tool for monitoring Celery. To add Flower to your Docker Compose setup:

version: '3'
services:
  # ...
  flower:
    build: .
    command: celery flower -A tasks --port=5555
    ports:
      - "5555:5555"
    depends_on:
      - celery

This adds a Flower service that depends on the Celery worker and exposes port 5555 for accessing the Flower web interface.

With these additions, your Docker Compose setup now includes a Flask app, PostgreSQL database, Celery worker, Redis message broker, and Flower monitoring tool. You can start all the services with a single docker-compose up command and develop your application locally with ease.

Conclusion

Thank you for reading! If you've enjoyed this article, consider subscribing to get notified when we publish our next one.

Setting up your editor properly will make your development experience better and save you time. In this article, let me show you my Visual Studio Code settings for working with Django.

If you're new to Python or to VSCode, check out our blog post How to set up Visual Studio Code for Python development for the initial editor set-up when working with Python.

Setting up VSCode for Django

There are just a few extensions you need to work with Django effectively in VSCode:

• Django
• Djlint
• Tailwind CSS IntelliSense (optional, but recommended!)

More info on what each one does below!

The Django extension

This extension helps us write Django templates using HTML and the Django templating language. It gives us:

• Syntax highlighting in the templates, so we keep HTML syntax and also the Django templating language.
• CMD+Click (or CTRL+Click on Windows) to "Go to definition" in templates. For example, in your {% extends 'base.html' %}, you can CMD+Click 'base.html' to go to that file. Neat!
• Support for snippets, but I don't tend to use these.

Linting HTML with Djlint

Djlint is a library for linting HTML. Just as we use Ruff for linting our Python code, Djlint can tell us of any issues in our HTML code.

To use Djlint, install the extension and also install the djlint Python package in your virtual environment:

source .venv/bin/activate
pip install -U djlint

Not using a virtual environment for your project? I strongly recommend you do, and I've written a complete guide to virtual environments for your enjoyment. It's our most popular free tutorial by a mile!

Optionally, formatting HTML with Djlint

You can use Djlint to format your HTML code as well as linting. This just means adding newlines to break down long lines, and indenting HTML attributes evenly.

I really like formatting my HTML, because doing it by hand takes a while.

But I tend to use Django with AlpineJS, and Djlint formatting doesn't work with AlpineJS well because the HTML attributes AlpineJS uses can get quite long.

If you don't use super long HTML attributes, I recommend you use Djlint for formatting! You can enable it in your settings.json file like so:

"[django-html]": {
	"editor.defaultFormatter": "monosans.djlint",
    "editor.detectIndentation": true,
    "editor.formatOnSave": true,
    "editor.tabSize": 2,
    "djlint.profile": "django"
}

This will automatically format on save. Feel free to disable it if you'd rather format manually.

To run formatting manually you'd open the command palette with CMD+Shift+P (or CTRL+Shift+P on Windows) and then "Format Document".

If you enable format on save and you want to save without formatting, you can use the shortcut CMD+k s (or CTRL+k s on Windows). That shortcut is a two-part shortcut, so you'd press CMD+k first, and then s.

As I said earlier, I don't use Djlint for formatting because it doesn't work well with AlpineJS, so I keep format on save off.

Tailwind CSS IntelliSense

If you use TailwindCSS (I do, and recommend it), install the Tailwind CSS IntelliSense extension. It will make it so in HTML files, when you start typing a class name, you get autocomplete and documentation as to what the class does.

Note: it only works if you have a tailwind.config.js in the root of your project (the folder you opened with VSCode). I've sometimes created an empty file there just so the extension works, if I have my config file somewhere else.

Conclusion

That's about it! We've installed a number of VSCode to make our life easier:

• Django
• Djlint
• Tailwind CSS IntelliSense

And some from our VSCode for Python blog post:

• Python (and Pylance)
• Ruff
• indent-rainbow
• Rainbow Brackets
• vscode-icons
• LiveShare

If you've enjoyed this blog post, consider subscribing below! We're working on a completely new Django mega-course that will be released in a couple months.

Subscribing will let me notify you when the course is available, and also you'll get new blog posts in your inbox (once a week or so).

See you in the next one!

When your application starts growing, you start wondering... Should my checkout button say "Checkout" or "Buy now"? Which one will make my customers buy more? Also, should it be green or blue?

If you have these questions, then A/B tests are the answer!

An A/B test lets you compare two versions of your code side by side, and check which version of the code achieve more of your goal.

Your goal may be increased conversions (purchases), or it may be more clickthroughs, more returning visitors, or anything else!

In PostHog, A/B tests are implemented using feature flags. If you haven't read our article on using feature flags with Python and PostHog, I recommend reading it first!

As a quick recap, once you've created your feature flags (or A/B tests), you can retrieve them in your Flask app with this snippet:

@app.before_request
def before_request():
    if "user_id" not in session:
        if current_user.is_authenticated:
            session["user_id"] = current_user.id
        else:
            session["user_id"] = str(uuid.uuid4())

	if current_user.is_authenticated and current_user.id != session.get("user_id"):
        posthog.alias(session["user_id"], current_user.id)
        session["user_id"] = current_user.id

    try:
        session["feature_flags"] = posthog.get_all_flags(
            session["user_id"], only_evaluate_locally=True
        )
    except:  # noqa
        session["feature_flags"] = {}

How to create an A/B test with PostHog

Let's say that you want to check whether the text "Purchase", "Buy now" or "Subscribe" performs better in the main homepage button.

First, click on the A/B tests section of the navigation, and then click on "New experiment":

Then you'd create your A/B test using PostHog:

Here you'd also give each test variant a value. Leaving one as "control" is the norm, so you always know that that's the default. The other can get a name that's meaningful for what you are testing. In this case, "buy_now" and "subscribe" may be suitable.

In the A/B test configuration you can select conversions as the metric you want to see a change in.

If you haven't set up event tracking with PostHog, read our article on how to do that!

Finally, you can optionally specify the minimum acceptable conversion. This helps PostHog tell you for how long the experiment should run, and when it has achieved the goal.

It can happen that there is no statistically significant difference between your variants! PostHog will tell you that in this screen as the experiment progresses, and in that case it won't matter which variant you opt for.

How to implement the A/B test in code

Now that we've got the A/B test created, we can use the PostHog client in our code to implement the two paths. For changing the button text, we'd do it in the template:

<button class="px-4 py-2 rounded-md shadow bg-green-500">
    {%- if session["feature_flags"].get("purchase_button") == "control" -%}
        Purchase
    {%- else if session["feature_flags"].get("purchase_button") == "buy_now" -%}
        Buy now
    {%- else if session["feature_flags"].get("purchase_button") == "subscribe" -%}
        Subscribe
    {%- endif -%}
</button>

When the experiment ends—after you've selected the winning variant in PostHog—it's important to go back and delete these if statements to simplify the code. At that point you'd just keep the code from the winning variant.

Simplify accessing feature flags in Jinja with a filter

Although that works fine, if we have a lot of feature flags, we can shorten the code quite a bit by using a custom Jinja filter.

In your app definition file, you can add this:

@app.template_filter("is_active")
def flag_is_active(feature_flag: str, test_name: str = None) -> bool:
    flag_value = test_name or True
    return session["feature_flags"].get(feature_flag) == flag_value

This is a simple filter called is_active that will let us check wither:

• A feature flag is active or not; or
• An A/B test has a specific value.

To use it in your template, you'd do this:

<button class="px-4 py-2 rounded-md shadow bg-green-500">
    {%- if "purchase_button" | is_active("control") -%}
        Checkout
    {%- else if "purchase_button" | is_active("buy_now") -%}
        Buy now
    {%- else if "purchase_button" | is_active("subscribe") -%}
        Subscribe
    {%- endif -%}
</button>

That's for an A/B test. If you wanted to use it for a feature flag without a payload, you could just do:

{% if "new_feature" | is_active %}

Conclusion

That's everything for now! I hope you've learned something new about running A/B tests with PostHog and how to use them.

If you want to learn more about web development with Flask, check out our Web Developer Bootcamp. You can enrol for a one-time fee, or subscribe to gain access to all our courses!

The term "feature flagging" means to use a boolean value to determine whether a certain feature should be enabled or disabled. A feature flag can be as simple as a Python variable!

Here's a very basic feature flag (note that secure_hash would have to be implemented separately):

username = input("Enter your username: ")
password = input("Enter your password: ")

use_hashing = False

if use_hashing:
	password = secure_hash(password)

print(username, password)

In the block of code above, use_hashing is a feature flag! When it is True, then the password hashing functionality would be used. If it isn't, then password hashing wouldn't be used.

Normally though, we don't use plain boolean variables as feature flags!

A key aspect of feature flagging is that we should be able to change the value of the flag without modifying the code.

What are feature flags?

As we've just seen, a feature flag is a boolean value that tells the code whether a certain feature should be turned on or off.

Normally feature flags are not hard-coded. Instead, they're read from a feature flag service. This could be a database or a third party service that stores feature flags and lets us change them while our code is running.

Why should you use feature flags?

As long as your feature flags are read from a third party service or a database, and you can change them while the code is running, using feature flags lets you modify what the code does, without requiring a code change and a re-deploy.

Because you don't need to change the code and re-deploy—you just toggle the feature flag on or off—it's much faster to enable or disable a feature.

This is particularly useful for:

• New features that you just added to your code, and you want to be able to turn them off if there's a problem.
• Features you're still working on, but you want to deploy the code while keeping the feature flag off. This means the app can still run, and the code can be integrated with the work other developers are doing.
• Features that you are upgrading as part of a new version, and you want to both turn the old version off and turn the new version on at the same time.

How to create feature flags with PostHog

First navigate to the Feature Flags section of the page using the left hand navigation. Then, click on "New feature flag":

Now you should give your feature flag a name so that you can check it in your code later. A description is never amiss, since sometimes feature flags can stick around for a long time and you might forget what it's about!

You can optionally tell PostHog to return a payload instead of true when the feature flag is enabled for a user. Below we're returning the string "v2".

You should also specify what percentage of users should see this feature flag. Using 100% means that when the feature flag is enabled, all users will see the new feature.

How to check the active feature flags from PostHog using Python

Before you can check the active feature flags for a user, you should set up tracking for anonymous and authenticated users. We looked at how to do this in our first PostHog blog post.

Once your users all have unique IDs, you can use the PostHog client to calculate the feature flags that should be enabled for this user.

You can do it in the same before_request function:

@app.before_request
def before_request():
    # Create a unique uuid identifier for this user
    # Store it in cookes
    # Use it to track user in PostHog
    if "user_id" not in session:
        if current_user.is_authenticated:
            session["user_id"] = current_user.id
        else:
            session["user_id"] = str(uuid.uuid4())

	if current_user.is_authenticated and current_user.id != session.get("user_id"):
        posthog.alias(session["user_id"], current_user.id)
        session["user_id"] = current_user.id

    try:
        session["feature_flags"] = posthog.get_all_flags(
            session["user_id"], only_evaluate_locally=True
        )
    except:  # noqa
        session["feature_flags"] = {}

Using only_evaluate_locally will mean that the PostHog client will make fewer requests to the PostHog API. Otherwise, many requests are made every time a request is made to your Flask app.

This works because the PostHog client periodically fetches the feature flag information from your account, and then can assign feature flag variants to users without having to make an API call per user request.

How to use feature flags in Flask

Above you learned how to check the feature flags for a given user. With that, you can now enable or disable specific features!

For example, let's say that you want to change the way an endpoint behaves. If a feature flag is active, you'll render one template. But if it isn't active, you'll render a different template.

@app.route("/homepage")
def homepage():
	if session["feature_flags"].get("new_homepage") == "v2":
		return render_template("homepage_v2.html")
	return render_template("homepage.html")

As you can see, using the feature flag is as simple as getting the feature flag name you created in PostHog from the session["feature_flags"] dictionary!

But what if you wanted to use a feature flag to show or hide a part of the page?

Since the feature flags are stored in the session, you can use them within a template.

How to change parts of the page using feature flags

Using a Jinja if statement, we can check the feature flag values and render part of the page or another.

Note that if you use caching together with feature flags, any changes to your feature flags won't be shown until your cache for the given page expires. That's because when a page is cached, the Python code doesn't run and the template isn't re-rendered.

Let's change part of the page template using feature flags (the feature flag below was created without a custom payload):

{% if session["feature_flags"].get("new_homepage_button") %}
<button class="modern-button">Click me!</button>
{% else %}
<button class="old-button">I'm looking dated...</button>
{% endif %}

It's as simple as that! Just wrap the new or modified page content using an if statement that checks the feature flag. Since the feature flags were loaded before the request was processed, rendering a template has access to the latest feature flags.

When to use feature flags and when to use A/B tests?

In PostHog, A/B testing and feature flags both are implemented using feature flags. However, when you create an A/B test in PostHog you get some extra analytics and tracking to help you identify which version (A or B) performs better.

If you just want to directly or incrementally release a new feature, using feature flags is the way to go as it's much simpler. If you want to compare two options for conversion rate optimization, you should run an A/B test.

In our next blog post we'll talk about A/B testing with PostHog.

Thank you for reading, and I hope you've learned something new!

If you want to learn more about web development with Flask, check out our Web Developer Bootcamp. You can enrol for a one-time fee, or subscribe to gain access to all our courses!

Understanding your users is crucial to the success of your web application.

Whether you're a startup or an established company, having access to some data around usage and engagement helps you make better decisions.

However, any discussion around web analytics needs a caveat: not everything can be described by a data point on a chart. Sometimes you need to talk to users. Other times, your gut and intuition are your best friends!

With that said, PostHog has an excellent offering that helps you understand usage as well as test variations (using A/B testing) and perform feature rollouts (with feature flags). Let's take a look.

By the way, I've made a video based on this blog post! You can check it out below.

Importance of Analytics in Growth

With user analytics, you can understand which features are most popular and which are essentially unused.

I've developed features before that nobody ended up using. But were users trying out the feature, and deciding they didn't need it? Or was the feature too hidden, and users didn't even know it was there?

Good analytics (and talking with your users) helps you detect which of these happened.

By analyzing product usage, sign-ups, and onboarding processes, you can identify patterns that guide your next big feature or enhancement.

Web analytics provide further granularity by revealing page views, session durations, and user flows across your marketing and content pages. Understanding these metrics is vital for optimizing user experience and conversion rate.

Feature Flags and A/B Testing

PostHog's feature flags offer the flexibility of progressively rolling out new features of your application.

For example, you could make a new feature available to just 5% of your users with a feature flag. If you see any glaring errors, you can turn the feature off without affecting your entire user base.

A/B testing is an extension of this concept. By presenting different versions of a page to different user segments, you can determine which performs better, which can help maximize conversions.

Session Replay and User Insight

Session replay is another powerful feature of PostHog. It provides a visual playback of user interactions, allowing you to diagnose errors and refine the user journey with precision.

Getting Started with PostHog

Firstly, you'll need to create a PostHog account. Register here and familiarize yourself with the dashboard. To track analytics, you can integrate PostHog into your application in several ways.

For Web Clients

Embedding PostHog into your web application begins with setting up the web client. You will include a script in your base HTML template that initializes PostHog and starts tracking page events.

Here’s a quick setup guide:

Insert the PostHog JavaScript snippet into the <head> section of your base.html template:

<!– base.html -->
<head>
    <script>
        <!-- PostHog initialization code -->
        <!-- PostHog user identification code -->
    </script>
</head>

Replace <!-- PostHog initialization code --> with the script provided by PostHog.

Remember to configure the script with your 'Project API Key' to begin tracking page loads and views.

Then, you'll want to identify users. Each user in your application should be identifiable with a unique ID. Assigning each user a unique ID is done in the Python code. More on that in a moment!

For Custom Events with Python API

To identify users and to send custom product analytics events, you'll use PostHog's Python library:

Install the PostHog library using pip:

pip install posthog

In your Python application, import and configure PostHog with your API key:

import posthog

posthog.api_key = 'your-posthog-api-key'
posthog.host = 'https://app.posthog.com'  # or eu.posthog.com

Capture events by calling posthog.capture, for example:

posthog.capture('user-id', 'User Signed Up')

Remember to replace 'user-id' with the actual identifier of your user.

But how do you get a user identifier? You use the database user ID, but there's a bit more to that... Read on!

Identifying registered and anonymous users with PostHog and Flask

Most (all?) users start their visit to a website as anonymous users. They don't have an account, and they're not logged in.

Then at some point they may register or log in.

In subsequent visits they may start the journey as logged-in users, or not. If their session has expired, they'll need to log in again.

This is to say, that our tracking needs to be able to track anonymous and registered users, and it also needs to handle when an anonymous user becomes a registered user, and make sure any captured data is stored under the registered user data.

For anonymous users, we'll define a unique ID and store that in the browser cookies. Every time they make a page request, that same user ID will be re-used. For registered users, we'll use their database ID.

from flask import session
from flask_security_too import current_user
import uuid
import posthog

posthog.api_key = 'your-posthog-api-key'
posthog.host = 'https://app.posthog.com'

@app.before_request
def before_request():
    if "user_id" not in session:
        if current_user.is_authenticated:
            session["user_id"] = current_user.id
        else:
            session["user_id"] = str(uuid.uuid4())

    # When an anonymous user signs in, PostHog aliases the new authenticated user ID with the UUID.
    if current_user.is_authenticated and current_user.id != session.get("user_id"):
        posthog.alias(session["user_id"], current_user.id)
        session["user_id"] = current_user.id

In the code above, we use the before_request Flask hook to check if a session-level user ID exists. If not, we assign one.

For authenticated users, we use their unique current_user.id from Flask-Security-Too. If you are using a different library, just replace that by your user's ID that is stored in the database.

For anonymous users, we generate and assign a UUID (str(uuid.uuid4())).

When an anonymous user registers or logs in, we use posthog.alias to merge the UUID session with the authenticated ID.

In your template, you'll then want to run this:

<!-- base.html -->
<head>
    <!-- Other head elements -->

    <!-- Start PostHog -->
    <script>
        <!-- PostHog initialization code -->

        <!-- PostHog user identification code -->
        posthog.identify("{{ session['user_id'] }}")
    </script>
    <!-- End PostHog -->
</head>

With this, you have consistent tracking, so you know what your users do before and after they authenticate!

Identifying registered and anonymous users with PostHog and Django

Doing this with Django is similar to with Flask, but instead of using the before_request hook, you'd write a middleware:

import uuid
import posthog

posthog.api_key = 'your-posthog-api-key'
posthog.host = 'https://app.posthog.com'  # or eu.posthog.com

def posthog_middleware(get_response):
	def middleware(request):
		if "user_id" not in request.session:
	        if request.user.is_authenticated:
	            request.session["user_id"] = request.user.id
	        else:
	            request.session["user_id"] = str(uuid.uuid4())

	    # When an anonymous user signs in, PostHog aliases the new authenticated user ID with the UUID.
	    if request.user.is_authenticated and request.user.id != session.get("user_id"):
	        posthog.alias(session["user_id"], request.user.id)
	        session["user_id"] = request.user.id

Then you can add this middleware to MIDDLEWARE in your settings.py file, making sure it is after other middlewares that must run first, such as for the session and authentication:

MIDDLEWARE = [
    # ... (other middleware entries)
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',

    # Add posthog_middleware after AuthenticationMiddleware
    'path.to.your.application.posthog_middleware',

    # ... (other middleware entries)
]

For more information on middleware, I strongly recommend reading the official documentation.

Then in your base template, you'd again call posthog.identify(), passing your user ID.

Conclusion

I really like PostHog, and it's super easy to get started with it! I use it for product analytics, web analytics, observing session replays, implementing feature flags, and A/B testing.

If you want to learn more about web development with Python and Flask, including web app design, HTML, and CSS, check out our Web Developer Bootcamp. It's a complete course that teaches you how to build web applications!

In our next PostHog article we'll look at working with feature flags using PostHog. I'll link it below when it's published next week!

In this article, I will show you how to add a contact form to your Flask website using HTML.

But writing the HTML for the contact form is only half the job!

I will also show you how to send emails using Python, so that when a user submits the contact form you receive an email with the form contents.

Here is an example of what the HTML contact form will look like:

To make the contact form we will use HTML and optionally Bootstrap, and for the backend code we will use Flask and the Resend API.

Our app will have a unique endpoint called /contact where the user will be able to write their name, email address, and a message. When the user submits the contact form, an email will be sent to the website owner with the information submitted by the user.

Initial setup to start coding the Flask app

To begin, set up your Python development environment. Check out this blog post if you're not sure how.

You'll also need a Resend account. For what we're doing in this blog post, it's free.

As a first step, create a Resend API key. Since we are only interested in sending emails, you can select the Send emails permission only. Make sure that you copy the API key, as you will not be able to see it again.

Once you have the API key, create a .env file in your project with the following contents:

RESEND_API_KEY=<Your Resend API Key>
ADMIN_EMAIL=<Your Resend email address>

The ADMIN_EMAIL is the email address that will receive the contact form submissions. An important thing to consider is that unless you have a custom domain (costs money), you will only be able to send emails to the email address with which you signed up for Resend. They do this to prevent spam.

As always, if you are planning on uploading the code to a public repository, make sure to add the .env file to your .gitignore file.

Afterwards, create a requirements.txt file with the following content in your working directory:

flask==3.0.0
python-dotenv==1.0.0
resend==0.5.2

Confirm that your virtual environment is activated, then, run the command:

pip install -r requirements.txt

Finally, add a .flaskenv file with the following content:

FLASK_DEBUG=1

This will ensure the app will reload when you make changes to the code.

Creating a basic HTML contact form

In this step we will add a contact form with no styling (we will add styles later on).

To do this, create a templates folder and add a user-contact-form-template.html file with the following content:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Contact Form</title>
  </head>
  <body>
        <h2>Contact Us</h2>
        <form action="/contact" method="POST">
          <div>
            <label for="name">Name</label>
            <input type="text" name="name" required/>
          </div>
          <div>
            <label for="email">Email</label>
            <input type="email" name="email" required/>
          </div>
          <div>
            <label for="message">Message</label>
            <textarea name="message" rows="4" required></textarea>
          </div>
          <div>
            <button type="submit">Submit</button>
          </div>
        </form>
      </div>
    </div>
  </body>
</html>

Creating the Flask app

Adding the imports

Now that we have all set up, we can start working on our app. Let's create an app.py file and add the imports:

import os

import resend
from flask import Flask, redirect, render_template, request

The resend package is the official Python client for the Resend API. We will use it to send emails.

From flask we import a few things:

• The Flask class to create a Flask app.
• redirect to send users to a different page when they submit the contact form.
• render_template to send our HTML to the user's browser.
• request to access the data submitted by the user.

We'll use the os module to access the environment variables we defined in the .env file.

Loading the environment variables with Flask

When we have the python-dotenv package installed, Flask will automatically load the .env file when we start the app.

To access their values, we use os.environ:

resend.api_key = os.environ["RESEND_API_KEY"]
ADMIN_EMAIL = os.environ["ADMIN_EMAIL"]

After these lines, create a variable to store the HTML that will be sent to the site owner.

Creating the email HTML body

CONTACT_EMAIL = """
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>New Message Notification</title>
</head>
<body>
    <h2>New Message Received!</h2>
    <p><strong>Name:</strong> {name}</p>
    <p><strong>Email:</strong> {email}</p>
    <p><strong>Message:</strong></p>
    <blockquote>
        {message}
    </blockquote>
</body>
</html>
"""

Later, we will use the .format() method to inject the variables name, email, and message into the HTML template.

Creating the Flask app object

Next, create the Flask app:

app = Flask(__name__)

Coding the Flask contact form endpoint

Our endpoint looks as follows:

@app.route("/contact", methods=["GET", "POST"])
def contact():
    if request.method == "POST":
        # Load form data
        form_data = request.form.to_dict()

        # Configuring the email fields
        params = {
            "from": "Your Flask App <onboarding@resend.dev>",
            "to": [ADMIN_EMAIL],
            "subject": f"New message from {form_data['name']}!",
            "html": CONTACT_EMAIL.format(**form_data),
        }

        # Sending the email and catching response
        response = resend.Emails.send(params)

        # Handle the response
        if response.get("id"):
            return redirect("/contact")
        else:
            return {"message": "Something went wrong. Please try again."}
    else:
        # Render the contact form
        return render_template("user-contact-form-template.html")

There are quite a lot of things going on here, so let's break it down!

As a first step, we check if the request method is POST. If it is, it means that the user submitted the contact form, so we can proceed to send the email. If it is not, it means that the user is trying to access the /contact endpoint, so we render the contact form:

@app.route("/contact", methods=["GET", "POST"])
def contact():
    if request.method == "POST":
        # Handle the form submission ...
    else:
        # Render the contact form
        return render_template("user-contact-form-template.html")

If the request method is POST, we load the contact form data into a dictionary using request.form.to_dict(). The resulting dictionary will look like this:

{
    'name': 'Some Name',
    'email': 'example@email.com',
    'message': 'Some message'
}

Next, we create a new dictionary with the filled email fields that we need to send the email:

@app.route("/contact", methods=["GET", "POST"])
def contact():
    if request.method == "POST":
        # Load form data
        form_data = request.form.to_dict()

        # Configuring the email fields
        params = {
            "from": "Your Flask App <onboarding@resend.dev>",
            "to": [ADMIN_EMAIL],
            "subject": f"New message from {form_data['name']}!",
            "html": CONTACT_EMAIL.format(**form_data),
        }
    else:
        # Render the contact form
        return render_template("user-contact-form-template.html")

• from: since we haven't configured a DNS, we can only send emails with the default resend account onboarding@resend.dev.
• to: it contains the administrator email loaded from the environment variable.
• subject: we create a custom title by using f-strings to inject the name loaded from the for data.
• html: contains the HTML body of the email. We use the .format() method with keyword arguments provided by the dictionary keys to inject the custom content.

After filling in the email data, we send it using Resend API and catch the response:

@app.route("/contact", methods=["GET", "POST"])
def contact():
    if request.method == "POST":
        # Load form data
        form_data = request.form.to_dict()

        # Configuring the email fields
        params = {
            "from": "Your Flask App <onboarding@resend.dev>",
            "to": [ADMIN_EMAIL],
            "subject": f"New message from {form_data['name']}!",
            "html": CONTACT_EMAIL.format(**form_data),
        }

        # Sending the email and catching response
        response = resend.Emails.send(params)

        # Handle the response
        if response.get("id"):
            return redirect("/contact")
        else:
            return {"message": "Something went wrong. Please try again."}
    else:
        # Render the contact form
        return render_template("user-contact-form-template.html")

Exploring the Resend dashboard

Resend has a really helpful user interface where we can see information related to the emails we sent, here is an example of the overview menu:

And another example of how the requests and responses look like from Render's side:

Filling in the HTML contact form

Now that we have put all the pieces together, we can go to the terminal and run flask with the command:

flask run

Then, navigate to the URL http://localhost:5000/contact, fill out the HTML contact form, and check out your mail inbox!

Remember that since we are using Resend's testing service, we can only send emails to the address we registered with.

Improve our HTML contact form with Bootstrap

To add Bootstrap 5 styles to our HTML contact form as shown in the first screenshot, replace the contents of the user-contact-form-template.html with the following code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Contact Form</title>
    <!-- Bootstrap CSS -->
    <link
      href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css"
      rel="stylesheet"
      integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC"
      crossorigin="anonymous"
    />

    <style>
      /* You can add additional custom styles here if needed */
      .contact-form {
        max-width: 600px;
        margin: 50px auto;
        padding: 20px;
        border: 1px solid #ccc;
        box-shadow: 0px 0px 10px rgba(0, 0, 0, 0.1);
      }
    </style>
  </head>
  <body>
    <div class="container">
      <div class="contact-form">
        <h2>Contact Us</h2>
        <form action="/contact" method="POST">
          <div class="mb-3">
            <label for="name" class="form-label">Name</label>
            <input
              type="text"
              class="form-control"
              id="name"
              name="name"
              required
            />
          </div>
          <div class="mb-3">
            <label for="email" class="form-label">Email</label>
            <input
              type="email"
              class="form-control"
              id="email"
              name="email"
              required
            />
          </div>
          <div class="mb-3">
            <label for="message" class="form-label">Message</label>
            <textarea
              class="form-control"
              id="message"
              name="message"
              rows="4"
              required
            ></textarea>
          </div>
          <div class="mb-3">
            <button type="submit" class="btn btn-primary">Submit</button>
          </div>
        </form>
      </div>
    </div>
  </body>
</html>

Conclusion

In this article we showed you how to send emails with the Resend API and Flask. We created an HTML contact form, processed the form data, populated the email fields and body with the form data, sent the email, handled the response, and finally we added custom Bootstrap 5 styling.

You can learn a lot more about web development with Flask with our course, Web Developer Bootcamp with Flask and Python. In it, we cover how to use Flask, HTML, and CSS, to build 4 different projects of increasing complexity. Check it out!

In this blog post, I'll show you how to build your first API with FastAPI, using pydantic and encode/databases. Our project will be a time-tracking API.

No time to waste! Let's build an API fast, with FastAPI 🚀

Project overview and set-up

Our API will be simple, it will have 3 endpoints:

• POST /track will receive user_id and description. It creates a new task and starts a timer for it.
• POST /stop will receive an id and stop the timer for that task.
• GET /times will receive a user_id and date (e.g. 2023-07-16) and will respond with a list of tasks and the time spent in each, in that day.

Our database will have a single table, tasks, with the following columns:

• id, an auto-generated integer ID for the task.
• description, a textual description of the task.
• user_id, the integer ID of the user.
• start_time, the time the task was started.
• end_time, the time the task was stopped.

First things first, create a virtual environment for your project:

python3 -m venv .venv

Then activate it (the command differs on Windows):

source .venv/bin/activate

Then let's create a file called requirements.txt, and put in all the libraries we need:

fastapi
uvicorn
sqlalchemy
databases[sqlite]
pydantic
python-dotenv

To install all of these, run:

pip install -r requirements.txt

How to define database tables using SQLAlchemy

SQLAlchemy is an ORM, which means that instead of sending SQL queries to the database and receiving rows of data back, we deal with Python classes and objects.

The first step is to define the tables of data that our application needs.

Write this code in database.py:

import databases
import sqlalchemy

# Define the URL for our SQLite database. This is a file path which makes
# the database in a file called data.db in the current directory.
DATABASE_URL = "sqlite:///data.db"

# MetaData is a container object that keeps together different features of a database being described.
metadata = sqlalchemy.MetaData()

task_table = sqlalchemy.Table(
    "tasks",
    metadata,
    sqlalchemy.Column("id", sqlalchemy.Integer, primary_key=True),
    sqlalchemy.Column("user_id", sqlalchemy.Integer),
    sqlalchemy.Column("start_time", sqlalchemy.DateTime),
    sqlalchemy.Column("end_time", sqlalchemy.DateTime)
)

# Create an engine that stores data in the local directory's data.db file. 
# "check_same_thread" is set to False as SQLite connections are not thread-safe by default. 
engine = sqlalchemy.create_engine(
    DATABASE_URL, connect_args={"check_same_thread": False}
)

# Create all tables stored in this metadata in the actual file.
metadata.create_all(engine)

# Initialize a database connection.
database = databases.Database(DATABASE_URL)

How to set up our FastAPI app

The start of every FastAPI always looks similar! We create the FastAPI object, and then we can start setting up the routes or endpoints.

When clients make requests to one of our endpoints, we trigger a Python function that can perform some actions and respond with some data. That response data is then sent to the client.

Let's set up our FastAPI app in main.py:

from fastapi import FastAPI

app = FastAPI()

That's the FastAPI set-up! Now we need to do two things:

1. Connect to our database.
2. Write our endpoint functions.

How to connect to our database using FastAPI lifespan events

We can configure a lifespan event in FastAPI apps, which is a function that can perform some set-up before the FastAPI app starts running, and some tear-down after the FastAPI app finishes running.

We will use it to connect to our database.

To write the lifespan event, we write an async context manager, which is an async function decorated with @asynccontextmanager. This function must include a yield statement.

Any code before the yield will run before the FastAPI app starts. During the yield, the FastAPI app runs. This can take seconds, or much longer--even days! The code after the yield is our tear-down code, which runs after the FastAPI app finishes running.

Write this code in the main.py file:

from contextlib import asynccontextmanager

from database import database
from fastapi import FastAPI


@asynccontextmanager
async def lifespan(app: FastAPI):
    await database.connect()
    yield
    await database.disconnect()


app = FastAPI(lifespan=lifespan)

The Pydantic models we need for data validation

FastAPI uses Pydantic models to automatically handle request validation, serialization, and documentation.

When clients send us data, we will pass this data through a Pydantic model to ensure it contains what we need. So if we need clients to send us a user_id and the id of the task, then we can write a Pydantic model for that.

We will need four Pydantic models:

• NewTaskItem, for when clients want to create a task. It ensures clients send us user_id, an integer, and description, a textual description of the task.
• TaskItem, for when clients want to stop a task. It ensures clients send us id, an integer.
• TaskOut, for when we want to respond with a task representation. We will use this model to ensure that our response has the right content. It ensures the response contains id, an integer, description, a string, and time_spent, a float.

Write this code in a models.py file:

from pydantic import BaseModel


class NewTaskItem(BaseModel):
    user_id: int
    description: str


class TaskItem(BaseModel):
    id: int


class TaskOut(BaseModel):
    id: int
    description: str
    time_spent: float

But up to now it may not be very clear how these models are used. Let's get into that with our first endpoint!

Writing an endpoint to start tracking a task

Here's our first endpoint. We'll add some code to main.py.

There are some new imports, add those at the top of the file. The rest of the code goes at the bottom of the file.

from datetime import datetime

from models import NewTaskItem
from database import task_table

...

@app.post("/track", response_model=TaskItem)
async def track(task: NewTaskItem):
    data = {**task.model_dump(), "start_time": datetime.now()}
    query = task_table.insert().values(data)
    last_record_id = await database.execute(query)

    return {"id": last_record_id}

When clients want to create a task, they'll send a request to our /track endpoint. They need to include the data that the TaskItem expects in the JSON payload of the request.

Pydantic will take that data and give us a TaskItem object. We then turn it into a dictionary using .model_dump() so we can insert it into our database. To that dictionary, we add the start_time.

To create a query to insert data, we use task_table.insert().values(data).

The id column is an integer primary key, which means it is auto-generated by the database when we create a new row.

When we execute an insert query, we get back the ID of the row we just inserted. We send that to the client so they can use it to stop the task later on.

Writing an endpoint to stop tracking a task

Just like the /track endpoint, our /stop endpoint needs to accept some data from the client, so we include a parameter with a Pydantic model.

In this case, we need to accept TaskItem, which includes id. We can then use this information to stop the task by updating its end_time in the database.

Let's update our main.py to include this endpoint:

from models import TaskItem

...

@app.post("/stop", response_model=TaskItem)
async def stop(task: TaskItem):
    end_time = datetime.now()
    query = (
        task_table.update().where(task_table.c.id == task.id).values(end_time=end_time)
    )
    await database.execute(query)
    return task

When a client sends a request to stop a task, they will include the task's ID. Pydantic will ensure that the field is present and is an integer, then provide us with a TaskItem object.

We then create a datetime object for the current time, which we will use as the end_time for the task.

To update a row in the table, we use the update method, specifying the row we want to update using the where method, and then the data we want to update using the values method.

Writing an endpoint to get the times worked on a day

When the client wants to get the tasks worked on a specific day, they need to send a GET request to the /times endpoint, with user_id and date as query parameters.

We calculate the start and end times of the day the client is interested in and then use these times to filter the tasks from the database.

Here's an example of what this URL might look like: http://our-api-domain.com/times?user_id=42&date=2023-07-18.

In this example, the client is requesting the tasks for the user with ID 42 on July 18th, 2023.

For FastAPI to take the query parameters from the URL, we need to add parameters to our function that aren't a Pydantic model (only int and str are supported for query string arguments).

Here's the code:

from datetime import timedelta, time

from models import GetTimesItem, TaskOut

...

@app.get("/times", response_model=list[TaskOut])
async def get_times(user_id: int, date: str):
    # Using `int` and `str` parameters instead of Pydantic models
    # tells FastAPI we want to get these values from the query string.
    selected_date = datetime.strptime(date, "%Y-%m-%d").date()
    start_of_day = datetime.combine(selected_date, time.min)
    end_of_day = datetime.combine(selected_date, time.max)

    query = task_table.select().where(
        (task_table.c.user_id == user_id)
        & (task_table.c.start_time <= end_of_day)
        & ((task_table.c.end_time >= start_of_day) | (task_table.c.end_time.is_(None)))
    )
    tasks = await database.fetch_all(query)

    result = []
    for task in tasks:
        end_time = task["end_time"]
        if task["end_time"] is None:
            end_time = datetime.now()

        actual_start = max(task["start_time"], start_of_day)
        actual_end = min(end_time, end_of_day)
        duration = actual_end - actual_start

        result.append({**task, "time_spent": duration.total_seconds()})

    return result

Here, start_of_day and end_of_day mark the beginning and end of the day the user wants the time tracking for. By using datetime.combine, we can combine a date and a time. The first argument, the date, is given by the user. The second argument, time.min or time.max is the minimum or maximum value a time can be (00:00:00 or 23:59:59 respectively).

The select query fetches tasks from the database where the user_id matches, the start_time is before the end of the day and either end_time is after the start of the day or is not set (indicating an ongoing task).

In the loop, for each task, if end_time is not set, it's assigned the current time as the task is still ongoing. We then find the actual start and end times by clamping the task's start and end times to the start and end of the day. We calculate the duration by subtracting actual_start from actual_end and append the task to the result list.

Finally, we return the result list, which is a list of dictionaries containing all the task data and time_spent for each task.

This is by far the most complicated function in our application!

How to get a deployed PostgreSQL database from ElephantSQL

ElephantSQL is a PostgreSQL database hosting service. We can use it to get a deployed database for free. Here's how to get a database up and running:

1. Go to the ElephantSQL website and create an account.
2. Once logged in, click on "Create new instance".
3. Choose the free plan, which gives you 20MB storage (good enough for a small project or for learning).
4. Give your instance a name and select a region close to where your users will be.
5. Click on "Select plan" at the bottom to create your instance.
6. Once created, click on the instance name in your dashboard to view its details.
7. In the details view, you will find your URL (in the format postgresql://user:password@host:port/dbname). This is your database URL, which you can plug into your application to connect to this database.

How to connect to your deployed database securely

It's not a good idea to hardcode the database connection string directly into your code, as this can pose significant security risks. For example, if your code is shared publicly (e.g., on a GitHub repository), anyone who has access to your code would also have access to your database!

A safer practice is to use environment variables to store sensitive information. An environment variable is a value that's available to your application's environment, and it can be read by your application. This way, you can share your code without exposing any sensitive information, as the actual credentials will be stored safely in the environment, not in the code.

To manage environment variables, we'll use the python-dotenv module, which allows you to specify environment variables in a .env file. This can be particularly handy during development, as it allows you to replicate the environment variables that will be used in production.

Create a .env file in the root of your project, and add the database connection string as an environment variable in the .env file:

DATABASE_URL="postgresql://username:password@hostname/databasename"

Then, in your database.py file, use os.getenv to get the value of the DATABASE_URL environment variable. Make sure to import the os module at the top of the file:

import os
import sqlalchemy
import databases

DATABASE_URL = os.getenv("DATABASE_URL")

metadata = sqlalchemy.MetaData()

# Define your tables here...

# You don't need check_same_thread=False when using PostgreSQL.
engine = sqlalchemy.create_engine(DATABASE_URL)

metadata.create_all(engine)
database = databases.Database(DATABASE_URL)

Now, when your application runs, it will read the DATABASE_URL from the environment variables, either from the .env file in a development environment or directly from the system environment in a production environment.

Ensuring the .env file doesn't end up in GitHub either

Now that we've moved the database connection string out of our code, we need to make sure that our .env file doesn't end up being publicly available, as that would defeat the point!

We need to make sure that the .env file doesn't end up in GitHub, and the best way to do that is to never commit it or upload it.

A good way to prevent accidentally committing the .env file to GitHub is by creating another file called .gitignore, and inside it putting this text:

.env

This tells Git to never include a file called .env in any commits.

How to deploy your FastAPI app to Render.com

1. Push Your Code to a Git Repository: Render uses Git repositories to fetch and build applications. Push your code to a repository on a service like GitHub.
2. Create a New Web Service on Render: Go to the Render dashboard and click on the "+ New" button, then select "Web Service."
3. Select Your Repository: You'll be asked to provide a repository where your FastAPI project is hosted. Choose your repository and branch.
4. Configure Your Service: You will need to specify some settings for your application:

• Build Command: This is the command Render will run to install your dependencies. If you're using Pipenv, this will be pipenv install. If you're using poetry, this will be poetry install. If you're using requirements.txt, it will be pip install -r requirements.txt.
• Start Command: This is the command to start your FastAPI server. Typically, it's uvicorn main:app --host 0.0.0.0 --port 10000. Replace main:app with the location of your FastAPI app if it's not in main.py at the root of your repository.

1. Advanced Settings: Our application requires environment variables, so let's add one with the name of DATABASE_URL and the value of our ElephantSQL connection string.
2. Deploy: Click "Save & Deploy" to create your service. Render will pull your code, install your dependencies, and start your service. Your service logs will be displayed, helping you monitor the deployment process.

Your FastAPI application should now be up and running on Render! The URL of your application will be in the format <service-name>.onrender.com.

Conclusion

We've walked you through building a simple yet practical time-tracking API with FastAPI and SQLAlchemy. This application can track tasks, stop tasks, and retrieve the time spent on tasks for a user on a given day.

If you're looking to take your FastAPI knowledge to the next level, check out our comprehensive FastAPI 101 course.

In this course, we cover how to build a complete, complex FastAPI project using pydantic, sqlalchemy, and more. We'll even guide you through implementing email confirmation, file uploads, and other advanced features. Join us in FastAPI 101 to make the most of FastAPI's speed and simplicity while building robust, production-ready applications.

Welcome to our beginner's guide on pytest! pytest is a powerful and easy-to-use testing framework in Python. In this blog post, we'll introduce you to the essential features of pytest, using code examples and explanations.

If you'd rather watch the YouTube video for this article, check it out below!

When we write code—let's say one function—it's easy to focus on just the one situation where we will use it. When that happens, we tend to forget about what will happen when we use the function in other circumstances, and also on how the function operates with the data available in our program.

What I mean to say (please bear with the super-simplified example) is we may write a function like this:

def divide(x, y):
    return x / y

And forget that the function may be called with y=0, which will result in an error.

Writing tests as we go along (or even before we write the code) can help put us in a mindset of "what do I want this function to do when given certain inputs?" and this moves from an implementation mindset into a more mathematical mindset.

In this article, I'll show you how to use pytest to write tests for your Python code!

How to install and run Pytest

To install pytest, just run:

pip install pytest

Remember that if you're using pytest in a project, you should first create a virtual environment. I also recommend working with pyenv so you can easily use multiple different Python versions in your computer.

Whenever you start a new project, I recommend using the latest Python version available (that is compatible with the libraries you plan to use) and always creating a virtual environment for the project.

Now that you've got your virtual environment created and pytest installed, let's write our first test! In a new file called test_simple.py (naming is important, should start with test_):

def test_simple_add():
    assert 1 + 1 == 2

Note the naming here is also important. Pytest tests are functions, and the functions names should start with test_.

Pytest uses Python assertions, so it's super simple to get started. In Python, 1 + 1 == 2 evaluates to the boolean value True, so assert True will pass and therefore your test will pass. Doing assert False will raise an AssertionError which would cause the test to fail. Simple, right?

To run all your tests (just 1, for now), activate your virtual environment and then run:

pytest

You should see something like this output (among potentially a few other things):

platform darwin -- Python 3.11.0, pytest-7.2.2, pluggy-1.0.0
rootdir: /Users/josesalvatierra/Documents/Teclado/Blog/posts/2023/02-07-testing-with-pytest/project
collected 1 item                                                                 

test_simple.py .           [100%]

=== 1 passed in 0.00s ===

The main thing there is:

test_simple.py .           [100%]

This tells you that in the file test_simple.py there was 1 passing test (denoted by the .). The [100%] at the end tells us that 100% of the tests have ran.

If you have many files, the file names and the . (or other characters, if the test doesn't pass) will appear as the tests run. Similarly the percentages will add up over a few (or many) lines until you reach 100%.

If you want to run a specific file because you have multiple files, you could always run:

pytest test_simple.py

And if you want to run a specific test, you can do so like this:

pytest -k test_simple_add

The -k flag must be my most-used one. Any tests that contain the string test_simple_add in their function name will run. At the moment it's just one, but you can see how you could do for example pytest -k register to run all tests related to user registration, for example.

Let's write another test:

def test_simple_add():
    assert 1 + 1 == 2


def test_failing():  # will fail
    assert 'a' == 'b'

This new test will fail. When you run pytest, you'll see this output (I'll skip showing you the printed boilerplate from now on):

test_simple.py .F                                             [100%]

===== FAILURES =====
_____ test_failing _____

    def test_failing():
>       assert 'a' == 'b'
E       AssertionError: assert 'a' == 'b'
E         - b
E         + a

test_simple.py:6: AssertionError
===== short test summary info =====
FAILED test_simple.py::test_failing - AssertionError: assert 'a' == 'b'

Now this is quite handy! You can see that in test_simple.py there is one passing test and one failing test with .F.

At the end of the test run, pytest shows you which tests have failed, and when there is an assertion that failed, it shows you the values and what the expectation was. Here we had 'b', but the assertion expected to see 'a' on the right side.

Test outcomes in pytest

This actually brings us nicely to the different test outcomes. So far we've seen:

• PASSED, denoted by .
• FAILED, denoted by F

But there are others too:

• SKIPPED (s)
• XPASS (X), a.k.a. "unexpectedly passed"
• ERROR (E)

Expected failure in pytest with xfail

Let's say that for whatever reason, we want to keep our second test but we want to tell pytest that it should fail. That is, that "success" for that test means "it fails".

We can mark it with a decorator:

import pytest


def test_simple_add():
    assert 1 + 1 == 2


@pytest.mark.xfail
def test_failing():
    assert 'a' == 'b'

Running these tests will now show us this:

test_simple.py .x

And all tests passed! The second test passed, because we said we expected it to fail. Confusing, right? It's not used very often, but it's there if you need it.

Note that the outcome was x, and not X. That's because we said the test should fail, and it did. It didn't "unexpectedly pass", it "expectedly failed".

If we change it to this:

import pytest


def test_simple_add():
    assert 1 + 1 == 2


@pytest.mark.xfail
def test_failing():
    assert 'a' == 'a'  # this will pass

Then the outcome will be:

test_simple.py .X

Pytest now says 1 passed, 1 xpassed.

How to skip tests with pytest

Using similar syntax, we can skip tests:

import pytest


def test_simple_add():
    assert 1 + 1 == 2


@pytest.mark.skip
def test_failing():
    assert 'a' == 'b'

And now the output:

test_simple.py .s

Again, all tests pass. You shouldn't skip tests very often, but sometimes there isn't anything you can do about a test failure (temporarily), so you can skip it.

You can also skip tests only under certain conditions. For example, if a certain test doesn't work on Mac computers because the library you're using isn't supported there, you can use skipif:

import os

import pytest


def test_simple_add():
    assert 1 + 1 == 2


@pytest.mark.skipif(os.name == 'posix', reason='does not run on mac')
def test_failing():
    assert 'a' == 'b'

Again, test is skipped on Mac computers, but not on Windows (where it would fail, since 'a' == 'b' always fails).

The error test outcome in pytest

The final test outcome, error, is pretty self-explanatory. If there's an error such as ValueError, NameError, or any other error during the runtime of the test that isn't AssertionError, the test will fail with ERROR (shown as E in the console).

How to write Pytest tests (with a better example)

Let's move on to a different example for the rest of this article. Let's say you are writing a class to represent replies in a forum thread. Something like this (in a file called reply.py):

import datetime


class Reply:
    def __init__(self, body: str, user: str, created: datetime.datetime) -> None:
        self.body = body
        self.user = user
        self.created = created
    
    def __repr__(self) -> str:
        return f"<Reply from '{self.user}' on '{self.created.strftime('%Y-%m-%d %H:%M')}'>"

    def __eq__(self, __value: object) -> bool:
        if not isinstance(__value, Reply):
            return False
        return (
            self.body == __value.body and
            self.user == __value.user and
            self.created == __value.created
        )

Now let's write some tests for this!

First we need to think about what different tests we may want to write:

• Test that creating a Reply object works (testing __init__).
• Test that calling repr(reply) works correctly (testing __repr__).
• Test __eq__:
  • Two Reply objects with the same data are equal when doing reply1 == reply2.
  • Two Reply objects with different data aren't equal.
  • A Reply object and something else (like a string) aren't equal.

The Given-When-Then structure for tests

Create a file test_reply.py for the next few tests.

First, we'd add our imports:

import datetime

from reply import Reply

Then let's test that we can create a Reply object:

def test_init():
    # Given
    body = "Hello, World!"
    user = "user1"
    created = datetime.datetime.now()

    # When
    reply = Reply(body, user, created)

    # Then
    assert reply.body == body
    assert reply.user == user
    assert reply.created == created

Here you can see the Given-When-Then structure of tests coming into play. It's a simple but effective way to structure your tests:

1. Start by defining the data your test will use ("given that this data is available...")
2. Then write the actual test ("when this happens...")
3. Finally, check that the result is what you expect ("then the result is...")

How to write tests for functions that process data

In our __repr__ method, objects have access to self.created, and they will transform it to a string to be displayed.

We may feel like doing something like this is warranted:

def test_repr():
    body = "Hello, World!"
    user = "user1"
    created = datetime.datetime.now()

    reply = Reply(body, user, created)
    expected_repr = f"<Reply from '{user}' on '{created.strftime('%Y-%m-%d %H:%M')'>"

    assert repr(reply) == expected_repr

But this would be a bit of a mistake, because the code in the Reply objects calls strftime, and so does our testing code. They're both doing the same thing, so you aren't really testing anything.

Instead, it's better to actually write the expected value in the test. It also makes it more readable!

def test_repr():
    body = "Hello, World!"
    user = "user1"
    created = datetime.datetime(2023, 1, 1, 0, 0, 0)

    reply = Reply(body, user, created)
    expected_repr = f"<Reply from '{user}' on '2023-01-01 00:00'>"

    assert repr(reply) == expected_repr

By the way, I should mention that if your tests fail and you're not sure why, running Pytest with the -v flag can be very helpful. It gives you a bit more information about the expected and actual assertion values.

pytest -v

Testing for expected exceptions

What happens when a user passes something that isn't a datetime object to a Reply?

Well, nothing until __repr__ is called. Let's write a test for that.

Here we will use an assertion helped, pytest.raises, to say that an exception should be raised:

def test_repr_without_date():
    body = "Hello, World!"
    user = "user1"
    created = "2021-02-07 12:00"

    reply = Reply(body, user, created)

    with pytest.raises(AttributeError):
        assert repr(reply) == f"<Reply from '{user}' on '2021-02-07 12:00'>"

Note that with pytest.raises(AttributeError) says that when we call repr(reply), an AttributeError should be raised because we can't call created.strftime() (since created isn't a datetime object).

There are other helpers that are worth knowing about. For example, pytest.approx(), which allows you to do things like:

import pytest

def test_almost_equal():
    x = 5
    y = 5.01
    assert x == pytest.approx(y, 0.1)  # True
    assert x == pytest.approx(y, 0.01)  # True
    assert x == pytest.approx(y, 0.001)  # False

This one checks that the two values are within an acceptable range of each other, given by the second argument. Handy, especially when comparing floats (did you know most programming languages don't represent floats very well in some cases?).

Testing the equality of two objects

To write our tests for testing equality, we do something similar to what we've been doing! First make variables for the values, then create the objects, and finally compare them:

def test_eq_same_values():
    body = "Hello, World!"
    user = "user1"
    created = datetime.datetime.now()

    reply1 = Reply(body, user, created)
    reply2 = Reply(body, user, created)

    assert reply1 == reply2


def test_eq_different_values():
    body1 = "Hello, World!"
    user1 = "user1"
    created1 = datetime.datetime.now()

    body2 = "Goodbye, World!"
    user2 = "user2"
    created2 = created1 + datetime.timedelta(minutes=1)

    reply1 = Reply(body1, user1, created1)
    reply2 = Reply(body2, user2, created2)

    assert reply1 != reply2


def test_eq_different_types():
    body = "Hello, World!"
    user = "user1"
    created = datetime.datetime.now()

    reply = Reply(body, user, created)
    non_reply = "Not a reply object"

    assert reply != non_reply

Testing a data store using pytest and fixtures

In order to showcase what "fixtures" are, let's add another class to our system:

from reply import Reply


class Thread:
    def __init__(self, title: str, user: str, replies: list[Reply] = None) -> None:
        self.title = title
        self.user = user
        self.replies = replies or []
    
    def __repr__(self) -> str:
        return f"<Thread '{self.title}' by '{self.user}'>"
    
    def reply(self, reply: Reply) -> None:
        if reply.created > self.replies[-1].created:
            raise ValueError("New reply is older than the last reply")
        self.replies.append(reply)

Here we've got a thread, with a title, the user who created the thread, and a list of replies.

It has one particularly interesting method, reply(), which takes in a Reply object and appends it to the replies list. But it only does so if the new reply is not older than the last reply in the thread. Or does it? I've introduced a bug in there to show you how easy it is to make a mistake here. Our testing will help us realise and fix the mistake!

Our first tests are fairly straightforward and introduce nothing new:

from thread import Thread
from reply import Reply

import datetime

def test_init():
    title = "Hello, World!"
    user = "user1"
    replies = [
        Reply("Hello, World!", "user1", datetime.datetime.now()),
        Reply("Goodbye, World!", "user2", datetime.datetime.now()),
    ]

    thread = Thread(title, user, replies)

    assert thread.title == title
    assert thread.user == user
    assert thread.replies == replies


def test_repr():
    title = "Hello, World!"
    user = "user1"
    replies = [
        Reply("Hello, World!", "user1", datetime.datetime.now()),
        Reply("Goodbye, World!", "user2", datetime.datetime.now()),
    ]

    thread = Thread(title, user, replies)

    assert repr(thread) == f"<Thread '{title}' by '{user}'>"

But now let's test the reply method:

def test_reply():
    title = "Hello, World!"
    user = "user1"
    replies = [
        Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 1, 0, 0, 0)),
        Reply("Goodbye, World!", "user2", datetime.datetime(2023, 1, 2, 0, 0, 0)),
    ]

    thread = Thread(title, user, replies)
    new_reply = Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 3, 0, 0, 0))

    thread.reply(new_reply)

    assert new_reply in thread.replies

If we run this (which by the way, you should be running your tests continuously, certainly after every new test, but preferably after every relevant code change)...

self = <Thread 'Hello, World!' by 'user1'>, reply = <Reply from 'user1' on '2023-01-03 00:00'>

    def reply(self, reply: Reply) -> None:
        if reply.created > self.replies[-1].created:
>           raise ValueError("New reply is older than the last reply")
E           ValueError: New reply is older than the last reply

simple_tests/thread.py:15: ValueError
===== short test summary info =====
FAILED simple_tests/test_thread.py::test_reply - ValueError: New reply is older than the last reply

How could this be? Our replies are correct:

• 2023-03-01
• 2023-03-02
• 2023-03-03

The first thing would be to check that the test is correct. But it seems it is, so maybe we've introduced a bug in the code!

After looking through it, you'll be able to see that we've got the > the wrong way round. It should be <:

if reply.created < self.replies[-1].created:

Changing that and re-running the tests shows us they pass. Excellent!

Now let's write a test that should fail:

def test_reply_more_recent():
    title = "Hello, World!"
    user = "user1"
    replies = [
        Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 1, 0, 0, 0)),
        Reply("Goodbye, World!", "user2", datetime.datetime(2023, 1, 2, 0, 0, 0)),
    ]

    thread = Thread(title, user, replies)
    new_reply = Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 1, 0, 0, 0))

    thread.reply(new_reply)

This one fails, so let's add pytest.raises(ValueError) at the end:

# At top of file
import pytest


def test_reply_more_recent():
    title = "Hello, World!"
    user = "user1"
    replies = [
        Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 1, 0, 0, 0)),
        Reply("Goodbye, World!", "user2", datetime.datetime(2023, 1, 2, 0, 0, 0)),
    ]

    thread = Thread(title, user, replies)
    new_reply = Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 1, 0, 0, 0))

    with pytest.raises(ValueError):
        thread.reply(new_reply)

Using fixtures with pytest

You may have noticed that all tests start the same way, defining the title, user, and replies of our thread. We can extract them to a variable (but it won't work):

import datetime

import pytest
from reply import Reply
from thread import Thread

title = "Hello, World!"
user = "user1"
replies = [
    Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 1, 0, 0, 0)),
    Reply("Goodbye, World!", "user2", datetime.datetime(2023, 1, 2, 0, 0, 0)),
]
thread = Thread(title, user, replies)


def test_init():
    assert thread.title == title
    assert thread.user == user
    assert thread.replies == replies


def test_repr():
    assert repr(thread) == f"<Thread '{title}' by '{user}'>"


def test_reply():
    new_reply = Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 3, 0, 0, 0))

    thread.reply(new_reply)

    assert new_reply in thread.replies


def test_reply_more_recent():
    new_reply = Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 1, 0, 0, 0))

    with pytest.raises(ValueError):
        thread.reply(new_reply)

Here the more experienced among you will notice that we've done something taboo! We've got a global variable, thread, and in our tests we're calling thread.reply(), which modifies the global variable.

This is a recipe for disaster because now the order in which our tests runs matters. You never want your tests to depend on each other.

Think about it, if test_reply runs before test_init, the latter will fail because the thread will have 3 replies in it instead of the expected 2.

So instead, we need to create a variable that is unique to each test. We can do that with a fixture:

@pytest.fixture(scope="function")
def thread():
    """This fixture returns a Thread object"""
    title = "Hello, World!"
    user = "user1"
    replies = [
        Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 1, 0, 0, 0)),
        Reply("Goodbye, World!", "user2", datetime.datetime(2023, 1, 2, 0, 0, 0)),
    ]
    return Thread(title, user, replies)

Now each test can gain access to this variable using dependency injection. This is just a fancy way to say: add thread as a parameter to the test, and Pytest will automatically call the thread() function and give the test its value when the test runs.

So let's modify our tests so they have a thread parameter (note I've not used this fixture in test_init):

import datetime

import pytest
from reply import Reply
from thread import Thread


@pytest.fixture
def thread():
    """This fixture returns a Thread object"""
    title = "Hello, World!"
    user = "user1"
    replies = [
        Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 1, 0, 0, 0)),
        Reply("Goodbye, World!", "user2", datetime.datetime(2023, 1, 2, 0, 0, 0)),
    ]
    return Thread(title, user, replies)


def test_init():
    title = "Hello, World!"
    user = "user1"
    replies = [
        Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 1, 0, 0, 0)),
        Reply("Goodbye, World!", "user2", datetime.datetime(2023, 1, 2, 0, 0, 0)),
    ]

    thread = Thread(title, user, replies)
    
    assert thread.title == "Hello, World!"
    assert thread.user == "user1"
    assert thread.replies == replies


def test_repr(thread):
    assert assert repr(thread) == "<Thread 'Hello, World!' by 'user1'>"


def test_reply(thread):
    new_reply = Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 3, 0, 0, 0))

    thread.reply(new_reply)

    assert new_reply in thread.replies


def test_reply_more_recent(thread):
    new_reply = Reply("Hello, World!", "user1", datetime.datetime(2023, 1, 1, 0, 0, 0))

    with pytest.raises(ValueError):
        thread.reply(new_reply)

So this helps us answer the question: "what are fixtures?"

Fixtures are functions that allow us to reuse data in our tests, and can be called once per test by Pytest.

Note that scope="function" can take other values! If you want the same fixture value to be reused in the entire file, you can say scope="module". If you want it to be reused in the entire test suite, you can use scope="session". There's also scope="class", but that only becomes relevant when you use an object-oriented approach to writing your tests, which is something I almost never do.

By default, fixtures can only be used in the file where they are defined. If you want to share a fixture between different test files, you can put the fixtures inside a file called conftest.py. Then the fixtures will be visible in any test file in the folder that contains conftest.py, or any sub-folder.

Setup and teardown in Pytest fixtures

Every fixture in Pytest can run some code before and after returning the value used in the tests.

Here's a non-useful example of how this works:

@pytest.fixture
def my_fixture():
    print("Hello, fixture!")
    yield 42
    print("Bye, fixture!")


def test_nothing(my_fixture):
    print("In the test!")
    print(f"Value from fixture: {my_fixture}")

Running this, you'll see this output is captured:

Hello, fixture!
In the test!
Value from fixture: 42
Bye, fixture!

Obviously, that example isn't very useful, but I'm sure you can see when it may be useful:

• If your tests need to interact with a file, you could use the setup and teardown functionality to open and close the file before and after giving it to your tests.
• If your tests use a database, you can use this to connect to the database and close the connection when you're done.

How to use multiple fixtures in a Pytest test

Using multiple fixtures is easy as pie! Just add multiple parameters to the tests, and Pytest will make sure the fixtures are called and the values passed:

def test_with_two_fixtures(fixture_one, fixture_two):
    pass

Tracing fixture execution and finding where fixtures are defined

When you execute the pytest command to run your tests, you can pass the --fixtures flag and it will show you all the fixtures that are available for your test functions to use. This includes fixtures Pytest provides, as well as your own:

cache -- .venv/lib/python3.11/site-packages/_pytest/cacheprovider.py:509
    Return a cache object that can persist state between testing sessions.

capsys -- .venv/lib/python3.11/site-packages/_pytest/capture.py:905
    Enable text capturing of writes to ``sys.stdout`` and ``sys.stderr``.

capsysbinary -- .venv/lib/python3.11/site-packages/_pytest/capture.py:933
    Enable bytes capturing of writes to ``sys.stdout`` and ``sys.stderr``.

... (there are a few)

----- fixtures defined from test_thread -----
thread -- simple_tests/test_thread.py:9
    This is a Thread object

If you want to see what fixtures each test used, you can use --fixtures-per-test:

$ pytest --fixtures-per-test -k test_thread
...
----- fixtures used by test_repr -----
----- (simple_tests/test_thread.py:36) -----
thread -- simple_tests/test_thread.py:9
    This fixture returns a Thread object

----- fixtures used by test_reply -----
----- (simple_tests/test_thread.py:40) -----
thread -- simple_tests/test_thread.py:9
    This fixture returns a Thread object

----- fixtures used by test_reply_more_recent -----
----- (simple_tests/test_thread.py:48) -----
thread -- simple_tests/test_thread.py:9
    This fixture returns a Thread object

Conclusion

In this beginner's guide to pytest, we've covered the basics of how to write tests using pytest, including assertions, fixtures, and selecting tests to run. We've also covered some advanced features like fixture scopes and sharing fixtures among multiple files using conftest.py.

Writing tests is an important part of software development, and pytest is a great tool for making testing in Python easy and effective. With the knowledge you've gained from this guide, you should be well on your way to writing better tests and building more reliable software!

If you want to learn more about Python generally, consider enrolling in our Complete Python Course! This comprehensive course teaches from the basics to the advanced, covering topics such as object-oriented programming, async development, GUI programming, and more.

For further reading, I strongly recommend the official documentation. Brian Okken has also written an excellent book:

• The official pytest documentation
• Python Testing with pytest by Brian Okken, an excellent book that covers everything you could want to know about Pytest

That's all for today! Thank you for joining me, I hope you've enjoyed the read, and I'll see you next time.

Let's quickly go over the fastest and cheapest way to deploy your Flask app and a MongoDB database on Render.com!

We will:

• Prepare the Flask app for deployment.
• Acquire a MongoDB database.
• Create a Render web service to host our app.
• Deploy!

Prepare your Flask app for deployment

To deploy any Flask app in Render.com you need to have two things clear:

• What dependencies does the app have?
• What Python version should the app use?

Once you know the answers to these questions, you can answer them:

• Write your app dependencies in the requirements.txt file, if you haven't already. Make sure to add gunicorn and pymongo[srv] as dependencies, as Render will use them to run your app and connect to MongoDB respectively.
• You'll select your Python version when you create the Render web service in step 3.

Acquire a MongoDB database

The fastest and cheapest way to acquire a MongoDB database is to use MongoDB Atlas, the official cloud database service from MongoDB. It's free for small databases!

Go to https://www.mongodb.com/atlas/database and sign up. Then you can create a free Cluster for your Flask app.

After creating a database you'll need to configure two security settings: Database Access and Network Access.

Under Database Access, create a user with a password. Make sure to use a secure password for this! For the user's Role, you can select "Read and write to any database".

Then go to Network Access, click on the "Add IP Address" button, and then click on "Add Current IP Address".

By doing this, only your computer will be able to access the database. When you create your Render service, you'll get another IP address to add to this list.

That's all the configuration you need for MongoDB! Now you can go back to the "Database" menu and click on "Connect", and then "Connect your application". Find the Python version you use, and copy the connection string. This is your MONGODB_URI, but remember to replace <password> with the secure password for the user you generated in the "Database Access" step.

Create a Render web service for your Flask app

To deploy to Render, you'll need to put your app in GitHub. Create a GitHub account and a new GitHub repository. It can be public or private.

If you're unfamiliar with Git, you can add your project files to GitHub using the UI:

Once you're files are in the GitHub repository, you can go over to Render.com.

To create a Render web service you'll need to make an account, and then click on New -> Web Service at the top right.

If you haven't already at this point, you'll need to link your GitHub account with Render. After doing so, you'll see the list of GitHub repositories in Render. Click "Connect" on your repository, and that will allow Render to download your code from GitHub.

Now comes the settings for Render. For a Flask app, they should almost always look like this (long image warning, right click and open in new tab to zoom in):

Here's what's going on in that image:

• You can name your service whatever you want.
• For a Region, choose something close to you and your users.
• Your branch name should match the branch name selected in GitHub.
• The build step installs your dependencies. Since we're using requirements.txt, this should be pip install -r requirements.txt.
• The start command actually runs your application. Here we use gunicorn "app:create_app()" because we assume you are using the Flask app factory pattern. If you aren't, you can use gunicorn app:app instead.
• We select a free server. There are a few limitations to free servers, but they're good to try out the deployment.
• In the environment variables section, we add PYTHON_VERSION to tell Render which Python version to use, and MONGODB_URI to store the connection string to MongoDB which your Flask app uses.

When you hit "Create Web Service", it should start deploying! It can take a few minutes though, so get a tea going and check back in 5!

Concurrency in Render with gunicorn

Once your app is deployed to Render.com, it has access to a certain amount of processing power in the Render server.

If the Flask application doesn't require all that power, you can run multiple copies of the Flask app together, in the same Render service.

That way you can save quite a bit of money (if you were not using the free option), and improve performance of you app.

And it's really easy! All you have to do is:

Go to the Environment tab in your Render.com service, and create a new environment variable called WEB_CONCURRENCY. You can set this to how many copies of your Flask app you want to run. I'd set it to 3 to start with.

Keep an eye on your Metrics, as you don't want the Memory to get close to your limit. You can see your limit in the Settings tab. The free option's memory is 256MB.

That's everything for this blog post. I wanted to show you how to get going with MongoDB and Flask in Render, but we also have another blog post on deploying Flask and PostgreSQL.

If you want to learn more about web development and Flask, consider enrolling in our Web Developer Bootcamp with Flask and Python course! It's a long video-course that covers HTML, CSS, Flask, MongoDB, deployments, and more. You'll get it at its best possible price by going through our link.

Thanks for reading, and I'll see you next time!

There are two things we may want to customise when we use Flask-Security-Too: pages and emails. For example, the login page or the account confirmation email. Let's take a look at how to do it.

This is the final article in this series of blog posts, where I show you how to work with Flask-Security-Too:

1. User authentication in Flask with Flask-Security-Too
2. User email confirmations with Flask-Security-Too
3. Customising templates and emails of Flask-Security-Too (this article)

All the page and email templates in Flask-Security-Too are written using HTML and Jinja, and you can find them all inside your virtual environment's folder, and then inside lib/python3/site-packages/flask_security/templates/security.

In this article, we will customise three templates:

• login_user.html
• _macros.html
• register_user.html

Doing this will help you learn how to customise any template, so you can do the same for others that you wish to modify.

Customising the login template

Begin by opening the login_user.html default template and copying its contents.

Then, inside your Flask app's templates folder, create a security folder. Inside there, create login_user.html, and paste the contents you copied from the default template.

Just by doing this, your Flask app will use your template instead of the default. For now, they have the same content! Let's look at how to change the content.

When I wrote this article, this was the content of login_user.html:

{% extends "security/base.html" %}
{% from "security/_macros.html" import render_field_with_errors, render_field, render_field_errors, render_form_errors %}

{% block content %}
{% include "security/_messages.html" %}
<h1>{{ _fsdomain('Login') }}</h1>
  <form action="{{ url_for_security('login') }}" method="POST" name="login_user_form">
    {{ login_user_form.hidden_tag() }}
    {{ render_form_errors(login_user_form) }}
    {% if "email" in identity_attributes %}
      {{ render_field_with_errors(login_user_form.email) }}
    {% endif %}
    {% if login_user_form.username and "username" in identity_attributes %}
      {% if "email" in identity_attributes %}
        <h3>{{ _fsdomain("or") }}</h3>
      {% endif %}
      {{ render_field_with_errors(login_user_form.username) }}
    {% endif %}
    <div class="fs-gap">
      {{ render_field_with_errors(login_user_form.password) }}</div>
    {{ render_field_with_errors(login_user_form.remember) }}
    {{ render_field_errors(login_user_form.csrf_token) }}
    {{ render_field(login_user_form.submit) }}
  </form>
  {% if security.webauthn %}
    <hr class="fs-gap">
    <h2>{{ _fsdomain("Use WebAuthn to Sign In") }}</h2>
    <div>
      <form method="GET" id="wan-signin-form" name="wan_signin_form">
        <input id="wan_signin" name="wan_signin" type="submit" value="{{ _fsdomain('Sign in with WebAuthn') }}"
          formaction="{{ url_for_security("wan_signin") }}">
      </form>
    </div>
  {% endif %}
{% include "security/_menu.html" %}
{% endblock %}

As you can see, there isn't much actual HTML in here. Mostly it's importing other files and using some pre-defined macros. If we want to change the style of the page, we would need to replace everything:

• The security/_messages.html file.
• The macros for rendering fields.
• The security/_menu.html file.

Lately, I've been using TailwindCSS for all my CSS, so if you're using that, here are two templates you can use.

{% block content %}
<div class="flex flex-col min-h-full items-center justify-center py-12 px-4 sm:px-6 lg:px-8">
  <div class="w-full max-w-md space-y-8">
    {% set messages = get_flashed_messages() %}
    {% if messages %}
      <div class="w-full my-6">
        {% for category, message in get_flashed_messages(with_categories=true) %}
          <p>{{ message }}</p>
        {% endfor %}
      </div>
    {% endif %}
    <div>
      <h2 class="mt-6 text-center text-3xl font-bold tracking-tight text-gray-900">Sign in to your account</h2>
      <p class="mt-2 text-center text-sm text-gray-600">
        Or
        <a href="{{ url_for_security('register') }}" class="font-medium text-indigo-600 hover:text-indigo-500">sign up instead?</a>
      </p>
    </div>
    <form action="{{ url_for_security('login') }}" method="POST" class="mt-8 space-y-6">
      {{ login_user_form.hidden_tag() }}
      {{ render_signup_login_field_w_errors(login_user_form.email, placeholder="Email", autocomplete="email") }}
      {{ render_signup_login_field_w_errors(login_user_form.password, placeholder="Password", autocomplete="current-password") }}
      {{ render_checkbox_with_errors(login_user_form.remember) }}
    
      <div>
        <button
          type="submit"
          class="w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500"
        >
          Sign in
        </button>
      </div>
    </form>
  </div>
</div>
{% endblock %}

And in security/_macros.html:

{% macro render_checkbox_with_errors(field) %}
  <div class="relative flex items-start">
    <div class="flex items-center h-5">
    {{ field(class_="focus:ring-indigo-500 h-4 w-4 text-indigo-600 border-gray-300 rounded", **kwargs)|safe }}
    </div>
    <div class="ml-3 text-sm">
    {{ field.label(class_="text-gray-700") }}</div>
    {% if field.errors %}
      <ul>
      {% for error in field.errors %}
        <li>{{ error }}</li>
      {% endfor %}
      </ul>
    {% endif %}
  </div>
{% endmacro %}

{% macro render_signup_login_field_w_errors(field, class_) %}
  <p class="{{ class_ }}">
    {{ field.label(class_="sr-only") }} {{ field(class_="relative block w-full appearance-none rounded-md border border-gray-300 px-3 py-2 text-gray-900 placeholder-gray-500 focus:z-10 focus:border-indigo-500 focus:outline-none focus:ring-indigo-500 sm:text-sm", **kwargs)|safe }}
    {% if field.errors %}
      <ul>
      {% for error in field.errors %}
        <li>{{ error }}</li>
      {% endfor %}
      </ul>
    {% endif %}
  </p>
{% endmacro %}

Then in security/register_user.html:

{% extends "security/base.html" %}
{% from "security/_macros.html" import render_signup_login_field_w_errors %}

{% block content %}
<div class="flex min-h-full items-center justify-center py-12 px-4 sm:px-6 lg:px-8">
  <div class="w-full max-w-md space-y-8">
    <div>
      <h2 class="mt-6 text-center text-3xl font-bold tracking-tight text-gray-900">Create your account</h2>
      <p class="mt-2 text-center text-sm text-gray-600">
        Or
        <a href="{{ url_for_security('login') }}" class="font-medium text-indigo-600 hover:text-indigo-500">log in instead?</a>
      </p>
    </div>
    <form action="{{ url_for_security('register') }}" method="POST" class="mt-8 space-y-6">
      {{ register_user_form.hidden_tag() }}
      {{ render_signup_login_field_w_errors(register_user_form.full_name, placeholder="Full name", autocomplete="name") }}
      {{ render_signup_login_field_w_errors(register_user_form.email, placeholder="Email", autocomplete="email") }}
      {% if security.username_enable %}
      {{ render_signup_login_field_w_errors(register_user_form.username, placeholder="Full name", autocomplete="name") }}
      {% endif %}
      {{ render_signup_login_field_w_errors(register_user_form.password, placeholder="Password", autocomplete="current-password") }}
      {% if register_user_form.password_confirm %}
      {{ render_signup_login_field_w_errors(register_user_form.password_confirm, placeholder="Confirm password") }}
      {% endif %}

    
      <div>
        <button
          type="submit"
          class="w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500"
        >
          Create your account
        </button>
        <p class="mt-3 text-center text-sm text-slate-700">By creating an account, you agree to our <a class="font-semibold" href="{{ url_for('resource_page', page_slug='terms-of-service') }}">Terms of Service</a> and <a class="font-semibold" href="{{ url_for('resource_page', page_slug='privacy-policy') }}">Privacy Policy</a>.</p>
      </div>
    </form>
  </div>
</div>
{% endblock %}

Customising templates by linking a stylesheet

If you wanted to add a CSS stylesheet instead of changing the template, that would be much easier. You'd copy and paste the original file contents, and link the CSS stylesheet like so:

{% extends "security/base.html" %}
{% from "security/_macros.html" import render_field_with_errors, render_field, render_field_errors, render_form_errors %}

{% block styles %}
<link rel="stylesheet" href="{{ url_for('static', filename='css/auth.css) }}">
{% endblock %}

{% block content %}
{% include "security/_messages.html" %}
<h1>{{ _fsdomain('Login') }}</h1>
  <form action="{{ url_for_security('login') }}" method="POST" name="login_user_form">
    {{ login_user_form.hidden_tag() }}
    {{ render_form_errors(login_user_form) }}
    {% if "email" in identity_attributes %}
      {{ render_field_with_errors(login_user_form.email) }}
    {% endif %}
    {% if login_user_form.username and "username" in identity_attributes %}
      {% if "email" in identity_attributes %}
        <h3>{{ _fsdomain("or") }}</h3>
      {% endif %}
      {{ render_field_with_errors(login_user_form.username) }}
    {% endif %}
    <div class="fs-gap">
      {{ render_field_with_errors(login_user_form.password) }}</div>
    {{ render_field_with_errors(login_user_form.remember) }}
    {{ render_field_errors(login_user_form.csrf_token) }}
    {{ render_field(login_user_form.submit) }}
  </form>
  {% if security.webauthn %}
    <hr class="fs-gap">
    <h2>{{ _fsdomain("Use WebAuthn to Sign In") }}</h2>
    <div>
      <form method="GET" id="wan-signin-form" name="wan_signin_form">
        <input id="wan_signin" name="wan_signin" type="submit" value="{{ _fsdomain('Sign in with WebAuthn') }}"
          formaction="{{ url_for_security("wan_signin") }}">
      </form>
    </div>
  {% endif %}
{% include "security/_menu.html" %}
{% endblock %}

The only thing that was added to the original content in the code above is this under the imports. This assumes that the CSS file name is under static/css/auth.css:

{% block styles %}
<link rel="stylesheet" href="{{ url_for('static', filename='css/auth.css) }}">
{% endblock %}

Remember that this original template extends the security/base.html template, so you can look at that one to see what different block elements are available.

Customising the confirmation email template

Next up, I like changing the look of the email confirmation template. The default template is basic, with just text. You can find it inside the templates/email/welcome.html file inside the flask_security folder in your virtual environment.

You'll also be able to find welcome.txt, which is a text representation of the email content. This will be used in those email clients that don't support HTML rendering (or have it disabled).

Create a templates/email/welcome.html file.

This is what my template looks like:

{# This template receives the following context:
  confirmation_link - the link that should be fetched (GET) to confirm
  confirmation_token - this token is part of confirmation link - but can be used to
    construct arbitrary URLs for redirecting.
  user - the entire user model object
  security - the Flask-Security configuration
#}
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" style="font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;">
<head>
<meta name="viewport" content="width=device-width" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Confirm your email</title>


<style type="text/css">
img {
max-width: 100%;
}
body {
-webkit-font-smoothing: antialiased; -webkit-text-size-adjust: none; width: 100% !important; height: 100%; line-height: 1.6em;
}
body {
background-color: #f6f6f6;
}
@media only screen and (max-width: 640px) {
  body {
    padding: 0 !important;
  }
  h1 {
    font-weight: 800 !important; margin: 20px 0 5px !important;
  }
  h2 {
    font-weight: 800 !important; margin: 20px 0 5px !important;
  }
  h3 {
    font-weight: 800 !important; margin: 20px 0 5px !important;
  }
  h4 {
    font-weight: 800 !important; margin: 20px 0 5px !important;
  }
  h1 {
    font-size: 22px !important;
  }
  h2 {
    font-size: 18px !important;
  }
  h3 {
    font-size: 16px !important;
  }
  .container {
    padding: 0 !important; width: 100% !important;
  }
  .content {
    padding: 0 !important;
  }
  .content-wrap {
    padding: 10px !important;
  }
  .invoice {
    width: 100% !important;
  }
}
</style>
</head>

<body itemscope itemtype="http://schema.org/EmailMessage" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; -webkit-font-smoothing: antialiased; -webkit-text-size-adjust: none; width: 100% !important; height: 100%; line-height: 1.6em; background-color: #f6f6f6; margin: 0;" bgcolor="#f6f6f6">

<table class="body-wrap" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; width: 100%; background-color: #f6f6f6; margin: 0;" bgcolor="#f6f6f6"><tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;"><td style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0;" valign="top"></td>
        <td class="container" width="600" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; display: block !important; max-width: 600px !important; clear: both !important; margin: 0 auto;" valign="top">
            <div class="content" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; max-width: 600px; display: block; margin: 0 auto; padding: 20px;">
                <table class="main" width="100%" cellpadding="0" cellspacing="0" itemprop="action" itemscope itemtype="http://schema.org/ConfirmAction" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; border-radius: 3px; background-color: #fff; margin: 0; border: 1px solid #e9e9e9;" bgcolor="#fff"><tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;"><td class="content-wrap" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0; padding: 20px;" valign="top">
                            <meta itemprop="name" content="Confirm Email" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;" /><table width="100%" cellpadding="0" cellspacing="0" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;"><tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;"><td class="content-block" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0; padding: 0 0 20px;" valign="top">
                                        Hey, {{user.username}}! {{ _fsdomain('Please confirm your email through the link below:') }}
                                    </td>
                                </tr><tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;"><td class="content-block" itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0; padding: 0 0 20px;" valign="top">
                                        <a href="{{ confirmation_link }}" class="btn-primary" itemprop="url" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; color: #FFF; text-decoration: none; line-height: 2em; font-weight: bold; text-align: center; cursor: pointer; display: inline-block; border-radius: 5px; text-transform: capitalize; background-color: #4F46E5; margin: 0; border-color: #4F46E5; border-style: solid; border-width: 6px 20px;">{{ _fsdomain('Confirm my account') }}</a>
                                    </td>
                                </tr><tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;"><td class="content-block" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0; padding: 0 0 20px;" valign="top">
                                        If clicking the button doesn't work, please copy this link and paste it into your browser's address bar:
                                    </td>
                                </tr><tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;"><td class="content-block" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0; padding: 0 0 20px; max-width: 20em;" valign="top">
                                        <a href="{{ confirmation_link }}">{{ confirmation_link }}</a>
                                    </td>
                                </tr>
                                <tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;"><td class="content-block" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0; padding: 0 0 20px;" valign="top">
                                        &mdash; Jose and the Teclado team
                                    </td>
                                </tr></table></td>
                    </tr></table><div class="footer" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; width: 100%; clear: both; color: #999; margin: 0; padding: 20px;">
                    <table width="100%" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;"><tr style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; margin: 0;"><td class="aligncenter content-block" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 12px; vertical-align: top; color: #999; text-align: center; margin: 0; padding: 0 0 20px;" align="center" valign="top">Follow <a href="http://twitter.com/tecladocode" style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 12px; color: #999; text-decoration: underline; margin: 0;">@tecladocode</a> on Twitter.</td>
                        </tr></table></div></div>
        </td>
        <td style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0;" valign="top"></td>
    </tr></table></body>
</html>

As you can see, it's long and rather confusing! That's because writing emails using HTML is really difficult. There are so many email clients, and they don't all support the same CSS.

My email is taken from Mailgun's official templates that you can see here, and I've adapted it to my needs. Mailgun has a nice writeup on HTML emails that you can read here.

Alright, that's everything for now! Thank you very much for reading, and I hope this series of articles has been useful. If you'd like to learn more about web development using Flask, consider enrolling in our Web Developer Bootcamp with Flask and Python! It's a complete video course that covers building multiple web apps and deploying them, all using Flask.

See you next time!

To prevent bot signups and reduce spam, you can require that users click a link in an email they receive when they register to your web apps. Flask-Security-Too can take care of this with some configuration.

This is article 2 of 3 in this series covering Flask-Security-Too:

1. User authentication in Flask with Flask-Security-Too
2. User email confirmations with Flask-Security-Too (this article)
3. Customising templates and emails of Flask-Security-Too

Let's get started!

The tricky bit about user confirmation is the email delivery. To actually send emails and have them reach the user's inbox (and not end up in spam), you need a few things: a domain name, an email delivery service, and proper configuration. We talk about this in depth in our REST APIs with Flask and Python course, and you can read that section of the course e-book here.

I like the email delivery service Mailgun. Create an account with them, and you'll be given a sandbox domain. You can use this domain to send emails to "authorised recipients". You can add yourself as an authorised recipient, so you can test out the email confirmation functionality of Flask-Security-Too. A step-by-step guide on how to do this is here. Read the "Setting up for Mailgun" section before continuing!

In the future, if you want to purchase a domain, you can use it to send emails with Mailgun (though that isn't free).

Now that you've got your Mailgun account, let's get the SMTP details. You can do this by clicking the "Select" button under "SMTP":

Let's add these to our .env file:

DATABASE_URL="sqlite:///data.db"
MAIL_SERVER=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=

Now we can tell Flask-Security-Too to use email confirmation with one configuration setting:

app.config["SECURITY_CONFIRMABLE"] = True

Doing this makes it so user accounts aren't valid until they are marked as confirmed (this is a column in our UserModel class, which you can see in models/auth.py). User accounts will be confirmed when the user clicks a link in an email they receive after registration.

Next, we'll configure the Flask-Mailman library, which Flask-Security-Too uses to send emails. In app.py:

# At top of file
from flask_mailman import Mail

# After 'Create app'
app.config["MAIL_SERVER"] = os.getenv("MAIL_SERVER")
app.config["MAIL_PORT"] = os.getenv("MAIL_PORT")
app.config["MAIL_USE_SSL"] = False
app.config["MAIL_USE_TLS"] = True
app.config["MAIL_USERNAME"] = os.getenv("MAIL_USERNAME")
app.config["MAIL_PASSWORD"] = os.getenv("MAIL_PASSWORD")
mail = Mail(app)

Note that the MAIL_USE_SSL and MAIL_USE_TLS values will depend on which provider you use. Mailgun uses TLS, so that's why we set SSL to False and TLS to True.

Now, when you register an account, you'll get a confirmation email with a link you must click. If you don't click the link, the account will not count as valid.

We can test this out by creating a protected endpoint (one that requires login). We can then register but not click the email link, and see if we can access it.

To create a protected endpoint, we use the @login_required decorator:

# At top of file
from flask_security import login_required

# At bottom of file
@app.route("/protected")
@login_required
def protected():
    return "You're logged in!"

Now let's try it out. Delete your data.db file and re-create it using flask shell:

>>> from app import app, db
>>> with app.app_context():
	 	db.create_all()

Then start the app with flask run and fill in your registration form. It's interesting to note that when we enable email confirmation, Flask-Security-Too automatically disables password confirmation in the signup form. Now there's just one password field instead of two:

Fill this in, making sure to use the email address that you used in your "authorised recipients" for Mailgun.

Then you should get an email (which might be in your Spam folder since we're using the Mailgun sandbox domain):

Don't click the link yet. Instead, navigate to the /protected endpoint with your browser: http://127.0.0.1:5000/protected. You should get redirected to the login page and you should see an error:

These errors use Flask's flashed messages, and you can see there are two messages:

• Thank you. Confirmation instructions have been sent to (my email).
• Please log in to access this page.

They both look like errors, but the first one is just a message that Flask-Security-Too flashes when registration is successful. Flashed messages must be displayed once, and since there was no place for it to be shown until now, it stuck around. Ideally, you would use message flashing in the page that you redirect the user to after registration to show this message.

The second message is the error we were expecting!

Now click the confirmation link in your email, and try again. It should work!

This is how you can use Flask-Security-Too to easily add use registration and confirmation to your Flask applications. Naturally, you'd want to style the login, register, and confirmation pages to match the rest of your application. We'll look at that in part 3 of this series.

Thank you for reading! If you'd like to learn more about web development using Flask, consider enrolling in our Web Developer Bootcamp with Flask and Python! It's a complete video course that covers building multiple web apps and deploying them, all using Flask.

Query string arguments are values added at the end of the URL which follow the format of name1=value1&name2=value2. You can separate multiple values with an ampersand (as shown). The query string arguments are separated from the main part of the URL by a question mark.

So a complete URL with query string arguments might look like this:

http://your-api.com/item/?tag=furniture

To get multiple values, you'd include two or more of the same query string argument:

http://your-api.com/item/?tag=furniture&tag=office

In my REST APIs with Flask and Python course, we build REST APIs using the Flask-Smorest library. In this blog post, let me show you how to use query string arguments together with Flask-Smorest.

If you'd rather watch a video instead, check it out here:

How to access query string values in a Flask endpoint

Accessing the query string values in a Flask endpoint is relatively straightforward:

• Import the request proxy from flask
• Query string arguments are stored in a dict-like value under request.args.

Here's a sample endpoint that returns all the stores in your database.

@app.route("/store")
def get_stores():
    return [{"name": store.name, "id": store.id} for store in StoreModel.query.all()]

Now let's say you want to add a query string argument value to filter stores by name. Our API users will send us name=Tec, and the API should respond with stores whose name starts with Tec.

To get the query string argument value, we use request.args.get("name"):

# at top of file
from flask import app, request


# in endpoint
@app.route("/store")
def get_stores():
    name = request.args.get("name")
    return [{"name": store.name, "id": store.id} for store in StoreModel.query.all()]

Then we can add a filter to .query before calling .all():

# at top of file
from flask import request


# in endpoint
@app.route("/store")
def get_stores():
    name = request.args.get("name")
    return [
        {"name": store.name, "id": store.id}
        for store in StoreModel.query.filter(StoreModel.name.startswith(name)).all()
    ]

As an aside, if instead of .startswith you wanted to search for the given value anywhere in the store name, you could use this:

StoreModel.query.filter(StoreModel.name.like(f"%{name}%")).all()

Accessing a list of values in a query string argument

First, ensure the user is sending the query string like so:

?tags=furniture&tags=office

Then in Flask, access the values like so:

request.args.getlist("tags")  # ["furniture", "office"]

If you use request.args.get("tags"), then only the first tag value will be returned.

Alternatively, you could (but I don't recommend it), do this to work with comma-separated values:

request.args.get("tags").split(",")

The issue I can foresee with this is potentially if a value is received that contains a comma, you'd run into trouble. This probably wouldn't happen with tags, but it might happen with other values. You're better off using the recommended approach, which is getting multiple query string arguments and use .getlist().

How to access query string arguments in a Flask-Smorest Resource

Here's a sample Resource class that returns all the stores in your database. This is similar to the endpoint we showed earlier.

@blp.route("/store")
class StoreList(MethodView):
    @blp.response(200, StoreSchema(many=True))
    def get(self):
        return StoreModel.query.all()

Now you want to add the same query string argument as earlier, to filter the stores by name. You could simply do it as in vanilla Flask, by importing request and then using request.args.get().

But one of the key benefits of Flask-Smorest is the documentation and validation, so let's try to do better than that.

First we'll define a schema for our query string arguments:

class StoreSearchQueryArgs(BaseSchema):
    name: str | None

Then we decorate the get method with a @blp.arguments() decorator, making sure to pass location="query", like so:

@blp.route("/store")
class StoreList(MethodView):
    @blp.arguments(StoreSearchQueryArgs, location="query")
    @blp.response(200, StoreSchema(many=True))
    def get(self, search_values):
        return StoreModel.query.all()

Then we can add the filter to .query before calling .all():

@blp.route("/store")
class StoreList(MethodView):
    @blp.arguments(StoreSearchQueryArgs, location="query")
    @blp.response(200, StoreSchema(many=True))
    def get(self, search_values):
        return StoreModel.query.filter(StoreModel.name.startswith(search_values.get("name", ""))).all()

For a complete Flask-Smorest application that you can see in action, check out this Gist.

Alright, that's everything for this blog post! I just wanted to show you how to work with query string parameters in Flask, focusing on REST APIs with Flask-Smorest.

If you want to learn more about REST API development with Flask, consider looking at our course: REST APIs with Flask and Python. It's a complete video-course that covers everything you need, from the basics to working with databases, deployments, background tasks, and much more!

Adding user authentication to a web application makes it able to tell which user is making a request. It can then return different responses to different users. This is called "personalisation".

This is article 1 of 3 in this series of blog posts, where I'll show you how to work with Flask-Security-Too:

1. User authentication in Flask with Flask-Security-Too (this article)
2. User email confirmations with Flask-Security-Too
3. Customising templates and emails of Flask-Security-Too

To help you understand user authentication, it's useful to remind ourselves of the separation between client and server. If you're developing a Flask application, then you're developing the server. Your clients are browsers or mobile apps making the requests to your application.

For this series, let's assume you are developing a Flask application that uses render_template to send HTML to your browser clients.

Before learning about Flask-Security-Too, it's probably going to be helpful to learn how to code your own user authentication manually. It's not terribly difficult, and will really aid in understanding how Flask-Security-Too works. We've got two blog posts that I recommend reading in order:

• How to add user logins to your Flask website
• Protecting endpoints in Flask apps by requiring login

Read those two and work through the examples provided. When you're done, you should have a Flask app that supports user signup and login. That's what we can replace most of our custom logic with Flask-Security-Too!

Add user registration and authentication using Flask-Security-Too

This is the bread and butter of Flask-Security-Too! Here's what you need:

• A database to store user data (username, password, that kind of thing).
• A few configuration options in your Flask app (secret key and password hashing salt).
• To actually initialise Flask-Security-too when you create your Flask object.

For our database interactions, I will use SQLAlchemy. We don't have any introductory blog posts on using SQLAlchemy, but our free REST APIs e-book does cover it in detail.

In any case, SQLAlchemy is relatively straightforward: you define a Python class which represents a table in your database. When you create new objects of said class, they can be inserted into the database as separate rows. You can also retrieve data from the database in the form of Python objects.

The aim of SQLAlchemy is to simplify working with data using Python by referring to everything as Python objects, rather than writing SQL yourself.

To work with SQLAlchemy using Flask apps, it's common to use the flask-sqlalchemy library.

Let's begin by installing it and flask-security-too. I'll add this to my requirements.txt file:

flask
flask-sqlalchemy
flask-security-too
flask-mailman
bcrypt
python-dotenv

The python-dotenv library is added to make it easier to load .env files when running our Flask app. More on that shortly! The flask-mailman library is used for sending confirmation emails (in part 2 of this series). The bcrypt library is used for password hashing.

Install the libraries:

pip install -r requirements.txt

Now let's create the SQLAlchemy object, which we will use to connect to the database. Inside database.py, write the following:

from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()

Next up, let's create our database models. These are the Python classes which represent tables in our database.

Inside a models folder, create auth.py and write the following:

from database import db
from flask_security import UserMixin, RoleMixin
from sqlalchemy import Boolean, DateTime, Column, Integer, String, ForeignKey
from sqlalchemy.orm import relationship, backref

class RolesUsers(db.Model):
    __tablename__ = "roles_users"
    id = Column(Integer(), primary_key=True)
    user_id = Column("user_id", Integer(), ForeignKey("user.id"))
    role_id = Column("role_id", Integer(), ForeignKey("role.id"))


class Role(db.Model, RoleMixin):
    __tablename__ = "role"
    id = Column(Integer(), primary_key=True)
    name = Column(String(80), unique=True)
    description = Column(String(255))


class User(db.Model, UserMixin):
    __tablename__ = "user"
    id = Column(Integer(), primary_key=True)
    email = Column(String(255), unique=True)
    username = Column(String(255), unique=True, nullable=True)
    password = Column(String(255), nullable=False)
    last_login_at = Column(DateTime())
    current_login_at = Column(DateTime())
    last_login_ip = Column(String(100))
    current_login_ip = Column(String(100))
    login_count = Column(Integer)
    active = Column(Boolean())
    premium = Column(Boolean())
    fs_uniquifier = Column(String(255), unique=True, nullable=False)
    confirmed_at = Column(DateTime())
    roles = relationship(
        "Role", secondary="roles_users", backref=backref("users", lazy="dynamic")
    )

As you can see, this defines three tables: one for users, one for roles (similar to permissions), and one for linking users and roles. We won't be using roles in this tutorial, but Flask-Security-Too requires it.

Finally, in app.py let's create our Flask app and set up Flask-Security-Too:

import os
from flask import Flask
from flask_security import SQLAlchemySessionUserDatastore, Security
from dotenv import load_dotenv
from database import db
from models.auth import User, Role

load_dotenv()

app = Flask(__name__)

app.config["SECRET_KEY"] = os.environ.get(
    "SECRET_KEY", "0aedgaii451cef0af8bd6432ec4b317c8999a9f8g77f5f3cb49fb9a8acds51d"
)
app.config["SECURITY_PASSWORD_SALT"] = os.environ.get(
    "SECURITY_PASSWORD_SALT",
    "ab3d3a0f6984c4f5hkao41509b097a7bd498e903f3c9b2eea667h16",
)
app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
app.config["SECURITY_REGISTERABLE"] = True

uri = os.getenv("DATABASE_URL")
app.config["SQLALCHEMY_DATABASE_URI"] = uri
db.init_app(app)
user_datastore = SQLAlchemySessionUserDatastore(db.session, User, Role)
security = Security(app, user_datastore)

@app.route("/")
def home():
	return "Hello, world!"

Now that we've got this, we need to set up our environment variables. At the very least, we need the DATABASE_URL, to tell our Flask app which database to connect to.

In a new file called .env, write this:

DATABASE_URL="sqlite:///data.db"

Now let's create our tables. In the console (having your virtual environment activated), type:

flask shell

And there, type:

>>> from app import app, db
>>> with app.app_context():
	 	db.create_all()

This will create your database using the app configuration, which should create an instance folder, and data.db inside it. If later on you delete instance/data.db, just re-run flask shell and type those commands in to re-create it.

Now you can run your Flask app! First exit the shell (by pressing CTRL+D) and then type:

flask run

Now you can access the login and signup pages that Flask-Security-Too has added to your Flask app for you. For example, going to http://127.0.0.1:5000/login should show you something like this:

If you use the menu in that page to go to the "Register" page (or navigate manually to http://127.0.0.1:5000/register) then you'll see a very similar form, which adds a password confirmation field.

These pages already include error handling and cookie support for the "Remember Me" checkbox.

However, they don't look very good. To fix that, you can either add some CSS code to target the existing elements, or you can code your own login and register pages. We won't talk about that in this blog post, but leave a comment at the end if it's something you'd like me to write about!

Now that we've added user authentication, we can move on to email confirmation in the next article of this series. Thank you for reading, and I'll see you there!

If you'd like to learn more about web development using Flask, consider enrolling in our Web Developer Bootcamp with Flask and Python! It's a complete video course that covers building multiple web apps and deploying them, all using Flask.

Ever since I made my course on REST APIs with Flask and Python, students have been asking for a FastAPI course.

After months of work, it's here! 🎉 We've just published our FastAPI for Beginners course!

This course helps you learn the ropes of FastAPI so you can create REST APIs using this modern framework. Plus it teaches:

• How to set up a FastAPI project.
• How to work with async databases using the encode/databases package.
• How to perform user authentication with JWTs using FastAPI.
• How to write pydantic models for different use cases.

In the course, you build a REST API project using FastAPI so it's all based on examples.

And did I mention that, at least for now, the course is free?

Click the button above to join the course, or use this link: https://teclado.com/fastapi-for-beginners

I hope you'll enjoy the course. I'll see you on the inside!

As a Python developer, I install new Python versions when they come out. We get new features and performance improvements, but we don't always want to use the latest version for everything. Some projects use older Python versions, and other projects must use a specific Python version.

If you need to install multiple Python versions, going the ol' installer route isn't the best idea. You end up with multiple Python executables in your PATH, such as python, python2, python3, python3.7, and so on. Also it becomes really tricky to distinguish minor versions, such as python3.10.3 from python3.10.4.

So, pyenv to the rescue! This command-line tool will handle installing and running specific Python versions!

Their README file actually explains how it works and how to install it really well. Give it a read!

As a note, for Windows I've often use the pyenv-win project, which has worked well for me.

To install pyenv on MacOS, I've just gone for Homebrew:

brew update
brew install pyenv

After installing you'll have to add a few things to your shell, to configure it. Detailed instructions are in the README.

How I actually use pyenv

The great thing about pyenv for me is that it just works, and I only use it at the very beginning of a project, to create a virtual environment.

Once I've created a virtual environment using a specific Python version (which I get from pyenv), from then on I just activate the virtual environment to get that version, and I don't have to faff around with pyenv any more.

So, how do you do this?

First, see if the version of Python you want is available (you may have to update pyenv to see recent versions, which I do with brew update && brew upgrade pyenv):

pyenv install --list

This will show you a long output, which may contain things like the following:

...
3.10.1
3.10.2
3.10.3
3.10.4
3.10.5
3.10.6
3.10.7
3.11.0rc2
3.11-dev
3.12-dev
...

So now you know, you can install from these versions (and again, reminder to update to see the most recently-added versions).

To install a Python version:

pyenv install 3.10.7

Selecting a Python version

You can see the currently-selected Python version with this command:

pyenv version

And you can see all versions (including the currently selected one) with:

pyenv versions

You can have a globally selected Python version, and then locally selected Python versions. The global version is used if no local version is selected.

You can select a local version with:

pyenv local 3.10.7

This creates a .python-version file in your current folder, which tells pyenv to use that Python version.

If you want to change the global Python version:

pyenv global 3.10.7

Using the selected Python version

Now, let's create a virtual environment using pyenv:

pyenv exec python -m venv .venv

This uses pyenv exec to run the python command, which will use Python 3.10.7 in our case. The -m venv .venv argument passed to python tells it to run the venv module, and gives it the name of .venv.

This will create a virtual environment in a folder called .venv.

And to be honest, this is how I use pyenv. That's it, nothing more!

If you want to test your applications in multiple Python versions, you can also do so easily. Real Python has a great in-depth blog post that covers that, so feel free to check it out.

That's everything! I hope you've found this interesting, and you've learned something new. If you want to delve deeper into Python and everything it has to offer, please consider joining our Complete Python Course. This mega-course covers many Python topics, and it's currently on sale!

Thanks for reading, and I'll see you next time.