Under the Hood: The Registration Mechanism

Blueprints in Flask are designed around a "deferred execution" model. Unlike the Flask application object, which is often ready to handle requests as soon as it is created, a Blueprint is essentially a recorded set of instructions that are only applied when the blueprint is registered on an actual application.

This design allows developers to modularize their code without needing access to the global app object at definition time, facilitating better project structure and reusability.

The Recording Phase

When you use decorators like @bp.route or @bp.before_request on a Blueprint instance, Flask does not immediately update the application's routing table or handler dictionaries. Instead, it uses two distinct mechanisms to store these operations for later.

Deferred Functions

For operations that depend on the final registration context—such as routes that need a URL prefix or a subdomain—the Blueprint class maintains a list called deferred_functions.

When add_url_rule is called on a blueprint (either directly or via the @route decorator), it records a lambda function that will eventually call BlueprintSetupState.add_url_rule.

# From src/flask/sansio/blueprints.py
def add_url_rule(
    self,
    rule: str,
    endpoint: str | None = None,
    view_func: ft.RouteCallable | None = None,
    provide_automatic_options: bool | None = None,
    **options: t.Any,
) -> None:
    # ... validation logic ...
    self.record(
        lambda s: s.add_url_rule(
            rule,
            endpoint,
            view_func,
            provide_automatic_options=provide_automatic_options,
            **options,
        )
    )

The record method simply appends these functions to self.deferred_functions. This list acts as a "to-do list" that Flask will execute during the registration phase.

Local Handler Storage

For handlers that are local to the blueprint (like before_request or errorhandler), Blueprint inherits storage structures from Scaffold. These are standard dictionaries like before_request_funcs and error_handler_spec. These are populated immediately when the decorator is used but are not integrated into the Flask application until registration.

The Registration Lifecycle

The transition from a "plan" to a "live" part of the application happens when app.register_blueprint(bp) is called. This triggers a sequence of events within Blueprint.register:

1. Name Resolution: Flask calculates the unique name for this registration. If a blueprint is nested or registered multiple times, it generates a dotted name (e.g., parent.child) to ensure endpoint uniqueness.
2. State Creation: It creates an instance of BlueprintSetupState. This object acts as a temporary coordinator, carrying the application instance, the registration options (like url_prefix), and the blueprint itself.
3. Merging Functions: The _merge_blueprint_funcs method is called. This iterates through the blueprint's local handlers (stored in the Scaffold dictionaries) and copies them into the Flask application's dictionaries, prefixing the keys with the blueprint's name.
4. Executing Deferred Functions: Flask iterates through self.deferred_functions, passing the BlueprintSetupState to each one. This is when routes are finally added to the application's url_map.
5. Recursive Registration: If the blueprint has nested blueprints (registered via bp.register_blueprint), it recursively calls register on them, passing down accumulated URL prefixes and subdomains.

The Role of BlueprintSetupState

The BlueprintSetupState class is the engine that applies the blueprint's configuration to the application. Its primary responsibility is to resolve the final state of a route based on the registration arguments.

When BlueprintSetupState.add_url_rule is called, it performs three critical transformations:

1. URL Prefixing: It prepends the registration's url_prefix to the rule.
2. Subdomain Assignment: It applies any subdomain specified during registration or defined on the blueprint.
3. Endpoint Namespacing: It prefixes the endpoint name with the blueprint's name (and any parent prefixes), resulting in the familiar blueprint_name.endpoint format used in url_for.

# From src/flask/sansio/blueprints.py
def add_url_rule(
    self,
    rule: str,
    endpoint: str | None = None,
    view_func: ft.RouteCallable | None = None,
    **options: t.Any,
) -> None:
    if self.url_prefix is not None:
        if rule:
            rule = "/".join((self.url_prefix.rstrip("/"), rule.lstrip("/")))
        else:
            rule = self.url_prefix
    
    # ...
    
    self.app.add_url_rule(
        rule,
        f"{self.name_prefix}.{self.name}.{endpoint}".lstrip("."),
        view_func,
        defaults=defaults,
        **options,
    )

Custom Setup Logic

Flask provides the @record and @record_once decorators to allow developers to hook into this registration process. This is useful for extensions or complex blueprints that need to modify the application configuration or register custom Jinja filters.

For example, to set an application config value when a blueprint is registered:

bp = Blueprint("admin", __name__)

@bp.record
def setup_admin(state):
    state.app.config["ADMIN_REGISTERED"] = True

The record_once variant ensures that even if a blueprint is registered multiple times (e.g., under different URL prefixes), the setup logic only runs once. This is used internally by Flask for methods like app_template_filter to prevent duplicate registration of global resources.

Constraints and Safety

To ensure consistency, Flask enforces a strict "no modification after registration" rule. Both Blueprint and Flask use the @setupmethod decorator, which calls _check_setup_finished.

In Blueprint, once register has been called, self._got_registered_once is set to True. Any subsequent attempt to call a setup method (like adding a route or a handler) will raise an AssertionError. This prevents situations where a blueprint is modified after its instructions have already been applied to an application, which would lead to unpredictable behavior.