Your First Application

In this tutorial, you will build a basic web application using the Flask class and learn how to properly initialize it. You will start with a minimal single-module application and then progress to the "Application Factory" pattern used in larger projects.

Prerequisites

To follow this guide, you need the flask package installed in your environment.

Step 1: The Minimal Application

The simplest way to create a Flask application is to instantiate the Flask class in a single Python file. Create a file named app.py with the following code:

# save this as app.py
from flask import Flask

app = Flask(__name__)

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

In this snippet, app = Flask(__name__) creates the central application object. The @app.route("/") decorator tells Flask which URL should trigger the hello function. When you visit the root URL, it returns the string "Hello, World!".

Step 2: Understanding the import_name Parameter

The first argument passed to the Flask constructor is import_name. In the example above, we used __name__.

As defined in src/flask/app.py, this parameter is used to resolve resources like templates and static files. Flask needs to know where your application is located on the filesystem to find these folders.

• Single Module: If you are using a single module (like app.py), __name__ is the correct value.
• Packages: If your application is a package (a folder with an __init__.py), it is often recommended to hardcode the package name or use the top-level package name:

# If your app is in yourapplication/app.py
app = Flask("yourapplication")

# Or dynamically
app = Flask(__name__.split(".")[0])

Providing the correct import_name is critical for debugging. Extensions like Flask-SQLAlchemy use this name to identify which part of your application triggered a database query. If this is set incorrectly, valuable debugging information may be lost.

Step 3: Using an Application Factory

For larger applications, it is better to create the Flask instance inside a function. This is known as the Application Factory pattern. This approach allows you to create multiple instances of the app with different configurations (e.g., for testing).

Here is an example based on examples/tutorial/flaskr/__init__.py:

import os
from flask import Flask

def create_app(test_config=None):
    # create and configure the app
    app = Flask(__name__, instance_relative_config=True)
    app.config.from_mapping(
        SECRET_KEY="dev",
        DATABASE=os.path.join(app.instance_path, "flaskr.sqlite"),
    )

    if test_config is None:
        # load the instance config, if it exists, when not testing
        app.config.from_pyfile("config.py", silent=True)
    else:
        # load the test config if passed in
        app.config.update(test_config)

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

    return app

In this pattern:

1. instance_relative_config=True tells the app that configuration files are relative to the instance folder.
2. app.instance_path is automatically determined based on the import_name provided during initialization.
3. The app object is returned at the end of the function, ready to be used by a WSGI server or the Flask CLI.

Step 4: Customizing Resource Folders

By default, Flask looks for a static folder for CSS/JS and a templates folder for HTML files relative to the application's root path. You can customize these during initialization:

app = Flask(
    __name__,
    static_folder="assets",
    template_folder="views",
    static_url_path="/static_files"
)

• static_folder: The directory containing static files (defaults to "static").
• template_folder: The directory containing Jinja templates (defaults to "templates").
• static_url_path: The URL prefix used to serve static files.

Important Lifecycle Rule

A critical rule in Flask is that you cannot perform setup actions—such as registering routes with @app.route or adding blueprints—after the application has started handling requests. Attempting to do so will result in an AssertionError. Always ensure your Flask instance is fully configured before it begins serving traffic.

Next Steps

Now that you have a working Flask instance, you can begin organizing your logic using Blueprints or connecting to a database using the app.config object.