Application Factory & Project Layout

from flask import Flask

app = Flask(__name__)


@app.get("/")
def index():
    return {"service": "bookshelf"}


# Flask's test client calls the app without starting a server
response = app.test_client().get("/")
print(response.status_code, response.get_json())
assert response.get_json() == {"service": "bookshelf"}

from flask import Flask, current_app


def create_app(test_config=None):
    app = Flask(__name__)
    app.config.from_mapping(GREETING="hello")
    if test_config is not None:
        app.config.from_mapping(test_config)

    @app.get("/greeting")
    def greeting():
        return current_app.config["GREETING"]

    return app


english = create_app()
spanish = create_app({"GREETING": "hola"})

assert english.test_client().get("/greeting").text == "hello"
assert spanish.test_client().get("/greeting").text == "hola"
assert english is not spanish
assert english.config["GREETING"] == "hello"  # the second app did not touch the first

from flask import current_app

try:
    current_app.config
except RuntimeError as error:
    print(error)

with english.app_context():
    print(current_app.config["GREETING"])

Working outside of application context.

This typically means that you attempted to use functionality that needed
the current application. To solve this, set up an application context
with app.app_context(). See the documentation for more information.
hello

from flask_sqlalchemy import SQLAlchemy
from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass


db = SQLAlchemy(model_class=Base)

import itertools

from flask import Flask, current_app, g


class RequestStamp:
    def __init__(self, app=None):
        if app is not None:
            self.init_app(app)

    def init_app(self, app):
        app.config.setdefault("REQUEST_STAMP_PREFIX", "req")
        app.extensions["request_stamp"] = {"counter": itertools.count(1)}
        app.before_request(self._assign)
        app.after_request(self._add_header)

    def _assign(self):
        state = current_app.extensions["request_stamp"]
        prefix = current_app.config["REQUEST_STAMP_PREFIX"]
        g._request_stamp = f"{prefix}-{next(state['counter'])}"  # prefixed name: g is shared

    def _add_header(self, response):
        response.headers["X-Request-Stamp"] = g._request_stamp
        return response


stamp = RequestStamp()  # created once, bound to any number of apps


def make(prefix):
    app = Flask(prefix)
    app.config["REQUEST_STAMP_PREFIX"] = prefix
    stamp.init_app(app)

    @app.get("/")
    def index():
        return "ok"

    return app


one, two = make("one"), make("two")
for app in (one, two, one):
    print(app.test_client().get("/").headers["X-Request-Stamp"])

one-1
two-1
one-2

import os
from typing import Any

from flask import Flask

from .config import CONFIGS
from .extensions import db


def create_app(
    config_name: str = "development",
    test_config: dict[str, Any] | None = None,
    instance_path: str | None = None,
) -> Flask:
    app = Flask(
        __name__,
        # must be absolute; with a src/ layout Flask would guess src/instance
        instance_path=instance_path or os.environ.get("BOOKSHELF_INSTANCE_PATH") or os.path.abspath("instance"),
        instance_relative_config=True,
    )

    # 1. configuration: defaults, then the instance folder, then the environment
    app.config.from_object(CONFIGS[config_name])
    if test_config is None:
        app.config.from_pyfile("config.py", silent=True)
    else:
        app.config.from_mapping(test_config)
    app.config.from_prefixed_env("BOOKSHELF")  # BOOKSHELF_SECRET_KEY=... becomes SECRET_KEY
    if not app.config["SECRET_KEY"]:
        raise RuntimeError("SECRET_KEY is not set: put it in instance/config.py or BOOKSHELF_SECRET_KEY")

    # 2. the instance folder must exist before anything writes to it
    os.makedirs(app.instance_path, exist_ok=True)

    # 3. extensions: bind the objects from extensions.py to this app
    db.init_app(app)

    # 3b. services: plain objects, built once and kept where current_app can find them
    from .catalog.repository import SqlAlchemyBookRepository
    from .catalog.services import CatalogService

    app.extensions["bookshelf.catalog"] = CatalogService(SqlAlchemyBookRepository(), db.session.commit)

    # 4. blueprints (imported here, once the extensions exist)
    from .api import bp as api_bp
    from .catalog import bp as catalog_bp

    app.register_blueprint(catalog_bp)
    app.register_blueprint(api_bp, url_prefix="/api")

    # 5. CLI commands, error handlers, context processors
    from . import cli

    cli.init_app(app)

    return app

