Creating and Registering Modules

Blueprints are a powerful way to organize your Flask application into distinct modules. Instead of registering routes and error handlers directly on the application instance, you register them on a Blueprint object. Once the blueprint is defined, you register it with the application.

This tutorial walks you through creating an authentication module using the Blueprint class from flask.blueprints.

Prerequisites

• A Flask application instance (typically created using an application factory).
• Basic knowledge of Flask routes and view functions.

Step 1: Define the Blueprint

First, create a new module for your blueprint. In this example, we will create an authentication module in a file named auth.py.

from flask import Blueprint

# Create a Blueprint instance
bp = Blueprint("auth", __name__, url_prefix="/auth")

When you create a Blueprint, you provide:

• name: The name of the blueprint (e.g., "auth"). This is used for namespacing endpoints. It cannot contain dots.
• import_name: Usually __name__, which helps Flask locate resources like templates and static files.
• url_prefix: (Optional) A path that will be prepended to all routes defined in this blueprint.

Step 2: Add Routes to the Blueprint

You define routes on a blueprint just as you would on a Flask app instance, using decorators like @bp.route or shortcuts like @bp.get.

from flask import render_template, request, redirect, url_for

@bp.route("/login", methods=("GET", "POST"))
def login():
    if request.method == "POST":
        # ... handle login logic ...
        return redirect(url_for("index"))

    return render_template("auth/login.html")

@bp.get("/register")
def register():
    return render_template("auth/register.html")

Note that the login view is registered at /auth/login because of the url_prefix we defined in Step 1.

Step 3: Register the Blueprint with the Application

To make the blueprint's routes active, you must register it with your Flask application instance using app.register_blueprint(). This is typically done inside your application factory function.

from flask import Flask
from . import auth  # Import the module containing your blueprint

def create_app():
    app = Flask(__name__)

    # Register the blueprint
    app.register_blueprint(auth.bp)

    return app

Once registered, all routes defined on auth.bp become part of the application.

Step 4: Using Blueprint Endpoints

When using url_for to generate URLs for blueprint routes, you must prefix the endpoint name with the blueprint's name followed by a dot.

# Generates the URL for the 'login' function in the 'auth' blueprint
login_url = url_for("auth.login") 
# Result: "/auth/login"

If you are inside a view function of the same blueprint, you can use a shortcut by starting with a dot:

# Inside a view in auth.py
redirect(url_for(".login"))

Advanced: Nesting Blueprints

You can also register a blueprint on another blueprint. This is useful for deeply nested structures.

parent = Blueprint("parent", __name__)
child = Blueprint("child", __name__)

# Register child on parent
parent.register_blueprint(child, url_prefix="/child")

# Register parent on the app
app.register_blueprint(parent, url_prefix="/parent")

In this case, a route defined as @child.route("/info") would be accessible at /parent/child/info, and its endpoint name would be parent.child.info.

Summary

By the end of this tutorial, you have:

1. Created a Blueprint instance to encapsulate related logic.
2. Defined routes using blueprint-specific decorators.
3. Registered the blueprint with a Flask application.
4. Generated URLs using namespaced endpoints.

For next steps, consider adding blueprint-specific error handlers using @bp.errorhandler or request hooks using @bp.before_app_request.