import secrets


class Config:
    TESTING = False
    SQLALCHEMY_DATABASE_URI = "sqlite:///bookshelf.sqlite"  # relative to the instance folder
    SECRET_KEY = None  # never committed: the instance config or FLASK_SECRET_KEY supplies it


class DevelopmentConfig(Config):
    # a random key per process: fine for a throw-away dev server, sessions just reset on restart
    SECRET_KEY = secrets.token_hex()


class TestingConfig(Config):
    TESTING = True
    SECRET_KEY = secrets.token_hex()
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"


class ProductionConfig(Config):
    pass


CONFIGS = {
    "development": DevelopmentConfig,
    "testing": TestingConfig,
    "production": ProductionConfig,
}

from flask import Blueprint

bp = Blueprint("catalog", __name__, template_folder="templates")

from . import routes  # noqa: E402,F401  (registers the views on bp)

from flask import current_app, render_template

from . import bp
from .services import CatalogService


def service() -> CatalogService:
    return current_app.extensions["bookshelf.catalog"]


@bp.get("/")
def index():
    return render_template("catalog/index.html", titles=service().titles())

<!doctype html>
<title>Bookshelf</title>
<h1>Bookshelf</h1>
<ul>
{% for title in titles %}  <li>{{ title }}</li>
{% endfor %}</ul>

from flask import Blueprint, current_app, jsonify, request

from ..catalog.services import CatalogService, DuplicateBook

bp = Blueprint("api", __name__)


def service() -> CatalogService:
    return current_app.extensions["bookshelf.catalog"]


@bp.get("/books")
def list_books():
    return jsonify(titles=service().titles())


@bp.post("/books")
def create_book():
    data = request.get_json()
    try:
        book = service().register(data["title"], data["author"])
    except DuplicateBook:
        return jsonify(error="duplicate title"), 409
    except (KeyError, ValueError) as error:
        return jsonify(error=str(error)), 422
    return jsonify(id=book.id, title=book.title), 201

from .book import Book

__all__ = ["Book"]

from sqlalchemy.orm import Mapped, mapped_column

from ..extensions import db


class Book(db.Model):
    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(unique=True)
    author: Mapped[str]

import click
from flask import Flask
from flask.cli import AppGroup

from .extensions import db

books_cli = AppGroup("books", help="Manage the catalogue.")


@books_cli.command("init-db")
def init_db() -> None:
    """Create the tables."""
    db.create_all()
    click.echo("Initialised the database.")


def init_app(app: Flask) -> None:
    app.cli.add_command(books_cli)

import pathlib
import secrets
import tempfile

from flask import Flask

demo_key = secrets.token_hex()  # generated for this run; a deployment writes its own key into instance/config.py
root = pathlib.Path(tempfile.mkdtemp())
instance = root / "instance"

app = Flask("bookshelf_demo", instance_path=str(instance), instance_relative_config=True)
assert app.instance_path == str(instance)

# the file does not exist yet: silent=True makes from_pyfile return False instead of raising
assert app.config.from_pyfile("config.py", silent=True) is False

instance.mkdir()
with app.open_instance_resource("config.py", "w") as handle:
    handle.write(f"SECRET_KEY = {demo_key!r}\nPAGE_SIZE = 20\n")

assert app.config.from_pyfile("config.py") is True
assert app.config["SECRET_KEY"] == demo_key
print(app.config["PAGE_SIZE"], len(app.config["SECRET_KEY"]))

try:
    Flask("bookshelf_demo", instance_path="relative/path")
except ValueError as error:
    print(error)

20 64
If an instance path is provided it must be absolute. A relative path was given instead.

# .gitignore
instance/
*.sqlite
.env

[project]
name = "bookshelf"
version = "0.1.0"
description = "Bookshelf: the running example of the Flask section."
requires-python = ">=3.10"
dependencies = [
    "flask>=3.1",
    "flask-sqlalchemy>=3.1",
]

[project.optional-dependencies]
test = ["pytest"]

[build-system]
requires = ["flit_core<4"]
build-backend = "flit_core.buildapi"

python -m venv .venv
source .venv/bin/activate      # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -e ".[test]"       # editable install of the project plus the test extra

# or with uv, which creates and manages the environment for you
uv venv && uv pip install -e ".[test]"

import pathlib
import subprocess
import sys
import tempfile

work = pathlib.Path(tempfile.mkdtemp())
(work / "hello.py").write_text(
    "from flask import Flask\n"
    "\n"
    "def make_app(greeting='hello'):\n"
    "    app = Flask(__name__)\n"
    "\n"
    "    @app.get('/')\n"
    "    def index():\n"
    "        return greeting\n"
    "\n"
    "    return app\n"
)
(work / "needs_arg.py").write_text(
    "from flask import Flask\n\ndef create_app(name):\n    return Flask(name)\n"
)


def flask(*args):
    result = subprocess.run([sys.executable, "-m", "flask", *args], cwd=work, capture_output=True, text=True)
    return result.returncode, (result.stdout + result.stderr).strip()


code, output = flask("--app", "hello", "routes")  # make_app found and called without arguments
assert code == 0 and "index" in output
print(output)

code, output = flask("--app", "hello:make_app(greeting='hi')", "routes")  # arguments as literals
assert code == 0

code, output = flask("--app", "needs_arg", "routes")  # a required argument cannot be guessed
assert code != 0
print(output.splitlines()[-1])

code, output = flask("--app", "hello:make_app(greeting=len)", "routes")  # not a literal
assert code != 0
print(output.splitlines()[-1])

Endpoint  Methods  Rule
--------  -------  -----------------------
index     GET      /
static    GET      /static/<path:filename>
Error: Detected factory 'create_app' in module 'needs_arg', but could not call it without arguments. Use 'needs_arg:create_app(args)' to specify arguments.
Error: Failed to parse arguments as literal values: 'make_app(greeting=len)'.

from flask import Flask, request, url_for
from werkzeug.middleware.dispatcher import DispatcherMiddleware
from werkzeug.middleware.proxy_fix import ProxyFix
from werkzeug.test import Client


def make(name):
    app = Flask(name)

    @app.get("/ping")
    def ping():
        return {
            "app": name,
            "path": request.path,
            "script_root": request.script_root,
            "url": url_for("ping"),
        }

    return app


public, admin = make("public"), make("admin")

# middleware wraps wsgi_app, not the app, so the Flask object keeps its methods
public.wsgi_app = ProxyFix(public.wsgi_app, x_proto=1, x_host=1)  # only behind a proxy you control

combined = DispatcherMiddleware(public, {"/admin": admin})
client = Client(combined)

print(client.get("/ping").get_json())
print(client.get("/admin/ping").get_json())

{'app': 'public', 'path': '/ping', 'script_root': '', 'url': '/ping'}
{'app': 'admin', 'path': '/ping', 'script_root': '/admin', 'url': '/admin/ping'}

import pathlib
import sys
import tempfile

from flask import Flask
from werkzeug.utils import cached_property, import_string

views_dir = pathlib.Path(tempfile.mkdtemp())
(views_dir / "bookshelf_views.py").write_text(
    "def index():\n"
    "    return 'catalogue'\n"
    "\n"
    "def book(book_id):\n"
    "    return f'book {book_id}'\n"
)
sys.path.insert(0, str(views_dir))


class LazyView:
    def __init__(self, import_name):
        self.__module__, self.__name__ = import_name.rsplit(".", 1)
        self.import_name = import_name

    @cached_property
    def view(self):
        return import_string(self.import_name)

    def __call__(self, *args, **kwargs):
        return self.view(*args, **kwargs)


app = Flask("lazy_demo")
app.add_url_rule("/", view_func=LazyView("bookshelf_views.index"))
app.add_url_rule("/books/<int:book_id>", view_func=LazyView("bookshelf_views.book"))

assert "bookshelf_views" not in sys.modules  # nothing imported at registration time
client = app.test_client()
assert client.get("/").text == "catalogue"
assert "bookshelf_views" in sys.modules      # imported by the first request
assert client.get("/books/7").text == "book 7"
assert [rule.endpoint for rule in app.url_map.iter_rules()][:2] == ["static", "index"]

from typing import Protocol

from ..extensions import db
from ..models import Book


class BookRepository(Protocol):
    def add(self, title: str, author: str) -> Book: ...
    def list_all(self) -> list[Book]: ...


class SqlAlchemyBookRepository:
    def add(self, title: str, author: str) -> Book:
        book = Book(title=title, author=author)
        db.session.add(book)
        return book

    def list_all(self) -> list[Book]:
        return list(db.session.scalars(db.select(Book).order_by(Book.title)))

from .repository import BookRepository


class DuplicateBook(Exception):
    pass


class CatalogService:
    def __init__(self, books: BookRepository, commit) -> None:
        self._books = books
        self._commit = commit  # the unit of work: db.session.commit in production

    def register(self, title: str, author: str):
        title = title.strip()
        if not title:
            raise ValueError("title must not be empty")
        if any(b.title == title for b in self._books.list_all()):
            raise DuplicateBook(title)
        book = self._books.add(title, author.strip())
        self._commit()
        return book

    def titles(self) -> list[str]:
        return [b.title for b in self._books.list_all()]

import pytest

from bookshelf.catalog.services import CatalogService, DuplicateBook


class FakeBook:
    def __init__(self, title: str, author: str) -> None:
        self.title, self.author = title, author


class InMemoryBookRepository:
    def __init__(self) -> None:
        self._books: list[FakeBook] = []

    def add(self, title: str, author: str) -> FakeBook:
        book = FakeBook(title, author)
        self._books.append(book)
        return book

    def list_all(self) -> list[FakeBook]:
        return sorted(self._books, key=lambda b: b.title)


def make_service() -> tuple[CatalogService, list[int]]:
    commits: list[int] = []
    return CatalogService(InMemoryBookRepository(), lambda: commits.append(1)), commits


def test_register_commits_once():
    service, commits = make_service()
    service.register("  Dune ", "Frank Herbert")
    assert service.titles() == ["Dune"]
    assert commits == [1]


def test_duplicates_and_blank_titles_are_rejected():
    service, _ = make_service()
    service.register("Dune", "Frank Herbert")
    with pytest.raises(DuplicateBook):
        service.register("Dune", "Someone Else")
    with pytest.raises(ValueError):
        service.register("   ", "Nobody")

import pytest

from bookshelf import create_app
from bookshelf.extensions import db


@pytest.fixture()
def app(tmp_path):
    app = create_app("testing", test_config={"TESTING": True}, instance_path=str(tmp_path))
    with app.app_context():
        db.create_all()
    yield app


@pytest.fixture()
def client(app):
    return app.test_client()


@pytest.fixture()
def runner(app):
    return app.test_cli_runner()

def test_empty_catalogue(client):
    response = client.get("/api/books")
    assert response.status_code == 200
    assert response.json == {"titles": []}


def test_create_and_list(client):
    created = client.post("/api/books", json={"title": "Dune", "author": "Frank Herbert"})
    assert created.status_code == 201
    assert client.get("/api/books").json == {"titles": ["Dune"]}
    assert client.get("/").text.count("<li>") == 1


def test_duplicate_is_rejected(client):
    payload = {"title": "Dune", "author": "Frank Herbert"}
    client.post("/api/books", json=payload)
    assert client.post("/api/books", json=payload).status_code == 409


def test_cli_command(runner):
    result = runner.invoke(args=["books", "init-db"])
    assert "Initialised" in result.output

import pytest

from bookshelf import create_app


def test_two_apps_do_not_share_state(tmp_path):
    first = create_app("testing", instance_path=str(tmp_path / "a"))
    second = create_app("testing", test_config={"TESTING": True, "GREETING": "hola"}, instance_path=str(tmp_path / "b"))
    assert "GREETING" not in first.config
    assert second.config["GREETING"] == "hola"
    assert first.instance_path != second.instance_path


def test_production_needs_a_secret_key(tmp_path, monkeypatch):
    monkeypatch.delenv("BOOKSHELF_SECRET_KEY", raising=False)
    with pytest.raises(RuntimeError):
        create_app("production", instance_path=str(tmp_path))
    monkeypatch.setenv("BOOKSHELF_SECRET_KEY", "0123abcd" * 8)
    assert create_app("production", instance_path=str(tmp_path)).config["SECRET_KEY"] == "0123abcd" * 8